@open-mercato/core 0.10.1-develop.7752.1.fd7c06569b → 0.10.1-develop.7756.1.8f5dec1b96

package/src/modules/auth/services/rbacService.ts

@@ -1,7 +1,7 @@
 import type { EntityManager, FilterQuery } from '@mikro-orm/postgresql'
 import type { CacheStrategy } from '@open-mercato/cache'
 import { getCurrentCacheTenant, runWithCacheTenant } from '@open-mercato/cache'
-import { UserAcl, RoleAcl, User, UserRole } from '@open-mercato/core/modules/auth/data/entities'
+import { UserAcl, RoleAcl, Role, User, UserRole } from '@open-mercato/core/modules/auth/data/entities'
 import { ApiKey } from '@open-mercato/core/modules/api_keys/data/entities'
 import { isSessionBoundApiKey, resolveApiKeyRoleIds } from '@open-mercato/core/modules/api_keys/services/sessionKeyRoles'
 import { Organization } from '@open-mercato/core/modules/directory/data/entities'
@@ -14,6 +14,9 @@ import {
 } from '@open-mercato/shared/security/featurePolicy'
 import { filterGrantsByEnabledModules } from '@open-mercato/shared/security/enabledModulesRegistry'
 import { resolveRoleOrganizationScope, roleAclAllowsOrganization } from './roleOrganizationScope'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+
+const logger = createLogger('auth.rbac')
 
 interface AclData {
   isSuperAdmin: boolean
@@ -381,39 +384,89 @@ export class RbacService {
     }
   }
 
-  private async isGlobalSuperAdmin(userId: string): Promise<boolean> {
-    if (this.globalSuperAdminCache.has(userId)) return this.globalSuperAdminCache.get(userId)!
-    const em = this.em.fork()
-    const userSuper = await em.findOne(UserAcl, { user: userId as any, isSuperAdmin: true })
-    if (userSuper && (userSuper as any).isSuperAdmin) {
-      this.globalSuperAdminCache.set(userId, true)
+  // A super-admin grant is deliberately GLOBAL: it survives every scope the
+  // caller asks about, which is what lets a platform super-admin work inside a
+  // customer tenant. What it must not do is survive the question of whose grant
+  // it is. Both lookups below are therefore evaluated against the user's OWN
+  // tenant (`users.tenant_id`), never against no tenant at all.
+  //
+  // Without that binding a single `user_acls` row — or a role link — stamped
+  // with ANY tenant confers platform super-admin everywhere, so a row written
+  // under the wrong tenant becomes a full privilege escalation with nothing in
+  // the schema or the UI to show for it. `user_acls` has no organization column
+  // and no uniqueness beyond its primary key, so such a row is cheap to create
+  // and invisible to the tenant/organization cross-wire checks.
+  //
+  // This is the tenant binding `resolveCanonicalStaffAuthContext` already
+  // applies when it computes `auth.isSuperAdmin` (see lib/sessionIntegrity.ts:
+  // `userAclGrantsSuperAdmin` / `roleAclGrantsSuperAdmin`, both bound to the
+  // user's own tenant). Before this change the two authorities disagreed:
+  // session integrity would say "not a super-admin" while `loadAcl` handed the
+  // same request `['*']`.
+  //
+  // The memo stays keyed by `userId` alone because the answer now depends only
+  // on the user's own tenant, which is a property of the user — not on the scope
+  // being asked about. `invalidateUserCache` therefore still clears it correctly.
+  private async isGlobalSuperAdmin(
+    em: EntityManager,
+    userId: string,
+    userTenantId: string | null,
+    useCache = true,
+  ): Promise<boolean> {
+    if (useCache && this.globalSuperAdminCache.has(userId)) return this.globalSuperAdminCache.get(userId)!
+    if (!userTenantId) {
+      logger.warn('Tenant-less principal cannot receive super-admin grants; assign an owning tenant before upgrading', { userId })
+      if (useCache) this.globalSuperAdminCache.set(userId, false)
+      return false
+    }
+    const userSuper = await em.findOne(UserAcl, {
+      user: userId as unknown as User,
+      tenantId: userTenantId,
+      isSuperAdmin: true,
+      deletedAt: null,
+    } as FilterQuery<UserAcl>)
+    if (userSuper?.isSuperAdmin) {
+      if (useCache) this.globalSuperAdminCache.set(userId, true)
       return true
     }
     const links = await findWithDecryption(
       em,
       UserRole,
-      { user: userId as any },
+      // Roles that belong to the user's own tenant, as
+      // `resolveCanonicalStaffAuthContext` already requires. The encryption
+      // scope stays `{ null, null }` as before — this change is about which rows
+      // count, not about which key decrypts them.
+      {
+        user: userId as unknown as User,
+        deletedAt: null,
+        role: { tenantId: userTenantId, deletedAt: null },
+      } as FilterQuery<UserRole>,
       { populate: ['role'] },
       { tenantId: null, organizationId: null },
     )
     const linkList = Array.isArray(links) ? links : []
     if (!linkList.length) {
-      this.globalSuperAdminCache.set(userId, false)
+      if (useCache) this.globalSuperAdminCache.set(userId, false)
       return false
     }
     const roleIds = Array.from(new Set(linkList.map((link) => {
-      const role = link.role as any
+      const role = link.role
       return role?.id ? String(role.id) : null
     }).filter((id): id is string => typeof id === 'string' && id.length > 0)))
     if (!roleIds.length) {
-      this.globalSuperAdminCache.set(userId, false)
+      if (useCache) this.globalSuperAdminCache.set(userId, false)
       return false
     }
-    const roleSupers = await em.find(RoleAcl, { isSuperAdmin: true, role: { $in: roleIds as any } } as any)
+    const roleSupers = await em.find(RoleAcl, {
+      isSuperAdmin: true,
+      tenantId: userTenantId,
+      deletedAt: null,
+      role: { $in: roleIds as unknown as Role[] },
+    } as FilterQuery<RoleAcl>)
     const result = roleSupers.some((roleAcl) => (
       !!roleAcl.isSuperAdmin && !isRestrictedRoleAcl(roleAcl)
     ))
-    this.globalSuperAdminCache.set(userId, result)
+    if (useCache) this.globalSuperAdminCache.set(userId, result)
     return result
   }
 
@@ -447,18 +500,6 @@ export class RbacService {
     const cached = userId.startsWith('api_key:') ? null : await this.getFromCache(cacheKey)
     if (cached) return cached
 
-    // Direct user-level super-admin grants and unrestricted role-level
-    // super-admin grants are global. Organization-restricted role grants are
-    // deliberately excluded by isGlobalSuperAdmin and continue through the
-    // scoped ACL projection below.
-    if (!userId.startsWith('api_key:')) {
-      if (await this.isGlobalSuperAdmin(userId)) {
-        const result = { isSuperAdmin: true, features: ['*'], organizations: null }
-        await this.setCache(cacheKey, result, userId, scope)
-        return result
-      }
-    }
-
     if (userId.startsWith('api_key:')) {
       const apiKeyId = userId.slice('api_key:'.length)
       const em = this.em.fork()
@@ -489,7 +530,11 @@ export class RbacService {
           tenantId,
           evaluatedOrganizationId,
         )
-        const racls = await em.find(RoleAcl, { tenantId, role: { $in: roleIds as any } } as any)
+        const racls = await em.find(RoleAcl, {
+          tenantId,
+          deletedAt: null,
+          role: { $in: roleIds as unknown as Role[], deletedAt: null },
+        } as FilterQuery<RoleAcl>)
         for (const acl of racls) {
           if (roleAclAllowsOrganization(acl, roleOrganizationScope)) {
             isSuper = isSuper || !!acl.isSuperAdmin
@@ -552,6 +597,23 @@ export class RbacService {
       await this.setCache(cacheKey, result, userId, scope)
       return result
     }
+
+    // Direct user-level super-admin grants and unrestricted role-level
+    // super-admin grants are global. Organization-restricted role grants are
+    // deliberately excluded by isGlobalSuperAdmin and continue through the
+    // scoped ACL projection below.
+    //
+    // The check runs AFTER the user is loaded because it is evaluated against
+    // the user's own tenant — see isGlobalSuperAdmin. It reuses that load and
+    // that EntityManager rather than issuing its own, so the reordering costs
+    // no extra query. API-key principals never reached it and still do not:
+    // their branch above has already returned.
+    if (await this.isGlobalSuperAdmin(em, userId, user.tenantId ?? null)) {
+      const result = { isSuperAdmin: true, features: ['*'], organizations: null }
+      await this.setCache(cacheKey, result, userId, scope)
+      return result
+    }
+
     const tenantId = scope.tenantId || user.tenantId || null
     const orgId = scope.organizationId || user.organizationId || null
 
@@ -561,8 +623,25 @@ export class RbacService {
       return result
     }
 
-    // Per-user ACL first
-    const uacl = await em.findOne(UserAcl, { user: userId as any, tenantId })
+    // Per-user ACL first. This row REPLACES the role ACLs rather than merging
+    // with them, so which row is returned decides the whole feature set. A
+    // partial unique index now makes a second live row impossible
+    // (`user_acls_active_unique_idx`, Migration20260828120000_auth), but the
+    // ordering is stated anyway: an index can be dropped by an operator, and an
+    // unordered `findOne` over a table that used to allow duplicates is exactly
+    // the read this pairs with. Soft-deleted rows are excluded — a revoked
+    // override must not keep answering.
+    const uacl = await em.findOne(
+      UserAcl,
+      { user: userId as unknown as User, tenantId, deletedAt: null } as FilterQuery<UserAcl>,
+      // `createdAt`/`id`, not `updatedAt`: `updated_at` is nullable and Postgres
+      // sorts NULLs FIRST under DESC, so ordering by it would prefer a row that
+      // was never updated. The migration's one-time collapse uses
+      // `coalesce(updated_at, created_at)` because there it is picking the row
+      // an operator would call current; here the only requirement is that the
+      // answer not vary between requests.
+      { orderBy: { createdAt: 'desc', id: 'desc' } } as const,
+    )
     if (uacl) {
       const result = {
         isSuperAdmin: !!uacl.isSuperAdmin,
@@ -577,12 +656,18 @@ export class RbacService {
     const links = await findWithDecryption(
       em,
       UserRole,
-      { user: userId as any, role: { tenantId } } as any,
+      {
+        user: userId as unknown as User,
+        deletedAt: null,
+        role: { tenantId, deletedAt: null },
+      } as FilterQuery<UserRole>,
       { populate: ['role'] },
       { tenantId, organizationId: orgId },
     )
     const linkList = Array.isArray(links) ? links : []
-    const roleIds = linkList.map((l) => (l.role as any)?.id).filter(Boolean)
+    const roleIds = linkList
+      .map((link) => link.role?.id ? String(link.role.id) : null)
+      .filter((roleId): roleId is string => roleId !== null)
     let isSuper = false
     const features: string[] = []
     let organizations: string[] | null = []
@@ -593,7 +678,11 @@ export class RbacService {
         tenantId,
         scope.organizationId,
       )
-      const racls = await em.find(RoleAcl, { tenantId, role: { $in: roleIds as any } } as any, {})
+      const racls = await em.find(RoleAcl, {
+        tenantId,
+        deletedAt: null,
+        role: { $in: roleIds as unknown as Role[] },
+      } as FilterQuery<RoleAcl>, {})
       const roleAcls = Array.isArray(racls) ? racls : []
       for (const r of roleAcls) {
         if (roleAclAllowsOrganization(r, roleOrganizationScope)) {
@@ -662,7 +751,7 @@ export class RbacService {
         evaluatedOrganizationId,
       )
       const roleAcls = tenantId && roleIds.length
-        ? await em.find(RoleAcl, { tenantId, role: { $in: roleIds as never } } as never)
+        ? await em.find(RoleAcl, { tenantId, deletedAt: null, role: { $in: roleIds as never, deletedAt: null } } as never)
         : []
       let isSuperAdmin = false
       const features: string[] = []
@@ -709,43 +798,22 @@ export class RbacService {
       return { isSuperAdmin: isSuperAdmin && organizations === null, features, organizations }
     }
 
-    const directGlobalGrant = await em.findOne(
-      UserAcl,
-      { user: userId as never, isSuperAdmin: true } as never,
+    const user = await findOneWithDecryption(
+      em, User, { id: userId }, {}, { tenantId: null, organizationId: null },
     )
-    if (directGlobalGrant?.isSuperAdmin) {
+    if (!user) return { isSuperAdmin: false, features: [], organizations: null }
+    if (await this.isGlobalSuperAdmin(em, userId, user.tenantId ?? null, false)) {
       return { isSuperAdmin: true, features: ['*'], organizations: null }
     }
-    const globalLinks = await findWithDecryption(
-      em,
-      UserRole,
-      { user: userId as never },
-      { populate: ['role'] },
-      { tenantId: null, organizationId: null },
-    )
-    const globalRoleIds = globalLinks
-      .map((link) => typeof link.role === 'string' ? link.role : link.role?.id ? String(link.role.id) : null)
-      .filter((roleId): roleId is string => typeof roleId === 'string' && roleId.length > 0)
-    if (globalRoleIds.length) {
-      const globalRoleGrants = await em.find(
-        RoleAcl,
-        {
-          role: { $in: globalRoleIds as never },
-          isSuperAdmin: true,
-        } as never,
-      )
-      if (globalRoleGrants.some((grant) => grant.isSuperAdmin && !isRestrictedRoleAcl(grant))) {
-        return { isSuperAdmin: true, features: ['*'], organizations: null }
-      }
-    }
-
-    const user = await em.findOne(User, { id: userId })
-    if (!user) return { isSuperAdmin: false, features: [], organizations: null }
     const tenantId = scope.tenantId || user.tenantId || null
     const organizationId = scope.organizationId || user.organizationId || null
     if (!tenantId) return { isSuperAdmin: false, features: [], organizations: null }
 
-    const userAcl = await em.findOne(UserAcl, { user: userId as never, tenantId } as never)
+    const userAcl = await em.findOne(
+      UserAcl,
+      { user: userId as never, tenantId, deletedAt: null } as FilterQuery<UserAcl>,
+      { orderBy: { createdAt: 'desc', id: 'desc' } },
+    )
     if (userAcl) {
       return {
         isSuperAdmin: userAcl.isSuperAdmin === true,
@@ -757,7 +825,7 @@ export class RbacService {
     const links = await findWithDecryption(
       em,
       UserRole,
-      { user: userId as never, role: { tenantId } } as never,
+      { user: userId as never, deletedAt: null, role: { tenantId, deletedAt: null } } as never,
       { populate: ['role'] },
       { tenantId, organizationId },
     )
@@ -765,7 +833,7 @@ export class RbacService {
       .map((link) => typeof link.role === 'string' ? link.role : link.role?.id ? String(link.role.id) : null)
       .filter((roleId): roleId is string => typeof roleId === 'string' && roleId.length > 0)
     const roleAcls = roleIds.length
-      ? await em.find(RoleAcl, { tenantId, role: { $in: roleIds as never } } as never)
+      ? await em.find(RoleAcl, { tenantId, deletedAt: null, role: { $in: roleIds as never, deletedAt: null } } as never)
       : []
     const roleScope = await resolveRoleOrganizationScopeWithEntityManager(
       em,
@@ -862,7 +930,7 @@ export class RbacService {
       tenantId,
       opts?.organizationId,
     )
-    const roleAcls = await em.find(RoleAcl, { tenantId, deletedAt: null } as any, {})
+    const roleAcls = await em.find(RoleAcl, { tenantId, deletedAt: null } as FilterQuery<RoleAcl>, {})
     const list = Array.isArray(roleAcls) ? roleAcls : []
 
     for (const acl of list) {
@@ -939,12 +1007,21 @@ export class RbacService {
     const denyAll = () => []
     if (!required.length) return { unrestricted: true, filterOrganizationIds: allowAll }
     if (!input.tenantId) return { unrestricted: false, filterOrganizationIds: denyAll }
-    if (
-      !userId.startsWith('api_key:')
-      && await this.isGlobalSuperAdmin(userId)
-      && authorizeFeatures(required, { grantedFeatures: ['*'], unrestricted: true })
-    ) {
-      return { unrestricted: true, filterOrganizationIds: allowAll }
+    if (!userId.startsWith('api_key:')) {
+      let globalSuperAdmin = this.globalSuperAdminCache.get(userId)
+      if (globalSuperAdmin === undefined) {
+        const em = this.em.fork()
+        const user = await findOneWithDecryption(
+          em, User, { id: userId }, {}, { tenantId: null, organizationId: null },
+        )
+        globalSuperAdmin = !!user && await this.isGlobalSuperAdmin(em, userId, user.tenantId ?? null)
+      }
+      if (
+        globalSuperAdmin
+        && authorizeFeatures(required, { grantedFeatures: ['*'], unrestricted: true })
+      ) {
+        return { unrestricted: true, filterOrganizationIds: allowAll }
+      }
     }
 
     const grants = await this.loadFeatureOrganizationGrants(userId, input.tenantId)
@@ -1056,7 +1133,8 @@ export class RbacService {
       if (!roleIds.length) return { kind: 'none' }
       const roleAcls = await em.find(RoleAcl, {
         tenantId,
-        role: { $in: roleIds },
+        deletedAt: null,
+        role: { $in: roleIds, deletedAt: null },
       })
       const keyOrganizationId = typeof key.organizationId === 'string' && key.organizationId.trim().length > 0
         ? key.organizationId.trim()
@@ -1068,10 +1146,16 @@ export class RbacService {
       }
     }
 
-    const user = await em.findOne(User, { id: userId })
+    const user = await findOneWithDecryption(
+      em, User, { id: userId }, {}, { tenantId: null, organizationId: null },
+    )
     if (!user) return { kind: 'none' }
 
-    const userAcl = await em.findOne(UserAcl, { user: userId, tenantId })
+    const userAcl = await em.findOne(
+      UserAcl,
+      { user: userId, tenantId, deletedAt: null },
+      { orderBy: { createdAt: 'desc', id: 'desc' } },
+    )
     if (userAcl) {
       return {
         kind: 'user_acl',
@@ -1084,7 +1168,7 @@ export class RbacService {
     const links = await findWithDecryption(
       em,
       UserRole,
-      { user: userId, role: { tenantId } },
+      { user: userId, deletedAt: null, role: { tenantId, deletedAt: null } },
       { populate: ['role'] },
       { tenantId, organizationId: null },
     )
@@ -1095,7 +1179,8 @@ export class RbacService {
 
     const roleAcls = await em.find(RoleAcl, {
       tenantId,
-      role: { $in: roleIds },
+      deletedAt: null,
+      role: { $in: roleIds, deletedAt: null },
     })
     return { kind: 'roles', roleGrants: roleAcls.map(toFeatureOrganizationRoleGrant) }
   }

package/src/modules/entities/cli.ts

@@ -32,6 +32,7 @@ import {
 } from '@open-mercato/shared/lib/encryption/tenantDataEncryptionService'
 import { resolveEntityIdFromMetadata } from '@open-mercato/shared/lib/encryption/entityIds'
 import { listEntityMetadata } from '@open-mercato/shared/lib/db/entityMetadata'
+import { rotateCustomEntityDocuments } from './lib/rotate-custom-entity-documents'
 import { Organization } from '../directory/data/entities'
 import type { EntityManager } from '@mikro-orm/postgresql'
 import crypto from 'node:crypto'
@@ -501,8 +502,18 @@ const rotateEncryptionKey: ModuleCli = {
       )
       return false
     })
+    const customDocuments = await rotateCustomEntityDocuments(em, {
+      encryptionService,
+      oldKms,
+      tenantId: tenantIdArg,
+      organizationId: organizationIdArg,
+      dryRun,
+    })
+    if (customDocuments > 0) {
+      console.log(`${dryRun ? '[dry-run] ' : ''}Encrypted ${customDocuments} custom entity document(s).`)
+    }
     if (!maps.length) {
-      console.log('No encryption maps found for the selected scope.')
+      if (!customDocuments) console.log('No encryption maps found for the selected scope.')
       return
     }
 

package/src/modules/entities/lib/helpers.ts

@@ -7,6 +7,23 @@ import {
 } from '@open-mercato/shared/modules/entities/validation'
 import { CustomFieldDef, CustomFieldValue } from '../data/entities'
 import { loadScopedCustomFieldDefs } from './scoped-field-defs'
+import { encryptCustomEntityDocument } from '@open-mercato/shared/lib/encryption/customEntityDoc'
+import { isTenantDataEncryptionEnabled } from '@open-mercato/shared/lib/encryption/toggles'
+
+/** @internal */
+export async function encryptCustomEntityRecordDocument(
+  em: EntityManager,
+  opts: { entityId: string; organizationId: string | null; tenantId: string | null; doc: Record<string, unknown>; encryptionService?: TenantDataEncryptionService | null },
+): Promise<Record<string, unknown>> {
+  if (!isTenantDataEncryptionEnabled() || Object.keys(opts.doc).every((key) => key === 'id')) return opts.doc
+  const definitions = await loadScopedCustomFieldDefs(em, opts)
+  const fields = Array.from(definitions.values(), (definition) => ({
+    key: definition.key,
+    kind: definition.kind,
+    encrypted: Boolean(definition.configJson?.encrypted),
+  }))
+  return encryptCustomEntityDocument(opts.doc, fields, opts.tenantId, resolveTenantEncryptionService(em, opts.encryptionService))
+}
 
 type Primitive = string | number | boolean | null | undefined
 type PrimitiveOrArray = Primitive | Primitive[]

package/src/modules/entities/lib/rotate-custom-entity-documents.ts

@@ -0,0 +1,200 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import type { FilterQuery } from '@mikro-orm/core'
+import {
+  decryptWithAesGcm,
+  TenantDataEncryptionError,
+  TenantDataEncryptionErrorCode,
+} from '@open-mercato/shared/lib/encryption/aes'
+import {
+  decryptCustomEntityDocument,
+  encryptCustomEntityDocument,
+  isCustomEntityDocumentCiphertext,
+  type CustomEntityDocumentField,
+} from '@open-mercato/shared/lib/encryption/customEntityDoc'
+import type { KmsService, TenantDek } from '@open-mercato/shared/lib/encryption/kms'
+import type { TenantDataEncryptionService } from '@open-mercato/shared/lib/encryption/tenantDataEncryptionService'
+import { CustomFieldDef } from '../data/entities'
+import { loadScopedCustomFieldDefs } from './scoped-field-defs'
+
+type RotationOptions = {
+  encryptionService: TenantDataEncryptionService
+  oldKms: KmsService | null
+  tenantId: string | null
+  organizationId: string | null
+  dryRun: boolean
+}
+
+type DocumentRow = {
+  id: string
+  entity_type: string
+  tenant_id: string | null
+  organization_id: string | null
+  doc: Record<string, unknown>
+}
+
+type DocumentFieldPolicy = {
+  fields: CustomEntityDocumentField[]
+  encryptedKeys: Set<string>
+  protectedKeys: Set<string>
+}
+
+const BATCH_SIZE = 100
+
+function holdsCiphertext(value: unknown): boolean {
+  return Array.isArray(value) ? value.some(isCustomEntityDocumentCiphertext) : isCustomEntityDocumentCiphertext(value)
+}
+
+function selectHistoricalDefinitions(definitions: CustomFieldDef[]): Map<string, CustomFieldDef> {
+  const selected = new Map<string, CustomFieldDef>()
+  const scopeScore = (definition: CustomFieldDef) => (definition.tenantId ? 2 : 0) + (definition.organizationId ? 1 : 0)
+  const updatedAt = (definition: CustomFieldDef) => new Date(definition.updatedAt).getTime()
+  for (const definition of definitions) {
+    const previous = selected.get(definition.key)
+    if (!previous || scopeScore(definition) > scopeScore(previous)
+      || (scopeScore(definition) === scopeScore(previous) && updatedAt(definition) >= updatedAt(previous))) {
+      selected.set(definition.key, definition)
+    }
+  }
+  return selected
+}
+
+/** @internal */
+export async function rotateCustomEntityDocuments(
+  em: EntityManager,
+  options: RotationOptions,
+): Promise<number> {
+  const definitionScope: FilterQuery<CustomFieldDef>[] = []
+  if (options.tenantId) definitionScope.push({ $or: [{ tenantId: options.tenantId }, { tenantId: null }] })
+  if (options.organizationId) definitionScope.push({ $or: [{ organizationId: options.organizationId }, { organizationId: null }] })
+  const definitions = await em.find(CustomFieldDef, {
+    ...(definitionScope.length ? { $and: definitionScope } : {}),
+  })
+  const entityIds = Array.from(new Set(definitions.map((definition) => definition.entityId)))
+  if (!entityIds.length) return 0
+
+  const connection = em.getConnection()
+  const fieldsByScope = new Map<string, DocumentFieldPolicy>()
+  const oldDeks = new Map<string, TenantDek | null>()
+  let cursor: string | null = null
+  let updated = 0
+  for (;;) {
+    const predicates = [`entity_type in (${entityIds.map(() => '?').join(', ')})`]
+    const parameters: unknown[] = [...entityIds]
+    if (options.tenantId) {
+      predicates.push('tenant_id = ?')
+      parameters.push(options.tenantId)
+    }
+    if (options.organizationId) {
+      predicates.push('organization_id = ?')
+      parameters.push(options.organizationId)
+    }
+    if (cursor) {
+      predicates.push('id > ?')
+      parameters.push(cursor)
+    }
+    const rows = await connection.execute<DocumentRow[]>(
+      `select id, entity_type, tenant_id, organization_id, doc from custom_entities_storage where ${predicates.join(' and ')} order by id asc limit ${BATCH_SIZE}`,
+      parameters,
+    )
+    if (!rows.length) break
+    for (const row of rows) {
+      const scopeKey = JSON.stringify([row.entity_type, row.tenant_id, row.organization_id])
+      let policy = fieldsByScope.get(scopeKey)
+      if (!policy) {
+        const scopedDefinitions = await loadScopedCustomFieldDefs(em, {
+          entityId: row.entity_type,
+          tenantId: row.tenant_id,
+          organizationId: row.organization_id,
+        })
+        const visibleDefinitions = definitions
+          .filter((definition) => definition.entityId === row.entity_type
+            && (definition.tenantId == null || definition.tenantId === row.tenant_id)
+            && (definition.organizationId == null || definition.organizationId === row.organization_id))
+        const keys = new Set(visibleDefinitions.map((definition) => definition.key))
+        const historicalDefinitions = selectHistoricalDefinitions(visibleDefinitions)
+        policy = {
+          fields: Array.from(keys, (key) => ({ key, kind: 'text', encrypted: true })),
+          protectedKeys: new Set(Array.from(keys)
+            .filter((key) => (scopedDefinitions.get(key) ?? historicalDefinitions.get(key))?.configJson?.encrypted === true)),
+          encryptedKeys: new Set(Array.from(scopedDefinitions.values())
+            .filter((definition) => definition.configJson?.encrypted === true)
+            .map((definition) => definition.key)),
+        }
+        fieldsByScope.set(scopeKey, policy)
+      }
+      const { fields, encryptedKeys, protectedKeys } = policy
+      const knownKeys = new Set(fields.map((field) => field.key))
+      const entries = Object.entries(row.doc).filter(([key, value]) => {
+        const normalizedKey = key.replace(/^cf[:_]/, '')
+        return value != null && knownKeys.has(normalizedKey) && (encryptedKeys.has(normalizedKey) || holdsCiphertext(value))
+      })
+      if (!entries.length) continue
+      const tenantId = row.tenant_id
+      if (!tenantId || !options.encryptionService.isEnabled()) {
+        throw new TenantDataEncryptionError(TenantDataEncryptionErrorCode.KMS_UNAVAILABLE, '[internal] Custom entity encryption requires an available tenant key')
+      }
+      const currentDek = await options.encryptionService.getDek(tenantId)
+      if (options.oldKms && !oldDeks.has(tenantId)) oldDeks.set(tenantId, await options.oldKms.getTenantDek(tenantId))
+      const oldDek = oldDeks.get(tenantId) ?? null
+      const candidates: Record<string, unknown> = {}
+      const arrayMasks = new Map<string, boolean[]>()
+      let changed = false
+      const prepare = (value: unknown, encryptPlaintext: boolean, requireCiphertextKey: boolean): { value: unknown; selected: boolean } => {
+        if (value == null) return { value, selected: false }
+        if (typeof value === 'string') {
+          if (currentDek && decryptWithAesGcm(value, currentDek.key) !== null) return { value, selected: true }
+          if (oldDek && decryptWithAesGcm(value, oldDek.key) !== null) {
+            changed = true
+            return { value, selected: true }
+          }
+        }
+        if (!isCustomEntityDocumentCiphertext(value)) {
+          if (options.oldKms || !encryptPlaintext) return { value: null, selected: false }
+          changed = true
+          return { value, selected: true }
+        }
+        if (!requireCiphertextKey) return { value: null, selected: false }
+        throw new TenantDataEncryptionError(TenantDataEncryptionErrorCode.WRONG_KEY, '[internal] Custom entity ciphertext does not decrypt under the supplied tenant keys')
+      }
+      for (const [key, value] of entries) {
+        const normalizedKey = key.replace(/^cf[:_]/, '')
+        const encryptPlaintext = encryptedKeys.has(normalizedKey)
+        const requireCiphertextKey = protectedKeys.has(normalizedKey)
+        if (Array.isArray(value)) {
+          const prepared = value.map((entry) => prepare(entry, encryptPlaintext, requireCiphertextKey))
+          candidates[key] = prepared.map((entry) => entry.value)
+          arrayMasks.set(key, prepared.map((entry) => entry.selected))
+        } else {
+          const prepared = prepare(value, encryptPlaintext, requireCiphertextKey)
+          if (prepared.selected) candidates[key] = prepared.value
+        }
+      }
+      if (!changed) continue
+      if (options.dryRun) {
+        updated += 1
+        continue
+      }
+      const plaintext = options.oldKms && oldDek
+        ? await decryptCustomEntityDocument(candidates, fields, tenantId, options.encryptionService, new Map([[tenantId, oldDek.key]]))
+        : candidates
+      const encrypted = await encryptCustomEntityDocument(plaintext, fields, tenantId, options.encryptionService)
+      const nextDoc = { ...row.doc }
+      for (const [key, value] of Object.entries(encrypted)) {
+        const mask = arrayMasks.get(key)
+        const previous = row.doc[key]
+        nextDoc[key] = mask && Array.isArray(value) && Array.isArray(previous)
+          ? value.map((entry, index) => mask[index] ? entry : previous[index])
+          : value
+      }
+      const written = await connection.execute<Array<{ id: string }>>(
+        'update custom_entities_storage set doc = ?::jsonb, updated_at = now() where id = ? and entity_type = ? and tenant_id is not distinct from ? and organization_id is not distinct from ? and doc = ?::jsonb returning id',
+        [JSON.stringify(nextDoc), row.id, row.entity_type, tenantId, row.organization_id, JSON.stringify(row.doc)],
+      )
+      if (!written.length) throw new Error('[internal] Custom entity document changed during encryption; retry the operation')
+      updated += 1
+    }
+    cursor = rows[rows.length - 1]!.id
+    if (rows.length < BATCH_SIZE) break
+  }
+  return updated
+}