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

package/dist/lib/query/types.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../src/lib/query/types.ts"],
-  "sourcesContent": ["import type { EntityId } from '@open-mercato/shared/modules/entities'\nimport type { Profiler } from '../profiler'\nimport type { ResolvedCustomFieldDefinitions } from '../crud/custom-field-definition-index'\n\n/**\n * `overlap` (additive, 2026-10-05): \"has any of\" over a multi-valued field. An index-document\n * string array compiles to jsonb `?|`, a `cf:*` key to any-value-in-set, and an array-typed base\n * column to `&&`. An empty value list matches nothing.\n *\n * `noverlap` (additive, 2026-10-05): \"has none of\" \u2014 the negation of `overlap` on an index-document\n * string array or an array-typed base column. Only a present array can match (a missing/null key or\n * NULL column never does); an empty value list excludes nothing. Unsupported on `cf:*` keys, where\n * it compiles to `false`.\n */\nexport type FilterOp = 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'nin' | 'like' | 'ilike' | 'exists' | 'overlap' | 'noverlap'\n\nexport enum SortDir {\n  Asc = 'asc',\n  Desc = 'desc',\n}\n\nexport type FieldSelector = string // base field or custom field key (prefixed with 'cf:')\n\nexport type Filter = {\n  field: FieldSelector\n  op: FilterOp\n  value?: any\n}\n\nexport type Sort = { field: FieldSelector; dir?: SortDir }\n\nexport type Page = { page?: number; pageSize?: number }\n\n// Mongo/Medusa-style filter operators (typed)\nexport type WhereOps<T> = {\n  $eq?: T\n  $ne?: T | null\n  $gt?: T extends number | Date ? T : never\n  $gte?: T extends number | Date ? T : never\n  $lt?: T extends number | Date ? T : never\n  $lte?: T extends number | Date ? T : never\n  $in?: T[]\n  $nin?: T[]\n  $like?: T extends string ? string : never\n  $ilike?: T extends string ? string : never\n  $exists?: boolean\n  $overlap?: T extends readonly (infer Element)[] ? Element[] : T[]\n  $noverlap?: T extends readonly (infer Element)[] ? Element[] : T[]\n}\n\n// A field filter can be a direct value (equals) or ops object\nexport type WhereValue<T = any> = T | WhereOps<T>\n\n// Generic shape for object filters. If you have a typed map of field\u2192type,\n// pass it as the generic to get end-to-end typing.\n// Example: Where<{\n//   id: string; title: string; created_at: Date; 'cf:severity': number\n// }>\nexport type Where<Fields extends Record<string, any> = Record<string, any>> =\n  Partial<{ [K in keyof Fields]: WhereValue<Fields[K]> }> & Record<string, WhereValue>\n\nexport type QueryCustomFieldJoin = {\n  fromField: string\n  toField: string\n  type?: 'left' | 'inner'\n}\n\nexport type QueryCustomFieldSource = {\n  entityId: EntityId\n  table?: string\n  alias?: string\n  recordIdColumn?: string\n  join?: QueryCustomFieldJoin\n  tenantField?: string\n  organizationField?: string\n}\n\nexport type QueryJoinEdge = {\n  alias: string\n  table?: string\n  entityId?: EntityId\n  from: {\n    alias?: string\n    field: string\n  }\n  to: {\n    field: string\n  }\n  type?: 'left' | 'inner'\n}\n\n/**\n * Optional context for query-level UMES extensions.\n * When provided, the query engine will execute sync lifecycle events\n * (querying/queried) and apply query-enabled enrichers.\n */\nexport type QueryExtensionsConfig = {\n  userId?: string\n  container?: unknown\n  userFeatures?: string[]\n  resolve?: <T = unknown>(name: string) => T\n}\n\nexport type QueryOptions = {\n  fields?: FieldSelector[] // base fields and/or 'cf:<key>' for custom fields\n  includeExtensions?: boolean | string[] // include all registered extensions or only specific ones by entity id\n  includeCustomFields?: boolean | string[] // include all CFs or specific keys\n  // Accept classic array syntax or Mongo-style object syntax\n  filters?: Filter[] | Where\n  sort?: Sort[]\n  page?: Page\n  organizationId?: string // enforce multi-tenant scope\n  tenantId?: string // enforce tenant scope\n  // Optional list of organization ids to scope results. Takes precedence over organizationId.\n  organizationIds?: string[]\n  /**\n   * When true, the engine does not apply default `organization_id` / `tenant_id` equality guards.\n   *\n   * Callers MUST encode full visibility in `filters` (for example with `$or` of scoped branches)\n   * and MUST fail closed when the authenticated principal lacks a resolvable tenant/org, otherwise\n   * queries return cross-tenant rows.\n   *\n   * When this flag is set, the hybrid query engine delegates to the basic engine. The basic engine\n   * still applies `cf:*` filters/sorts, but `search_tokens` fulltext filtering, the JSONB index read\n   * path, and the vector-search branch are BYPASSED. Only use this on entities whose scoping does\n   * not match the standard `organization_id = X AND tenant_id = Y` shape.\n   */\n  omitAutomaticTenantOrgScope?: boolean\n  // Soft-delete behavior: when false (default), rows with non-null deleted_at\n  // are excluded if the base table has that column. Set true to include them.\n  withDeleted?: boolean\n  customFieldSources?: QueryCustomFieldSource[]\n  joins?: QueryJoinEdge[]\n  profiler?: Profiler\n  // When true, suppress automatic reindex scheduling triggered by coverage gap detection.\n  // Used by the search indexing pipeline to prevent feedback loops where indexing triggers\n  // re-indexing indefinitely.\n  skipAutoReindex?: boolean\n  /**\n   * Force routing this query to custom-entity doc storage (`custom_entities_storage`)\n   * instead of classifying the entity automatically. Automatic classification routes\n   * ids backed by a registered ORM table to that base table, so surfaces that manage\n   * doc records for ids that are ALSO table-backed (e.g. the entities records browser\n   * reading a module-declared custom entity such as `example:todo`) must set this flag.\n   * Honored by the hybrid query engine only; `BasicQueryEngine` has no doc-storage\n   * reader and ignores it.\n   */\n  forceCustomEntityStorage?: boolean\n  // Optional UMES query extensions context. When provided, the engine will\n  // emit sync lifecycle events and apply query-level enrichers.\n  extensions?: QueryExtensionsConfig\n}\n\nexport type PartialIndexWarning = {\n  entity: EntityId\n  entityLabel?: string | null\n  baseCount?: number | null\n  indexedCount?: number | null\n  scope?: 'scoped' | 'global'\n}\n\nexport type EncryptedSortRowCapWarning = {\n  entity: EntityId\n  sortFields: string[]\n  maxRows: number\n  /**\n   * Exact when `meta.listCountCapWarning` is absent; a floor when it is\n   * present (the list total itself was bounded at the cap).\n   */\n  totalMatched: number\n}\n\n/**\n * Present when the list COUNT was bounded at `cap` matching rows\n * (`OM_LIST_COUNT_CAP`): `total` is a floor, not an exact value. Surfaced on\n * CRUD list payloads as `totalIsCapped: true`.\n */\nexport type ListCountCapWarning = {\n  entity: EntityId\n  cap: number\n}\n\nexport type QueryResultMeta = {\n  partialIndexWarning?: PartialIndexWarning\n  encryptedSortRowCapWarning?: EncryptedSortRowCapWarning\n  listCountCapWarning?: ListCountCapWarning\n}\n\nexport type QueryResult<T = any> = {\n  items: T[]\n  page: number\n  pageSize: number\n  total: number\n  meta?: QueryResultMeta\n  /**\n   * Custom-field definitions the engine resolved while building this result\n   * (only present when `includeCustomFields: true`). Lets the CRUD factory\n   * decorate list rows without reloading definitions from the DB (issue #2133).\n   * Internal contract \u2014 additive and optional; callers must treat absence as a\n   * cue to load definitions themselves.\n   */\n  customFieldDefinitions?: ResolvedCustomFieldDefinitions\n}\n\nexport interface QueryEngine {\n  query<T = any>(entity: EntityId, opts?: QueryOptions): Promise<QueryResult<T>>\n}\n"],
+  "sourcesContent": ["import type { EntityId } from '@open-mercato/shared/modules/entities'\nimport type { Profiler } from '../profiler'\nimport type { ResolvedCustomFieldDefinitions } from '../crud/custom-field-definition-index'\n\n/**\n * `overlap` (additive, 2026-10-05): \"has any of\" over a multi-valued field. An index-document\n * string array compiles to jsonb `?|`, a `cf:*` key to any-value-in-set, and an array-typed base\n * column to `&&`. An empty value list matches nothing.\n *\n * `noverlap` (additive, 2026-10-05): \"has none of\" \u2014 the negation of `overlap` on an index-document\n * string array or an array-typed base column. Only a present array can match (a missing/null key or\n * NULL column never does); an empty value list excludes nothing. Unsupported on `cf:*` keys, where\n * it compiles to `false`.\n */\nexport type FilterOp = 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'nin' | 'like' | 'ilike' | 'exists' | 'overlap' | 'noverlap'\n\nexport enum SortDir {\n  Asc = 'asc',\n  Desc = 'desc',\n}\n\nexport type FieldSelector = string // base field or custom field key (prefixed with 'cf:')\n\nexport type Filter = {\n  field: FieldSelector\n  op: FilterOp\n  value?: any\n}\n\nexport type Sort = { field: FieldSelector; dir?: SortDir }\n\nexport type Page = { page?: number; pageSize?: number }\n\n// Mongo/Medusa-style filter operators (typed)\nexport type WhereOps<T> = {\n  $eq?: T\n  $ne?: T | null\n  $gt?: T extends number | Date ? T : never\n  $gte?: T extends number | Date ? T : never\n  $lt?: T extends number | Date ? T : never\n  $lte?: T extends number | Date ? T : never\n  $in?: T[]\n  $nin?: T[]\n  $like?: T extends string ? string : never\n  $ilike?: T extends string ? string : never\n  $exists?: boolean\n  $overlap?: T extends readonly (infer Element)[] ? Element[] : T[]\n  $noverlap?: T extends readonly (infer Element)[] ? Element[] : T[]\n}\n\n// A field filter can be a direct value (equals) or ops object\nexport type WhereValue<T = any> = T | WhereOps<T>\n\n// Generic shape for object filters. If you have a typed map of field\u2192type,\n// pass it as the generic to get end-to-end typing.\n// Example: Where<{\n//   id: string; title: string; created_at: Date; 'cf:severity': number\n// }>\nexport type Where<Fields extends Record<string, any> = Record<string, any>> =\n  Partial<{ [K in keyof Fields]: WhereValue<Fields[K]> }> & Record<string, WhereValue>\n\nexport type QueryCustomFieldJoin = {\n  fromField: string\n  toField: string\n  type?: 'left' | 'inner'\n}\n\nexport type QueryCustomFieldSource = {\n  entityId: EntityId\n  table?: string\n  alias?: string\n  recordIdColumn?: string\n  join?: QueryCustomFieldJoin\n  tenantField?: string\n  organizationField?: string\n}\n\nexport type QueryJoinEdge = {\n  alias: string\n  table?: string\n  entityId?: EntityId\n  from: {\n    alias?: string\n    field: string\n  }\n  to: {\n    field: string\n  }\n  type?: 'left' | 'inner'\n}\n\n/**\n * Optional context for query-level UMES extensions.\n * When provided, the query engine will execute sync lifecycle events\n * (querying/queried) and apply query-enabled enrichers.\n */\nexport type QueryExtensionsConfig = {\n  userId?: string\n  container?: unknown\n  userFeatures?: string[]\n  resolve?: <T = unknown>(name: string) => T\n}\n\nexport type QueryOptions = {\n  fields?: FieldSelector[] // base fields and/or 'cf:<key>' for custom fields\n  includeExtensions?: boolean | string[] // include all registered extensions or only specific ones by entity id\n  includeCustomFields?: boolean | string[] // include all CFs or specific keys\n  // Accept classic array syntax or Mongo-style object syntax\n  filters?: Filter[] | Where\n  sort?: Sort[]\n  page?: Page\n  organizationId?: string // enforce multi-tenant scope\n  tenantId?: string // enforce tenant scope\n  // Optional list of organization ids to scope results. Takes precedence over organizationId.\n  organizationIds?: string[]\n  /**\n   * When true, the engine does not apply default `organization_id` / `tenant_id` equality guards.\n   *\n   * Callers MUST encode full visibility in `filters` (for example with `$or` of scoped branches)\n   * and MUST fail closed when the authenticated principal lacks a resolvable tenant/org, otherwise\n   * queries return cross-tenant rows.\n   *\n   * When this flag is set, the hybrid query engine delegates to the basic engine. The basic engine\n   * still applies `cf:*` filters/sorts, but `search_tokens` fulltext filtering, the JSONB index read\n   * path, and the vector-search branch are BYPASSED. Only use this on entities whose scoping does\n   * not match the standard `organization_id = X AND tenant_id = Y` shape.\n   */\n  omitAutomaticTenantOrgScope?: boolean\n  /**\n   * When `false`, the engine returns encrypted fields as stored (ciphertext) instead of decrypting\n   * them, and performs no DEK lookup at all. Defaults to `true` \u2014 today's behaviour \u2014 so existing\n   * callers are unaffected.\n   *\n   * Use it on generic, entity-agnostic surfaces that select every column and do not need plaintext.\n   * Opting in to decline decryption is not an access control: when decryption DOES run it is bound\n   * to the caller's tenant by `resolveDecryptScope`, which refuses any row whose `tenant_id`\n   * contradicts `tenantId`.\n   *\n   * Caveat: declining also disables the plaintext-sort path, so a `sort` on an encrypted field\n   * degrades to SQL `ORDER BY` over ciphertext \u2014 a meaningless order. Both engines log one warning\n   * when that combination is requested.\n   */\n  decryptEncryptedFields?: boolean\n  // Soft-delete behavior: when false (default), rows with non-null deleted_at\n  // are excluded if the base table has that column. Set true to include them.\n  withDeleted?: boolean\n  customFieldSources?: QueryCustomFieldSource[]\n  joins?: QueryJoinEdge[]\n  profiler?: Profiler\n  // When true, suppress automatic reindex scheduling triggered by coverage gap detection.\n  // Used by the search indexing pipeline to prevent feedback loops where indexing triggers\n  // re-indexing indefinitely.\n  skipAutoReindex?: boolean\n  /**\n   * Force routing this query to custom-entity doc storage (`custom_entities_storage`)\n   * instead of classifying the entity automatically. Automatic classification routes\n   * ids backed by a registered ORM table to that base table, so surfaces that manage\n   * doc records for ids that are ALSO table-backed (e.g. the entities records browser\n   * reading a module-declared custom entity such as `example:todo`) must set this flag.\n   * Honored by the hybrid query engine only; `BasicQueryEngine` has no doc-storage\n   * reader and ignores it.\n   */\n  forceCustomEntityStorage?: boolean\n  // Optional UMES query extensions context. When provided, the engine will\n  // emit sync lifecycle events and apply query-level enrichers.\n  extensions?: QueryExtensionsConfig\n}\n\nexport type PartialIndexWarning = {\n  entity: EntityId\n  entityLabel?: string | null\n  baseCount?: number | null\n  indexedCount?: number | null\n  scope?: 'scoped' | 'global'\n}\n\nexport type EncryptedSortRowCapWarning = {\n  entity: EntityId\n  sortFields: string[]\n  maxRows: number\n  /**\n   * Exact when `meta.listCountCapWarning` is absent; a floor when it is\n   * present (the list total itself was bounded at the cap).\n   */\n  totalMatched: number\n}\n\n/**\n * Present when the list COUNT was bounded at `cap` matching rows\n * (`OM_LIST_COUNT_CAP`): `total` is a floor, not an exact value. Surfaced on\n * CRUD list payloads as `totalIsCapped: true`.\n */\nexport type ListCountCapWarning = {\n  entity: EntityId\n  cap: number\n}\n\nexport type QueryResultMeta = {\n  partialIndexWarning?: PartialIndexWarning\n  encryptedSortRowCapWarning?: EncryptedSortRowCapWarning\n  listCountCapWarning?: ListCountCapWarning\n}\n\nexport type QueryResult<T = any> = {\n  items: T[]\n  page: number\n  pageSize: number\n  total: number\n  meta?: QueryResultMeta\n  /**\n   * Custom-field definitions the engine resolved while building this result\n   * (only present when `includeCustomFields: true`). Lets the CRUD factory\n   * decorate list rows without reloading definitions from the DB (issue #2133).\n   * Internal contract \u2014 additive and optional; callers must treat absence as a\n   * cue to load definitions themselves.\n   */\n  customFieldDefinitions?: ResolvedCustomFieldDefinitions\n}\n\nexport interface QueryEngine {\n  query<T = any>(entity: EntityId, opts?: QueryOptions): Promise<QueryResult<T>>\n}\n"],
   "mappings": "AAgBO,IAAK,UAAL,kBAAKA,aAAL;AACL,EAAAA,SAAA,SAAM;AACN,EAAAA,SAAA,UAAO;AAFG,SAAAA;AAAA,GAAA;",
   "names": ["SortDir"]
 }

package/dist/lib/version.js

@@ -1,4 +1,4 @@
-const APP_VERSION = "0.10.1-develop.7679.1.cb2c13f49e";
+const APP_VERSION = "0.10.1-develop.7687.1.e1a6f9de51";
 const appVersion = APP_VERSION;
 export {
   APP_VERSION,

package/dist/lib/version.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/lib/version.ts"],
-  "sourcesContent": ["// Build-time generated version\nexport const APP_VERSION = '0.10.1-develop.7679.1.cb2c13f49e';\nexport const appVersion = APP_VERSION;\n"],
+  "sourcesContent": ["// Build-time generated version\nexport const APP_VERSION = '0.10.1-develop.7687.1.e1a6f9de51';\nexport const appVersion = APP_VERSION;\n"],
   "mappings": "AACO,MAAM,cAAc;AACpB,MAAM,aAAa;",
   "names": []
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/shared",
-  "version": "0.10.1-develop.7679.1.cb2c13f49e",
+  "version": "0.10.1-develop.7687.1.e1a6f9de51",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
@@ -126,7 +126,7 @@
     "@mikro-orm/core": "^7.1.14",
     "@mikro-orm/decorators": "^7.1.14",
     "@mikro-orm/postgresql": "^7.1.14",
-    "@open-mercato/cache": "0.10.1-develop.7679.1.cb2c13f49e",
+    "@open-mercato/cache": "0.10.1-develop.7687.1.e1a6f9de51",
     "@types/html-to-text": "^9.0.4",
     "@types/sanitize-html": "^2.16.1",
     "dotenv": "^17.4.2",

package/src/lib/crud/__tests__/crud-factory.test.ts

@@ -586,6 +586,22 @@ describe('CRUD Factory', () => {
     } as any,
   })
 
+  it('GET forwards list.decryptEncryptedFields=false to the query engine (#5430)', async () => {
+    await makeSortedRoute({ decryptEncryptedFields: false }).GET(
+      new Request('http://x/api/example/todos?page=1&pageSize=10'),
+    )
+
+    const queryArgs = queryEngine.query.mock.calls.at(-1)?.[1]
+    expect(queryArgs?.decryptEncryptedFields).toBe(false)
+  })
+
+  it('GET leaves decryptEncryptedFields unset when the list does not opt out', async () => {
+    await makeSortedRoute().GET(new Request('http://x/api/example/todos?page=1&pageSize=10'))
+
+    const queryArgs = queryEngine.query.mock.calls.at(-1)?.[1]
+    expect(queryArgs?.decryptEncryptedFields).toBeUndefined()
+  })
+
   it('GET falls back to sorting by id when no default sort is configured', async () => {
     await makeSortedRoute().GET(new Request('http://x/api/example/todos?page=1&pageSize=10'))
 

package/src/lib/crud/factory.ts

@@ -271,6 +271,16 @@ export type ListConfig<TList> = {
    * filters/sorts, `search_tokens` fulltext filtering, and vector-search branches are bypassed.
    */
   omitAutomaticTenantOrgScope?: boolean
+  /**
+   * When false, the query engine returns encrypted fields as stored (ciphertext) and performs no
+   * DEK lookup. Defaults to true — today's behaviour. Set it on generic, entity-agnostic list
+   * surfaces that select every column and do not need plaintext.
+   *
+   * Caveat: declining also disables the plaintext-sort path, so a sort on an encrypted field
+   * degrades to SQL `ORDER BY` over ciphertext. The query engine logs one warning when that
+   * combination is requested.
+   */
+  decryptEncryptedFields?: boolean
   /** When true, skip server-side CRUD GET cache for this list (avoids stale empty payloads after mutations). */
   disableListCache?: boolean
 }
@@ -1977,6 +1987,9 @@ export function makeCrudRoute<TCreate = any, TUpdate = any, TList = any>(opts: C
         if (opts.list.omitAutomaticTenantOrgScope) {
           queryOpts.omitAutomaticTenantOrgScope = true
         }
+        if (opts.list.decryptEncryptedFields === false) {
+          queryOpts.decryptEncryptedFields = false
+        }
         const queryEntity = String(opts.list.entityId)
         profiler.mark('query_options_ready')
         const queryProfiler = profiler.child('query_engine', { entity: queryEntity })

package/src/lib/encryption/__tests__/decrypt-scope.test.ts

@@ -0,0 +1,134 @@
+import {
+  DecryptRefusalTally,
+  resolveDecryptEnabled,
+  resolveDecryptScope,
+} from '../decryptScope'
+
+describe('resolveDecryptScope', () => {
+  test('decrypts when the row tenant matches the caller tenant', () => {
+    const decision = resolveDecryptScope({
+      rowTenantId: 't1',
+      rowOrganizationId: 'org1',
+      callerTenantId: 't1',
+      callerOrganizationId: 'org9',
+    })
+    expect(decision).toEqual({ decrypt: true, tenantId: 't1', organizationId: 'org1' })
+  })
+
+  test('refuses when the row tenant contradicts the caller tenant', () => {
+    const decision = resolveDecryptScope({
+      rowTenantId: 't2',
+      rowOrganizationId: 'org1',
+      callerTenantId: 't1',
+      callerOrganizationId: 'org1',
+    })
+    expect(decision).toEqual({
+      decrypt: false,
+      reason: 'tenant-mismatch',
+      rowTenantId: 't2',
+      callerTenantId: 't1',
+    })
+  })
+
+  test('falls back to the caller scope when the row carries no tenant', () => {
+    const decision = resolveDecryptScope({
+      rowTenantId: null,
+      rowOrganizationId: null,
+      callerTenantId: 't1',
+      callerOrganizationId: 'org1',
+    })
+    expect(decision).toEqual({ decrypt: true, tenantId: 't1', organizationId: 'org1' })
+  })
+
+  test('keeps the row tenant for a deliberate cross-tenant read that asserts no caller tenant', () => {
+    const decision = resolveDecryptScope({
+      rowTenantId: 't2',
+      rowOrganizationId: 'org2',
+      callerTenantId: null,
+      callerOrganizationId: null,
+    })
+    expect(decision).toEqual({ decrypt: true, tenantId: 't2', organizationId: 'org2' })
+  })
+
+  test('resolves a null scope when neither side carries ids', () => {
+    const decision = resolveDecryptScope({})
+    expect(decision).toEqual({ decrypt: true, tenantId: null, organizationId: null })
+  })
+
+  test('never refuses on an organization mismatch alone', () => {
+    const decision = resolveDecryptScope({
+      rowTenantId: 't1',
+      rowOrganizationId: 'org2',
+      callerTenantId: 't1',
+      callerOrganizationId: 'org1',
+    })
+    expect(decision).toEqual({ decrypt: true, tenantId: 't1', organizationId: 'org2' })
+  })
+
+  test('prefers the row organization and falls back to the caller organization', () => {
+    expect(resolveDecryptScope({ rowTenantId: 't1', callerTenantId: 't1', callerOrganizationId: 'org1' }))
+      .toEqual({ decrypt: true, tenantId: 't1', organizationId: 'org1' })
+  })
+})
+
+describe('resolveDecryptEnabled', () => {
+  test('defaults to decrypting, so existing callers are unaffected', () => {
+    expect(resolveDecryptEnabled({})).toBe(true)
+    expect(resolveDecryptEnabled({ decryptEncryptedFields: undefined })).toBe(true)
+  })
+
+  test('only an explicit false declines decryption', () => {
+    expect(resolveDecryptEnabled({ decryptEncryptedFields: false })).toBe(false)
+    expect(resolveDecryptEnabled({ decryptEncryptedFields: true })).toBe(true)
+  })
+})
+
+describe('DecryptRefusalTally', () => {
+  const refusal = (rowTenantId: string, callerTenantId = 't1') =>
+    ({ decrypt: false, reason: 'tenant-mismatch', rowTenantId, callerTenantId }) as const
+
+  test('starts empty', () => {
+    expect(new DecryptRefusalTally().refused).toBe(0)
+  })
+
+  test('counts every refusal but samples a bounded set of row tenant ids', () => {
+    const tally = new DecryptRefusalTally()
+    for (const tenant of ['t2', 't3', 't4', 't5', 't6']) tally.record(refusal(tenant))
+    expect(tally.refused).toBe(5)
+    const context = tally.toLogContext('customers:customer')
+    expect(context.refusedRows).toBe(5)
+    expect(context.callerTenantId).toBe('t1')
+    expect(context.rowTenantIds).toEqual(['t2', 't3', 't4'])
+  })
+
+  // The plaintext-sort path decrypts an overlapping row set twice (candidate scan, then page
+  // rows), so counting both passes overstated the refusal count by up to a page.
+  test('counts a row once however many times it is recorded', () => {
+    const tally = new DecryptRefusalTally()
+    tally.record(refusal('t2'), 'row-1')
+    tally.record(refusal('t3'), 'row-2')
+    tally.record(refusal('t2'), 'row-1')
+    expect(tally.refused).toBe(2)
+    expect(tally.toLogContext('customers:customer').refusedRows).toBe(2)
+  })
+
+  test('counts rows recorded without an id individually', () => {
+    const tally = new DecryptRefusalTally()
+    tally.record(refusal('t2'))
+    tally.record(refusal('t2'), null)
+    tally.record(refusal('t2'), '')
+    tally.record(refusal('t2'), 'row-1')
+    expect(tally.refused).toBe(4)
+  })
+
+  test('log context carries ids only — never row values', () => {
+    const tally = new DecryptRefusalTally()
+    tally.record(refusal('t2'))
+    expect(Object.keys(tally.toLogContext('customers:customer')).sort()).toEqual([
+      'callerTenantId',
+      'entity',
+      'refusedRows',
+      'rowTenantIds',
+    ])
+  })
+})

package/src/lib/encryption/__tests__/subscriber.onload-tenant-binding.test.ts

@@ -0,0 +1,234 @@
+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 }) }
+})
+
+jest.mock('../likeFilterWarning', () => ({ warnOnEncryptedLikeFilter: jest.fn(async () => undefined) }))
+
+import { ReferenceKind } from '@mikro-orm/core'
+import { TenantEncryptionSubscriber } from '../subscriber'
+import { findAndCountWithDecryption, findOneWithDecryption, findWithDecryption } from '../find'
+import { DECRYPT_REFUSAL_LOG_MESSAGE } from '../decryptScope'
+import { registerEntityIds } from '../entityIds'
+import type { TenantDataEncryptionService } from '../tenantDataEncryptionService'
+
+// The ORM half of #5430 as it runs in production: `em.find` hydrates entities and fires the
+// registered subscriber's `onLoad` BEFORE `find*WithDecryption` gets to apply the caller's scope.
+// The fake EntityManager below mirrors that order, including an async gap before hydration, so a
+// binding that only engages after `em.find` returns cannot pass.
+
+const CHILD_META = { className: 'Child', tableName: 'children', properties: {} } as any
+
+const LINK_META = {
+  className: 'Link',
+  tableName: 'links',
+  properties: { child: { name: 'child', kind: ReferenceKind.MANY_TO_ONE } },
+} as any
+
+type Call = { entityId: string; tenantId: string | null }
+
+function makeService(calls: Call[]): TenantDataEncryptionService {
+  return {
+    isEnabled: () => true,
+    async decryptEntityPayload(entityId: string, target: Record<string, unknown>, tenantId: string | null) {
+      calls.push({ entityId, tenantId })
+      const value = target.secret
+      if (typeof value === 'string' && value.startsWith('enc:')) return { secret: value.slice('enc:'.length) }
+      return {}
+    },
+  } as unknown as TenantDataEncryptionService
+}
+
+function makeHydratingEm(subscriber: TenantEncryptionSubscriber, rows: Array<Record<string, unknown>>) {
+  const hydrate = async () => {
+    await new Promise((resolve) => setImmediate(resolve))
+    for (const row of rows) {
+      await subscriber.onLoad({ entity: row, meta: row.__meta, em } as any)
+    }
+  }
+  const em = {
+    getMetadata: () => undefined,
+    getComparator: () => undefined,
+    async find() {
+      await hydrate()
+      return rows
+    },
+    async findOne() {
+      await hydrate()
+      return rows[0] ?? null
+    },
+    async findAndCount() {
+      await hydrate()
+      return [rows, rows.length]
+    },
+  }
+  return em
+}
+
+const refusalWarnings = () => warnMock.mock.calls.filter(([message]) => message === DECRYPT_REFUSAL_LOG_MESSAGE)
+
+describe('find*WithDecryption tenant binding through the ORM onLoad hook (#5430)', () => {
+  const originalToggle = process.env.TENANT_DATA_ENCRYPTION
+
+  beforeEach(() => {
+    warnMock.mockClear()
+    delete process.env.TENANT_DATA_ENCRYPTION
+    registerEntityIds({ test: { child: 'test:child', link: 'test:link' } })
+  })
+
+  afterEach(() => {
+    if (originalToggle === undefined) delete process.env.TENANT_DATA_ENCRYPTION
+    else process.env.TENANT_DATA_ENCRYPTION = originalToggle
+  })
+
+  it('refuses a foreign-tenant entity during hydration and reports the read once', async () => {
+    const calls: Call[] = []
+    const service = makeService(calls)
+    const own = { id: 'own', secret: 'enc:alpha', tenantId: 'tenant-a', __meta: CHILD_META }
+    const foreignOne = { id: 'f1', secret: 'enc:beta', tenantId: 'tenant-b', __meta: CHILD_META }
+    const foreignTwo = { id: 'f2', secret: 'enc:gamma', tenantId: 'tenant-b', __meta: CHILD_META }
+    const em = makeHydratingEm(new TenantEncryptionSubscriber(service), [own, foreignOne, foreignTwo])
+
+    await findWithDecryption(em as any, 'Child' as any, {}, undefined, {
+      tenantId: 'tenant-a',
+      organizationId: null,
+      encryptionService: service,
+    })
+
+    expect(calls.every((call) => call.tenantId === 'tenant-a')).toBe(true)
+    expect(own.secret).toBe('alpha')
+    expect(foreignOne.secret).toBe('enc:beta')
+    expect(foreignTwo.secret).toBe('enc:gamma')
+    expect(refusalWarnings()).toHaveLength(1)
+    expect(refusalWarnings()[0][1]).toMatchObject({ entity: 'test:child', refusedRows: 2, callerTenantId: 'tenant-a' })
+  })
+
+  it('applies the binding to findOne and findAndCount reads as well', async () => {
+    const calls: Call[] = []
+    const service = makeService(calls)
+    const foreign = { id: 'f1', secret: 'enc:beta', tenantId: 'tenant-b', __meta: CHILD_META }
+    const subscriber = new TenantEncryptionSubscriber(service)
+    const scope = { tenantId: 'tenant-a', organizationId: null, encryptionService: service }
+
+    await findOneWithDecryption(makeHydratingEm(subscriber, [foreign]) as any, 'Child' as any, {}, undefined, scope)
+    await findAndCountWithDecryption(makeHydratingEm(subscriber, [foreign]) as any, 'Child' as any, {}, undefined, scope)
+
+    expect(calls).toEqual([])
+    expect(foreign.secret).toBe('enc:beta')
+  })
+
+  it('keeps decrypting with the row tenant when the read asserts no tenant', async () => {
+    const calls: Call[] = []
+    const service = makeService(calls)
+    const foreign = { id: 'f1', secret: 'enc:beta', tenantId: 'tenant-b', __meta: CHILD_META }
+    const em = makeHydratingEm(new TenantEncryptionSubscriber(service), [foreign])
+
+    await findWithDecryption(em as any, 'Child' as any, {}, undefined, { encryptionService: service })
+
+    expect(calls[0]).toEqual({ entityId: 'test:child', tenantId: 'tenant-b' })
+    expect(foreign.secret).toBe('beta')
+    expect(refusalWarnings()).toHaveLength(0)
+  })
+
+  it('does not hand an outer read scope to a nested read that asserts none', async () => {
+    const calls: Call[] = []
+    const service = makeService(calls)
+    const subscriber = new TenantEncryptionSubscriber(service)
+    const foreign = { id: 'f1', secret: 'enc:beta', tenantId: 'tenant-b', __meta: CHILD_META }
+    const outerEm = makeHydratingEm(subscriber, [])
+    outerEm.find = async () => {
+      await findWithDecryption(makeHydratingEm(subscriber, [foreign]) as any, 'Child' as any, {}, undefined, {
+        encryptionService: service,
+      })
+      return []
+    }
+
+    await findWithDecryption(outerEm as any, 'Child' as any, {}, undefined, {
+      tenantId: 'tenant-a',
+      encryptionService: service,
+    })
+
+    expect(calls).toEqual([
+      { entityId: 'test:child', tenantId: 'tenant-b' },
+      { entityId: 'test:child', tenantId: 'tenant-b' },
+    ])
+    expect(foreign.secret).toBe('beta')
+  })
+
+  it('does not bind the caller scope outside the read that asserted it', async () => {
+    const calls: Call[] = []
+    const subscriber = new TenantEncryptionSubscriber(makeService(calls))
+    const foreign = { id: 'f1', secret: 'enc:beta', tenantId: 'tenant-b', __meta: CHILD_META }
+
+    await subscriber.onLoad({ entity: foreign, meta: CHILD_META, em: makeHydratingEm(subscriber, []) } as any)
+
+    expect(calls).toEqual([{ entityId: 'test:child', tenantId: 'tenant-b' }])
+    expect(foreign.secret).toBe('beta')
+  })
+})
+
+describe('relation scope inherited from a tenant-less parent (#5430)', () => {
+  const originalToggle = process.env.TENANT_DATA_ENCRYPTION
+
+  beforeEach(() => {
+    warnMock.mockClear()
+    delete process.env.TENANT_DATA_ENCRYPTION
+    registerEntityIds({ test: { child: 'test:child', link: 'test:link' } })
+  })
+
+  afterEach(() => {
+    if (originalToggle === undefined) delete process.env.TENANT_DATA_ENCRYPTION
+    else process.env.TENANT_DATA_ENCRYPTION = originalToggle
+  })
+
+  it('does not refuse a relation of a tenant-less parent against the caller tenant', async () => {
+    const calls: Call[] = []
+    const child = { id: 'c1', secret: 'enc:beta', tenantId: 'tenant-b', __meta: CHILD_META }
+    const link = { id: 'l1', child: { isInitialized: () => true, unwrap: () => child }, __meta: LINK_META }
+
+    await new TenantEncryptionSubscriber(makeService(calls)).decryptEntityGraph(link, LINK_META, undefined, {
+      syncOriginal: true,
+      fallbackScope: { tenantId: 'tenant-a', organizationId: null },
+    })
+
+    expect(calls).toContainEqual({ entityId: 'test:child', tenantId: 'tenant-b' })
+    expect(child.secret).toBe('beta')
+    expect(refusalWarnings()).toHaveLength(0)
+  })
+
+  it('still keys a tenant-less relation of a tenant-less parent off the caller tenant', async () => {
+    const calls: Call[] = []
+    const child = { id: 'c1', secret: 'enc:beta', __meta: CHILD_META }
+    const link = { id: 'l1', child: { isInitialized: () => true, unwrap: () => child }, __meta: LINK_META }
+
+    await new TenantEncryptionSubscriber(makeService(calls)).decryptEntityGraph(link, LINK_META, undefined, {
+      syncOriginal: true,
+      fallbackScope: { tenantId: 'tenant-a', organizationId: null },
+    })
+
+    expect(calls).toContainEqual({ entityId: 'test:child', tenantId: 'tenant-a' })
+    expect(child.secret).toBe('beta')
+  })
+
+  it('keeps binding a relation reached through a parent of the caller tenant', async () => {
+    const calls: Call[] = []
+    const child = { id: 'c1', secret: 'enc:beta', tenantId: 'tenant-b', __meta: CHILD_META }
+    const link = {
+      id: 'l1',
+      tenantId: 'tenant-a',
+      child: { isInitialized: () => true, unwrap: () => child },
+      __meta: LINK_META,
+    }
+
+    await new TenantEncryptionSubscriber(makeService(calls)).decryptEntityGraph(link, LINK_META, undefined, {
+      syncOriginal: true,
+      fallbackScope: { tenantId: 'tenant-a', organizationId: null },
+    })
+
+    expect(calls.some((call) => call.entityId === 'test:child')).toBe(false)
+    expect(child.secret).toBe('enc:beta')
+    expect(refusalWarnings()).toHaveLength(1)
+  })
+})

package/src/lib/encryption/__tests__/subscriber.refusal-aggregation.test.ts

@@ -0,0 +1,105 @@
+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 { decryptEntitiesWithFallbackScope, TenantEncryptionSubscriber } from '../subscriber'
+import { DECRYPT_REFUSAL_LOG_MESSAGE } from '../decryptScope'
+import { registerEntityIds } from '../entityIds'
+import type { TenantDataEncryptionService } from '../tenantDataEncryptionService'
+
+// A mis-scoped `findWithDecryption` refuses its whole result list. The docs promise one aggregated
+// warning per read; the ORM path used to emit one line per entity, so a page of 500 foreign rows
+// produced 500 warnings.
+
+const CHILD_META = { className: 'Child', tableName: 'children', properties: {} } as any
+
+const makeEm = () => ({ getMetadata: () => undefined, getComparator: () => undefined })
+
+const makeService = (): TenantDataEncryptionService =>
+  ({
+    isEnabled: () => true,
+    async decryptEntityPayload(_entityId: string, target: Record<string, unknown>) {
+      const value = target.secret
+      if (typeof value === 'string' && value.startsWith('enc:')) return { secret: value.slice('enc:'.length) }
+      return {}
+    },
+  }) as unknown as TenantDataEncryptionService
+
+const refusalWarnings = () => warnMock.mock.calls.filter(([message]) => message === DECRYPT_REFUSAL_LOG_MESSAGE)
+
+describe('ORM decrypt-refusal aggregation (#5430)', () => {
+  const originalToggle = process.env.TENANT_DATA_ENCRYPTION
+
+  beforeEach(() => {
+    warnMock.mockClear()
+    delete process.env.TENANT_DATA_ENCRYPTION
+    registerEntityIds({ test: { child: 'test:child' } })
+  })
+
+  afterEach(() => {
+    if (originalToggle === undefined) delete process.env.TENANT_DATA_ENCRYPTION
+    else process.env.TENANT_DATA_ENCRYPTION = originalToggle
+  })
+
+  it('emits one warning for a whole refused batch, not one per entity', async () => {
+    const entities = ['tenant-b', 'tenant-c', 'tenant-d', 'tenant-e'].map((tenantId, index) => ({
+      id: `row-${index}`,
+      secret: 'enc:alpha',
+      tenantId,
+      __meta: CHILD_META,
+    }))
+
+    await decryptEntitiesWithFallbackScope(entities, {
+      em: makeEm() as any,
+      tenantId: 'tenant-a',
+      encryptionService: makeService(),
+    })
+
+    const warnings = refusalWarnings()
+    expect(warnings).toHaveLength(1)
+    expect(warnings[0][1]).toEqual({
+      entity: 'test:child',
+      refusedRows: 4,
+      callerTenantId: 'tenant-a',
+      rowTenantIds: ['tenant-b', 'tenant-c', 'tenant-d'],
+    })
+    for (const entity of entities) expect(entity.secret).toBe('enc:alpha')
+  })
+
+  it('emits no warning when the batch is correctly scoped', async () => {
+    const entities = [
+      { id: 'row-0', secret: 'enc:alpha', tenantId: 'tenant-a', __meta: CHILD_META },
+      { id: 'row-1', secret: 'enc:beta', tenantId: 'tenant-a', __meta: CHILD_META },
+    ]
+
+    await decryptEntitiesWithFallbackScope(entities, {
+      em: makeEm() as any,
+      tenantId: 'tenant-a',
+      encryptionService: makeService(),
+    })
+
+    expect(refusalWarnings()).toHaveLength(0)
+    expect(entities.map((entity) => entity.secret)).toEqual(['alpha', 'beta'])
+  })
+
+  it('still reports immediately for a single-entity call that takes no tally', async () => {
+    const entity = { id: 'row-0', secret: 'enc:alpha', tenantId: 'tenant-b', __meta: CHILD_META }
+
+    await new TenantEncryptionSubscriber(makeService()).decryptEntityGraph(entity, CHILD_META, makeEm() as any, {
+      syncOriginal: true,
+      fallbackScope: { tenantId: 'tenant-a', organizationId: null },
+    })
+
+    const warnings = refusalWarnings()
+    expect(warnings).toHaveLength(1)
+    expect(warnings[0][1]).toEqual({
+      entity: 'test:child',
+      refusedRows: 1,
+      callerTenantId: 'tenant-a',
+      rowTenantIds: ['tenant-b'],
+    })
+  })
+})