test(service-settings,objectql,service-datasource,cli): pin the scoped, versioned AAD and each producer's scope

Claude-Session: https://claude.ai/code/session_01YDt3PzwfrkuFzUBF89WPmM
Co-authored-by: Claude <noreply@anthropic.com>

Author: claude

packages/cli/src/utils/secret-reference-union.test.ts

@@ -214,6 +214,7 @@ async function buildRuntime() {
 
   // --- family 1: a settings handle, minted by the real provider -------------
   const settingsHandle = await crypto.encrypt('smtp-app-password', {
+    scope: 'settings',
     namespace: 'smtp',
     key: 'password',
   });

packages/cli/src/utils/sys-secret-orphan-sweep.test.ts

@@ -217,7 +217,7 @@ async function buildRuntime() {
   };
 
   // --- family 1: a settings handle, minted by the real provider, IN FORCE ---
-  const settingsHandle = await crypto.encrypt('smtp-app-password', { namespace: 'smtp', key: 'password' });
+  const settingsHandle = await crypto.encrypt('smtp-app-password', { scope: 'settings', namespace: 'smtp', key: 'password' });
   seedSecret(settingsHandle, 'smtp', 'password');
   store.seed('sys_setting', {
     id: 'set_1', namespace: 'smtp', key: 'password', scope: 'tenant', user_id: null,
@@ -229,7 +229,7 @@ async function buildRuntime() {
   // deliberately not referenced by any sys_setting row. This is the one class
   // the ruling permits deleting, and it is what keeps every "deletable is
   // empty" assertion below falsifiable.
-  const orphanHandle = await crypto.encrypt('rotated-away-token', { namespace: 'smtp', key: 'retired_token' });
+  const orphanHandle = await crypto.encrypt('rotated-away-token', { scope: 'settings', namespace: 'smtp', key: 'retired_token' });
   seedSecret(orphanHandle, 'smtp', 'retired_token');
 
   // --- family 2: the engine's own secret-field channel, LIVE ---------------
@@ -428,7 +428,7 @@ describe('the classes the ruling puts out of reach', () => {
   });
 
   it('a LEGACY INLINE sibling is withheld — the #8063 guard in the opposite direction', async () => {
-    const inlineHandle = await rt.crypto.encrypt('older-inline', { namespace: 'smtp', key: 'inline_legacy' });
+    const inlineHandle = await rt.crypto.encrypt('older-inline', { scope: 'settings', namespace: 'smtp', key: 'inline_legacy' });
     rt.store.seed('sys_secret', {
       id: inlineHandle.id, namespace: 'smtp', key: 'inline_legacy',
       kms_key_id: inlineHandle.kmsKeyId, alg: inlineHandle.alg,
@@ -557,7 +557,7 @@ describe('the mandatory pre-delete export', () => {
 describe('the handle predicate comes from the producer', () => {
   it('agrees with a handle minted by the real LocalCryptoProvider', async () => {
     const crypto = new LocalCryptoProvider({ mode: 'test' });
-    const handle = await crypto.encrypt('x', { namespace: 'smtp', key: 'password' });
+    const handle = await crypto.encrypt('x', { scope: 'settings', namespace: 'smtp', key: 'password' });
     expect(isSecretHandle(handle.id)).toBe(true);
     // A legacy inline value is not a handle — the discriminator the guard rests on.
     expect(isSecretHandle('AQIDBAUGBwgJCg==')).toBe(false);

packages/objectql/src/secret-fields.test.ts

@@ -116,9 +116,12 @@ function makeStubDriver() {
 function makeFakeCrypto() {
   let n = 0;
   const calls: { encrypt: number; decrypt: number } = { encrypt: 0, decrypt: 0 };
+  /** Every context the engine handed the provider, per verb (ADR-0128 D1 pin). */
+  const contexts: { encrypt: CryptoContext[]; decrypt: CryptoContext[] } = { encrypt: [], decrypt: [] };
   const provider: ICryptoProvider = {
-    async encrypt(plain: string, _ctx: CryptoContext): Promise<CryptoHandle> {
+    async encrypt(plain: string, ctx: CryptoContext): Promise<CryptoHandle> {
       calls.encrypt += 1;
+      contexts.encrypt.push(ctx);
       n += 1;
       return {
         id: `sec_${n}`,
@@ -128,8 +131,9 @@ function makeFakeCrypto() {
         ciphertext: Buffer.from(plain, 'utf8').toString('base64'),
       };
     },
-    async decrypt(handle: CryptoHandle, _ctx: CryptoContext): Promise<string> {
+    async decrypt(handle: CryptoHandle, ctx: CryptoContext): Promise<string> {
       calls.decrypt += 1;
+      contexts.decrypt.push(ctx);
       return Buffer.from(handle.ciphertext, 'base64').toString('utf8');
     },
     async rotateKey(handle: CryptoHandle): Promise<CryptoHandle> {
@@ -138,7 +142,7 @@ function makeFakeCrypto() {
     digest(plain: string): string { return `d:${plain.length}`; },
     async keyedDigest(plain: string): Promise<string> { return `k:${plain.length}`; },
   };
-  return { provider, calls };
+  return { provider, calls, contexts };
 }
 
 const sysSecretObject = {
@@ -237,6 +241,21 @@ describe('objectql secret-field channel', () => {
     expect(ctx.crypto.calls.decrypt).toBe(1);
   });
 
+  it('seals and dereferences under its own scope, object_secret_field (ADR-0128 D1)', async () => {
+    const created = await ctx.engine.insert('ext_datasource', { name: 'pg', db_password: 's3cr3t' });
+    const stored = ctx.stores.get('ext_datasource')!.get(created.id) as any;
+    await ctx.engine.resolveSecret(stored.db_password);
+    await ctx.engine.resolveSecretField('ext_datasource', String(created.id), 'db_password');
+
+    expect(ctx.crypto.contexts.encrypt).toEqual([
+      expect.objectContaining({ scope: 'object_secret_field', namespace: 'ext_datasource', key: 'db_password' }),
+    ]);
+    expect(ctx.crypto.contexts.decrypt).toHaveLength(2);
+    for (const opened of ctx.crypto.contexts.decrypt) {
+      expect(opened).toMatchObject({ scope: 'object_secret_field', namespace: 'ext_datasource', key: 'db_password' });
+    }
+  });
+
   // [#6231] `resolveSecret` reads `sys_secret` straight off the driver. That
   // call used to spell `{ object: 'sys_secret', where: { id } } as QueryAST`,
   // where the cast existed only to satisfy the AST's then-required `object`.

packages/services/service-datasource/src/__tests__/datasource-secret-binder.test.ts

@@ -10,25 +10,28 @@ import {
 } from '../datasource-secret-binder.js';
 
 /**
- * Minimal AAD-binding crypto fake: ciphertext = base64(`${ns}|${key}::${plain}`).
- * decrypt() verifies the (namespace,key) AAD matches what encrypt() sealed —
- * mirroring InMemoryCryptoProvider's guarantee without pulling in node:crypto.
+ * Minimal AAD-binding crypto fake: ciphertext = base64(JSON([aad, plain])), where
+ * the AAD is the structured triple `[scope, namespace, key]`. decrypt() verifies
+ * the triple matches what encrypt() sealed — mirroring LocalCryptoProvider's
+ * producer-discriminated guarantee (ADR-0128 D1) without pulling in node:crypto.
  */
-function fakeCrypto(): ICryptoProvider {
+function fakeCrypto(seen: CryptoContext[] = []): ICryptoProvider {
+  const aadOf = (ctx: CryptoContext) => JSON.stringify([ctx.scope, ctx.namespace, ctx.key]);
   return {
     async encrypt(plain: string, ctx: CryptoContext): Promise<CryptoHandle> {
+      seen.push(ctx);
       return {
         id: 'sec_' + ctx.key,
         kmsKeyId: 'local:test:v1',
         alg: 'aes-256-gcm',
         version: 1,
-        ciphertext: Buffer.from(`${ctx.namespace}|${ctx.key}::${plain}`, 'utf8').toString('base64'),
+        ciphertext: Buffer.from(JSON.stringify([aadOf(ctx), plain]), 'utf8').toString('base64'),
       };
     },
     async decrypt(handle: CryptoHandle, ctx: CryptoContext): Promise<string> {
-      const raw = Buffer.from(handle.ciphertext, 'base64').toString('utf8');
-      const [aad, plain] = raw.split('::');
-      if (aad !== `${ctx.namespace}|${ctx.key}`) throw new Error('AAD mismatch');
+      seen.push(ctx);
+      const [aad, plain] = JSON.parse(Buffer.from(handle.ciphertext, 'base64').toString('utf8'));
+      if (aad !== aadOf(ctx)) throw new Error('AAD mismatch');
       return plain;
     },
     async rotateKey(handle: CryptoHandle): Promise<CryptoHandle> {
@@ -77,6 +80,40 @@ describe('createDatasourceSecretBinder', () => {
     expect(await binder.resolve(ref)).toBe('super-secret-pw');
   });
 
+  it('binds and resolves under its own scope, datasource_credential (ADR-0128 D1)', async () => {
+    const engine = fakeEngine();
+    const seen: CryptoContext[] = [];
+    const binder = createDatasourceSecretBinder({ engine, cryptoProvider: fakeCrypto(seen) });
+
+    const ref = await binder.bind({ value: 'pw' }, { name: 'reporting' });
+    expect(await binder.resolve(ref)).toBe('pw');
+    expect(seen).toEqual([
+      { scope: 'datasource_credential', namespace: 'datasource', key: 'reporting' },
+      { scope: 'datasource_credential', namespace: 'datasource', key: 'reporting' },
+    ]);
+  });
+
+  it('does not resolve a row another producer sealed, even at the same (namespace, key)', async () => {
+    const engine = fakeEngine();
+    const crypto = fakeCrypto();
+    const binder = createDatasourceSecretBinder({ engine, cryptoProvider: crypto });
+    // A row at this binder's own coordinate, sealed under a different scope.
+    const foreign = await crypto.encrypt('pw', { scope: 'settings', namespace: 'datasource', key: 'reporting' });
+    await engine.insert('sys_secret', {
+      id: foreign.id,
+      namespace: 'datasource',
+      key: 'reporting',
+      kms_key_id: foreign.kmsKeyId,
+      alg: foreign.alg,
+      version: foreign.version,
+      ciphertext: foreign.ciphertext,
+    });
+    expect(await binder.resolve(toCredentialsRef(foreign.id))).toBeUndefined();
+    // Positive control: the binder's own seal at the same coordinate resolves.
+    const own = await binder.bind({ value: 'pw' }, { name: 'reporting' });
+    expect(await binder.resolve(own)).toBe('pw');
+  });
+
   it('resolve() returns undefined after unbind (row gone)', async () => {
     const engine = fakeEngine();
     const binder = createDatasourceSecretBinder({ engine, cryptoProvider: fakeCrypto() });

packages/services/service-settings/src/local-crypto-provider.test.ts

@@ -5,13 +5,22 @@ import { mkdtempSync, mkdirSync, rmSync, writeFileSync, existsSync } from 'node:
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { createHash, createHmac, randomBytes } from 'node:crypto';
+import {
+  CRYPTO_CONTEXT_SCOPES,
+  type CryptoContext,
+  type CryptoContextScope,
+  type CryptoHandle,
+} from '@objectstack/spec/contracts';
 import {
   LocalCryptoProvider,
   InMemoryCryptoProvider,
   KeyedDigestKeyUnavailableError,
+  CryptoContextScopeError,
+  UnknownCiphertextVersionError,
+  aadForVersion2,
 } from './local-crypto-provider.js';
 
-const ctx = { namespace: 'mail', key: 'api_key' };
+const ctx: CryptoContext = { scope: 'settings', namespace: 'mail', key: 'api_key' };
 
 describe('LocalCryptoProvider — key resolution', () => {
   let home: string;
@@ -131,9 +140,9 @@ describe('LocalCryptoProvider — key resolution', () => {
 describe('LocalCryptoProvider — crypto semantics', () => {
   it('AAD binding rejects ciphertexts swapped across (namespace,key)', async () => {
     const p = new LocalCryptoProvider({ key: randomBytes(32) });
-    const handle = await p.encrypt('value', { namespace: 'mail', key: 'api_key' });
+    const handle = await p.encrypt('value', { scope: 'settings', namespace: 'mail', key: 'api_key' });
     await expect(
-      p.decrypt(handle, { namespace: 'mail', key: 'smtp_password' }),
+      p.decrypt(handle, { scope: 'settings', namespace: 'mail', key: 'smtp_password' }),
     ).rejects.toThrow();
   });
 
@@ -155,6 +164,184 @@ describe('LocalCryptoProvider — crypto semantics', () => {
   });
 });
 
+/**
+ * ADR-0128 D1–D3 — the AAD is producer-discriminated (D1), delimiter-safe
+ * (D2), built at the producer of the AAD with no consumer-side fallback (D3),
+ * and every ciphertext records the derivation that sealed it.
+ */
+describe('LocalCryptoProvider — scoped, versioned AAD (ADR-0128)', () => {
+  /** A fixed data key for the pinned vectors (bytes 0x00..0x1f). */
+  const PINNED_KEY = Buffer.from('000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f', 'hex');
+
+  /**
+   * Sealed by the provider as it stood BEFORE derivations were versioned
+   * (`origin/main` at 3a6d92f78b), under `PINNED_KEY`, for
+   * `('legacy_ns', 'legacy_key')`. It is the shape every handle already at
+   * rest has: bare base64, no marker.
+   */
+  const LEGACY_HANDLE: CryptoHandle = {
+    id: 'sec_0cab6d627ca4a3e44ee65398eb7f5a74',
+    kmsKeyId: 'local:v1',
+    alg: 'aes-256-gcm',
+    version: 1,
+    ciphertext: '3k1P9mqvLWg6LImhxsapht2tMnc7FTBzcM55GwNJxZVLooqJ8oPHsG8bb3DttWZrP0S/Ug==',
+  };
+  const LEGACY_PLAIN = 'sealed-before-versioning';
+
+  /** Sealed by this derivation under `PINNED_KEY` — pins it against drift. */
+  const V2_HANDLE: CryptoHandle = {
+    id: 'sec_54a8311e4159cef5d286af80f028e727',
+    kmsKeyId: 'local:v1',
+    alg: 'aes-256-gcm',
+    version: 1,
+    ciphertext: 'v2:SNo5hjab0WpiNk/LLEwVv7OslY4okZxLjKGFi7mbc9CnTqNT/pxIBtZ6rRdKj4iS8P0=',
+  };
+  const V2_CTX: CryptoContext = { scope: 'settings', namespace: 'pinned_ns', key: 'pinned_key' };
+  const V2_PLAIN = 'sealed-under-version-2';
+
+  const at = (scope: CryptoContextScope, namespace = 'same_ns', key = 'same_key'): CryptoContext => ({
+    scope,
+    namespace,
+    key,
+  });
+
+  it('seals every new ciphertext under the version-2 marker', async () => {
+    const p = new LocalCryptoProvider({ key: randomBytes(32) });
+    for (const scope of CRYPTO_CONTEXT_SCOPES) {
+      const h = await p.encrypt('x', at(scope));
+      expect(h.ciphertext.startsWith('v2:')).toBe(true);
+      expect(h.ciphertext.slice(3)).toMatch(/^[A-Za-z0-9+/]+=*$/);
+      expect(await p.decrypt(h, at(scope))).toBe('x');
+    }
+  });
+
+  it('opens a handle sealed before versioning with the derivation it was sealed with', async () => {
+    // The pre-versioning blob is bare base64, which has no `:` — so it reads
+    // as version 1 without any row being consulted.
+    expect(LEGACY_HANDLE.ciphertext).not.toContain(':');
+    const p = new LocalCryptoProvider({ key: PINNED_KEY });
+    expect(
+      await p.decrypt(LEGACY_HANDLE, { scope: 'settings', namespace: 'legacy_ns', key: 'legacy_key' }),
+    ).toBe(LEGACY_PLAIN);
+    // Version 1 still binds its (namespace, key): another coordinate fails.
+    await expect(
+      p.decrypt(LEGACY_HANDLE, { scope: 'settings', namespace: 'legacy_ns', key: 'other_key' }),
+    ).rejects.toThrow();
+  });
+
+  it('opens a version-1 handle without binding the scope — the older guarantee, until re-wrapped', async () => {
+    // Version 1 never had a scope, so it cannot bind one; this is the weaker
+    // guarantee CryptoContext documents for pre-versioning ciphertext.
+    const p = new LocalCryptoProvider({ key: PINNED_KEY });
+    for (const scope of CRYPTO_CONTEXT_SCOPES) {
+      expect(await p.decrypt(LEGACY_HANDLE, at(scope, 'legacy_ns', 'legacy_key'))).toBe(LEGACY_PLAIN);
+    }
+  });
+
+  it('opens a pinned version-2 vector, so the derivation cannot drift under sealed data', async () => {
+    const p = new LocalCryptoProvider({ key: PINNED_KEY });
+    expect(await p.decrypt(V2_HANDLE, V2_CTX)).toBe(V2_PLAIN);
+  });
+
+  it('pins the version-2 AAD bytes: lead byte, label, then each component length-prefixed', () => {
+    const aad = aadForVersion2({ scope: 'datasource_credential', namespace: 'datasource', key: 'reporting' });
+    expect(aad.toString('hex')).toBe(
+      'ff' +
+        Buffer.from('objectstack/crypto-context-aad/v2', 'utf8').toString('hex') +
+        '00000015' + Buffer.from('datasource_credential', 'utf8').toString('hex') +
+        '0000000a' + Buffer.from('datasource', 'utf8').toString('hex') +
+        '00000009' + Buffer.from('reporting', 'utf8').toString('hex'),
+    );
+    expect(aad.toString('hex')).toBe(
+      'ff6f626a656374737461636b2f63727970746f2d636f6e746578742d6161642f76320000001564617461736f757263655f63726564656e7469616c0000000a64617461736f75726365000000097265706f7274696e67',
+    );
+  });
+
+  it('D1: a ciphertext sealed under one scope does not open under any other, for the same (namespace, key)', async () => {
+    const p = new LocalCryptoProvider({ key: randomBytes(32) });
+    for (const sealedAs of CRYPTO_CONTEXT_SCOPES) {
+      const h = await p.encrypt('scoped', at(sealedAs));
+      for (const openedAs of CRYPTO_CONTEXT_SCOPES) {
+        if (openedAs === sealedAs) {
+          expect(await p.decrypt(h, at(openedAs))).toBe('scoped');
+        } else {
+          await expect(p.decrypt(h, at(openedAs))).rejects.toThrow();
+        }
+      }
+    }
+  });
+
+  it('D2: two contexts whose unescaped join collides produce different AAD bytes and do not open each other', async () => {
+    const left: CryptoContext = { scope: 'settings', namespace: 'a|b', key: 'c' };
+    const right: CryptoContext = { scope: 'settings', namespace: 'a', key: 'b|c' };
+    // The collision vector: an unescaped join cannot tell these apart.
+    expect([left.scope, left.namespace, left.key].join('|')).toBe(
+      [right.scope, right.namespace, right.key].join('|'),
+    );
+    expect(aadForVersion2(left).equals(aadForVersion2(right))).toBe(false);
+
+    const p = new LocalCryptoProvider({ key: randomBytes(32) });
+    const sealedLeft = await p.encrypt('left', left);
+    const sealedRight = await p.encrypt('right', right);
+    await expect(p.decrypt(sealedLeft, right)).rejects.toThrow();
+    await expect(p.decrypt(sealedRight, left)).rejects.toThrow();
+    expect(await p.decrypt(sealedLeft, left)).toBe('left');
+    expect(await p.decrypt(sealedRight, right)).toBe('right');
+  });
+
+  it('refuses a derivation it does not know — fail closed, nothing else is tried', async () => {
+    const p = new LocalCryptoProvider({ key: PINNED_KEY });
+    const unknown = { ...V2_HANDLE, ciphertext: 'v3:' + V2_HANDLE.ciphertext.slice(3) };
+    const refusal = p.decrypt(unknown, V2_CTX);
+    await expect(refusal).rejects.toBeInstanceOf(UnknownCiphertextVersionError);
+    await expect(refusal).rejects.toMatchObject({ marker: 'v3' });
+    // Positive control: the same body under its own marker opens.
+    expect(await p.decrypt(V2_HANDLE, V2_CTX)).toBe(V2_PLAIN);
+  });
+
+  it('a ciphertext presented under the other derivation never authenticates', async () => {
+    const p = new LocalCryptoProvider({ key: PINNED_KEY });
+    // A version-2 body with its marker removed reads as version 1 and fails.
+    const stripped = { ...V2_HANDLE, ciphertext: V2_HANDLE.ciphertext.slice(3) };
+    await expect(p.decrypt(stripped, V2_CTX)).rejects.toThrow();
+    // A version-1 body with a version-2 marker added fails.
+    const relabelled = { ...LEGACY_HANDLE, ciphertext: 'v2:' + LEGACY_HANDLE.ciphertext };
+    await expect(
+      p.decrypt(relabelled, { scope: 'settings', namespace: 'legacy_ns', key: 'legacy_key' }),
+    ).rejects.toThrow();
+  });
+
+  it('rotateKey re-wraps a version-1 handle under version 2, bound to the scope', async () => {
+    const p = new LocalCryptoProvider({ key: PINNED_KEY });
+    const sealedFor = at('settings', 'legacy_ns', 'legacy_key');
+    const rotated = await p.rotateKey(LEGACY_HANDLE, sealedFor);
+    expect(rotated.id).toBe(LEGACY_HANDLE.id);
+    expect(rotated.version).toBe(LEGACY_HANDLE.version + 1);
+    expect(rotated.ciphertext.startsWith('v2:')).toBe(true);
+    expect(await p.decrypt(rotated, sealedFor)).toBe(LEGACY_PLAIN);
+    await expect(p.decrypt(rotated, at('object_secret_field', 'legacy_ns', 'legacy_key'))).rejects.toThrow();
+  });
+
+  it('refuses a context without a member of the closed scope set, on every entry point', async () => {
+    const p = new LocalCryptoProvider({ key: randomBytes(32) });
+    const sealed = await p.encrypt('x', at('settings'));
+    const invalid = [
+      { namespace: 'same_ns', key: 'same_key' },
+      { scope: 'setting', namespace: 'same_ns', key: 'same_key' },
+      { scope: '', namespace: 'same_ns', key: 'same_key' },
+    ] as unknown as CryptoContext[];
+    for (const bad of invalid) {
+      await expect(p.encrypt('x', bad)).rejects.toBeInstanceOf(CryptoContextScopeError);
+      await expect(p.decrypt(sealed, bad)).rejects.toBeInstanceOf(CryptoContextScopeError);
+      await expect(p.decrypt(LEGACY_HANDLE, bad)).rejects.toBeInstanceOf(CryptoContextScopeError);
+      await expect(p.rotateKey(sealed, bad)).rejects.toBeInstanceOf(CryptoContextScopeError);
+    }
+    // Positive control: the same calls with a member succeed.
+    expect(await p.decrypt(sealed, at('settings'))).toBe('x');
+    expect((await p.rotateKey(sealed, at('settings'))).ciphertext.startsWith('v2:')).toBe(true);
+  });
+});
+
 describe('LocalCryptoProvider — keyedDigest', () => {
   const KEYED_SHAPE = /^hmac-sha256:[0-9a-f]{64}$/;
   const input = 'sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a';