@open-mercato/shared 0.6.5-develop.5048.1.fd82f4ae17 → 0.6.5-develop.5116.1.f0af9e5080

package/src/lib/commands/scope.ts

@@ -1,44 +1,69 @@
 import { CrudHttpError } from '@open-mercato/shared/lib/crud/errors'
 import type { CommandRuntimeContext } from '@open-mercato/shared/lib/commands'
 import { isOrganizationAccessAllowed } from '@open-mercato/shared/lib/auth/organizationAccess'
+import { parseBooleanWithDefault } from '@open-mercato/shared/lib/boolean'
 import { env } from 'process'
 
+function buildScopeLogContext(ctx: CommandRuntimeContext) {
+  const requestInfo =
+    ctx.request && typeof ctx.request === 'object'
+      ? {
+          method: (ctx.request as Request).method ?? undefined,
+          url: (ctx.request as Request).url ?? undefined,
+        }
+      : null
+  const scope = ctx.organizationScope
+    ? {
+        selectedId: ctx.organizationScope.selectedId ?? null,
+        tenantId: ctx.organizationScope.tenantId ?? null,
+        allowedIdsCount: Array.isArray(ctx.organizationScope.allowedIds)
+          ? ctx.organizationScope.allowedIds.length
+          : null,
+        filterIdsCount: Array.isArray(ctx.organizationScope.filterIds)
+          ? ctx.organizationScope.filterIds.length
+          : null,
+      }
+    : null
+  return {
+    userId: ctx.auth?.sub ?? null,
+    actorTenantId: ctx.auth?.tenantId ?? null,
+    actorOrganizationId: ctx.auth?.orgId ?? null,
+    selectedOrganizationId: ctx.selectedOrganizationId ?? null,
+    organizationIdsCount: Array.isArray(ctx.organizationIds) ? ctx.organizationIds.length : null,
+    scope,
+    request: requestInfo,
+  }
+}
+
+function isStrictOrganizationScopeEnforced(): boolean {
+  return parseBooleanWithDefault(env.OM_ENFORCE_ORG_SCOPE_STRICT, false)
+}
+
 function logScopeViolation(
   ctx: CommandRuntimeContext,
   expected: string,
   actual: string | null
 ): void {
   try {
-    const requestInfo =
-      ctx.request && typeof ctx.request === 'object'
-        ? {
-            method: (ctx.request as Request).method ?? undefined,
-            url: (ctx.request as Request).url ?? undefined,
-          }
-        : null
-    const scope = ctx.organizationScope
-      ? {
-          selectedId: ctx.organizationScope.selectedId ?? null,
-          tenantId: ctx.organizationScope.tenantId ?? null,
-          allowedIdsCount: Array.isArray(ctx.organizationScope.allowedIds)
-            ? ctx.organizationScope.allowedIds.length
-            : null,
-          filterIdsCount: Array.isArray(ctx.organizationScope.filterIds)
-            ? ctx.organizationScope.filterIds.length
-            : null,
-        }
-      : null
     if (env.NODE_ENV !== 'test') {
       console.warn('[scope] Forbidden organization scope mismatch detected', {
         expectedId: expected,
         actualId: actual,
-        userId: ctx.auth?.sub ?? null,
-        actorTenantId: ctx.auth?.tenantId ?? null,
-        actorOrganizationId: ctx.auth?.orgId ?? null,
-        selectedOrganizationId: ctx.selectedOrganizationId ?? null,
-        organizationIdsCount: Array.isArray(ctx.organizationIds) ? ctx.organizationIds.length : null,
-        scope,
-        request: requestInfo,
+        ...buildScopeLogContext(ctx),
+      })
+    }
+  } catch {
+    // best-effort logging
+  }
+}
+
+function logUnscopedOrganizationAccess(ctx: CommandRuntimeContext, organizationId: string): void {
+  try {
+    if (env.NODE_ENV !== 'test') {
+      console.warn('[scope] Unscoped organization command executed without organization context', {
+        targetOrganizationId: organizationId,
+        strictEnforcement: isStrictOrganizationScopeEnforced(),
+        ...buildScopeLogContext(ctx),
       })
     }
   } catch {
@@ -52,36 +77,11 @@ function logTenantScopeViolation(
   actualTenantId: string | null
 ): void {
   try {
-    const requestInfo =
-      ctx.request && typeof ctx.request === 'object'
-        ? {
-            method: (ctx.request as Request).method ?? undefined,
-            url: (ctx.request as Request).url ?? undefined,
-          }
-        : null
-    const scope = ctx.organizationScope
-      ? {
-          selectedId: ctx.organizationScope.selectedId ?? null,
-          tenantId: ctx.organizationScope.tenantId ?? null,
-          allowedIdsCount: Array.isArray(ctx.organizationScope.allowedIds)
-            ? ctx.organizationScope.allowedIds.length
-            : null,
-          filterIdsCount: Array.isArray(ctx.organizationScope.filterIds)
-            ? ctx.organizationScope.filterIds.length
-            : null,
-        }
-      : null
     if (env.NODE_ENV !== 'test') {
       console.warn('[scope] Forbidden tenant scope mismatch detected', {
         expectedTenantId,
         actualTenantId,
-        userId: ctx.auth?.sub ?? null,
-        actorTenantId: ctx.auth?.tenantId ?? null,
-        actorOrganizationId: ctx.auth?.orgId ?? null,
-        selectedOrganizationId: ctx.selectedOrganizationId ?? null,
-        organizationIdsCount: Array.isArray(ctx.organizationIds) ? ctx.organizationIds.length : null,
-        scope,
-        request: requestInfo,
+        ...buildScopeLogContext(ctx),
       })
     }
   } catch {
@@ -100,9 +100,24 @@ export function ensureOrganizationScope(ctx: CommandRuntimeContext, organization
   if (!scope) {
     if (isSuperAdmin) return
     const currentOrg = ctx.selectedOrganizationId ?? ctx.auth?.orgId ?? null
-    if (currentOrg && currentOrg !== organizationId) {
-      logScopeViolation(ctx, organizationId, currentOrg)
-      throw new CrudHttpError(403, { error: 'Forbidden' })
+    if (currentOrg) {
+      if (currentOrg !== organizationId) {
+        logScopeViolation(ctx, organizationId, currentOrg)
+        throw new CrudHttpError(403, { error: 'Forbidden' })
+      }
+      return
+    }
+    // No current org could be resolved either. This branch previously returned
+    // with no validation and no signal — a fail-open-by-omission shape (#2441):
+    // a new command path reaching here with `organizationScope: null` would act
+    // on an arbitrary target org silently. Preserve the legacy allow behavior by
+    // default (the path is load-bearing) but make the unscoped access observable,
+    // and let operators harden it into a deny via OM_ENFORCE_ORG_SCOPE_STRICT.
+    if (organizationId) {
+      logUnscopedOrganizationAccess(ctx, organizationId)
+      if (isStrictOrganizationScopeEnforced()) {
+        throw new CrudHttpError(403, { error: 'Forbidden' })
+      }
     }
     return
   }

package/src/lib/encryption/__tests__/dek-lifecycle.test.ts

@@ -0,0 +1,194 @@
+import { decryptWithAesGcm, generateDek } from '../aes'
+import { HashicorpVaultKmsService, type KmsService, type TenantDek } from '../kms'
+import { TenantDataEncryptionService } from '../tenantDataEncryptionService'
+
+const originalEnv = { ...process.env }
+
+type DuckResponse = { ok: boolean; status: number; json: () => Promise<unknown> }
+
+function jsonResponse(status: number, body: Record<string, unknown>): DuckResponse {
+  return { ok: status >= 200 && status < 300, status, json: async () => body }
+}
+
+// Minimal in-memory Vault KV v2 simulator: GET reads the stored key, POST writes
+// it unless a `cas: 0` write loses to an existing version (concurrent create).
+function makeVaultSim() {
+  const store = new Map<string, string>()
+  const counts = { reads: 0, posts: 0, persisted: 0 }
+  const fetchMock = jest.fn(async (input: unknown, init?: RequestInit): Promise<DuckResponse> => {
+    const url = String(input)
+    const path = url.slice(url.indexOf('/v1/') + '/v1/'.length)
+    const method = (init?.method || 'GET').toUpperCase()
+    if (method === 'GET') {
+      counts.reads++
+      const key = store.get(path)
+      if (!key) return jsonResponse(404, { errors: [] })
+      return jsonResponse(200, { data: { data: { key } } })
+    }
+    counts.posts++
+    const body = init?.body ? (JSON.parse(String(init.body)) as { data?: { key?: string }; options?: { cas?: number } }) : {}
+    const cas = body.options?.cas
+    if (cas === 0 && store.has(path)) {
+      return jsonResponse(400, { errors: ['check-and-set parameter did not match the current version'] })
+    }
+    store.set(path, body.data?.key ?? '')
+    counts.persisted++
+    return jsonResponse(200, { data: { version: 1 } })
+  })
+  return { store, counts, fetchMock }
+}
+
+function installFetch(fetchMock: jest.Mock) {
+  ;(globalThis as { fetch?: typeof fetch }).fetch = fetchMock as unknown as typeof fetch
+}
+
+const fixedKey = (fill: number) => Buffer.alloc(32, fill).toString('base64')
+
+describe('HashicorpVaultKmsService DEK creation race (issue #2746)', () => {
+  afterEach(() => {
+    process.env = { ...originalEnv }
+    jest.restoreAllMocks()
+  })
+
+  it('reuses an existing Vault DEK instead of overwriting it (read-before-write)', async () => {
+    const { store, counts, fetchMock } = makeVaultSim()
+    installFetch(fetchMock)
+    const service = new HashicorpVaultKmsService({ vaultAddr: 'http://vault.test', vaultToken: 'token' })
+    const existingKey = fixedKey(7)
+    store.set('secret/data/tenant_key_tenant-existing', existingKey)
+
+    const dek = await service.createTenantDek('tenant-existing')
+
+    expect(dek?.key).toBe(existingKey)
+    expect(counts.persisted).toBe(0) // never overwrote the active key
+  })
+
+  it('converges concurrent createTenantDek calls on a single key via CAS', async () => {
+    const { counts, fetchMock } = makeVaultSim()
+    installFetch(fetchMock)
+    const service = new HashicorpVaultKmsService({ vaultAddr: 'http://vault.test', vaultToken: 'token' })
+
+    const [a, b] = await Promise.all([
+      service.createTenantDek('tenant-cas'),
+      service.createTenantDek('tenant-cas'),
+    ])
+
+    expect(a?.key).toBeTruthy()
+    expect(a?.key).toBe(b?.key) // both adopt the same winning key — no orphaned rows
+    expect(counts.persisted).toBe(1) // exactly one key persisted, last-write-wins eliminated
+  })
+
+  it('invalidateDek forces a re-read from Vault', async () => {
+    const { store, counts, fetchMock } = makeVaultSim()
+    installFetch(fetchMock)
+    const service = new HashicorpVaultKmsService({ vaultAddr: 'http://vault.test', vaultToken: 'token' })
+    const path = 'secret/data/tenant_key_tenant-inv'
+    store.set(path, fixedKey(3))
+
+    const first = await service.getTenantDek('tenant-inv')
+    await service.getTenantDek('tenant-inv') // served from the KMS TTL cache
+    expect(counts.reads).toBe(1)
+
+    store.set(path, fixedKey(9)) // operator rotates the key in Vault
+    service.invalidateDek('tenant-inv')
+    const rotated = await service.getTenantDek('tenant-inv')
+
+    expect(counts.reads).toBe(2)
+    expect(rotated?.key).not.toBe(first?.key)
+  })
+})
+
+describe('TenantDataEncryptionService DEK lifecycle (issue #2746)', () => {
+  const entityId = 'customers:person'
+  let tenantSeq = 0
+  const uniqueTenant = (label: string) => `tenant-${label}-2746-${tenantSeq++}`
+
+  afterEach(() => {
+    jest.restoreAllMocks()
+  })
+
+  function makeCreatingKms() {
+    const created: string[] = []
+    const kms: KmsService = {
+      isHealthy: () => true,
+      getTenantDek: jest.fn(async (): Promise<TenantDek | null> => null),
+      createTenantDek: jest.fn(async (tenantId: string): Promise<TenantDek | null> => {
+        const key = generateDek()
+        created.push(key)
+        return { tenantId, key, fetchedAt: Date.now() }
+      }),
+    }
+    return { kms, created }
+  }
+
+  function makeFetchingKms() {
+    const kms: KmsService = {
+      isHealthy: () => true,
+      getTenantDek: jest.fn(async (tenantId: string): Promise<TenantDek | null> => ({
+        tenantId,
+        key: generateDek(),
+        fetchedAt: Date.now(),
+      })),
+      createTenantDek: jest.fn(async (): Promise<TenantDek | null> => null),
+    }
+    return { kms }
+  }
+
+  it('dedupes concurrent first-time DEK creation so no row is orphaned', async () => {
+    const { kms, created } = makeCreatingKms()
+    const service = new TenantDataEncryptionService({} as never, { kms })
+    jest.spyOn(service, 'isEnabled').mockReturnValue(true)
+    ;(service as unknown as { getMap: () => Promise<{ entityId: string; fields: { field: string }[] }> }).getMap =
+      jest.fn(async () => ({ entityId, fields: [{ field: 'secret' }] }))
+    const tenantId = uniqueTenant('race')
+
+    const rows = await Promise.all(
+      Array.from({ length: 12 }, (_, i) =>
+        service.encryptEntityPayload(entityId, { secret: `value-${i}` }, tenantId),
+      ),
+    )
+
+    expect((kms.createTenantDek as jest.Mock)).toHaveBeenCalledTimes(1)
+    expect(new Set(created).size).toBe(1)
+
+    const dek = await service.getDek(tenantId)
+    expect(dek).not.toBeNull()
+    rows.forEach((row, i) => {
+      expect(decryptWithAesGcm(String(row.secret), (dek as TenantDek).key)).toBe(`value-${i}`)
+    })
+  })
+
+  it('re-fetches a cached DEK after the TTL elapses (no stale key after rotation)', async () => {
+    const { kms } = makeFetchingKms()
+    const service = new TenantDataEncryptionService({} as never, { kms })
+    const tenantId = uniqueTenant('ttl')
+    let now = 1_700_000_000_000
+    jest.spyOn(Date, 'now').mockImplementation(() => now)
+
+    await service.getDek(tenantId)
+    await service.getDek(tenantId)
+    expect((kms.getTenantDek as jest.Mock)).toHaveBeenCalledTimes(1) // cached within TTL
+
+    now += 15 * 60 * 1000 + 1
+    await service.getDek(tenantId)
+    expect((kms.getTenantDek as jest.Mock)).toHaveBeenCalledTimes(2) // expired → re-fetch
+  })
+
+  it('invalidateDek clears both the service cache and the KMS cache', async () => {
+    const { kms } = makeFetchingKms()
+    const kmsInvalidate = jest.fn()
+    ;(kms as KmsService).invalidateDek = kmsInvalidate
+    const service = new TenantDataEncryptionService({} as never, { kms })
+    const tenantId = uniqueTenant('invalidate')
+
+    await service.getDek(tenantId)
+    await service.getDek(tenantId)
+    expect((kms.getTenantDek as jest.Mock)).toHaveBeenCalledTimes(1)
+
+    service.invalidateDek(tenantId)
+    expect(kmsInvalidate).toHaveBeenCalledWith(tenantId)
+
+    await service.getDek(tenantId)
+    expect((kms.getTenantDek as jest.Mock)).toHaveBeenCalledTimes(2)
+  })
+})

package/src/lib/encryption/__tests__/kms.test.ts

@@ -10,11 +10,17 @@ describe('kms timeout handling', () => {
   })
 
   it('marks Vault unhealthy after a timed out write', async () => {
-    const fetchMock = jest.fn((_url: string, init?: RequestInit) =>
-      new Promise((_resolve, reject) => {
+    // createTenantDek now reads-before-write (#2746): the read probe answers fast
+    // with no existing key so the flow reaches the write, which then times out.
+    const fetchMock = jest.fn((_url: string, init?: RequestInit) => {
+      const method = (init?.method || 'GET').toUpperCase()
+      if (method === 'GET') {
+        return Promise.resolve({ ok: true, status: 200, json: async () => ({ data: { data: {} } }) })
+      }
+      return new Promise((_resolve, reject) => {
         init?.signal?.addEventListener('abort', () => reject(new Error('aborted')))
-      }),
-    )
+      })
+    })
     ;(globalThis as { fetch?: typeof fetch }).fetch = fetchMock as typeof fetch
 
     const service = new HashicorpVaultKmsService({
@@ -25,7 +31,7 @@ describe('kms timeout handling', () => {
 
     await expect(service.createTenantDek('tenant-1')).resolves.toBeNull()
     expect(service.isHealthy()).toBe(false)
-    expect(fetchMock).toHaveBeenCalledTimes(1)
+    expect(fetchMock).toHaveBeenCalledTimes(2) // read probe + the timed-out write
   })
 
   it('falls back to derived keys after the primary Vault call times out', async () => {

package/src/lib/encryption/__tests__/lookupHash.test.ts

@@ -0,0 +1,113 @@
+import crypto from 'node:crypto'
+import { hashForLookup, legacyHashForLookup, lookupHashCandidates } from '../aes'
+
+const originalEnv = { ...process.env }
+
+function clearLookupEnv() {
+  delete process.env.LOOKUP_HASH_PEPPER
+  delete process.env.TENANT_DATA_ENCRYPTION_FALLBACK_KEY
+  delete process.env.TENANT_DATA_ENCRYPTION_KEY
+}
+
+describe('hashForLookup keyed digest (issue #2718)', () => {
+  afterEach(() => {
+    process.env = { ...originalEnv }
+  })
+
+  it('emits a keyed v2 HMAC when a lookup pepper is configured', () => {
+    clearLookupEnv()
+    process.env.LOOKUP_HASH_PEPPER = 'installation-pepper-secret-value'
+    const digest = hashForLookup('User@Example.com')
+    expect(digest.startsWith('v2:')).toBe(true)
+    const expected = crypto
+      .createHmac('sha256', 'installation-pepper-secret-value')
+      .update('user@example.com')
+      .digest('hex')
+    expect(digest).toBe(`v2:${expected}`)
+  })
+
+  it('is not equal to the legacy unkeyed sha256 (defeats precomputed rainbow tables)', () => {
+    clearLookupEnv()
+    process.env.LOOKUP_HASH_PEPPER = 'installation-pepper-secret-value'
+    const keyed = hashForLookup('user@example.com')
+    const legacy = legacyHashForLookup('user@example.com')
+    expect(keyed).not.toBe(legacy)
+    // The legacy digest is exactly what an attacker would precompute.
+    const naive = crypto.createHash('sha256').update('user@example.com').digest('hex')
+    expect(legacy).toBe(naive)
+    expect(keyed).not.toContain(naive)
+  })
+
+  it('produces different digests across installations (no cross-installation correlation)', () => {
+    clearLookupEnv()
+    process.env.LOOKUP_HASH_PEPPER = 'pepper-installation-a'
+    const a = hashForLookup('user@example.com')
+    process.env.LOOKUP_HASH_PEPPER = 'pepper-installation-b'
+    const b = hashForLookup('user@example.com')
+    expect(a).not.toBe(b)
+  })
+
+  it('binds the digest to the optional field/entity context (not portable across columns)', () => {
+    clearLookupEnv()
+    process.env.LOOKUP_HASH_PEPPER = 'installation-pepper-secret-value'
+    const withoutContext = hashForLookup('user@example.com')
+    const emailContext = hashForLookup('user@example.com', 'auth.user:email')
+    const phoneContext = hashForLookup('user@example.com', 'auth.user:phone')
+    expect(emailContext).not.toBe(withoutContext)
+    expect(emailContext).not.toBe(phoneContext)
+  })
+
+  it('normalizes case and surrounding whitespace before hashing', () => {
+    clearLookupEnv()
+    process.env.LOOKUP_HASH_PEPPER = 'installation-pepper-secret-value'
+    expect(hashForLookup('  User@Example.com  ')).toBe(hashForLookup('user@example.com'))
+  })
+
+  it('resolves the pepper from existing encryption secrets when no dedicated pepper is set', () => {
+    clearLookupEnv()
+    process.env.TENANT_DATA_ENCRYPTION_FALLBACK_KEY = 'fallback-secret'
+    const fromFallback = hashForLookup('user@example.com')
+    expect(fromFallback.startsWith('v2:')).toBe(true)
+
+    clearLookupEnv()
+    process.env.TENANT_DATA_ENCRYPTION_KEY = 'fallback-secret'
+    const fromKey = hashForLookup('user@example.com')
+    expect(fromKey).toBe(fromFallback)
+  })
+
+  it('prefers LOOKUP_HASH_PEPPER over the encryption fallback secrets', () => {
+    clearLookupEnv()
+    process.env.LOOKUP_HASH_PEPPER = 'dedicated-pepper'
+    process.env.TENANT_DATA_ENCRYPTION_FALLBACK_KEY = 'fallback-secret'
+    const expected = crypto
+      .createHmac('sha256', 'dedicated-pepper')
+      .update('user@example.com')
+      .digest('hex')
+    expect(hashForLookup('user@example.com')).toBe(`v2:${expected}`)
+  })
+
+  it('falls back to the legacy unkeyed digest only when no secret is configured', () => {
+    clearLookupEnv()
+    const digest = hashForLookup('user@example.com')
+    expect(digest.startsWith('v2:')).toBe(false)
+    expect(digest).toBe(legacyHashForLookup('user@example.com'))
+  })
+
+  it('exposes keyed and legacy candidates for migration-window reads', () => {
+    clearLookupEnv()
+    process.env.LOOKUP_HASH_PEPPER = 'installation-pepper-secret-value'
+    const candidates = lookupHashCandidates('user@example.com')
+    expect(candidates).toEqual([
+      hashForLookup('user@example.com'),
+      legacyHashForLookup('user@example.com'),
+    ])
+    expect(candidates).toHaveLength(2)
+  })
+
+  it('collapses candidates to a single value when running in legacy (no-pepper) mode', () => {
+    clearLookupEnv()
+    const candidates = lookupHashCandidates('user@example.com')
+    expect(candidates).toEqual([legacyHashForLookup('user@example.com')])
+    expect(candidates).toHaveLength(1)
+  })
+})

package/src/lib/encryption/aes.ts

@@ -80,8 +80,84 @@ export function decryptWithAesGcm(payload: string, dekBase64: string): string |
   }
 }
 
-export function hashForLookup(value: string): string {
-  return crypto.createHash('sha256').update(value.toLowerCase().trim()).digest('hex')
+const LOOKUP_HASH_V2_PREFIX = 'v2:'
+
+function normalizeLookupValue(value: string): string {
+  return value.toLowerCase().trim()
+}
+
+/**
+ * Legacy, unkeyed lookup digest (`sha256(lower(trim(value)))`).
+ *
+ * @deprecated Unkeyed digests are vulnerable to offline rainbow-table attacks and
+ * cross-installation correlation (issue #2718). New writes use {@link hashForLookup},
+ * which emits a keyed `v2:` HMAC when a lookup pepper is configured. This helper is
+ * retained only so existing `*_hash` columns written before the keyed format can still
+ * be matched (see {@link lookupHashCandidates}) until a backfill migration recomputes them.
+ */
+export function legacyHashForLookup(value: string): string {
+  return crypto.createHash('sha256').update(normalizeLookupValue(value)).digest('hex')
+}
+
+/**
+ * Resolve the installation-wide lookup pepper used to key lookup hashes.
+ *
+ * Order of precedence (never `AUTH_SECRET`, per issue #2718):
+ * 1. `LOOKUP_HASH_PEPPER` — dedicated secret for lookup hashing
+ * 2. `TENANT_DATA_ENCRYPTION_FALLBACK_KEY` — existing encryption fallback secret
+ * 3. `TENANT_DATA_ENCRYPTION_KEY` — existing encryption secret
+ *
+ * Returns `null` when no secret is configured, in which case {@link hashForLookup}
+ * falls back to the legacy unkeyed digest so deployments without any configured key
+ * keep working unchanged.
+ */
+function resolveLookupPepper(): string | null {
+  const candidates = [
+    process.env.LOOKUP_HASH_PEPPER,
+    process.env.TENANT_DATA_ENCRYPTION_FALLBACK_KEY,
+    process.env.TENANT_DATA_ENCRYPTION_KEY,
+  ]
+  for (const candidate of candidates) {
+    if (typeof candidate !== 'string') continue
+    const normalized = candidate.trim().replace(/(?:^['"]|['"]$)/g, '')
+    if (normalized) return normalized
+  }
+  return null
+}
+
+/**
+ * Compute a deterministic lookup hash for a low-entropy PII value (email, phone, …).
+ *
+ * When a lookup pepper is configured the result is a keyed HMAC-SHA-256 prefixed with
+ * `v2:` and bound to the optional `context` (entity/field) so digests are not portable
+ * across columns, installations, or tenants without the secret. When no pepper is
+ * configured it falls back to the legacy unkeyed digest for backward compatibility.
+ *
+ * The `context` MUST be supplied identically on both the write and the read side for a
+ * given column; callers that do not pass one stay mutually consistent.
+ */
+export function hashForLookup(value: string, context?: string): string {
+  const pepper = resolveLookupPepper()
+  const normalized = normalizeLookupValue(value)
+  if (!pepper) {
+    return legacyHashForLookup(value)
+  }
+  const message = context ? `${context}:${normalized}` : normalized
+  const digest = crypto.createHmac('sha256', pepper).update(message).digest('hex')
+  return `${LOOKUP_HASH_V2_PREFIX}${digest}`
+}
+
+/**
+ * Candidate lookup hashes for matching a value against `*_hash` columns that may hold
+ * either the new keyed (`v2:`) digest or a legacy unkeyed digest. Use this in `$in` /
+ * `IN (...)` filters during the migration window so reads keep matching rows written
+ * before the keyed format. Once a backfill has recomputed all columns this can collapse
+ * back to a single {@link hashForLookup} value.
+ */
+export function lookupHashCandidates(value: string, context?: string): string[] {
+  const primary = hashForLookup(value, context)
+  const legacy = legacyHashForLookup(value)
+  return primary === legacy ? [primary] : [primary, legacy]
 }
 
 /**