test(stack): add a cross-identity lock-context test (second Clerk machine)

Proves the property the single-identity tests can't: a row sealed under
identity A must not decrypt under a DIFFERENT identity B. B is a second Clerk
machine (a distinct `sub`) in the same Clerk instance, federated via a new
`CLERK_MACHINE_TOKEN_B` secret. The test decrypts A's row as A (control, must
succeed) and as B (must be denied with a key/identity error, not an infra
fault).

- clerkJwtProvider(tokenEnvVar='CLERK_MACHINE_TOKEN') is now parameterized and
  self-asserts its token (throws, never skips), so a second identity is one
  argument. The now-unused `clerk` requirement is dropped from test-kit env.
- CI: the Drizzle job passes CLERK_MACHINE_TOKEN_B (job env only, not the
  preflight — a missing B fails only the cross-identity test).

Claude-Session: https://claude.ai/code/session_01MxTTPaPP16m6br7Hoab94w

Author: coderdan

.github/workflows/integration-drizzle.yml

@@ -73,10 +73,13 @@ jobs:
       CS_CLIENT_KEY: ${{ secrets.CS_CLIENT_KEY }}
       CS_CLIENT_ACCESS_KEY: ${{ secrets.CS_CLIENT_ACCESS_KEY }}
       # The identity suites federate a freshly-minted Clerk M2M JWT into a CTS
-      # token. Only they read this; the other suites ignore it. If it is unset
-      # they fail loudly (throw, never skip) rather than taking the whole job
-      # down, so it is NOT part of the require-cs-secrets preflight.
+      # token. Only they read these; the other suites ignore them. If one is
+      # unset the relevant suite fails loudly (throw, never skip) rather than
+      # taking the whole job down, so they are NOT in the require-cs-secrets
+      # preflight. `_B` is a SECOND machine (a distinct `sub`) in the same Clerk
+      # instance, used only by the cross-identity test.
       CLERK_MACHINE_TOKEN: ${{ secrets.CLERK_MACHINE_TOKEN }}
+      CLERK_MACHINE_TOKEN_B: ${{ secrets.CLERK_MACHINE_TOKEN_B }}
       # Job-level env, not a `.env` file: `dotenv/config` does not override an
       # already-set `process.env`, so these win and no secret is written to disk.
       DATABASE_URL: ${{ matrix.database-url }}

packages/stack/integration/helpers/clerk.ts

@@ -1,4 +1,3 @@
-import { requireIntegrationEnv } from '@cipherstash/test-kit'
 import { createClerkClient } from '@clerk/backend'
 
 /**
@@ -11,17 +10,27 @@ import { createClerkClient } from '@clerk/backend'
  * in an env var or a CI secret. The only secret is `CLERK_MACHINE_TOKEN`, a
  * rotatable machine key.
  *
- * The federated identity is the Clerk machine (`CTS|CS|mch_…`), which is stable
- * across encrypt and decrypt — enough for the symmetric round-trip and the
- * no-context negative path. The cross-identity test needs a SECOND machine
- * token (a distinct `sub`) and remains a follow-up.
+ * The federated identity is the Clerk machine (`CTS|CS|mch_…`), stable across
+ * encrypt and decrypt. Pass a different `tokenEnvVar` (e.g. a second machine's
+ * `CLERK_MACHINE_TOKEN_B`) to federate as a DISTINCT identity — that is what the
+ * cross-identity test uses to prove a row sealed under one machine does not
+ * decrypt under another.
  *
  * The workspace named by `CS_WORKSPACE_CRN` must have this Clerk instance
  * registered on its OIDC-providers page, or `/api/authorise` rejects the token.
  */
-export function clerkJwtProvider(): () => Promise<string> {
-  requireIntegrationEnv(['clerk'])
-  const machineSecretKey = process.env['CLERK_MACHINE_TOKEN'] as string
+export function clerkJwtProvider(
+  tokenEnvVar = 'CLERK_MACHINE_TOKEN',
+): () => Promise<string> {
+  const machineSecretKey = process.env[tokenEnvVar]
+  if (!machineSecretKey) {
+    throw new Error(
+      `Integration suite cannot run — missing ${tokenEnvVar} (a Clerk machine ` +
+        'secret key, ak_...). Its Clerk instance must be registered on the ' +
+        'CS_WORKSPACE_CRN workspace OIDC-providers page. This suite FAILS rather ' +
+        'than skips: a green skip would hide a real regression.',
+    )
+  }
 
   // `createToken` authenticates with `machineSecretKey`; `createClerkClient`
   // still wants a `secretKey` string at construction that this path never uses.

packages/stack/integration/identity/lock-context.integration.test.ts

@@ -27,9 +27,10 @@
  * insufficient: they drop the context identically on both sides, so they stay
  * green even if it were ignored entirely.
  *
- * A cross-identity non-match (sealed under A, queried under B) still needs a
- * second JWT with a different `sub` — a lock context only names the claim while
- * ZeroKMS resolves its value from the authenticating token. Tracked separately.
+ * The cross-identity non-match (sealed under A, decrypted under B) is covered by
+ * the final test: it federates a SECOND Clerk machine (`CLERK_MACHINE_TOKEN_B`,
+ * a distinct `sub`) and asserts B cannot read A's row, with A reading it as the
+ * control.
  */
 import { OidcFederationStrategy } from '@cipherstash/auth'
 import { databaseUrl, V3_MATRIX } from '@cipherstash/test-kit'
@@ -240,11 +241,11 @@ describe('v3 drizzle operators with lock context (live pg)', () => {
   // assumed they were and asserted `[]`; this is corrected to the OBSERVED
   // behaviour, with the real boundary proven by the decryption test.
   //
-  // A true CROSS-identity proof (sealed under A, queried under B) needs a
+  // The true CROSS-identity proof (sealed under A, decrypted under B) needs a
   // SECOND machine identity with a different `sub`; the lock context only names
   // the claim (`['sub']`) while ZeroKMS resolves its value from the
-  // authenticating token. Only one Clerk machine token is wired up, so that
-  // remains a follow-up.
+  // authenticating token. That is the final test in this suite, federating
+  // `CLERK_MACHINE_TOKEN_B`.
   it('an eq matches the same row with or without a lock context (search is not identity-bound)', async () => {
     const bound = await ops.eq(secretTable.secret, SECRET_A, {
       lockContext: IDENTITY_CLAIM as never,
@@ -300,4 +301,54 @@ describe('v3 drizzle operators with lock context (live pg)', () => {
     expect(message).toMatch(IDENTITY_DENIAL)
     expect(message).not.toMatch(INFRA_FAULT)
   }, 30000)
+
+  // The true cross-identity proof: same `['sub']` claim, a DIFFERENT
+  // authenticating machine. Everything above uses one identity, so it cannot
+  // tell "bound to A" from "bound to nothing" — this can. Machine B must be a
+  // distinct machine (its own `sub`) in the same Clerk instance registered on
+  // the workspace; `clerkJwtProvider('CLERK_MACHINE_TOKEN_B')` throws if that
+  // token is unset, so this fails loudly rather than skipping.
+  it('a row sealed under identity A does not decrypt under a different identity (B)', async () => {
+    const crn = process.env.CS_WORKSPACE_CRN as string
+    const federationB = OidcFederationStrategy.create(
+      crn,
+      clerkJwtProvider('CLERK_MACHINE_TOKEN_B'),
+    )
+    if (federationB.failure) {
+      throw new Error(`[federation B]: ${federationB.failure.message}`)
+    }
+    const clientB = await EncryptionV3({
+      schemas: [schema],
+      config: { authStrategy: federationB.data },
+    })
+
+    const [row] = await sqlClient.unsafe<Array<{ value: unknown }>>(
+      `SELECT secret::jsonb AS value FROM ${TABLE_NAME}
+         WHERE test_run_id = $1 AND row_key = $2`,
+      [RUN, ROW_A],
+    )
+    expect(row).toBeDefined()
+
+    // Control: identity A reads its own row. If this is denied, A's federation
+    // or the fixture is broken and the cross-identity assertion below would
+    // "pass" for the wrong reason.
+    const asA = await decryptOutcome(() =>
+      client.decrypt(row.value as never).withLockContext(IDENTITY_CLAIM),
+    )
+    expect(
+      asA.denied,
+      `identity A must read its own row (got: ${asA.message})`,
+    ).toBe(false)
+
+    // Cross-identity: B names the same `['sub']` claim, but its value is B's
+    // machine, so ZeroKMS cannot reproduce A's key.
+    const asB = await decryptOutcome(() =>
+      clientB.decrypt(row.value as never).withLockContext(IDENTITY_CLAIM),
+    )
+    expect(asB.denied, 'identity B must NOT decrypt a row sealed under A').toBe(
+      true,
+    )
+    expect(asB.message).toMatch(IDENTITY_DENIAL)
+    expect(asB.message).not.toMatch(INFRA_FAULT)
+  }, 30000)
 })

packages/test-kit/src/env.ts

@@ -12,7 +12,7 @@ import { join } from 'node:path'
  * to fix it.
  */
 
-export type Requirement = 'cipherstash' | 'database' | 'pgrest' | 'clerk'
+export type Requirement = 'cipherstash' | 'database' | 'pgrest'
 
 /** Every variable protect-ffi's `AutoStrategy` needs to authenticate from the environment. */
 const CS_VARS = [
@@ -87,16 +87,6 @@ const HINTS: Record<Requirement, () => string | null> = {
       : 'PGRST_URL. The Supabase adapter speaks PostgREST, not Postgres:\n' +
         '      docker compose -f local/docker-compose.supabase.yml up -d --wait\n' +
         '      export PGRST_URL=http://localhost:55430',
-
-  clerk: () =>
-    process.env['CLERK_MACHINE_TOKEN']
-      ? null
-      : 'CLERK_MACHINE_TOKEN. The identity / lock-context suites federate a\n' +
-        '    freshly-minted Clerk machine (M2M) JWT into a CTS token, so they need\n' +
-        "    the machine's secret key (ak_...):\n" +
-        '      export CLERK_MACHINE_TOKEN=ak_...\n' +
-        '    The CS_WORKSPACE_CRN workspace must have that Clerk instance registered\n' +
-        '    on its OIDC-providers page.',
 }
 
 /**