@open-mercato/shared 0.10.1-develop.7679.1.cb2c13f49e → 0.10.1-develop.7687.1.e1a6f9de51

package/src/lib/query/__tests__/engine-decrypt-refusal-log.test.ts

@@ -0,0 +1,168 @@
+const warnMock = jest.fn()
+
+jest.mock('../../logger', () => {
+  const child = () => ({ debug: jest.fn(), info: jest.fn(), warn: warnMock, error: jest.fn(), child })
+  return { createLogger: () => ({ debug: jest.fn(), info: jest.fn(), warn: warnMock, error: jest.fn(), child }) }
+})
+
+import { BasicQueryEngine } from '../engine'
+import { SortDir } from '../types'
+import { registerModules } from '../../i18n/server'
+import {
+  DECLINED_ENCRYPTED_SORT_LOG_MESSAGE,
+  DECRYPT_REFUSAL_LOG_MESSAGE,
+} from '../../encryption/decryptScope'
+
+registerModules([] as any)
+
+type FakeRow = Record<string, any>
+
+function createFakeDb(rows: FakeRow[]) {
+  const columns = ['id', 'tenant_id', 'organization_id', 'deleted_at', 'display_name'].map((column_name) => ({
+    table_name: 'customer_entities',
+    column_name,
+  }))
+  const build = (table: string) => {
+    const state: any = { table, rows: table === 'customer_entities' ? rows : columns }
+    const chain: any = new Proxy(
+      {},
+      {
+        get(_target, prop: string) {
+          if (prop === 'execute') return async () => state.rows.map((row: FakeRow) => ({ ...row }))
+          if (prop === 'executeTakeFirst') return async () => ({ count: String(state.rows.length) })
+          if (prop === 'then') return undefined
+          return () => chain
+        },
+      },
+    )
+    return chain
+  }
+  return { selectFrom: (table: string) => build(table), fn: { count: () => ({ as: () => ({}) }) } }
+}
+
+describe('BasicQueryEngine aggregated decrypt-refusal warning (#5430)', () => {
+  beforeEach(() => warnMock.mockClear())
+
+  const engineFor = (rows: FakeRow[]) =>
+    new BasicQueryEngine({} as any, () => createFakeDb(rows) as any, () => ({
+      isEnabled: () => true,
+      getEncryptedFieldNames: async () => ['display_name'],
+      decryptEntityPayload: async () => ({ display_name: 'PLAINTEXT' }),
+    }))
+
+  const run = (rows: FakeRow[]) =>
+    engineFor(rows).query('customers:customer_entity', {
+      tenantId: 'tenant-a',
+      fields: ['id', 'display_name'],
+      page: { page: 1, pageSize: 10 },
+    })
+
+  const refusalWarnings = () => warnMock.mock.calls.filter(([message]) => message === DECRYPT_REFUSAL_LOG_MESSAGE)
+
+  test('emits exactly one warning for a page containing several refused rows', async () => {
+    await run([
+      { id: '1', tenant_id: 'tenant-b', organization_id: 'org1', display_name: 'cipher-1' },
+      { id: '2', tenant_id: 'tenant-c', organization_id: 'org1', display_name: 'cipher-2' },
+      { id: '3', tenant_id: 'tenant-d', organization_id: 'org1', display_name: 'cipher-3' },
+    ])
+    const warnings = refusalWarnings()
+    expect(warnings).toHaveLength(1)
+    expect(warnings[0][1]).toEqual({
+      entity: 'customers:customer_entity',
+      refusedRows: 3,
+      callerTenantId: 'tenant-a',
+      rowTenantIds: ['tenant-b', 'tenant-c', 'tenant-d'],
+    })
+  })
+
+  test('samples at most three distinct row tenant ids while counting them all', async () => {
+    await run(
+      ['tenant-b', 'tenant-c', 'tenant-d', 'tenant-e', 'tenant-f'].map((tenant, index) => ({
+        id: String(index + 1),
+        tenant_id: tenant,
+        organization_id: 'org1',
+        display_name: `cipher-${index}`,
+      })),
+    )
+    const [, context] = refusalWarnings()[0]
+    expect(context.refusedRows).toBe(5)
+    expect(context.rowTenantIds).toHaveLength(3)
+  })
+
+  test('emits no warning when every row matches the caller tenant', async () => {
+    await run([
+      { id: '1', tenant_id: 'tenant-a', organization_id: 'org1', display_name: 'cipher-1' },
+      { id: '2', tenant_id: 'tenant-a', organization_id: 'org1', display_name: 'cipher-2' },
+    ])
+    expect(refusalWarnings()).toHaveLength(0)
+  })
+
+  // The plaintext-sort path decrypts the candidate scan and then the page rows, so an unkeyed
+  // counter tallied every surviving row twice and the count the docs promise was wrong.
+  test('counts a refused row once even though the plaintext-sort path decrypts it twice', async () => {
+    const rows = ['tenant-b', 'tenant-c', 'tenant-d'].map((tenant, index) => ({
+      id: String(index + 1),
+      tenant_id: tenant,
+      organization_id: 'org1',
+      display_name: `cipher-${index}`,
+    }))
+    await engineFor(rows).query('customers:customer_entity', {
+      tenantId: 'tenant-a',
+      fields: ['id', 'display_name'],
+      sort: [{ field: 'display_name', dir: SortDir.Asc }],
+      page: { page: 1, pageSize: 10 },
+    })
+    const warnings = refusalWarnings()
+    expect(warnings).toHaveLength(1)
+    expect(warnings[0][1]).toMatchObject({ refusedRows: 3 })
+  })
+
+  test('warns once when a declined query sorts on an encrypted field', async () => {
+    await engineFor([
+      { id: '1', tenant_id: 'tenant-a', organization_id: 'org1', display_name: 'cipher-1' },
+    ]).query('customers:customer_entity', {
+      tenantId: 'tenant-a',
+      decryptEncryptedFields: false,
+      fields: ['id', 'display_name'],
+      sort: [{ field: 'display_name', dir: SortDir.Asc }],
+      page: { page: 1, pageSize: 10 },
+    })
+    const warnings = warnMock.mock.calls.filter(([message]) => message === DECLINED_ENCRYPTED_SORT_LOG_MESSAGE)
+    expect(warnings).toHaveLength(1)
+    expect(warnings[0][1]).toEqual({
+      entity: 'customers:customer_entity',
+      sortFields: ['display_name'],
+    })
+  })
+
+  test('does not warn when a declined query sorts on a plaintext column', async () => {
+    await engineFor([
+      { id: '1', tenant_id: 'tenant-a', organization_id: 'org1', display_name: 'cipher-1' },
+    ]).query('customers:customer_entity', {
+      tenantId: 'tenant-a',
+      decryptEncryptedFields: false,
+      fields: ['id', 'display_name'],
+      sort: [{ field: 'id', dir: SortDir.Asc }],
+      page: { page: 1, pageSize: 10 },
+    })
+    expect(warnMock.mock.calls.filter(([message]) => message === DECLINED_ENCRYPTED_SORT_LOG_MESSAGE)).toHaveLength(0)
+  })
+
+  test('does not warn about an encrypted sort when the query decrypts normally', async () => {
+    await engineFor([
+      { id: '1', tenant_id: 'tenant-a', organization_id: 'org1', display_name: 'cipher-1' },
+    ]).query('customers:customer_entity', {
+      tenantId: 'tenant-a',
+      fields: ['id', 'display_name'],
+      sort: [{ field: 'display_name', dir: SortDir.Asc }],
+      page: { page: 1, pageSize: 10 },
+    })
+    expect(warnMock.mock.calls.filter(([message]) => message === DECLINED_ENCRYPTED_SORT_LOG_MESSAGE)).toHaveLength(0)
+  })
+
+  test('never puts a decrypted or ciphertext field value in the log context', async () => {
+    await run([{ id: '1', tenant_id: 'tenant-b', organization_id: 'org1', display_name: 'cipher-secret' }])
+    expect(JSON.stringify(refusalWarnings()[0][1])).not.toContain('cipher-secret')
+    expect(JSON.stringify(refusalWarnings()[0][1])).not.toContain('PLAINTEXT')
+  })
+})

package/src/lib/query/__tests__/engine.test.ts

@@ -1803,3 +1803,240 @@ describe('module-scoped column-existence cache (#5605)', () => {
     expect(columnProbesFor(fakeDb, 'tenant_id').length).toBeGreaterThan(probesAfterFirstEngine)
   })
 })
+
+describe('BasicQueryEngine decrypt tenant binding (#5430)', () => {
+  const informationSchema = [
+    { table_name: 'customer_entities', column_name: 'id' },
+    { table_name: 'customer_entities', column_name: 'tenant_id' },
+    { table_name: 'customer_entities', column_name: 'organization_id' },
+    { table_name: 'customer_entities', column_name: 'deleted_at' },
+    { table_name: 'customer_entities', column_name: 'display_name' },
+  ]
+
+  function setup(rows: any[], encryptedFieldNames: string[] = ['display_name']) {
+    const fakeDb = createFakeKysely({ customer_entities: rows, 'information_schema.columns': informationSchema })
+    const decryptCalls: Array<{ tenantId: string | null; organizationId: string | null }> = []
+    const engine = new BasicQueryEngine(
+      {} as any,
+      () => fakeDb as any,
+      () => ({
+        isEnabled: () => true,
+        getEncryptedFieldNames: async () => encryptedFieldNames,
+        decryptEntityPayload: async (_entityId: any, _payload: any, tenantId: any, organizationId: any) => {
+          decryptCalls.push({ tenantId, organizationId })
+          return { display_name: 'PLAINTEXT' }
+        },
+      }),
+    )
+    return { engine, decryptCalls, fakeDb }
+  }
+
+  // Every column named in any SELECT issued against the base table.
+  const selectedBaseColumns = (fakeDb: any): string[] =>
+    fakeDb._calls
+      .filter((call: any) => call._ops.table === 'customer_entities')
+      .flatMap((call: any) => selectAliases(call))
+
+  test('returns ciphertext and never fetches a DEK when the row tenant contradicts the query tenant', async () => {
+    const { engine, decryptCalls } = setup([
+      { id: '1', tenant_id: 'tenant-b', organization_id: 'org1', display_name: 'cipher-1' },
+    ])
+    const result = await engine.query('customers:customer_entity', {
+      tenantId: 'tenant-a',
+      fields: ['id', 'display_name'],
+      page: { page: 1, pageSize: 10 },
+    })
+    expect(decryptCalls).toEqual([])
+    expect((result.items[0] as any).display_name).toBe('cipher-1')
+  })
+
+  test('still decrypts a row whose tenant matches the query tenant', async () => {
+    const { engine, decryptCalls } = setup([
+      { id: '1', tenant_id: 'tenant-a', organization_id: 'org1', display_name: 'cipher-1' },
+    ])
+    const result = await engine.query('customers:customer_entity', {
+      tenantId: 'tenant-a',
+      fields: ['id', 'display_name'],
+      page: { page: 1, pageSize: 10 },
+    })
+    expect(decryptCalls).toEqual([{ tenantId: 'tenant-a', organizationId: 'org1' }])
+    expect((result.items[0] as any).display_name).toBe('PLAINTEXT')
+  })
+
+  // Both engines require `opts.tenantId` on every query, so a row that carries no tenant of its
+  // own — a global row on an `omitAutomaticTenantOrgScope` read — is the only fallback case left.
+  test('a row with no tenant of its own still decrypts under the caller tenant', async () => {
+    const { engine, decryptCalls } = setup([
+      { id: '1', tenant_id: null, organization_id: null, display_name: 'cipher-1' },
+    ])
+    const result = await engine.query('customers:customer_entity', {
+      tenantId: 'tenant-a',
+      omitAutomaticTenantOrgScope: true,
+      fields: ['id', 'display_name'],
+      page: { page: 1, pageSize: 10 },
+    })
+    expect(decryptCalls).toEqual([{ tenantId: 'tenant-a', organizationId: null }])
+    expect((result.items[0] as any).display_name).toBe('PLAINTEXT')
+  })
+
+  test('performs no DEK lookup at all when the query declines decryption', async () => {
+    const { engine, decryptCalls } = setup([
+      { id: '1', tenant_id: 'tenant-a', organization_id: 'org1', display_name: 'cipher-1' },
+    ])
+    const result = await engine.query('customers:customer_entity', {
+      tenantId: 'tenant-a',
+      decryptEncryptedFields: false,
+      fields: ['id', 'display_name'],
+      page: { page: 1, pageSize: 10 },
+    })
+    expect(decryptCalls).toEqual([])
+    expect((result.items[0] as any).display_name).toBe('cipher-1')
+  })
+
+  test('an explicit true keeps decrypting, as does omitting the flag', async () => {
+    for (const decryptEncryptedFields of [true, undefined]) {
+      const { engine, decryptCalls } = setup([
+        { id: '1', tenant_id: 'tenant-a', organization_id: 'org1', display_name: 'cipher-1' },
+      ])
+      const result = await engine.query('customers:customer_entity', {
+        tenantId: 'tenant-a',
+        decryptEncryptedFields,
+        fields: ['id', 'display_name'],
+        page: { page: 1, pageSize: 10 },
+      })
+      expect(decryptCalls).toHaveLength(1)
+      expect((result.items[0] as any).display_name).toBe('PLAINTEXT')
+    }
+  })
+
+  // A declined query must not take the plaintext-sort path: that path exists only to sort on
+  // decrypted values, so running it without decryption scans the full candidate set and then
+  // orders by ciphertext. It reads the encryption MAP once — not a DEK — only to warn that the
+  // requested sort has degraded to ciphertext ordering.
+  test('a declined query resolves no encrypted sort fields and never scans for a plaintext sort', async () => {
+    const fakeDb = createFakeKysely({
+      customer_entities: [
+        { id: '1', tenant_id: 'tenant-a', organization_id: 'org1', display_name: 'cipher-b' },
+        { id: '2', tenant_id: 'tenant-a', organization_id: 'org1', display_name: 'cipher-a' },
+      ],
+      'information_schema.columns': informationSchema,
+    })
+    const decryptCalls: string[] = []
+    const engine = new BasicQueryEngine(
+      {} as any,
+      () => fakeDb as any,
+      () => ({
+        isEnabled: () => true,
+        getEncryptedFieldNames: async () => ['display_name'],
+        decryptEntityPayload: async () => {
+          decryptCalls.push('called')
+          return { display_name: 'PLAINTEXT' }
+        },
+      }),
+    )
+
+    const result = await engine.query('customers:customer_entity', {
+      tenantId: 'tenant-a',
+      decryptEncryptedFields: false,
+      fields: ['id', 'display_name'],
+      sort: [{ field: 'display_name', dir: SortDir.Asc }],
+      page: { page: 1, pageSize: 10 },
+    })
+
+    expect(decryptCalls).toEqual([])
+    expect((result.items[0] as any).display_name).toBe('cipher-b')
+    const baseCalls = fakeDb._calls.filter((call: any) => call._ops.table === 'customer_entities')
+    // The plaintext-sort path issues a second (phase-1 candidate) query with no ORDER BY;
+    // a declined query must stay on the single ordinary SQL-ordered read.
+    expect(baseCalls.some((call: any) => call._ops.orderBys?.length > 0)).toBe(true)
+  })
+
+  test('an omitAutomaticTenantOrgScope query still decrypts by default', async () => {
+    const { engine, decryptCalls } = setup([
+      { id: '1', tenant_id: null, organization_id: null, display_name: 'cipher-1' },
+    ])
+    await engine.query('customers:customer_entity', {
+      tenantId: 'tenant-a',
+      omitAutomaticTenantOrgScope: true,
+      fields: ['id', 'display_name'],
+      page: { page: 1, pageSize: 10 },
+    })
+    expect(decryptCalls).toHaveLength(1)
+  })
+
+  // The decision reads the row's own tenant_id, so a `fields` list that omits it would leave
+  // `rowTenantId` null and make the guard inert on exactly the routes that project narrowly
+  // (e.g. the deals map route). The engine widens the projection and strips the column back out.
+  describe('tenant_id is carried into the decrypt decision regardless of the projection', () => {
+    test('a projection without tenant_id still refuses a foreign-tenant row', async () => {
+      const { engine, decryptCalls, fakeDb } = setup([
+        { id: '1', tenant_id: 'tenant-b', organization_id: 'org1', display_name: 'cipher-1' },
+      ])
+      const result = await engine.query('customers:customer_entity', {
+        tenantId: 'tenant-a',
+        fields: ['id', 'organization_id', 'display_name'],
+        page: { page: 1, pageSize: 10 },
+      })
+      expect(selectedBaseColumns(fakeDb)).toContain('tenant_id')
+      expect(decryptCalls).toEqual([])
+      expect((result.items[0] as any).display_name).toBe('cipher-1')
+    })
+
+    test('the injected column is stripped from the response shape', async () => {
+      const { engine, fakeDb } = setup([
+        { id: '1', tenant_id: 'tenant-a', organization_id: 'org1', display_name: 'cipher-1' },
+      ])
+      const result = await engine.query('customers:customer_entity', {
+        tenantId: 'tenant-a',
+        fields: ['id', 'organization_id', 'display_name'],
+        page: { page: 1, pageSize: 10 },
+      })
+      expect(selectedBaseColumns(fakeDb)).toContain('tenant_id')
+      expect(Object.prototype.hasOwnProperty.call(result.items[0], 'tenant_id')).toBe(false)
+      expect((result.items[0] as any).display_name).toBe('PLAINTEXT')
+    })
+
+    test('a caller that asked for tenant_id still gets it back', async () => {
+      const { engine } = setup([
+        { id: '1', tenant_id: 'tenant-a', organization_id: 'org1', display_name: 'cipher-1' },
+      ])
+      const result = await engine.query('customers:customer_entity', {
+        tenantId: 'tenant-a',
+        fields: ['id', 'tenant_id', 'display_name'],
+        page: { page: 1, pageSize: 10 },
+      })
+      expect((result.items[0] as any).tenant_id).toBe('tenant-a')
+    })
+
+    test('an entity with no encryption map keeps its projection untouched', async () => {
+      const { engine, fakeDb } = setup(
+        [{ id: '1', tenant_id: 'tenant-a', organization_id: 'org1', display_name: 'plain-1' }],
+        [],
+      )
+      await engine.query('customers:customer_entity', {
+        tenantId: 'tenant-a',
+        fields: ['id', 'display_name'],
+        page: { page: 1, pageSize: 10 },
+      })
+      expect(selectedBaseColumns(fakeDb)).not.toContain('tenant_id')
+    })
+  })
+
+  test('refuses each mismatching row independently within one page', async () => {
+    const { engine, decryptCalls } = setup([
+      { id: '1', tenant_id: 'tenant-a', organization_id: 'org1', display_name: 'cipher-1' },
+      { id: '2', tenant_id: 'tenant-b', organization_id: 'org1', display_name: 'cipher-2' },
+      { id: '3', tenant_id: 'tenant-c', organization_id: 'org1', display_name: 'cipher-3' },
+    ])
+    const result = await engine.query('customers:customer_entity', {
+      tenantId: 'tenant-a',
+      fields: ['id', 'display_name'],
+      page: { page: 1, pageSize: 10 },
+    })
+    expect(decryptCalls).toHaveLength(1)
+    const byId = new Map((result.items as any[]).map((row) => [row.id, row.display_name]))
+    expect(byId.get('1')).toBe('PLAINTEXT')
+    expect(byId.get('2')).toBe('cipher-2')
+    expect(byId.get('3')).toBe('cipher-3')
+  })
+})

package/src/lib/query/encrypted-sort.ts

@@ -44,21 +44,36 @@ export function resolveEncryptedSortMaxRows(): number | null {
   return Math.floor(parsed)
 }
 
-export async function resolveEncryptedSortFields(
+/**
+ * Reads the entity's encryption map once so a query can answer both "which sort fields are
+ * encrypted" and "must the projection carry `tenant_id` into the decrypt decision" without paying
+ * for two lookups.
+ *
+ * `null` means the map is unavailable — no service, or one that cannot report field names. A query
+ * that reads `null` keeps today's behaviour for sorting (no plaintext-sort path) but must assume a
+ * decrypt attempt may still follow. An empty array means the entity genuinely encrypts nothing.
+ */
+export async function resolveEncryptedFieldNames(
   service: QueryEncryptionService | null | undefined,
   entity: EntityId,
-  sortFields: readonly string[],
   tenantId?: string | null,
   organizationId?: string | null,
-): Promise<Set<string>> {
-  if (!service?.getEncryptedFieldNames) return new Set()
-  if (service.isEnabled && !service.isEnabled()) return new Set()
-  const encrypted = await service.getEncryptedFieldNames(entity, tenantId ?? null, organizationId ?? null)
+): Promise<readonly string[] | null> {
+  if (service?.isEnabled && !service.isEnabled()) return []
+  if (!service?.getEncryptedFieldNames) return null
+  return await service.getEncryptedFieldNames(entity, tenantId ?? null, organizationId ?? null)
+}
+
+export function matchEncryptedSortFields(
+  encryptedFieldNames: readonly string[] | null,
+  sortFields: readonly string[],
+): Set<string> {
+  const result = new Set<string>()
+  if (!encryptedFieldNames || encryptedFieldNames.length === 0) return result
   const encryptedCandidates = new Set<string>()
-  for (const field of encrypted) {
+  for (const field of encryptedFieldNames) {
     for (const candidate of fieldNameCandidates(field)) encryptedCandidates.add(candidate)
   }
-  const result = new Set<string>()
   for (const field of sortFields) {
     if (field.startsWith('cf:')) continue
     const matches = fieldNameCandidates(field).some((candidate) => encryptedCandidates.has(candidate))
@@ -67,6 +82,17 @@ export async function resolveEncryptedSortFields(
   return result
 }
 
+export async function resolveEncryptedSortFields(
+  service: QueryEncryptionService | null | undefined,
+  entity: EntityId,
+  sortFields: readonly string[],
+  tenantId?: string | null,
+  organizationId?: string | null,
+): Promise<Set<string>> {
+  const encryptedFieldNames = await resolveEncryptedFieldNames(service, entity, tenantId, organizationId)
+  return matchEncryptedSortFields(encryptedFieldNames, sortFields)
+}
+
 function readField(row: Record<string, unknown>, field: string): unknown {
   for (const candidate of fieldNameCandidates(field)) {
     if (Object.prototype.hasOwnProperty.call(row, candidate)) return row[candidate]

package/src/lib/query/engine.ts

@@ -33,9 +33,22 @@ import {
   type ResolvedCustomFieldDefinitions,
 } from '../crud/custom-field-definition-index'
 import { warnOnCiphertextLikeFallback } from './ciphertext-search-warning'
-import { resolveEncryptedSortFields, resolveEncryptedSortMaxRows, sortRowsInMemory } from './encrypted-sort'
+import {
+  matchEncryptedSortFields,
+  resolveEncryptedFieldNames,
+  resolveEncryptedSortFields,
+  resolveEncryptedSortMaxRows,
+  sortRowsInMemory,
+} from './encrypted-sort'
 import { resolveListCountCap } from './count-cap'
 import { mapWithConcurrency } from './bounded-decrypt'
+import {
+  DECLINED_ENCRYPTED_SORT_LOG_MESSAGE,
+  DECRYPT_REFUSAL_LOG_MESSAGE,
+  DecryptRefusalTally,
+  resolveDecryptEnabled,
+  resolveDecryptScope,
+} from '../encryption/decryptScope'
 import { parseNumberWithDefault } from '../number'
 import { createLogger } from '../logger'
 import {
@@ -726,7 +739,8 @@ export class BasicQueryEngine implements QueryEngine {
     const fallbackOrgId =
       opts.organizationId
       ?? (Array.isArray(opts.organizationIds) && opts.organizationIds.length === 1 ? opts.organizationIds[0] : null)
-    const encryptionService = this.getEncryptionService()
+    const decryptEnabled = resolveDecryptEnabled(opts)
+    const encryptionService = decryptEnabled ? this.getEncryptionService() : null
     const resolvedSorts: Sort[] = []
     for (const s of opts.sort || []) {
       if (s.field.startsWith('cf:')) {
@@ -736,14 +750,41 @@ export class BasicQueryEngine implements QueryEngine {
         if (column) resolvedSorts.push({ ...s, field: column })
       }
     }
-    const encryptedSortFields = await resolveEncryptedSortFields(
+    const plainSortFields = resolvedSorts
+      .filter((sort) => !sort.field.startsWith('cf:'))
+      .map((sort) => sort.field)
+    const encryptedFieldNames = await resolveEncryptedFieldNames(
       encryptionService,
       entity,
-      resolvedSorts.filter((sort) => !sort.field.startsWith('cf:')).map((sort) => sort.field),
       opts.tenantId ?? null,
       fallbackOrgId,
     )
+    const encryptedSortFields = matchEncryptedSortFields(encryptedFieldNames, plainSortFields)
     const requiresPlaintextSort = encryptedSortFields.size > 0
+    if (!decryptEnabled && plainSortFields.length > 0) {
+      const declinedSortFields = await resolveEncryptedSortFields(
+        this.getEncryptionService(),
+        entity,
+        plainSortFields,
+        opts.tenantId ?? null,
+        fallbackOrgId,
+      )
+      if (declinedSortFields.size > 0) {
+        logger.warn(DECLINED_ENCRYPTED_SORT_LOG_MESSAGE, {
+          entity: String(entity),
+          sortFields: Array.from(declinedSortFields),
+        })
+      }
+    }
+
+    const requestedFields = opts.fields && opts.fields.length ? opts.fields.map(String) : null
+    const injectsTenantIdForDecrypt =
+      encryptionService != null
+      && requestedFields != null
+      && !requestedFields.includes('tenant_id')
+      && !requestedFields.includes('tenantId')
+      && (encryptedFieldNames === null || encryptedFieldNames.length > 0)
+      && await this.columnExists(table, 'tenant_id')
 
     const tenantId = opts.tenantId
     const sanitize = (s: string) => s.replace(/[^a-zA-Z0-9_]/g, '_')
@@ -880,6 +921,7 @@ export class BasicQueryEngine implements QueryEngine {
         if (requiresPlaintextSort) {
           for (const field of encryptedSortFields) cols.add(field)
         }
+        if (injectsTenantIdForDecrypt) cols.add('tenant_id')
         for (const c of cols) {
           // Qualify and alias to base names to avoid ambiguity
           q = q.select(sql.ref(qualify(c)).as(c))
@@ -1443,15 +1485,22 @@ export class BasicQueryEngine implements QueryEngine {
           ) => Promise<Record<string, unknown>>)
         | null
 
+    const refusalTally = new DecryptRefusalTally()
+
     const decryptRow = async (item: ResultRow): Promise<ResultRow> => {
       if (!decryptPayload) return item
+      const decision = resolveDecryptScope({
+        rowTenantId: (item?.tenant_id ?? item?.tenantId ?? null) as string | null,
+        rowOrganizationId: (item?.organization_id ?? item?.organizationId ?? null) as string | null,
+        callerTenantId: opts.tenantId ?? null,
+        callerOrganizationId: fallbackOrgId ?? null,
+      })
+      if (!decision.decrypt) {
+        refusalTally.record(decision, item?.id == null ? null : String(item.id))
+        return item
+      }
       try {
-        const decrypted = await decryptPayload(
-          entity,
-          item,
-          (item?.tenant_id ?? item?.tenantId ?? opts.tenantId ?? null) as string | null,
-          (item?.organization_id ?? item?.organizationId ?? fallbackOrgId ?? null) as string | null,
-        )
+        const decrypted = await decryptPayload(entity, item, decision.tenantId, decision.organizationId)
         return { ...item, ...decrypted }
       } catch (err) {
         logger.error('Error decrypting entity payload', { err })
@@ -1459,6 +1508,11 @@ export class BasicQueryEngine implements QueryEngine {
       }
     }
 
+    const reportDecryptRefusals = () => {
+      if (refusalTally.refused === 0) return
+      logger.warn(DECRYPT_REFUSAL_LOG_MESSAGE, refusalTally.toLogContext(String(entity)))
+    }
+
     const normalizeCfJsonAliases = (rows: ResultRow[]) => {
       if (cfJsonAliases.size === 0) return
       for (const row of rows) {
@@ -1556,6 +1610,12 @@ export class BasicQueryEngine implements QueryEngine {
         : items
     }
 
+    reportDecryptRefusals()
+
+    if (injectsTenantIdForDecrypt) {
+      for (const row of pagedItems) delete row.tenant_id
+    }
+
     let queryResult: QueryResult<T> = { items: pagedItems as unknown as T[], page, pageSize, total }
 
     if (encryptedSortRowCapWarning || listCountCapWarning) {

package/src/lib/query/types.ts

@@ -126,6 +126,21 @@ export type QueryOptions = {
    * not match the standard `organization_id = X AND tenant_id = Y` shape.
    */
   omitAutomaticTenantOrgScope?: boolean
+  /**
+   * When `false`, the engine returns encrypted fields as stored (ciphertext) instead of decrypting
+   * them, and performs no DEK lookup at all. Defaults to `true` — today's behaviour — so existing
+   * callers are unaffected.
+   *
+   * Use it on generic, entity-agnostic surfaces that select every column and do not need plaintext.
+   * Opting in to decline decryption is not an access control: when decryption DOES run it is bound
+   * to the caller's tenant by `resolveDecryptScope`, which refuses any row whose `tenant_id`
+   * contradicts `tenantId`.
+   *
+   * Caveat: declining also disables the plaintext-sort path, so a `sort` on an encrypted field
+   * degrades to SQL `ORDER BY` over ciphertext — a meaningless order. Both engines log one warning
+   * when that combination is requested.
+   */
+  decryptEncryptedFields?: boolean
   // Soft-delete behavior: when false (default), rows with non-null deleted_at
   // are excluded if the base table has that column. Set true to include them.
   withDeleted?: boolean