@open-mercato/shared 0.6.4-develop.4371.1.8f3030407e → 0.6.4

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

@@ -1,4 +1,5 @@
-import { createKmsService, HashicorpVaultKmsService } from '../kms'
+import crypto from 'node:crypto'
+import { buildDerivedKeyFallbackBannerLines, createKmsService, HashicorpVaultKmsService } from '../kms'
 
 const originalEnv = { ...process.env }
 
@@ -9,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({
@@ -24,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 () => {
@@ -67,6 +74,37 @@ describe('kms timeout handling', () => {
     expect(dek).toBeNull()
   })
 
+  it('never prints the explicit fallback secret verbatim in the banner, regardless of NODE_ENV', () => {
+    const secret = 'super-secret-tenant-encryption-key'
+    for (const nodeEnv of ['development', 'staging', 'preview', 'PRODUCTION', 'production', undefined]) {
+      if (nodeEnv === undefined) delete process.env.NODE_ENV
+      else process.env.NODE_ENV = nodeEnv
+
+      const lines = buildDerivedKeyFallbackBannerLines({
+        secret,
+        source: 'explicit',
+        envName: 'TENANT_DATA_ENCRYPTION_FALLBACK_KEY',
+      })
+      const rendered = lines.join('\n')
+
+      expect(rendered).not.toContain(secret)
+      expect(rendered).toContain('Source: TENANT_DATA_ENCRYPTION_FALLBACK_KEY')
+      const expectedFingerprint = crypto.createHash('sha256').update(secret, 'utf8').digest('hex').slice(0, 16)
+      expect(rendered).toContain(`Secret fingerprint (sha256, truncated): ${expectedFingerprint}`)
+    }
+  })
+
+  it('does not echo the dev default secret verbatim in the banner either', () => {
+    const lines = buildDerivedKeyFallbackBannerLines({
+      secret: 'om-dev-tenant-encryption',
+      source: 'dev-default',
+      envName: 'DEV_DEFAULT',
+    })
+    const rendered = lines.join('\n')
+    expect(rendered).not.toContain('om-dev-tenant-encryption')
+    expect(rendered).toContain('Source: dev default secret (do NOT use in production)')
+  })
+
   it('requires an explicit opt-in before using the dev default derived key', async () => {
     process.env.NODE_ENV = 'test'
     process.env.TENANT_DATA_ENCRYPTION = 'yes'

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/__tests__/subscriber.change-tracking.test.ts

@@ -0,0 +1,96 @@
+import { TenantEncryptionSubscriber } from '../subscriber'
+import { registerEntityIds } from '../entityIds'
+import type { TenantDataEncryptionService } from '../tenantDataEncryptionService'
+
+// Regression coverage for issue #2498: the deep-decrypt re-baseline (syncOriginalEntityData) must
+// NOT clear a managed entity's pending changes. When a command mutates an entity and then loads a
+// related encrypted entity (whose deep-decrypt recurses back into the still-dirty entity) before
+// the final flush, re-baselining the dirty entity silently dropped the pending write — the update
+// command issued no UPDATE and `updated_at` never fired. The fix gates the re-baseline on the
+// entity having no un-flushed changes (per MikroORM's own comparator).
+
+type Helper = { __originalEntityData?: Record<string, unknown>; __touched?: boolean }
+
+function makeComparator() {
+  return {
+    // Mirror MikroORM's prepared snapshot: a plain scalar copy of the entity.
+    prepareEntity(entity: Record<string, unknown>) {
+      const snapshot: Record<string, unknown> = {}
+      for (const [key, value] of Object.entries(entity)) {
+        if (key === '__helper' || key === '__meta') continue
+        snapshot[key] = value
+      }
+      return snapshot
+    },
+    // True when the two snapshots are identical (no pending changes). Order-independent, like
+    // MikroORM's real comparator (the production fix depends on that property-wise semantics).
+    matching(_entityName: string, a: Record<string, unknown>, b: Record<string, unknown>) {
+      const aKeys = Object.keys(a)
+      const bKeys = Object.keys(b)
+      if (aKeys.length !== bKeys.length) return false
+      return aKeys.every((key) => JSON.stringify(a[key]) === JSON.stringify(b[key]))
+    },
+  }
+}
+
+function makeEm() {
+  const comparator = makeComparator()
+  return { getComparator: () => comparator, getMetadata: () => undefined }
+}
+
+const META = { className: 'Thing', tableName: 'things', properties: {} } as any
+
+describe('TenantEncryptionSubscriber change-tracking preservation (issue #2498)', () => {
+  const originalToggle = process.env.TENANT_DATA_ENCRYPTION
+
+  beforeEach(() => {
+    delete process.env.TENANT_DATA_ENCRYPTION // default => encryption enabled
+    registerEntityIds({ test: { thing: 'test:thing' } })
+  })
+
+  afterEach(() => {
+    if (originalToggle === undefined) delete process.env.TENANT_DATA_ENCRYPTION
+    else process.env.TENANT_DATA_ENCRYPTION = originalToggle
+    jest.restoreAllMocks()
+  })
+
+  function makeService(
+    decryptEntityPayload: (entityId: string, target: Record<string, unknown>) => Record<string, unknown> = () => ({}),
+  ): TenantDataEncryptionService {
+    return {
+      isEnabled: () => true,
+      async decryptEntityPayload(entityId: string, target: Record<string, unknown>) {
+        return decryptEntityPayload(entityId, target)
+      },
+    } as unknown as TenantDataEncryptionService
+  }
+
+  it('preserves pending scalar changes when re-baselining a dirty managed entity', async () => {
+    const helper: Helper = { __originalEntityData: { displayName: 'CHANGED', tenantId: 't1' }, __touched: true }
+    // Command restored the value in-memory but has not flushed yet.
+    const entity: Record<string, unknown> = { tenantId: 't1', displayName: 'Before', __helper: helper }
+
+    const subscriber = new TenantEncryptionSubscriber(makeService())
+    await subscriber.decryptEntityGraph(entity, META, makeEm(), { syncOriginal: true })
+
+    // Baseline must still reflect the un-restored value so the flush computes a non-empty changeset.
+    expect(helper.__originalEntityData).toEqual({ displayName: 'CHANGED', tenantId: 't1' })
+    expect(helper.__touched).toBe(true)
+  })
+
+  it('still re-baselines a clean entity so decrypted values are not re-persisted', async () => {
+    const helper: Helper = { __originalEntityData: { secret: 'enc:plain', tenantId: 't1' }, __touched: false }
+    const entity: Record<string, unknown> = { tenantId: 't1', secret: 'enc:plain', __helper: helper }
+
+    // Decrypt rewrites the ciphertext column to plaintext.
+    const subscriber = new TenantEncryptionSubscriber(
+      makeService(() => ({ secret: 'plain' })),
+    )
+    await subscriber.decryptEntityGraph(entity, META, makeEm(), { syncOriginal: true })
+
+    // Clean entity: re-baseline must snapshot the decrypted value so the next flush sees no change.
+    expect(entity.secret).toBe('plain')
+    expect(helper.__originalEntityData).toEqual({ secret: 'plain', tenantId: 't1' })
+    expect(helper.__touched).toBe(false)
+  })
+})

package/src/lib/encryption/__tests__/subscriber.deep-decrypt-collections.test.ts

@@ -0,0 +1,123 @@
+import { ReferenceKind } from '@mikro-orm/core'
+import { TenantEncryptionSubscriber } from '../subscriber'
+import { registerEntityIds } from '../entityIds'
+import type { TenantDataEncryptionService } from '../tenantDataEncryptionService'
+
+// Regression coverage for issue #2744: a loaded *-to-many Collection relation must be expanded into
+// its items during deep-decrypt. extractEntities() previously matched the MikroORM Reference branch
+// first — both a Collection and a Reference expose isInitialized() — so a Collection (which has no
+// unwrap()/__entity) was returned as the wrapper itself and decrypt() ran on the Collection instead
+// of each item, leaving encrypted child fields as ciphertext in populated response graphs.
+
+// Mirrors a MikroORM Collection: exposes isInitialized() + getItems(), but NO unwrap()/__entity.
+function makeCollection(items: Record<string, unknown>[], initialized = true) {
+  return {
+    isInitialized: () => initialized,
+    getItems: () => items,
+  }
+}
+
+// Mirrors a MikroORM Reference: exposes isInitialized() + unwrap(), but NO getItems().
+function makeReference(entity: Record<string, unknown>, initialized = true) {
+  return {
+    isInitialized: () => initialized,
+    unwrap: () => entity,
+  }
+}
+
+const CHILD_META = { className: 'Child', tableName: 'children', properties: {} } as any
+
+const parentMeta = (childKind: ReferenceKind, relationName: string) =>
+  ({
+    className: 'Parent',
+    tableName: 'parents',
+    properties: { [relationName]: { name: relationName, kind: childKind } },
+  }) as any
+
+function makeEm() {
+  return { getMetadata: () => undefined, getComparator: () => undefined }
+}
+
+// Decrypts by stripping an "enc:" prefix; records every entity id it was asked to decrypt.
+function makeService(decryptedEntityIds: string[]): TenantDataEncryptionService {
+  return {
+    isEnabled: () => true,
+    async decryptEntityPayload(entityId: string, target: Record<string, unknown>) {
+      decryptedEntityIds.push(entityId)
+      const value = target.secret
+      if (typeof value === 'string' && value.startsWith('enc:')) {
+        return { secret: value.slice('enc:'.length) }
+      }
+      return {}
+    },
+  } as unknown as TenantDataEncryptionService
+}
+
+describe('TenantEncryptionSubscriber deep-decrypt of loaded collection relations (issue #2744)', () => {
+  const originalToggle = process.env.TENANT_DATA_ENCRYPTION
+
+  beforeEach(() => {
+    delete process.env.TENANT_DATA_ENCRYPTION // default => encryption enabled
+    registerEntityIds({ test: { parent: 'test:parent', child: 'test:child' } })
+  })
+
+  afterEach(() => {
+    if (originalToggle === undefined) delete process.env.TENANT_DATA_ENCRYPTION
+    else process.env.TENANT_DATA_ENCRYPTION = originalToggle
+    jest.restoreAllMocks()
+  })
+
+  it('decrypts every item of an initialized ONE_TO_MANY collection', async () => {
+    const decryptedEntityIds: string[] = []
+    const childA = { secret: 'enc:alpha', tenantId: 't1', __meta: CHILD_META }
+    const childB = { secret: 'enc:beta', tenantId: 't1', __meta: CHILD_META }
+    const meta = parentMeta(ReferenceKind.ONE_TO_MANY, 'children')
+    const parent = { tenantId: 't1', children: makeCollection([childA, childB]), __meta: meta }
+
+    const subscriber = new TenantEncryptionSubscriber(makeService(decryptedEntityIds))
+    await subscriber.decryptEntityGraph(parent, meta, makeEm(), { syncOriginal: true })
+
+    expect(childA.secret).toBe('alpha')
+    expect(childB.secret).toBe('beta')
+    expect(decryptedEntityIds.filter((id) => id === 'test:child')).toHaveLength(2)
+  })
+
+  it('decrypts every item of an initialized MANY_TO_MANY collection', async () => {
+    const decryptedEntityIds: string[] = []
+    const child = { secret: 'enc:gamma', tenantId: 't1', __meta: CHILD_META }
+    const meta = parentMeta(ReferenceKind.MANY_TO_MANY, 'children')
+    const parent = { tenantId: 't1', children: makeCollection([child]), __meta: meta }
+
+    const subscriber = new TenantEncryptionSubscriber(makeService(decryptedEntityIds))
+    await subscriber.decryptEntityGraph(parent, meta, makeEm(), { syncOriginal: true })
+
+    expect(child.secret).toBe('gamma')
+    expect(decryptedEntityIds).toContain('test:child')
+  })
+
+  it('leaves an uninitialized collection untouched (does not decrypt unloaded items)', async () => {
+    const decryptedEntityIds: string[] = []
+    const child = { secret: 'enc:delta', tenantId: 't1', __meta: CHILD_META }
+    const meta = parentMeta(ReferenceKind.ONE_TO_MANY, 'children')
+    const parent = { tenantId: 't1', children: makeCollection([child], false), __meta: meta }
+
+    const subscriber = new TenantEncryptionSubscriber(makeService(decryptedEntityIds))
+    await subscriber.decryptEntityGraph(parent, meta, makeEm(), { syncOriginal: true })
+
+    expect(child.secret).toBe('enc:delta')
+    expect(decryptedEntityIds).not.toContain('test:child')
+  })
+
+  it('still decrypts a single-valued MANY_TO_ONE Reference (reorder must not regress references)', async () => {
+    const decryptedEntityIds: string[] = []
+    const child = { secret: 'enc:epsilon', tenantId: 't1', __meta: CHILD_META }
+    const meta = parentMeta(ReferenceKind.MANY_TO_ONE, 'child')
+    const parent = { tenantId: 't1', child: makeReference(child), __meta: meta }
+
+    const subscriber = new TenantEncryptionSubscriber(makeService(decryptedEntityIds))
+    await subscriber.decryptEntityGraph(parent, meta, makeEm(), { syncOriginal: true })
+
+    expect(child.secret).toBe('epsilon')
+    expect(decryptedEntityIds).toContain('test:child')
+  })
+})

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

@@ -1,4 +1,4 @@
-import { encryptWithAesGcm } from '../aes'
+import { decryptWithAesGcm, encryptWithAesGcm, hashForLookup } from '../aes'
 import {
   TenantDataEncryptionService,
   parseDecryptedFieldValue,
@@ -129,6 +129,73 @@ describe('TenantDataEncryptionService.decryptFields (issue #1734)', () => {
   })
 })
 
+describe('TenantDataEncryptionService.encryptFields (issue #2720)', () => {
+  function makeService() {
+    type Anything = Record<string, unknown>
+    const service = new TenantDataEncryptionService({} as never) as unknown as {
+      encryptFields: (
+        obj: Anything,
+        fields: { field: string; hashField?: string | null }[],
+        dek: { key: string },
+      ) => Anything
+    }
+    return service
+  }
+
+  it('encrypts a forged ciphertext-shaped value instead of storing it verbatim', () => {
+    const service = makeService()
+    const forged = 'aaaa:bbbb:cccc:v1'
+    const out = service.encryptFields(
+      { email: forged },
+      [{ field: 'email', hashField: 'email_hash' }],
+      { key: fixedKey } as never,
+    )
+    expect(out.email).not.toBe(forged)
+    expect(typeof out.email).toBe('string')
+    // The stored value must be real ciphertext that decrypts back to the forged input.
+    expect(decryptWithAesGcm(out.email as string, fixedKey)).toBe(forged)
+    // The lookup hash must be generated (the bypass previously skipped it).
+    expect(out.email_hash).toBe(hashForLookup(forged))
+  })
+
+  it('does not re-encrypt a value that genuinely decrypts under the DEK', () => {
+    const service = makeService()
+    const real = encryptWithAesGcm('mail@example.com', fixedKey).value as string
+    const out = service.encryptFields(
+      { email: real },
+      [{ field: 'email' }],
+      { key: fixedKey } as never,
+    )
+    expect(out.email).toBe(real)
+  })
+
+  it('encrypts a structurally-valid payload that was sealed with a different key', () => {
+    const service = makeService()
+    const otherKey = Buffer.alloc(32, 2).toString('base64')
+    const sealedElsewhere = encryptWithAesGcm('secret', otherKey).value as string
+    const out = service.encryptFields(
+      { email: sealedElsewhere },
+      [{ field: 'email' }],
+      { key: fixedKey } as never,
+    )
+    expect(out.email).not.toBe(sealedElsewhere)
+    expect(decryptWithAesGcm(out.email as string, fixedKey)).toBe(sealedElsewhere)
+  })
+
+  it('encrypts plaintext that happens to look like a v1 payload', () => {
+    const service = makeService()
+    const plaintext = 'user:supplied:colon:v1'
+    const out = service.encryptFields(
+      { email: plaintext },
+      [{ field: 'email', hashField: 'email_hash' }],
+      { key: fixedKey } as never,
+    )
+    expect(out.email).not.toBe(plaintext)
+    expect(decryptWithAesGcm(out.email as string, fixedKey)).toBe(plaintext)
+    expect(out.email_hash).toBe(hashForLookup(plaintext))
+  })
+})
+
 describe('TenantDataEncryptionService.getEncryptedFieldNames', () => {
   it('returns active encryption-map field names for query planning', async () => {
     const service = new TenantDataEncryptionService({} as never)

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]
 }
 
 /**