@open-mercato/shared 0.6.7 → 0.6.8-canary.320.1.bf889f49e4

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

@@ -196,6 +196,64 @@ describe('TenantDataEncryptionService.encryptFields (issue #2720)', () => {
   })
 })
 
+describe('TenantDataEncryptionService system-scoped maps', () => {
+  const originalToggle = process.env.TENANT_DATA_ENCRYPTION
+
+  beforeEach(() => {
+    process.env.TENANT_DATA_ENCRYPTION = 'yes'
+  })
+
+  afterEach(() => {
+    if (originalToggle === undefined) delete process.env.TENANT_DATA_ENCRYPTION
+    else process.env.TENANT_DATA_ENCRYPTION = originalToggle
+  })
+
+  it('encrypts tenant-less payloads with a stable entity-scoped KMS key', async () => {
+    const entityId = 'onboarding:onboarding_request'
+    const systemKeyId = `system:${entityId}`
+    const getTenantDek = jest.fn(async (keyId: string) => (
+      keyId === systemKeyId
+        ? { tenantId: keyId, key: fixedKey, fetchedAt: new Date() }
+        : null
+    ))
+    const service = new TenantDataEncryptionService(
+      {
+        getConnection: () => ({ execute: jest.fn(async () => []) }),
+      } as never,
+      {
+        kms: {
+          getTenantDek,
+          createTenantDek: jest.fn(async () => null),
+          isHealthy: () => true,
+        },
+        defaultEncryptionMaps: [
+          {
+            entityId,
+            keyScope: 'system',
+            fields: [
+              { field: 'email', hashField: 'email_hash' },
+              { field: 'password_hash' },
+            ],
+          },
+        ],
+      } as never,
+    )
+
+    const encrypted = await service.encryptEntityPayload(entityId, {
+      email: 'person@example.com',
+      email_hash: null,
+      password_hash: 'bcrypt-value',
+    }, null, null)
+
+    expect(getTenantDek).toHaveBeenCalledWith(systemKeyId)
+    expect(encrypted.email).not.toBe('person@example.com')
+    expect(encrypted.password_hash).not.toBe('bcrypt-value')
+    expect(encrypted.email_hash).toBe(hashForLookup('person@example.com'))
+    expect(decryptWithAesGcm(encrypted.email as string, fixedKey)).toBe('person@example.com')
+    expect(decryptWithAesGcm(encrypted.password_hash as string, fixedKey)).toBe('bcrypt-value')
+  })
+})
+
 describe('TenantDataEncryptionService.getEncryptedFieldNames', () => {
   it('returns active encryption-map field names for query planning', async () => {
     const service = new TenantDataEncryptionService({} as never)

package/src/lib/encryption/find.ts

@@ -5,6 +5,7 @@ import type {
   FindOneOptions,
   FindOptions,
 } from '@mikro-orm/postgresql'
+import { warnOnEncryptedLikeFilter } from './likeFilterWarning'
 import { decryptEntitiesWithFallbackScope } from './subscriber'
 import type { TenantDataEncryptionService } from './tenantDataEncryptionService'
 
@@ -24,6 +25,13 @@ export async function findWithDecryption<Entity extends object, Hint extends str
   options?: AnyFindOptions<Entity, Hint>,
   scope?: DecryptionScope,
 ): Promise<Entity[]> {
+  await warnOnEncryptedLikeFilter({
+    em,
+    entityName,
+    where,
+    tenantId: scope?.tenantId,
+    encryptionService: scope?.encryptionService,
+  })
   const records = (await em.find<Entity, Hint, any, any>(entityName as any, where as any, options as any)) as any as
     | Entity[]
     | undefined
@@ -44,6 +52,13 @@ export async function findOneWithDecryption<Entity extends object, Hint extends
   options?: AnyFindOneOptions<Entity, Hint>,
   scope?: DecryptionScope,
 ): Promise<Entity | null> {
+  await warnOnEncryptedLikeFilter({
+    em,
+    entityName,
+    where,
+    tenantId: scope?.tenantId,
+    encryptionService: scope?.encryptionService,
+  })
   const record = (await em.findOne<Entity, Hint, any, any>(entityName as any, where as any, options as any)) as any as
     | Entity
     | null
@@ -64,6 +79,13 @@ export async function findAndCountWithDecryption<Entity extends object, Hint ext
   options?: AnyFindOptions<Entity, Hint>,
   scope?: DecryptionScope,
 ): Promise<[Entity[], number]> {
+  await warnOnEncryptedLikeFilter({
+    em,
+    entityName,
+    where,
+    tenantId: scope?.tenantId,
+    encryptionService: scope?.encryptionService,
+  })
   const [recordsRaw, count] = await em.findAndCount<Entity, Hint, any, any>(
     entityName as any,
     where as any,

package/src/lib/encryption/likeFilterWarning.ts

@@ -0,0 +1,102 @@
+import type { EntityManager, EntityName } from '@mikro-orm/postgresql'
+import { warnOnCiphertextLikeFallback } from '../query/ciphertext-search-warning'
+import { resolveTenantEncryptionService } from './customFieldValues'
+import { resolveEntityIdFromMetadata } from './entityIds'
+import type { TenantDataEncryptionService } from './tenantDataEncryptionService'
+
+const LIKE_OPERATORS = new Set(['$like', '$ilike', '$re', '$fulltext'])
+const LOGICAL_OPERATORS = new Set(['$and', '$or', '$not', '$every', '$some', '$none'])
+
+const isPlainObject = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value) && !(value instanceof Date)
+
+// An operator object holds only `$`-prefixed keys. Anything else is a nested
+// relation filter, whose property names belong to another entity's encryption
+// map — attributing them to the root entity would produce false warnings.
+const isOperatorObject = (value: unknown): value is Record<string, unknown> => {
+  if (!isPlainObject(value)) return false
+  const keys = Object.keys(value)
+  return keys.length > 0 && keys.every((key) => key.startsWith('$'))
+}
+
+function walkFilter(node: unknown, field: string | null, out: Set<string>): void {
+  if (Array.isArray(node)) {
+    for (const item of node) walkFilter(item, field, out)
+    return
+  }
+  if (!isPlainObject(node)) return
+  for (const [key, value] of Object.entries(node)) {
+    if (LIKE_OPERATORS.has(key)) {
+      if (field) out.add(field)
+      continue
+    }
+    if (LOGICAL_OPERATORS.has(key)) {
+      walkFilter(value, field, out)
+      continue
+    }
+    if (key.startsWith('$')) continue
+    if (isOperatorObject(value)) walkFilter(value, key, out)
+  }
+}
+
+/**
+ * Lists the root-entity properties a filter targets with a string-matching
+ * operator (`$like`, `$ilike`, `$re`, `$fulltext`), including inside
+ * `$and`/`$or`/`$not` branches.
+ */
+export function collectLikeFilterFields(where: unknown): string[] {
+  const found = new Set<string>()
+  walkFilter(where, null, found)
+  return Array.from(found)
+}
+
+// The map lookup behind the warning issues an uncached read against
+// `encryption_maps`, and this path runs on every matching query rather than in a
+// rare fallback branch — so the check stays out of production entirely.
+const isWarningEnabled = (): boolean => process.env.NODE_ENV !== 'production'
+
+function resolveEntityId(em: EntityManager, entityName: EntityName<any>): string | null {
+  const metadata = (em as any)?.getMetadata?.()
+  if (!metadata || typeof metadata.find !== 'function') return null
+  const name = typeof entityName === 'string' ? entityName : (entityName as any)?.name
+  if (!name) return null
+  return resolveEntityIdFromMetadata(metadata.find(name) ?? undefined)
+}
+
+/**
+ * Warn, outside production, when a `where` clause matches an encrypted-at-rest
+ * column with a string operator.
+ *
+ * Decryption happens on load, not on filter, so the predicate compares a
+ * plaintext pattern against ciphertext: it matches nothing and does not raise,
+ * which is indistinguishable from a genuine empty result. The query engines
+ * already warn about their own `ILIKE` fallback; this covers the raw-ORM path
+ * that never reaches them. Issue #5051, related to #2990.
+ *
+ * Never throws and never blocks the query.
+ */
+export async function warnOnEncryptedLikeFilter(params: {
+  em: EntityManager
+  entityName: EntityName<any>
+  where: unknown
+  tenantId?: string | null
+  encryptionService?: TenantDataEncryptionService | null
+}): Promise<void> {
+  if (!isWarningEnabled()) return
+  const fields = collectLikeFilterFields(params.where)
+  if (!fields.length) return
+  try {
+    const entity = resolveEntityId(params.em, params.entityName)
+    if (!entity) return
+    const service = params.encryptionService ?? resolveTenantEncryptionService(params.em)
+    await warnOnCiphertextLikeFallback({
+      entity,
+      fields,
+      tenantId: params.tenantId ?? null,
+      reason: 'raw-orm-filter',
+      service,
+    })
+  } catch {
+    // A diagnostic must never break the query it is diagnosing.
+  }
+}

package/src/lib/encryption/subscriber.ts

@@ -6,6 +6,7 @@ import { isTenantDataEncryptionEnabled } from './toggles'
 import { isEncryptionDebugEnabled } from './toggles'
 import { resolveTenantEncryptionService } from './customFieldValues'
 import { createLogger } from '../logger'
+import { listEntityMetadataFromRegistry } from '../db/entityMetadata'
 
 const logger = createLogger('shared').child({ component: 'encryption' })
 
@@ -85,13 +86,8 @@ export class TenantEncryptionSubscriber implements EventSubscriber<any> {
     try { return registry.find?.(ctor) } catch {}
     try { return registry.get?.(name) } catch {}
     try { return registry.get?.(ctor) } catch {}
-    const all =
-      (typeof registry.getAll === 'function' && registry.getAll()) ||
-      (Array.isArray((registry as any).metadata) ? (registry as any).metadata : undefined) ||
-      (registry as any).metadata ||
-      {}
     try {
-      const entries = Array.isArray(all) ? all : Object.values<any>(all)
+      const entries = listEntityMetadataFromRegistry(registry)
       const match = entries.find(
         (m: any) =>
           m?.className === name ||
@@ -224,10 +220,6 @@ export class TenantEncryptionSubscriber implements EventSubscriber<any> {
       return
     }
     const { tenantId, organizationId } = resolveScope(target)
-    if (!tenantId) {
-      debug('⚪️ subscriber.skip', { reason: 'no-tenant', entityId })
-      return
-    }
     const encrypted = await this.service.encryptEntityPayload(entityId, target, tenantId, organizationId)
     const metaProps: Record<string, unknown> = resolvedMeta?.properties && typeof resolvedMeta.properties === 'object'
       ? resolvedMeta.properties
@@ -325,10 +317,6 @@ export class TenantEncryptionSubscriber implements EventSubscriber<any> {
     const { tenantId, organizationId } = resolveScope(target)
     const scopedTenantId = tenantId ?? fallbackScope?.tenantId ?? null
     const scopedOrgId = organizationId ?? fallbackScope?.organizationId ?? null
-    if (!scopedTenantId) {
-      debug('⚪️ subscriber.skip', { reason: 'no-tenant', entityId })
-      return
-    }
     // Capture pending (un-flushed) changes BEFORE decrypt mutates the target. Re-baselining a
     // managed entity that a command already mutated would clear its dirty changeset and silently
     // drop the pending write (e.g. an undo handler that mutates an entity, then loads a related

package/src/lib/encryption/tenantDataEncryptionService.ts

@@ -4,6 +4,7 @@ import { decryptWithAesGcm, encryptWithAesGcm, hashForLookup } from './aes'
 import { createKmsService, type KmsService, type TenantDek } from './kms'
 import { isTenantDataEncryptionEnabled, isEncryptionDebugEnabled } from './toggles'
 import { createLogger } from '../logger'
+import type { EncryptionKeyScope, ModuleEncryptionMap } from '../../modules/encryption'
 
 const logger = createLogger('shared').child({ component: 'tenant-encryption' })
 
@@ -14,6 +15,7 @@ export type EncryptedFieldRule = {
 
 export type EncryptionMapRecord = {
   entityId: string
+  keyScope?: EncryptionKeyScope
   fields: EncryptedFieldRule[]
 }
 
@@ -154,13 +156,23 @@ export class TenantDataEncryptionService {
   private readonly inflightDeks = TenantDataEncryptionService.globalInflightDeks
   private readonly inflightMaps = TenantDataEncryptionService.globalInflightMaps
   private readonly missCache = TenantDataEncryptionService.globalMissCache
+  private readonly systemDefaultMaps: Map<string, ModuleEncryptionMap>
 
   constructor(
     private em: EntityManager,
-    opts?: { cache?: CacheStrategy; kms?: KmsService }
+    opts?: {
+      cache?: CacheStrategy
+      kms?: KmsService
+      defaultEncryptionMaps?: readonly ModuleEncryptionMap[]
+    }
   ) {
     this.cache = opts?.cache
     this.kms = opts?.kms ?? createKmsService()
+    this.systemDefaultMaps = new Map(
+      (opts?.defaultEncryptionMaps ?? [])
+        .filter((map) => map.keyScope === 'system')
+        .map((map) => [map.entityId, map]),
+    )
   }
 
   isEnabled(): boolean {
@@ -239,6 +251,24 @@ export class TenantDataEncryptionService {
     }
   }
 
+  private applySystemDefault(record: EncryptionMapRecord | null, entityId: string): EncryptionMapRecord | null {
+    const declared = this.systemDefaultMaps.get(entityId)
+    if (!declared) return record
+    const fields: EncryptedFieldRule[] = declared.fields.map((field) => ({
+      field: field.field,
+      hashField: field.hashField ?? null,
+    }))
+    const declaredFields = new Set(fields.map((field) => field.field))
+    for (const field of record?.fields ?? []) {
+      if (!declaredFields.has(field.field)) fields.push(field)
+    }
+    return {
+      entityId,
+      keyScope: 'system',
+      fields,
+    }
+  }
+
   private async getMap(key: MapCacheKey): Promise<EncryptionMapRecord | null> {
     const shouldSkipLookup = (tag: string) => {
       const expiresAt = this.missCache.get(tag)
@@ -262,13 +292,13 @@ export class TenantDataEncryptionService {
       if (this.inflightMaps.has(tag)) {
         const pending = this.inflightMaps.get(tag)!
         const resolved = await pending
-        if (resolved) return resolved
+        if (resolved) return this.applySystemDefault(resolved, key.entityId)
       }
       const mem = this.memoryCache.get(tag)
-      if (mem) return mem
+      if (mem) return this.applySystemDefault(mem, key.entityId)
       if (this.cache && typeof this.cache.get === 'function') {
         const cached = await this.cache.get(tag)
-        if (cached) return cached as EncryptionMapRecord
+        if (cached) return this.applySystemDefault(cached as EncryptionMapRecord, key.entityId)
       }
       const pending = this.fetchMap(candidate)
       this.inflightMaps.set(tag, pending)
@@ -288,9 +318,9 @@ export class TenantDataEncryptionService {
       if (this.cache && typeof this.cache.set === 'function') {
         await this.cache.set(tag, loaded, { ttl: 300 })
       }
-      return loaded
+      return this.applySystemDefault(loaded, key.entityId)
     }
-    return null
+    return this.applySystemDefault(null, key.entityId)
   }
 
   private async fetchAllOrganizationFieldNames(entityId: string, tenantId: string | null): Promise<string[]> {
@@ -336,12 +366,26 @@ export class TenantDataEncryptionService {
     this.kms.invalidateDek?.(tenantId)
   }
 
+  /**
+   * Lists the fields an encryption map marks as encrypted at rest.
+   *
+   * `isEnabled()` folds the environment toggle together with KMS health, so by default an
+   * unhealthy KMS reports "nothing is encrypted" — which is safe for write paths but wrong for
+   * readers that must decide whether a stored column holds ciphertext. `ignoreRuntimeHealth`
+   * answers the on-disk question instead: it consults the map even when the KMS cannot currently
+   * resolve a DEK, so callers can fail closed rather than treat ciphertext as plaintext (#4622).
+   */
   async getEncryptedFieldNames(
     entityId: string,
     tenantId: string | null | undefined,
-    organizationId?: string | null
+    organizationId?: string | null,
+    options?: { ignoreRuntimeHealth?: boolean }
   ): Promise<string[]> {
-    if (!this.isEnabled()) return []
+    if (options?.ignoreRuntimeHealth) {
+      if (!isTenantDataEncryptionEnabled()) return []
+    } else if (!this.isEnabled()) {
+      return []
+    }
     const map = await this.getMap({ entityId, tenantId: tenantId ?? null, organizationId: organizationId ?? null })
     const fields = new Set(normalizeEncryptedFieldNames(map?.fields))
     if (organizationId == null) {
@@ -421,16 +465,17 @@ export class TenantDataEncryptionService {
       debug('⚪️ encrypt.skip.disabled', { entityId, tenantId })
       return payload
     }
-    const dek = await this.resolveDekForEncrypt(tenantId ?? null)
-    if (!dek) {
-      debug('⚠️ encrypt.skip.no-dek', { entityId, tenantId })
-      return payload
-    }
     const map = await this.getMap({ entityId, tenantId: tenantId ?? null, organizationId: organizationId ?? null })
     if (!map || !map.fields?.length) {
       debug('⚪️ encrypt.skip.no-map', { entityId, tenantId })
       return payload
     }
+    const keyId = map.keyScope === 'system' ? `system:${entityId}` : tenantId ?? null
+    const dek = await this.resolveDekForEncrypt(keyId)
+    if (!dek) {
+      debug('⚠️ encrypt.skip.no-dek', { entityId, tenantId, keyScope: map.keyScope ?? 'tenant' })
+      return payload
+    }
     debug('🔒 encrypt_entity', { entityId, tenantId, organizationId, fields: map.fields.length })
     return this.encryptFields(payload, map.fields, dek)
   }
@@ -445,16 +490,17 @@ export class TenantDataEncryptionService {
       debug('⚪️ decrypt.skip.disabled', { entityId, tenantId })
       return payload
     }
-    const dek = await this.getDek(tenantId ?? null)
-    if (!dek) {
-      debug('⚠️ decrypt.skip.no-dek', { entityId, tenantId })
-      return payload
-    }
     const map = await this.getMap({ entityId, tenantId: tenantId ?? null, organizationId: organizationId ?? null })
     if (!map || !map.fields?.length) {
       debug('⚪️ decrypt.skip.no-map', { entityId, tenantId })
       return payload
     }
+    const keyId = map.keyScope === 'system' ? `system:${entityId}` : tenantId ?? null
+    const dek = await this.getDek(keyId)
+    if (!dek) {
+      debug('⚠️ decrypt.skip.no-dek', { entityId, tenantId, keyScope: map.keyScope ?? 'tenant' })
+      return payload
+    }
     debug('🔓 decrypt_entity', { entityId, tenantId, organizationId, fields: map.fields.length })
     return this.decryptFields(payload, map.fields, dek)
   }

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

@@ -0,0 +1,8 @@
+import { defaultLocale, locales, type Locale } from '../config'
+
+describe('supported application locales', () => {
+  it('registers Korean without changing the default locale', () => {
+    expect(locales).toEqual<Locale[]>(['en', 'pl', 'es', 'de', 'ko'])
+    expect(defaultLocale).toBe('en')
+  })
+})

package/src/lib/i18n/__tests__/dictionary-cache.test.ts

@@ -41,6 +41,29 @@ describe('i18n dictionary memoization', () => {
     expect(loader).toHaveBeenCalledTimes(2)
   })
 
+  it('keeps other locale dictionaries cached after locale-scoped module registration', async () => {
+    const loader = jest.fn(async (locale: Locale) => ({ greeting: locale }))
+    registerAppDictionaryLoader(loader)
+    registerModules([
+      { id: 'demo', translations: { en: { module: 'English' }, pl: { module: 'Polski' } } },
+    ] as any)
+
+    const englishBefore = await loadDictionary('en')
+    const polishBefore = await loadDictionary('pl')
+
+    registerModules([
+      { id: 'demo', translations: { pl: { module: 'Polski 2' } } },
+    ] as any)
+
+    const englishAfter = await loadDictionary('en')
+    const polishAfter = await loadDictionary('pl')
+
+    expect(englishAfter).toBe(englishBefore)
+    expect(polishAfter).not.toBe(polishBefore)
+    expect(polishAfter.module).toBe('Polski 2')
+    expect(loader).toHaveBeenCalledTimes(3)
+  })
+
   it('rebuilds after modules are re-registered', async () => {
     registerAppDictionaryLoader(async () => ({}))
     registerModules([{ translations: { en: { a: 'one' } } }] as any)

package/src/lib/i18n/__tests__/server-dictionary-cache.test.ts

@@ -0,0 +1,30 @@
+import { loadDictionary, registerModules } from '../server'
+import type { Module } from '../../../modules/registry'
+
+describe('loadDictionary memoization', () => {
+  it('returns a cached dictionary for repeated calls with the same locale', async () => {
+    registerModules([
+      { id: 'demo', translations: { en: { 'demo.hello': 'Hello' } } },
+    ] satisfies Module[])
+
+    const first = await loadDictionary('en')
+    const second = await loadDictionary('en')
+
+    expect(second).toBe(first)
+    expect(first['demo.hello']).toBe('Hello')
+  })
+
+  it('busts the cache when the registered module set changes', async () => {
+    registerModules([{ id: 'a', translations: { en: { 'a.k': 'A' } } }] satisfies Module[])
+    const before = await loadDictionary('en')
+
+    registerModules([
+      { id: 'a', translations: { en: { 'a.k': 'A' } } },
+      { id: 'b', translations: { en: { 'b.k': 'B' } } },
+    ] satisfies Module[])
+    const after = await loadDictionary('en')
+
+    expect(after).not.toBe(before)
+    expect(after['b.k']).toBe('B')
+  })
+})

package/src/lib/i18n/__tests__/server-unbootstrapped.test.ts

@@ -0,0 +1,29 @@
+import { invalidateDictionaryCache, loadDictionary, registerModules, resolveTranslations } from '../server'
+import type { Module } from '../../../modules/registry'
+
+const REGISTRY_GLOBAL_KEY = '__openMercatoModulesRegistry__'
+
+describe('loadDictionary without a bootstrapped module registry', () => {
+  beforeEach(() => {
+    delete (globalThis as Record<string, unknown>)[REGISTRY_GLOBAL_KEY]
+    invalidateDictionaryCache()
+  })
+
+  it('resolves the app dictionary instead of throwing a bootstrap error', async () => {
+    await expect(loadDictionary('en')).resolves.toEqual(expect.any(Object))
+  })
+
+  it('lets a route handler translate its response before bootstrap runs', async () => {
+    const { translate } = await resolveTranslations()
+
+    expect(translate('storage_s3.upload.errors.unsupported', 'Unsupported file type')).toBe('Unsupported file type')
+  })
+
+  it('picks up module translations once bootstrap registers them', async () => {
+    await loadDictionary('en')
+
+    registerModules([{ id: 'demo', translations: { en: { 'demo.hello': 'Hello' } } }] satisfies Module[])
+
+    await expect(loadDictionary('en')).resolves.toMatchObject({ 'demo.hello': 'Hello' })
+  })
+})

package/src/lib/i18n/config.ts

@@ -1,4 +1,4 @@
-export type Locale = 'en' | 'pl' | 'es' | 'de'
+export type Locale = 'en' | 'pl' | 'es' | 'de' | 'ko'
 
-export const locales: Locale[] = ['en', 'pl', 'es', 'de']
+export const locales: Locale[] = ['en', 'pl', 'es', 'de', 'ko']
 export const defaultLocale: Locale = 'en'

package/src/lib/i18n/dictionary-cache.ts

@@ -33,3 +33,8 @@ export function setCachedDictionary(locale: Locale, dict: Dict): void {
 export function invalidateDictionaryCache(): void {
   getCache().clear()
 }
+
+export function invalidateDictionaryCacheLocales(locales: readonly Locale[]): void {
+  const cache = getCache()
+  for (const locale of locales) cache.delete(locale)
+}

package/src/lib/i18n/server.ts

@@ -2,7 +2,7 @@ import { defaultLocale, locales, type Locale } from './config'
 import type { Dict } from './context'
 import { resolveForcedLocale, resolveLocaleFromAcceptLanguage } from './locale'
 import { createFallbackTranslator, createTranslator } from './translate'
-import { getModules } from '../modules/registry'
+import { tryGetModules } from '../modules/registry'
 import { loadAppDictionary } from './app-dictionaries'
 import { getCachedDictionary, setCachedDictionary } from './dictionary-cache'
 
@@ -61,7 +61,11 @@ export async function loadDictionary(locale: Locale): Promise<Dict> {
   // Load from registry instead of @/ import (works in standalone packages)
   const baseRaw = await loadAppDictionary(locale)
   const merged: Dict = { ...flattenDictionary(baseRaw) }
-  const modules = getModules()
+  // Route handlers translate their responses, so they resolve a dictionary even
+  // when they are exercised in isolation without a bootstrapped registry. The
+  // app dictionary alone is the right degraded answer there — `registerModules`
+  // invalidates this cache, so a later bootstrap still gets the merged result.
+  const modules = tryGetModules() ?? []
   for (const m of modules) {
     const dict = m.translations?.[locale]
     if (dict) Object.assign(merged, flattenDictionary(dict))

package/src/lib/logger/__tests__/logger.test.ts

@@ -3,7 +3,9 @@ import {
   createLogger,
   getLogLevel,
   isLevelEnabled,
+  registerLoggerExtension,
   resetLogLevelCache,
+  resetLoggerExtension,
   resetLoggerRegistry,
 } from '../index'
 import { resolveLevel, type LogLevel } from '../level'
@@ -65,6 +67,7 @@ function resetLoggerState(): void {
   resetLoggerRegistry()
   resetServerLoggerCache()
   resetLogPrettyCache()
+  resetLoggerExtension()
 }
 
 function forcePinoTransport(): void {
@@ -241,6 +244,80 @@ describe('structured logging facade', () => {
     })
   })
 
+  describe('process-wide logger extension', () => {
+    beforeEach(() => {
+      forcePinoTransport()
+    })
+
+    it('keeps one local line and observes one correlated record with child bindings', () => {
+      const fake = createFakePinoHarness()
+      mockPinoLoader(fake.factory)
+      const records: unknown[] = []
+      registerLoggerExtension({
+        enrich: () => ({ trace_id: 'trace-1', span_id: 'span-1' }),
+        emit: (record) => records.push(record),
+      })
+
+      createLogger('orders')
+        .child({ module: 'sales' })
+        .info('Order placed', { orderId: 'o-1' })
+
+      expect(fake.calls).toEqual([{
+        level: 'info',
+        args: [{
+          orderId: 'o-1',
+          trace_id: 'trace-1',
+          span_id: 'span-1',
+        }, 'Order placed'],
+      }])
+      expect(records).toHaveLength(1)
+      expect(records[0]).toMatchObject({
+        level: 'info',
+        namespace: 'orders',
+        message: 'Order placed',
+        fields: {
+          module: 'sales',
+          orderId: 'o-1',
+          trace_id: 'trace-1',
+          span_id: 'span-1',
+        },
+      })
+    })
+
+    it('applies the shared level gate to local and remote output', () => {
+      process.env.OM_LOG_LEVEL = 'warn'
+      resetLogLevelCache()
+      const fake = createFakePinoHarness()
+      mockPinoLoader(fake.factory)
+      const emit = jest.fn()
+      registerLoggerExtension({ emit })
+      const logger = createLogger('gated-extension')
+
+      logger.info('quiet')
+      logger.warn('visible')
+
+      expect(fake.calls.map((call) => call.level)).toEqual(['warn'])
+      expect(emit).toHaveBeenCalledTimes(1)
+      expect(emit.mock.calls[0][0]).toMatchObject({ level: 'warn', message: 'visible' })
+    })
+
+    it('isolates extension failures from application logging', () => {
+      const fake = createFakePinoHarness()
+      mockPinoLoader(fake.factory)
+      registerLoggerExtension({
+        enrich: () => {
+          throw new Error('context failed')
+        },
+        emit: () => {
+          throw new Error('sink failed')
+        },
+      })
+
+      expect(() => createLogger('resilient-extension').error('Still local')).not.toThrow()
+      expect(fake.calls).toEqual([{ level: 'error', args: [{}, 'Still local'] }])
+    })
+  })
+
   describe('isomorphism', () => {
     beforeEach(() => {
       forcePinoTransport()