@open-mercato/shared 0.6.7-develop.6706.1.b3a4c759bb → 0.6.7-develop.6726.1.983ae8a07e

package/src/lib/query/__tests__/ciphertext-search-warning.test.ts

@@ -0,0 +1,178 @@
+import {
+  normalizeColumnName,
+  resetCiphertextLikeWarnCache,
+  warnOnCiphertextLikeFallback,
+} from '../ciphertext-search-warning'
+import { createLogger } from '../../logger'
+
+jest.mock('../../logger', () => {
+  const warn = jest.fn()
+  const debug = jest.fn()
+  const child = jest.fn(() => ({ warn, debug }))
+  return { createLogger: jest.fn(() => ({ child })), __warn: warn, __debug: debug }
+})
+
+const loggerModule = jest.requireMock('../../logger') as { __warn: jest.Mock; __debug: jest.Mock }
+
+function createService(encryptedFields: string[], overrides: Record<string, unknown> = {}) {
+  return {
+    isEnabled: () => true,
+    getEncryptedFieldNames: jest.fn(async () => encryptedFields),
+    ...overrides,
+  }
+}
+
+describe('warnOnCiphertextLikeFallback', () => {
+  beforeEach(() => {
+    resetCiphertextLikeWarnCache()
+    loggerModule.__warn.mockClear()
+    loggerModule.__debug.mockClear()
+  })
+
+  it('warns when the filtered column is covered by an encryption map', async () => {
+    const service = createService(['email', 'display_name'])
+    await warnOnCiphertextLikeFallback({
+      entity: 'customers:customer_entity',
+      fields: ['display_name'],
+      tenantId: 'tenant-1',
+      reason: 'no-search-tokens',
+      service,
+    })
+
+    expect(loggerModule.__warn).toHaveBeenCalledTimes(1)
+    const [message, payload] = loggerModule.__warn.mock.calls[0]
+    expect(message).toBe('Text search filter cannot match an encrypted column')
+    expect(payload).toMatchObject({
+      entity: 'customers:customer_entity',
+      field: 'display_name',
+      reason: 'no-search-tokens',
+    })
+  })
+
+  it('stays quiet for columns outside the encryption map', async () => {
+    await warnOnCiphertextLikeFallback({
+      entity: 'currencies:currency',
+      fields: ['code', 'symbol'],
+      tenantId: 'tenant-1',
+      reason: 'no-search-tokens',
+      service: createService(['unrelated']),
+    })
+    expect(loggerModule.__warn).not.toHaveBeenCalled()
+  })
+
+  it('does not cache a non-encrypted lookup as already warned', async () => {
+    await warnOnCiphertextLikeFallback({
+      entity: 'auth:user', fields: ['email'], tenantId: 'tenant-1', reason: 'no-search-tokens', service: createService([]),
+    })
+    await warnOnCiphertextLikeFallback({
+      entity: 'auth:user', fields: ['email'], tenantId: 'tenant-1', reason: 'no-search-tokens', service: createService(['email']),
+    })
+    expect(loggerModule.__warn).toHaveBeenCalledTimes(1)
+  })
+
+  it('matches camelCase filter fields against snake_case map entries', async () => {
+    await warnOnCiphertextLikeFallback({
+      entity: 'checkout:checkout_transaction',
+      fields: ['firstName'],
+      tenantId: null,
+      reason: 'no-search-tokens',
+      service: createService(['first_name']),
+    })
+    expect(loggerModule.__warn).toHaveBeenCalledTimes(1)
+    expect(loggerModule.__warn.mock.calls[0][1]).toMatchObject({ field: 'first_name' })
+  })
+
+  it('warns once per entity, tenant and field', async () => {
+    const service = createService(['email'])
+    const params = {
+      entity: 'auth:user',
+      fields: ['email'],
+      tenantId: 'tenant-1',
+      reason: 'no-search-tokens' as const,
+      service,
+    }
+    await warnOnCiphertextLikeFallback(params)
+    await warnOnCiphertextLikeFallback(params)
+    await warnOnCiphertextLikeFallback(params)
+
+    expect(loggerModule.__warn).toHaveBeenCalledTimes(1)
+    expect(service.getEncryptedFieldNames).toHaveBeenCalledTimes(1)
+  })
+
+  it('warns separately for a different tenant', async () => {
+    const service = createService(['email'])
+    await warnOnCiphertextLikeFallback({
+      entity: 'auth:user', fields: ['email'], tenantId: 'tenant-1', reason: 'no-search-tokens', service,
+    })
+    await warnOnCiphertextLikeFallback({
+      entity: 'auth:user', fields: ['email'], tenantId: 'tenant-2', reason: 'no-search-tokens', service,
+    })
+    expect(loggerModule.__warn).toHaveBeenCalledTimes(2)
+  })
+
+  it('does nothing when encryption is unavailable or disabled', async () => {
+    await warnOnCiphertextLikeFallback({
+      entity: 'auth:user', fields: ['email'], tenantId: null, reason: 'no-search-tokens', service: null,
+    })
+    await warnOnCiphertextLikeFallback({
+      entity: 'auth:user',
+      fields: ['email'],
+      tenantId: null,
+      reason: 'no-search-tokens',
+      service: createService(['email'], { isEnabled: () => false }),
+    })
+    expect(loggerModule.__warn).not.toHaveBeenCalled()
+  })
+
+  it('ignores custom-field filters', async () => {
+    const service = createService(['cf:secret_note'])
+    await warnOnCiphertextLikeFallback({
+      entity: 'example:todo', fields: ['cf:secret_note'], tenantId: null, reason: 'no-search-tokens', service,
+    })
+    expect(service.getEncryptedFieldNames).not.toHaveBeenCalled()
+    expect(loggerModule.__warn).not.toHaveBeenCalled()
+  })
+
+  it('reports the disabled-search reason with its own hint', async () => {
+    await warnOnCiphertextLikeFallback({
+      entity: 'auth:user', fields: ['email'], tenantId: null, reason: 'search-disabled', service: createService(['email']),
+    })
+    expect(loggerModule.__warn.mock.calls[0][1]).toMatchObject({ reason: 'search-disabled' })
+    expect(loggerModule.__warn.mock.calls[0][1].hint).toContain('OM_SEARCH_ENABLED')
+  })
+
+  it('reports values that are too short to tokenize', async () => {
+    await warnOnCiphertextLikeFallback({
+      entity: 'auth:user', fields: ['email'], tenantId: null, reason: 'no-indexable-tokens', service: createService(['email']),
+    })
+    expect(loggerModule.__warn.mock.calls[0][1]).toMatchObject({ reason: 'no-indexable-tokens' })
+    expect(loggerModule.__warn.mock.calls[0][1].hint).toContain('OM_SEARCH_MIN_LEN')
+  })
+
+  it('never rethrows when the encryption lookup fails', async () => {
+    const service = {
+      isEnabled: () => true,
+      getEncryptedFieldNames: jest.fn(async () => { throw new Error('kms down') }),
+    }
+    await expect(warnOnCiphertextLikeFallback({
+      entity: 'auth:user', fields: ['email'], tenantId: null, reason: 'no-search-tokens', service,
+    })).resolves.toBeUndefined()
+    expect(loggerModule.__warn).not.toHaveBeenCalled()
+    expect(loggerModule.__debug).toHaveBeenCalled()
+  })
+})
+
+describe('normalizeColumnName', () => {
+  it('converts camelCase to snake_case and lowercases', () => {
+    expect(normalizeColumnName('firstName')).toBe('first_name')
+    expect(normalizeColumnName('primaryEmail')).toBe('primary_email')
+    expect(normalizeColumnName('display_name')).toBe('display_name')
+    expect(normalizeColumnName('Email')).toBe('email')
+  })
+})
+
+describe('logger wiring', () => {
+  it('uses the shared query logger namespace', () => {
+    expect(createLogger).toHaveBeenCalledWith('shared')
+  })
+})

package/src/lib/query/ciphertext-search-warning.ts

@@ -0,0 +1,95 @@
+import { createLogger } from '../logger'
+import type { EntityId } from '../../modules/entities'
+
+const logger = createLogger('shared').child({ component: 'query' })
+
+/**
+ * Minimal slice of `TenantDataEncryptionService` needed to decide whether a
+ * text filter targets an encrypted column.
+ */
+export type CiphertextWarningEncryptionService = {
+  getEncryptedFieldNames?: (
+    entityId: EntityId,
+    tenantId?: string | null,
+    organizationId?: string | null,
+  ) => Promise<readonly string[]>
+  isEnabled?: () => boolean
+} | null | undefined
+
+export type CiphertextLikeFallbackReason = 'no-indexable-tokens' | 'no-search-tokens' | 'search-disabled'
+
+// One warning per entity/tenant/field per process — the fallback repeats on
+// every request, and an operator only needs to learn about it once.
+const WARN_CACHE_CAP = 5000
+const warned = new Set<string>()
+
+const warnKey = (entity: string, tenantId: string | null, field: string): string =>
+  `${entity}|${tenantId ?? 'null'}|${field}`
+
+export const normalizeColumnName = (value: string): string =>
+  value.replace(/([a-z0-9])([A-Z])/g, '$1_$2').toLowerCase()
+
+/** Test seam: the warn-once cache is process-global by design. */
+export function resetCiphertextLikeWarnCache(): void {
+  warned.clear()
+}
+
+/**
+ * Warn when a `like`/`ilike` filter is about to run against a column that an
+ * encryption map covers while the token index is unavailable.
+ *
+ * Without this the query degrades silently: the predicate compares a plaintext
+ * pattern against ciphertext, matches nothing, and the endpoint returns an
+ * empty page that is indistinguishable from a genuine no-result. Issue #2990.
+ *
+ * Never throws and never blocks the query — a failure here is logged at debug
+ * level and the caller proceeds unchanged.
+ */
+export async function warnOnCiphertextLikeFallback(params: {
+  entity: string
+  fields: readonly string[]
+  tenantId: string | null
+  reason: CiphertextLikeFallbackReason
+  service: CiphertextWarningEncryptionService
+}): Promise<void> {
+  const { entity, tenantId, reason, service } = params
+  if (!service || service.isEnabled?.() === false) return
+  if (typeof service.getEncryptedFieldNames !== 'function') return
+
+  const candidates = params.fields
+    .filter((field) => typeof field === 'string' && !field.startsWith('cf:'))
+    .map((field) => normalizeColumnName(field))
+    .filter((field, index, all) => field.length > 0 && all.indexOf(field) === index)
+    .filter((field) => !warned.has(warnKey(entity, tenantId, field)))
+  if (!candidates.length) return
+
+  try {
+    // `organizationId: null` resolves the global map plus every per-organization
+    // override, so a field encrypted for any organization is reported.
+    const encrypted = new Set(
+      (await service.getEncryptedFieldNames(entity, tenantId, null)).map((field) =>
+        normalizeColumnName(String(field)),
+      ),
+    )
+    for (const field of candidates) {
+      if (!encrypted.has(field)) continue
+      if (warned.size >= WARN_CACHE_CAP) warned.clear()
+      warned.add(warnKey(entity, tenantId, field))
+      logger.warn('Text search filter cannot match an encrypted column', {
+        entity,
+        field,
+        reason,
+        hint: reason === 'search-disabled'
+          ? 'OM_SEARCH_ENABLED is off, so the filter runs as ILIKE against ciphertext and matches nothing.'
+          : reason === 'no-indexable-tokens'
+            ? 'The filter value produced no search tokens, so it runs as ILIKE against ciphertext and matches nothing. Use at least OM_SEARCH_MIN_LEN indexable characters, or filter on the deterministic hash column.'
+            : 'No search_tokens exist for this entity and scope, so the filter runs as ILIKE against ciphertext and matches nothing. Index the entity through query_index and reindex, or filter on the deterministic hash column.',
+      })
+    }
+  } catch (err) {
+    logger.debug('Ciphertext search warning check failed', {
+      entity,
+      err: err instanceof Error ? err.message : String(err),
+    })
+  }
+}

package/src/lib/query/engine.ts

@@ -20,6 +20,7 @@ import {
   type CustomFieldDefinitionRow,
   type ResolvedCustomFieldDefinitions,
 } from '../crud/custom-field-definition-index'
+import { warnOnCiphertextLikeFallback } from './ciphertext-search-warning'
 import { resolveEncryptedSortFields, resolveEncryptedSortMaxRows, sortRowsInMemory } from './encrypted-sort'
 import { mapWithConcurrency } from './bounded-decrypt'
 import { createLogger } from '../logger'
@@ -333,6 +334,46 @@ export class BasicQueryEngine implements QueryEngine {
           organizationScope: orgScope,
         })
       }
+      const fallbackFields = searchFilters
+        .filter((filter) => !searchActive || typeof filter.value !== 'string' || tokenizeText(filter.value, searchConfig).hashes.length === 0)
+        .map((filter) => String(filter.field))
+      if (fallbackFields.length) {
+        await warnOnCiphertextLikeFallback({
+          entity: String(entity),
+          fields: fallbackFields,
+          tenantId: opts.tenantId ?? null,
+          // `searchEnabled` also folds in the missing-table and
+          // omitAutomaticTenantOrgScope cases, which are "no usable tokens"
+          // rather than "the operator switched search off".
+          reason: searchActive
+            ? 'no-indexable-tokens'
+            : searchConfig.enabled ? 'no-search-tokens' : 'search-disabled',
+          service: this.getEncryptionService(),
+        })
+      }
+    }
+    for (const [alias, joinedFilters] of joinFilters) {
+      const filters = joinedFilters.filter((entry) => entry.op === 'like' || entry.op === 'ilike')
+      if (!filters.length) continue
+      const join = joinMap.get(alias)
+      if (!join?.entityId) continue
+      const hasJoinedTokens = searchEnabled
+        ? await this.hasSearchTokens(join.entityId, opts.tenantId ?? null, orgScope)
+        : false
+      joinSearchAvailability.set(join.entityId, hasJoinedTokens)
+      const fallbackFields = filters
+        .filter((filter) => !hasJoinedTokens || typeof filter.value !== 'string' || tokenizeText(filter.value, searchConfig).hashes.length === 0)
+        .map((filter) => filter.column)
+      if (!fallbackFields.length) continue
+      await warnOnCiphertextLikeFallback({
+        entity: join.entityId,
+        fields: fallbackFields,
+        tenantId: opts.tenantId ?? null,
+        reason: hasJoinedTokens
+          ? 'no-indexable-tokens'
+          : searchConfig.enabled ? 'no-search-tokens' : 'search-disabled',
+        service: this.getEncryptionService(),
+      })
     }
     const recordIdColumn = qualify('id')
 

package/src/lib/search/__tests__/config.test.ts

@@ -1,5 +1,6 @@
 import {
   DEFAULT_SEARCH_MIN_TOKEN_LENGTH,
+  isSearchFieldBlocklisted,
   resolveSearchConfig,
   resolveSearchMinTokenLength,
 } from '../config'
@@ -40,3 +41,120 @@ describe('resolveSearchMinTokenLength', () => {
     expect(resolveSearchConfig().minTokenLength).toBe(resolveSearchMinTokenLength())
   })
 })
+
+describe('OM_SEARCH_FIELD_BLOCKLIST parsing', () => {
+  const originalValue = process.env.OM_SEARCH_FIELD_BLOCKLIST
+
+  afterEach(() => {
+    if (originalValue === undefined) {
+      delete process.env.OM_SEARCH_FIELD_BLOCKLIST
+    } else {
+      process.env.OM_SEARCH_FIELD_BLOCKLIST = originalValue
+    }
+  })
+
+  it('always includes the built-in defaults', () => {
+    delete process.env.OM_SEARCH_FIELD_BLOCKLIST
+    const config = resolveSearchConfig()
+    expect(config.blocklistedFields).toEqual(expect.arrayContaining(['password', 'token', 'secret', 'hash']))
+    expect(config.entityBlocklistedFields).toEqual({})
+  })
+
+  it('treats an unprefixed entry as global and lowercases it', () => {
+    process.env.OM_SEARCH_FIELD_BLOCKLIST = ' Body , body '
+    const config = resolveSearchConfig()
+    expect(config.blocklistedFields.filter((entry) => entry === 'body')).toHaveLength(1)
+    expect(config.entityBlocklistedFields).toEqual({})
+  })
+
+  it('routes an entityType@field entry into the per-entity map only', () => {
+    process.env.OM_SEARCH_FIELD_BLOCKLIST = 'customers:customer_interaction@body'
+    const config = resolveSearchConfig()
+    expect(config.blocklistedFields).not.toContain('body')
+    expect(config.entityBlocklistedFields).toEqual({ 'customers:customer_interaction': ['body'] })
+  })
+
+  it('groups several fields under the same entity type', () => {
+    process.env.OM_SEARCH_FIELD_BLOCKLIST = 'customers:customer_interaction@body,customers:customer_interaction@subject'
+    expect(resolveSearchConfig().entityBlocklistedFields).toEqual({
+      'customers:customer_interaction': ['body', 'subject'],
+    })
+  })
+
+  it('ignores entries whose field part is empty', () => {
+    process.env.OM_SEARCH_FIELD_BLOCKLIST = 'customers:customer_interaction@,@,body'
+    const config = resolveSearchConfig()
+    expect(config.blocklistedFields).toContain('body')
+    expect(config.entityBlocklistedFields).toEqual({})
+  })
+
+  it('treats a leading separator as a global entry', () => {
+    process.env.OM_SEARCH_FIELD_BLOCKLIST = '@body'
+    const config = resolveSearchConfig()
+    expect(config.blocklistedFields).toContain('body')
+    expect(config.entityBlocklistedFields).toEqual({})
+  })
+
+  it('stores entity types that collide with inherited object keys as own entries', () => {
+    process.env.OM_SEARCH_FIELD_BLOCKLIST = 'constructor@body,toString@summary,__proto__@notes'
+    const config = resolveSearchConfig()
+
+    expect(Object.getPrototypeOf(config.entityBlocklistedFields)).toBeNull()
+    expect(config.entityBlocklistedFields?.['constructor']).toEqual(['body'])
+    expect(config.entityBlocklistedFields?.['tostring']).toEqual(['summary'])
+    expect(config.entityBlocklistedFields?.['__proto__']).toEqual(['notes'])
+    expect(isSearchFieldBlocklisted('body', 'constructor', config)).toBe(true)
+    expect(isSearchFieldBlocklisted('summary', 'toString', config)).toBe(true)
+    expect(isSearchFieldBlocklisted('notes', '__proto__', config)).toBe(true)
+  })
+})
+
+describe('isSearchFieldBlocklisted', () => {
+  const baseConfig = {
+    enabled: true,
+    minTokenLength: 3,
+    enablePartials: true,
+    hashAlgorithm: 'sha256' as const,
+    storeRawTokens: false,
+  }
+
+  it('matches global entries by substring for any entity type', () => {
+    const config = { ...baseConfig, blocklistedFields: ['password'], entityBlocklistedFields: {} }
+    expect(isSearchFieldBlocklisted('password_hash', 'customers:person', config)).toBe(true)
+    expect(isSearchFieldBlocklisted('password_hash', null, config)).toBe(true)
+    expect(isSearchFieldBlocklisted('display_name', 'customers:person', config)).toBe(false)
+  })
+
+  it('applies an entity-scoped entry only to its own entity type', () => {
+    const config = {
+      ...baseConfig,
+      blocklistedFields: [],
+      entityBlocklistedFields: { 'customers:customer_interaction': ['body'] },
+    }
+    expect(isSearchFieldBlocklisted('body', 'customers:customer_interaction', config)).toBe(true)
+    expect(isSearchFieldBlocklisted('body', 'customers:person', config)).toBe(false)
+    expect(isSearchFieldBlocklisted('body', null, config)).toBe(false)
+  })
+
+  it('compares entity types case-insensitively', () => {
+    const config = {
+      ...baseConfig,
+      blocklistedFields: [],
+      entityBlocklistedFields: { 'customers:customer_interaction': ['body'] },
+    }
+    expect(isSearchFieldBlocklisted('BODY', ' Customers:Customer_Interaction ', config)).toBe(true)
+  })
+
+  it('ignores inherited Object.prototype keys when looking up an entity type', () => {
+    const config = { ...baseConfig, blocklistedFields: [], entityBlocklistedFields: {} }
+    expect(isSearchFieldBlocklisted('body', 'constructor', config)).toBe(false)
+    expect(isSearchFieldBlocklisted('body', 'toString', config)).toBe(false)
+    expect(isSearchFieldBlocklisted('body', '__proto__', config)).toBe(false)
+  })
+
+  it('tolerates a config without the per-entity map', () => {
+    const config = { ...baseConfig, blocklistedFields: ['secret'] }
+    expect(isSearchFieldBlocklisted('client_secret', 'customers:person', config)).toBe(true)
+    expect(isSearchFieldBlocklisted('body', 'customers:person', config)).toBe(false)
+  })
+})

package/src/lib/search/__tests__/tokenLookup.test.ts

@@ -0,0 +1,206 @@
+import {
+  findEntityIdsBySearchTokens,
+  findEntityIdsBySearchTokensCompat,
+} from '../tokenLookup'
+import { resolveSearchConfig } from '../config'
+import { tokenizeText } from '../tokenize'
+
+type KyselyCall = {
+  method: string
+  args: unknown[]
+}
+
+function createKyselyMock(rows: Array<{ entity_id: unknown }>) {
+  const calls: KyselyCall[] = []
+  const tableNameRef: { value: string | null } = { value: null }
+  const builder: Record<string, unknown> = {}
+  const passthrough = (method: string) =>
+    (...args: unknown[]) => {
+      calls.push({ method, args })
+      return builder
+    }
+  builder.select = passthrough('select')
+  builder.where = passthrough('where')
+  builder.groupBy = passthrough('groupBy')
+  builder.having = passthrough('having')
+  builder.execute = jest.fn(async () => rows)
+
+  const db = {
+    selectFrom: (table: string) => {
+      tableNameRef.value = table
+      return builder
+    },
+  }
+  return { db: db as never, calls, tableNameRef, builder }
+}
+
+function compileSql(raw: unknown): string {
+  if (raw && typeof raw === 'object' && 'toOperationNode' in raw && typeof raw.toOperationNode === 'function') {
+    const node = raw.toOperationNode() as { sqlFragments?: unknown }
+    return Array.isArray(node.sqlFragments) ? node.sqlFragments.join(' ? ') : ''
+  }
+  if (raw && typeof raw === 'object' && 'sql' in raw) return String(raw.sql)
+  return String(raw)
+}
+
+function rawWhereFragments(calls: KyselyCall[]): string[] {
+  return calls
+    .filter((call) => call.method === 'where' && call.args.length === 1)
+    .map((call) => compileSql(call.args[0]))
+}
+
+describe('findEntityIdsBySearchTokens', () => {
+  const baseInput = {
+    entityType: 'customers:customer_entity',
+    query: 'Hello',
+  }
+
+  it('skips the lookup for a blank query', async () => {
+    const { db, builder } = createKyselyMock([])
+    const result = await findEntityIdsBySearchTokens({ ...baseInput, db, query: '   ' })
+    expect(result).toEqual({ matched: false, reason: 'empty-query' })
+    expect(builder.execute).not.toHaveBeenCalled()
+  })
+
+  it('skips the lookup when token search is disabled', async () => {
+    const { db, builder } = createKyselyMock([])
+    const result = await findEntityIdsBySearchTokens({
+      ...baseInput,
+      db,
+      config: { ...resolveSearchConfig(), enabled: false },
+    })
+    expect(result).toEqual({ matched: false, reason: 'search-disabled' })
+    expect(builder.execute).not.toHaveBeenCalled()
+  })
+
+  it('skips the lookup when the query yields no indexable tokens', async () => {
+    const { db, builder } = createKyselyMock([])
+    const result = await findEntityIdsBySearchTokens({ ...baseInput, db, query: '!' })
+    expect(result).toEqual({ matched: false, reason: 'no-tokens' })
+    expect(builder.execute).not.toHaveBeenCalled()
+  })
+
+  it('requires every query token to be present on the record', async () => {
+    const { db, calls } = createKyselyMock([{ entity_id: 'a' }])
+    await findEntityIdsBySearchTokens({ ...baseInput, db, query: 'ada lovelace' })
+
+    const expectedHashes = tokenizeText('ada lovelace', resolveSearchConfig()).hashes
+    const hashFilter = calls.find((call) => call.args[0] === 'token_hash' && call.args[1] === 'in')
+    expect(hashFilter?.args[2]).toEqual(expectedHashes)
+
+    const having = calls.find((call) => call.method === 'having')
+    expect(compileSql(having?.args[0])).toContain('count(distinct token_hash) >=')
+  })
+
+  it('returns the matched ids and drops non-string rows', async () => {
+    const { db, tableNameRef } = createKyselyMock([
+      { entity_id: 'id-1' },
+      { entity_id: null },
+      { entity_id: 42 },
+      { entity_id: '' },
+      { entity_id: 'id-2' },
+    ])
+    const result = await findEntityIdsBySearchTokens({ ...baseInput, db })
+    expect(result).toEqual({ matched: true, ids: ['id-1', 'id-2'] })
+    expect(tableNameRef.value).toBe('search_tokens')
+  })
+
+  it('reports an empty match instead of a skip when nothing matched', async () => {
+    const { db } = createKyselyMock([])
+    const result = await findEntityIdsBySearchTokens({ ...baseInput, db })
+    expect(result).toEqual({ matched: true, ids: [] })
+  })
+
+  it('narrows a single field with equality and multiple fields with IN', async () => {
+    const single = createKyselyMock([])
+    await findEntityIdsBySearchTokens({ ...baseInput, db: single.db, fields: ['name'] })
+    expect(single.calls).toContainEqual({ method: 'where', args: ['field', '=', 'name'] })
+
+    const multi = createKyselyMock([])
+    await findEntityIdsBySearchTokens({ ...baseInput, db: multi.db, fields: ['name', 'email'] })
+    expect(multi.calls).toContainEqual({ method: 'where', args: ['field', 'in', ['name', 'email']] })
+  })
+
+  it('omits the field predicate when no fields are supplied', async () => {
+    const { db, calls } = createKyselyMock([])
+    await findEntityIdsBySearchTokens({ ...baseInput, db, fields: [] })
+    expect(calls.some((call) => call.args[0] === 'field')).toBe(false)
+  })
+
+  it('omits tenant and organization predicates when the scope is absent', async () => {
+    const { db, calls } = createKyselyMock([])
+    await findEntityIdsBySearchTokens({ ...baseInput, db })
+    expect(rawWhereFragments(calls)).toEqual([])
+    expect(calls.some((call) => call.args[0] === 'organization_id')).toBe(false)
+  })
+
+  it('emits a null-safe tenant predicate for an explicit null tenant', async () => {
+    const { db, calls } = createKyselyMock([])
+    await findEntityIdsBySearchTokens({ ...baseInput, db, scope: { tenantId: null } })
+    expect(rawWhereFragments(calls).some((s) => s.includes('tenant_id is not distinct from'))).toBe(true)
+  })
+
+  it('emits a null-safe organization predicate for an explicit null organization', async () => {
+    const { db, calls } = createKyselyMock([])
+    await findEntityIdsBySearchTokens({ ...baseInput, db, scope: { organizationId: null } })
+    expect(rawWhereFragments(calls).some((s) => s.includes('organization_id is not distinct from'))).toBe(true)
+  })
+
+  it('prefers a concrete organization over the visible-organization list', async () => {
+    const { db, calls } = createKyselyMock([])
+    await findEntityIdsBySearchTokens({
+      ...baseInput,
+      db,
+      scope: { organizationId: 'org-1', organizationIds: ['org-1', 'org-2'] },
+    })
+    expect(calls).toContainEqual({ method: 'where', args: ['organization_id', '=', 'org-1'] })
+    expect(calls.some((call) => call.args[1] === 'in' && call.args[0] === 'organization_id')).toBe(false)
+  })
+
+  it('falls back to the visible-organization list when no organization is selected', async () => {
+    const { db, calls } = createKyselyMock([])
+    await findEntityIdsBySearchTokens({
+      ...baseInput,
+      db,
+      scope: { organizationIds: ['org-1', 'org-2'] },
+    })
+    expect(calls).toContainEqual({ method: 'where', args: ['organization_id', 'in', ['org-1', 'org-2']] })
+  })
+})
+
+describe('findEntityIdsBySearchTokensCompat', () => {
+  it('returns null only for a blank query', async () => {
+    const { db } = createKyselyMock([])
+    await expect(findEntityIdsBySearchTokensCompat({
+      db,
+      entityType: 'customers:customer_entity',
+      query: ' ',
+    })).resolves.toBeNull()
+  })
+
+  it('returns an empty array for the remaining skip reasons', async () => {
+    const noTokens = createKyselyMock([])
+    await expect(findEntityIdsBySearchTokensCompat({
+      db: noTokens.db,
+      entityType: 'customers:customer_entity',
+      query: '!',
+    })).resolves.toEqual([])
+
+    const disabled = createKyselyMock([])
+    await expect(findEntityIdsBySearchTokensCompat({
+      db: disabled.db,
+      entityType: 'customers:customer_entity',
+      query: 'Hello',
+      config: { ...resolveSearchConfig(), enabled: false },
+    })).resolves.toEqual([])
+  })
+
+  it('returns the matched ids', async () => {
+    const { db } = createKyselyMock([{ entity_id: 'id-1' }])
+    await expect(findEntityIdsBySearchTokensCompat({
+      db,
+      entityType: 'customers:customer_entity',
+      query: 'Hello',
+    })).resolves.toEqual(['id-1'])
+  })
+})

package/src/lib/search/auto-indexing.ts

@@ -0,0 +1,22 @@
+import { parseBooleanToken } from '../boolean'
+
+/**
+ * Module id backing the tenant-scoped vector auto-indexing switch. Kept as `vector`
+ * (rather than `search`) for backwards compatibility with rows written before the
+ * search module absorbed the vector settings.
+ */
+export const SEARCH_AUTO_INDEX_CONFIG_MODULE = 'vector'
+export const SEARCH_AUTO_INDEX_CONFIG_KEY = 'auto_index_enabled'
+
+/**
+ * Instance-wide kill switch for vector auto-indexing. Lives in `@open-mercato/shared`
+ * so consumers outside `@open-mercato/search` (for example the query index status page)
+ * can report vector coverage honestly without duplicating the env-var contract.
+ */
+export function envDisablesAutoIndexing(): boolean {
+  const raw =
+    process.env.OM_DISABLE_VECTOR_SEARCH_AUTOINDEXING ??
+    process.env.DISABLE_VECTOR_SEARCH_AUTOINDEXING
+  if (!raw) return false
+  return parseBooleanToken(raw) === true
+}