objectstack-ai
diff --git a/‎.changeset/21263-crypto-provider-keyed-digest.md‎
Lines changed: 40 additions & 0 deletions b/‎.changeset/21263-crypto-provider-keyed-digest.md‎
Lines changed: 40 additions & 0 deletions
diff --git a/‎packages/objectql/src/secret-fields.test.ts‎
Lines changed: 1 addition & 0 deletions b/‎packages/objectql/src/secret-fields.test.ts‎
Lines changed: 1 addition & 0 deletions
diff --git a/‎packages/plugins/plugin-auth/src/sso-client-secret-at-rest.test.ts‎
Lines changed: 1 addition & 0 deletions b/‎packages/plugins/plugin-auth/src/sso-client-secret-at-rest.test.ts‎
Lines changed: 1 addition & 0 deletions
diff --git a/‎packages/plugins/plugin-webhooks/src/webhook-headers-gate.test.ts‎
Lines changed: 1 addition & 0 deletions b/‎packages/plugins/plugin-webhooks/src/webhook-headers-gate.test.ts‎
Lines changed: 1 addition & 0 deletions
diff --git a/‎packages/plugins/plugin-webhooks/src/webhook-secret-at-rest.test.ts‎
Lines changed: 1 addition & 0 deletions b/‎packages/plugins/plugin-webhooks/src/webhook-secret-at-rest.test.ts‎
Lines changed: 1 addition & 0 deletions
diff --git a/‎packages/services/service-datasource/src/__tests__/datasource-secret-binder.test.ts‎
Lines changed: 1 addition & 0 deletions b/‎packages/services/service-datasource/src/__tests__/datasource-secret-binder.test.ts‎
Lines changed: 1 addition & 0 deletions
diff --git a/‎packages/services/service-settings/src/local-crypto-provider.test.ts‎
Lines changed: 114 additions & 2 deletions b/‎packages/services/service-settings/src/local-crypto-provider.test.ts‎
Lines changed: 114 additions & 2 deletions
diff --git a/‎packages/services/service-settings/src/local-crypto-provider.ts‎
Lines changed: 76 additions & 1 deletion b/‎packages/services/service-settings/src/local-crypto-provider.ts‎
Lines changed: 76 additions & 1 deletion
diff --git a/‎packages/spec/src/contracts/crypto-provider.ts‎
Lines changed: 35 additions & 0 deletions b/‎packages/spec/src/contracts/crypto-provider.ts‎
Lines changed: 35 additions & 0 deletions
@@ -0,0 +1,40 @@
+---
+'@objectstack/spec': minor
+'@objectstack/service-settings': minor
+---
+
+feat(spec): `ICryptoProvider` gains a required `keyedDigest(plain): Promise<string>` member, and `LocalCryptoProvider` implements it (#21263)
+
+Clause-②: yes
+
+**BREAKING** for `ICryptoProvider` implementers: the new member is required, so a
+provider that does not declare it stops compiling (`TS2420` on a class, `TS2741`
+on an object literal), and the compiler names the missing member. Code that only
+calls a provider is unaffected.
+
+`keyedDigest` is a digest of `plain` under the provider's server-held key, for a
+value that is handed to a caller but must not let that caller check a guess about
+the input offline. The contract requires three things of every implementation:
+
+- **Keyed.** The output cannot be computed without the provider's key. A provider
+  that holds no key material rejects; it never returns an unkeyed value.
+- **Stable per key.** Under one key, equal input gives equal output in every
+  process and on every node that holds the key. Replacing the key changes every
+  output.
+- **Not a substitute for `digest`.** `digest` keeps its contract and the stability
+  the audit trail relies on.
+
+The output is `hmac-sha256:` followed by the 64 lowercase hex characters of an
+HMAC-SHA-256: 76 characters from `[0-9a-z:-]`, which travel unchanged in an HTTP
+header, a query string and JSON, and never collide with the `sha256:` spelling of
+an unkeyed content hash.
+
+`LocalCryptoProvider` computes it from the 32-byte data key it already resolves
+(`OS_SECRET_KEY`, `OS_DEV_CRYPTO_KEY`, the persisted key file, or the ephemeral
+test-mode key), through a MAC key derived from that data key, so the AES-GCM key
+is never used as a MAC key. There is no new secret or environment variable to
+configure. An instance constructed with an explicit key that is not 32 bytes holds
+no usable key material, and its `keyedDigest` rejects with
+`KeyedDigestKeyUnavailableError`.
+
+<!-- adr-0087: not-required (no-migration-prescription) `ICryptoProvider` is a TypeScript contract with no metadata surface: no Zod schema, no authorable key, no export renamed or removed and no stored row changes shape, so `objectstack migrate meta` has nothing to rewrite. The affected party is a provider implementer, and the compiler names the missing member at their declaration. -->
@@ -136,6 +136,7 @@ function makeFakeCrypto() {
       return { ...handle, version: handle.version + 1 };
     },
     digest(plain: string): string { return `d:${plain.length}`; },
+    async keyedDigest(plain: string): Promise<string> { return `k:${plain.length}`; },
   };
   return { provider, calls };
 }
 
@@ -100,6 +100,7 @@ function makeFakeCrypto(): ICryptoProvider {
       return { ...handle, version: handle.version + 1 };
     },
     digest(plain: string): string { return `d:${plain.length}`; },
+    async keyedDigest(plain: string): Promise<string> { return `k:${plain.length}`; },
   };
 }
 
 
@@ -143,6 +143,7 @@ function makeFakeCrypto(): ICryptoProvider {
             return { ...handle, version: handle.version + 1 };
         },
         digest(plain: string): string { return `d:${plain.length}`; },
+        async keyedDigest(plain: string): Promise<string> { return `k:${plain.length}`; },
     };
 }
 
 
@@ -170,6 +170,7 @@ function makeFakeCrypto() {
             return { ...handle, version: handle.version + 1 };
         },
         digest(plain: string): string { return `d:${plain.length}`; },
+        async keyedDigest(plain: string): Promise<string> { return `k:${plain.length}`; },
     };
     return provider;
 }
 
@@ -35,6 +35,7 @@ function fakeCrypto(): ICryptoProvider {
       return handle;
     },
     digest: (plain: string) => 'sha256:' + plain,
+    keyedDigest: async (plain: string) => `k:${plain.length}`,
   };
 }
 
 
@@ -1,13 +1,14 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-import { mkdtempSync, rmSync, writeFileSync, existsSync } from 'node:fs';
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync, existsSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
-import { randomBytes } from 'node:crypto';
+import { createHash, createHmac, randomBytes } from 'node:crypto';
 import {
   LocalCryptoProvider,
   InMemoryCryptoProvider,
+  KeyedDigestKeyUnavailableError,
 } from './local-crypto-provider.js';
 
 const ctx = { namespace: 'mail', key: 'api_key' };
@@ -154,6 +155,117 @@ describe('LocalCryptoProvider — crypto semantics', () => {
   });
 });
 
+describe('LocalCryptoProvider — keyedDigest', () => {
+  const KEYED_SHAPE = /^hmac-sha256:[0-9a-f]{64}$/;
+  const input = 'sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a';
+  const sha256Hex = (s: string) => createHash('sha256').update(s, 'utf8').digest('hex');
+
+  let home: string;
+  beforeEach(() => {
+    home = mkdtempSync(join(tmpdir(), 'os-crypto-keyed-'));
+  });
+  afterEach(() => {
+    rmSync(home, { recursive: true, force: true });
+  });
+
+  it('is keyed: the output differs from the unkeyed SHA-256 of the same input', async () => {
+    const p = new LocalCryptoProvider({ key: randomBytes(32) });
+    const out = await p.keyedDigest(input);
+    expect(out).toMatch(KEYED_SHAPE);
+    expect(out).toHaveLength(76);
+    const hexBody = out.slice('hmac-sha256:'.length);
+    expect(hexBody).not.toBe(sha256Hex(input));
+    expect(out).not.toBe(p.digest(input));
+    expect(out).not.toContain(input);
+  });
+
+  it('is equal for equal input under one key — within an instance and across instances', async () => {
+    const hex = randomBytes(32).toString('hex');
+    const env = { NODE_ENV: 'production', OS_SECRET_KEY: hex, OS_HOME: home };
+    const a = new LocalCryptoProvider({ env });
+    // A second instance resolving the same key stands in for another process or node.
+    const b = new LocalCryptoProvider({ env });
+    expect(await a.keyedDigest(input)).toBe(await a.keyedDigest(input));
+    expect(await b.keyedDigest(input)).toBe(await a.keyedDigest(input));
+    // The same key spelled base64 is the same key.
+    const c = new LocalCryptoProvider({
+      env: { NODE_ENV: 'production', OS_SECRET_KEY: Buffer.from(hex, 'hex').toString('base64'), OS_HOME: home },
+    });
+    expect(await c.keyedDigest(input)).toBe(await a.keyedDigest(input));
+    // Equal under one key is not constant under one key.
+    expect(await a.keyedDigest(input + ' ')).not.toBe(await a.keyedDigest(input));
+  });
+
+  it('differs under a different key', async () => {
+    const a = new LocalCryptoProvider({ key: randomBytes(32) });
+    const b = new LocalCryptoProvider({ key: randomBytes(32) });
+    expect(await a.keyedDigest(input)).not.toBe(await b.keyedDigest(input));
+  });
+
+  it('keys its MAC with a key derived from the data key, never with the data key itself', async () => {
+    const key = randomBytes(32);
+    const out = await new LocalCryptoProvider({ key }).keyedDigest(input);
+    const underDataKey = createHmac('sha256', key).update(input, 'utf8').digest('hex');
+    expect(out).toMatch(KEYED_SHAPE);
+    expect(out.slice('hmac-sha256:'.length)).not.toBe(underDataKey);
+  });
+
+  it('answers a pinned vector, so builds on two nodes of one rolling deploy agree', async () => {
+    // Vector computed outside this implementation (Python `hmac`): the MAC key is
+    // HMAC-SHA-256(dataKey, label || 0x01), the output HMAC-SHA-256(macKey, input).
+    const p = new LocalCryptoProvider({ key: Buffer.from(Array.from({ length: 32 }, (_, i) => i)) });
+    expect(await p.keyedDigest('hello')).toBe(
+      'hmac-sha256:de27f4140f1e5db4cdabc24d91dbf5eef67eeaaacd5fefa0aa491f283bdcded6',
+    );
+    expect(await p.keyedDigest(input)).toBe(
+      'hmac-sha256:ac3e935526f452d6e230db8667e46422fdfe53800f70c13a70006576fae8a21b',
+    );
+  });
+
+  it('is computed from whichever source resolved the data key', async () => {
+    const key = randomBytes(32);
+    const expected = await new LocalCryptoProvider({ key }).keyedDigest(input);
+
+    const fromSecret = new LocalCryptoProvider({
+      env: { NODE_ENV: 'production', OS_SECRET_KEY: key.toString('hex'), OS_HOME: home },
+    });
+    expect(fromSecret.keySource).toBe('env:OS_SECRET_KEY');
+    expect(await fromSecret.keyedDigest(input)).toBe(expected);
+
+    const fromDevKey = new LocalCryptoProvider({
+      env: { NODE_ENV: 'development', OS_DEV_CRYPTO_KEY: key.toString('hex'), HOME: home },
+    });
+    expect(fromDevKey.keySource).toBe('env:OS_DEV_CRYPTO_KEY');
+    expect(await fromDevKey.keyedDigest(input)).toBe(expected);
+
+    mkdirSync(join(home, '.objectstack'), { recursive: true });
+    writeFileSync(join(home, '.objectstack', 'dev-crypto-key'), key.toString('base64'), { mode: 0o600 });
+    const fromFile = new LocalCryptoProvider({ env: { NODE_ENV: 'production', HOME: home } });
+    expect(fromFile.keySource).toBe('file');
+    expect(await fromFile.keyedDigest(input)).toBe(expected);
+
+    const ephemeral = new LocalCryptoProvider({ env: { NODE_ENV: 'test', HOME: home } });
+    expect(ephemeral.keySource).toBe('ephemeral');
+    expect(await ephemeral.keyedDigest(input)).toMatch(KEYED_SHAPE);
+  });
+
+  it('a provider without key material refuses — it never falls back to an unkeyed digest', async () => {
+    // The explicit-key route is the one source that is not length-checked, so it
+    // is where an instance without usable key material can exist at all. The
+    // positive control takes the same route with a real key.
+    const control = new LocalCryptoProvider({ key: randomBytes(32) });
+    expect(await control.keyedDigest(input)).toMatch(KEYED_SHAPE);
+
+    for (const key of [Buffer.alloc(0), randomBytes(16)]) {
+      const p = new LocalCryptoProvider({ key });
+      expect(p.keySource).toBe('explicit');
+      const refusal = p.keyedDigest(input);
+      await expect(refusal).rejects.toBeInstanceOf(KeyedDigestKeyUnavailableError);
+      await expect(refusal).rejects.toMatchObject({ keyLength: key.length });
+    }
+  });
+});
+
 describe('InMemoryCryptoProvider backward-compat alias', () => {
   it('is the same class as LocalCryptoProvider', () => {
     expect(InMemoryCryptoProvider).toBe(LocalCryptoProvider);
 
@@ -5,7 +5,7 @@ import type {
   CryptoHandle,
   ICryptoProvider,
 } from '@objectstack/spec/contracts';
-import { createHash, randomBytes, createCipheriv, createDecipheriv } from 'node:crypto';
+import { createHash, createHmac, randomBytes, createCipheriv, createDecipheriv } from 'node:crypto';
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
@@ -74,6 +74,32 @@ import { dirname, join } from 'node:path';
  * ciphertext rewrapped from a different (ns, key) tuple fails decryption —
  * guards against operators accidentally copying rows between namespaces.
  *
+ * ## Keyed digest
+ * `keyedDigest(plain)` is `hmac-sha256:` + hex(HMAC-SHA-256(macKey, plain)),
+ * where `macKey` is DERIVED from the same 32-byte data key the AES path uses —
+ * whichever source resolved it above — so it needs no secret of its own:
+ *
+ *   macKey = HMAC-SHA-256(dataKey, KEYED_DIGEST_KDF_INFO || 0x01)
+ *
+ * That is RFC 5869 HKDF-Expand for one 32-byte block, with the data key as the
+ * pseudorandom key (§3.3 lets a uniformly random key skip the Extract step).
+ * The data key is never used as the MAC key directly: one key, one purpose. The
+ * AES-GCM key stays a pure encryption key, the MAC key is a separate value
+ * nobody can turn back into it, and the versioned label makes a future change
+ * of construction a deliberate, visible one rather than a silent drift. The
+ * derivation is deterministic, so every process and node that resolves the
+ * same data key computes the same digest.
+ *
+ * Only `createHmac` is used (no `hkdfSync`), so the WebContainer runtime that
+ * cannot run AES-GCM through `node:crypto` is not handed a second primitive it
+ * may lack.
+ *
+ * A provider whose data key is not 32 bytes — reachable only through an
+ * explicit `opts.key`, because every env and file source is length-checked —
+ * holds no usable key material. `keyedDigest` rejects with
+ * {@link KeyedDigestKeyUnavailableError} there; ⛔ it never falls back to an
+ * unkeyed hash, nor to an HMAC under an empty key, which anyone can compute.
+ *
  * ## WebContainer (StackBlitz) note
  * `node:crypto.createCipheriv('aes-256-gcm', …)` is not implemented in
  * WebContainer. When we detect that runtime, we swap to a pure-JS AES-GCM
@@ -94,6 +120,40 @@ const DEV_KEY_LEGACY_ENV = 'OBJECTSTACK_DEV_CRYPTO_KEY';
  */
 const AUTOKEY_ENV = 'OS_CRYPTO_AUTOKEY';
 
+/** The data key's only legal length: AES-256 needs exactly 32 bytes. */
+const DATA_KEY_BYTES = 32;
+
+/**
+ * HKDF-Expand `info` label for the keyed-digest MAC key. Versioned: changing
+ * it changes every keyed digest this provider has ever handed out, so a new
+ * construction takes a new label, never an edit of this one.
+ */
+const KEYED_DIGEST_KDF_INFO = 'objectstack/crypto-provider/keyed-digest/v1';
+
+/** HKDF-Expand's first-block input: `info || 0x01` (RFC 5869 §2.3, T(1)). */
+const KEYED_DIGEST_KDF_INPUT = Buffer.concat([Buffer.from(KEYED_DIGEST_KDF_INFO, 'utf8'), Buffer.from([0x01])]);
+
+/** Output prefix the `ICryptoProvider.keyedDigest` contract fixes. */
+const KEYED_DIGEST_PREFIX = 'hmac-sha256:';
+
+/**
+ * Rejection of {@link LocalCryptoProvider.keyedDigest} when the provider holds
+ * no usable key material. The refusal is the guarantee: a keyed digest
+ * computed without a key would be an unkeyed digest wearing a keyed name.
+ */
+export class KeyedDigestKeyUnavailableError extends Error {
+  constructor(readonly keyLength: number) {
+    super(
+      `[LocalCryptoProvider] Refusing to compute a keyed digest: the provider holds no usable key ` +
+        `material (a ${keyLength}-byte data key; exactly ${DATA_KEY_BYTES} bytes are required). ` +
+        `A digest computed without a key can be recomputed by anyone holding the input. ` +
+        `Fix: construct the provider with a ${DATA_KEY_BYTES}-byte key, or let it resolve ` +
+        `${SECRET_KEY_ENV} from the environment.`,
+    );
+    this.name = 'KeyedDigestKeyUnavailableError';
+  }
+}
+
 type EnvMap = Record<string, string | undefined>;
 
 /** Where the provider resolved its data key from (for diagnostics). */
@@ -423,6 +483,12 @@ const loadNobleGcm = (): Promise<GcmFactory | undefined> => {
 
 export class LocalCryptoProvider implements ICryptoProvider {
   private readonly key: Buffer;
+  /**
+   * The keyed-digest MAC key, derived from {@link key} (see "Keyed digest"
+   * above). `undefined` exactly when the data key is not usable key material,
+   * which is what makes `keyedDigest` refuse.
+   */
+  private readonly macKey: Buffer | undefined;
   private readonly useNoble: boolean;
   /** Where the active data key came from. Exposed for diagnostics/tests. */
   readonly keySource: KeySource;
@@ -431,6 +497,10 @@ export class LocalCryptoProvider implements ICryptoProvider {
     const resolved = resolveDataKey(opts);
     this.key = resolved.key;
     this.keySource = resolved.source;
+    this.macKey =
+      resolved.key.length === DATA_KEY_BYTES
+        ? createHmac('sha256', resolved.key).update(KEYED_DIGEST_KDF_INPUT).digest()
+        : undefined;
     this.useNoble = isWebContainerRuntime();
   }
 
@@ -501,6 +571,11 @@ export class LocalCryptoProvider implements ICryptoProvider {
     return 'sha256:' + createHash('sha256').update(plain, 'utf8').digest('hex');
   }
 
+  async keyedDigest(plain: string): Promise<string> {
+    if (!this.macKey) throw new KeyedDigestKeyUnavailableError(this.key.length);
+    return KEYED_DIGEST_PREFIX + createHmac('sha256', this.macKey).update(plain, 'utf8').digest('hex');
+  }
+
   private encryptNode(plainBytes: Buffer, iv: Buffer, aad: Buffer): string {
     const cipher = createCipheriv('aes-256-gcm', this.key, iv);
     cipher.setAAD(aad);
 
@@ -157,6 +157,41 @@ export interface ICryptoProvider {
    * reveal the plaintext (use HMAC or SHA-256 of canonical JSON).
    * Same hash for same input enables operators to detect duplicate
    * writes without exposing secrets.
+   *
+   * Not keyed by contract: plain SHA-256 satisfies it, so anyone holding a
+   * candidate input can recompute it. A value that must not be computable
+   * without the provider's key comes from {@link ICryptoProvider.keyedDigest}.
    */
   digest(plain: string): string;
+
+  /**
+   * Keyed digest of `plain` under the provider's server-held key — the
+   * primitive for a value that is handed to a caller yet must not let that
+   * caller confirm a guess about the input offline.
+   *
+   * Each of the following is a requirement on every implementation:
+   *
+   *  1. **Keyed.** The output MUST NOT be computable from `plain` without
+   *     the provider's key. An implementation that holds no key material
+   *     MUST reject — ⛔ never resolve to an unkeyed value (a plain hash of
+   *     `plain`, or a MAC under an empty or publicly known key).
+   *  2. **Stable per key.** Under one key, equal `plain` yields an equal
+   *     output in every process and on every node holding that key, so a
+   *     value one node hands out compares equal when a caller echoes it to
+   *     another. Replacing the key changes every output.
+   *  3. **Not a substitute for {@link ICryptoProvider.digest}.** `digest`
+   *     keeps its own contract and the stability the audit trail relies on;
+   *     nothing that records or compares audit digests moves to this method,
+   *     and this method is not an audit fingerprint.
+   *
+   * Output: `hmac-sha256:` followed by the 64 lowercase hex characters of an
+   * HMAC-SHA-256 — 76 characters drawn from `[0-9a-z:-]`. That one token
+   * travels unchanged in an HTTP header value, a query-string value and a
+   * JSON string, and its prefix keeps it disjoint from the `sha256:`
+   * spelling of an unkeyed content hash.
+   *
+   * Asynchronous because a managed-custody provider computes the MAC inside
+   * its KMS, where the key never leaves.
+   */
+  keyedDigest(plain: string): Promise<string>;
 }
Original file line number	Diff line number	Diff line change
`@@ -136,6 +136,7 @@ function makeFakeCrypto() {`
`136`	`136`	`return { ...handle, version: handle.version + 1 };`
`137`	`137`	`},`
`138`	`138`	digest(plain: string): string { return `d:${plain.length}`; },
	`139`	+ async keyedDigest(plain: string): Promise<string> { return `k:${plain.length}`; },
`139`	`140`	`};`
`140`	`141`	`return { provider, calls };`
`141`	`142`	`}`
Original file line number	Diff line number	Diff line change
`@@ -100,6 +100,7 @@ function makeFakeCrypto(): ICryptoProvider {`
`100`	`100`	`return { ...handle, version: handle.version + 1 };`
`101`	`101`	`},`
`102`	`102`	digest(plain: string): string { return `d:${plain.length}`; },
	`103`	+ async keyedDigest(plain: string): Promise<string> { return `k:${plain.length}`; },
`103`	`104`	`};`
`104`	`105`	`}`
`105`	`106`
Original file line number	Diff line number	Diff line change
`@@ -143,6 +143,7 @@ function makeFakeCrypto(): ICryptoProvider {`
`143`	`143`	`return { ...handle, version: handle.version + 1 };`
`144`	`144`	`},`
`145`	`145`	digest(plain: string): string { return `d:${plain.length}`; },
	`146`	+ async keyedDigest(plain: string): Promise<string> { return `k:${plain.length}`; },
`146`	`147`	`};`
`147`	`148`	`}`
`148`	`149`
Original file line number	Diff line number	Diff line change
`@@ -170,6 +170,7 @@ function makeFakeCrypto() {`
`170`	`170`	`return { ...handle, version: handle.version + 1 };`
`171`	`171`	`},`
`172`	`172`	digest(plain: string): string { return `d:${plain.length}`; },
	`173`	+ async keyedDigest(plain: string): Promise<string> { return `k:${plain.length}`; },
`173`	`174`	`};`
`174`	`175`	`return provider;`
`175`	`176`	`}`
Original file line number	Diff line number	Diff line change
`@@ -35,6 +35,7 @@ function fakeCrypto(): ICryptoProvider {`
`35`	`35`	`return handle;`
`36`	`36`	`},`
`37`	`37`	`digest: (plain: string) => 'sha256:' + plain,`
	`38`	+ keyedDigest: async (plain: string) => `k:${plain.length}`,
`38`	`39`	`};`
`39`	`40`	`}`
`40`	`41`