@open-mercato/shared 0.7.1-develop.7183.1.db9678eeb8 → 0.7.1-develop.7186.1.6e080a5017

package/.turbo/turbo-build.log

@@ -1,2 +1,2 @@
-[build:shared] found 284 entry points
+[build:shared] found 286 entry points
 [build:shared] built successfully

package/dist/lib/encryption/aes.js

@@ -17,6 +17,14 @@ class TenantDataEncryptionError extends Error {
     this.code = code;
   }
 }
+const BASE64_PART = /^[A-Za-z0-9+/]+={0,2}$/;
+function looksLikeEncryptedPayload(value) {
+  if (typeof value !== "string") return false;
+  const parts = value.split(":");
+  if (parts.length !== 4 || parts[3] !== "v1") return false;
+  const [iv, ciphertext, tag] = parts;
+  return iv.length === 16 && tag.length === 24 && ciphertext.length > 0 && BASE64_PART.test(iv) && BASE64_PART.test(ciphertext) && BASE64_PART.test(tag);
+}
 function generateDek() {
   return crypto.randomBytes(32).toString("base64");
 }
@@ -146,6 +154,7 @@ export {
   generateDek,
   hashForLookup,
   legacyHashForLookup,
+  looksLikeEncryptedPayload,
   lookupHashCandidates
 };
 //# sourceMappingURL=aes.js.map

package/dist/lib/encryption/aes.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../src/lib/encryption/aes.ts"],
-  "sourcesContent": ["import crypto from 'node:crypto'\nimport { isEncryptionDebugEnabled } from './toggles'\nimport { createLogger } from '../logger'\n\nconst logger = createLogger('shared').child({ component: 'encryption' })\n\nexport type EncryptionPayload = {\n  value: string | null\n  raw: string\n  version: string\n}\n\nexport enum TenantDataEncryptionErrorCode {\n  AUTH_FAILED = 'AUTH_FAILED',\n  MALFORMED_PAYLOAD = 'MALFORMED_PAYLOAD',\n  KMS_UNAVAILABLE = 'KMS_UNAVAILABLE',\n  WRONG_KEY = 'WRONG_KEY',\n  DECRYPT_INTERNAL = 'DECRYPT_INTERNAL',\n}\n\nexport class TenantDataEncryptionError extends Error {\n  code: TenantDataEncryptionErrorCode\n  constructor(code: TenantDataEncryptionErrorCode, message: string) {\n    super(message)\n    this.name = 'TenantDataEncryptionError'\n    this.code = code\n  }\n}\n\nexport function generateDek(): string {\n  return crypto.randomBytes(32).toString('base64')\n}\n\nfunction logDebug(event: string, payload: Record<string, unknown>) {\n  if (!isEncryptionDebugEnabled()) return\n  try {\n    logger.debug(event, payload)\n  } catch {\n    // ignore\n  }\n}\n\nexport function encryptWithAesGcm(value: string, dekBase64: string): EncryptionPayload {\n  const dek = Buffer.from(dekBase64, 'base64')\n  const iv = crypto.randomBytes(12)\n  const cipher = crypto.createCipheriv('aes-256-gcm', dek, iv)\n  const ciphertext = Buffer.concat([cipher.update(value, 'utf8'), cipher.final()])\n  const tag = cipher.getAuthTag()\n  const payload = [\n    iv.toString('base64'),\n    ciphertext.toString('base64'),\n    tag.toString('base64'),\n    'v1',\n  ].join(':')\n  logDebug('encrypt', { length: ciphertext.length })\n  return { value: payload, raw: payload, version: 'v1' }\n}\n\nfunction runAesGcmDecrypt(dek: Buffer, iv: Buffer, ciphertext: Buffer, tag: Buffer): string {\n  const decipher = crypto.createDecipheriv('aes-256-gcm', dek, iv)\n  decipher.setAuthTag(tag)\n  return Buffer.concat([decipher.update(ciphertext), decipher.final()]).toString('utf8')\n}\n\nexport function decryptWithAesGcm(payload: string, dekBase64: string): string | null {\n  if (!payload) return null\n  const parts = payload.split(':')\n  if (parts.length !== 4) return null\n  const [ivB64, ciphertextB64, tagB64, version] = parts\n  if (version !== 'v1') return null\n  const dek = Buffer.from(dekBase64, 'base64')\n  const iv = Buffer.from(ivB64, 'base64')\n  const ciphertext = Buffer.from(ciphertextB64, 'base64')\n  const tag = Buffer.from(tagB64, 'base64')\n  try {\n    const result = runAesGcmDecrypt(dek, iv, ciphertext, tag)\n    logDebug('decrypt', { iv: ivB64, tag: tagB64 })\n    return result\n  } catch (err) {\n    logDebug('decrypt_error', { message: (err as Error)?.message || String(err) })\n    return null\n  }\n}\n\nconst LOOKUP_HASH_V2_PREFIX = 'v2:'\n\nfunction normalizeLookupValue(value: string): string {\n  return value.toLowerCase().trim()\n}\n\n/**\n * Legacy, unkeyed lookup digest (`sha256(lower(trim(value)))`).\n *\n * @deprecated Unkeyed digests are vulnerable to offline rainbow-table attacks and\n * cross-installation correlation (issue #2718). New writes use {@link hashForLookup},\n * which emits a keyed `v2:` HMAC when a lookup pepper is configured. This helper is\n * retained only so existing `*_hash` columns written before the keyed format can still\n * be matched (see {@link lookupHashCandidates}) until a backfill migration recomputes them.\n */\nexport function legacyHashForLookup(value: string): string {\n  return crypto.createHash('sha256').update(normalizeLookupValue(value)).digest('hex')\n}\n\n/**\n * Resolve the installation-wide lookup pepper used to key lookup hashes.\n *\n * Order of precedence (never `AUTH_SECRET`, per issue #2718):\n * 1. `LOOKUP_HASH_PEPPER` \u2014 dedicated secret for lookup hashing\n * 2. `TENANT_DATA_ENCRYPTION_FALLBACK_KEY` \u2014 existing encryption fallback secret\n * 3. `TENANT_DATA_ENCRYPTION_KEY` \u2014 existing encryption secret\n *\n * Returns `null` when no secret is configured, in which case {@link hashForLookup}\n * falls back to the legacy unkeyed digest so deployments without any configured key\n * keep working unchanged.\n */\nfunction resolveLookupPepper(): string | null {\n  const candidates = [\n    process.env.LOOKUP_HASH_PEPPER,\n    process.env.TENANT_DATA_ENCRYPTION_FALLBACK_KEY,\n    process.env.TENANT_DATA_ENCRYPTION_KEY,\n  ]\n  for (const candidate of candidates) {\n    if (typeof candidate !== 'string') continue\n    const normalized = candidate.trim().replace(/(?:^['\"]|['\"]$)/g, '')\n    if (normalized) return normalized\n  }\n  return null\n}\n\n/**\n * Compute a deterministic lookup hash for a low-entropy PII value (email, phone, \u2026).\n *\n * When a lookup pepper is configured the result is a keyed HMAC-SHA-256 prefixed with\n * `v2:` and bound to the optional `context` (entity/field) so digests are not portable\n * across columns, installations, or tenants without the secret. When no pepper is\n * configured it falls back to the legacy unkeyed digest for backward compatibility.\n *\n * The `context` MUST be supplied identically on both the write and the read side for a\n * given column; callers that do not pass one stay mutually consistent.\n */\nexport function hashForLookup(value: string, context?: string): string {\n  const pepper = resolveLookupPepper()\n  const normalized = normalizeLookupValue(value)\n  if (!pepper) {\n    return legacyHashForLookup(value)\n  }\n  const message = context ? `${context}:${normalized}` : normalized\n  const digest = crypto.createHmac('sha256', pepper).update(message).digest('hex')\n  return `${LOOKUP_HASH_V2_PREFIX}${digest}`\n}\n\n/**\n * Candidate lookup hashes for matching a value against `*_hash` columns that may hold\n * either the new keyed (`v2:`) digest or a legacy unkeyed digest. Use this in `$in` /\n * `IN (...)` filters during the migration window so reads keep matching rows written\n * before the keyed format. Once a backfill has recomputed all columns this can collapse\n * back to a single {@link hashForLookup} value.\n */\nexport function lookupHashCandidates(value: string, context?: string): string[] {\n  const primary = hashForLookup(value, context)\n  const legacy = legacyHashForLookup(value)\n  return primary === legacy ? [primary] : [primary, legacy]\n}\n\n/**\n * Strict variant of decryptWithAesGcm that throws typed TenantDataEncryptionError.\n * - Format mismatch (not iv:ct:tag:v1): throws AUTH_FAILED (treat as plaintext).\n * - Valid format but invalid buffer sizes (bad base64): throws MALFORMED_PAYLOAD.\n * - AES-GCM auth tag failure: throws AUTH_FAILED.\n * - Unexpected crypto error: throws DECRYPT_INTERNAL.\n */\nexport function decryptWithAesGcmStrict(payload: string, dekBase64: string): string {\n  const parts = payload.split(':')\n  if (parts.length !== 4 || parts[3] !== 'v1') {\n    throw new TenantDataEncryptionError(\n      TenantDataEncryptionErrorCode.AUTH_FAILED,\n      'Value is not an encrypted payload (format mismatch)',\n    )\n  }\n  const [ivB64, ciphertextB64, tagB64] = parts as [string, string, string, string]\n  let dek: Buffer, iv: Buffer, ciphertext: Buffer, tag: Buffer\n  try {\n    dek = Buffer.from(dekBase64, 'base64')\n    iv = Buffer.from(ivB64, 'base64')\n    ciphertext = Buffer.from(ciphertextB64, 'base64')\n    tag = Buffer.from(tagB64, 'base64')\n  } catch {\n    throw new TenantDataEncryptionError(\n      TenantDataEncryptionErrorCode.MALFORMED_PAYLOAD,\n      'Failed to decode base64 components',\n    )\n  }\n  if (iv.length !== 12 || tag.length !== 16 || ciphertext.length === 0) {\n    throw new TenantDataEncryptionError(\n      TenantDataEncryptionErrorCode.MALFORMED_PAYLOAD,\n      'Invalid AES-GCM payload: unexpected IV, tag, or ciphertext size',\n    )\n  }\n  try {\n    return runAesGcmDecrypt(dek, iv, ciphertext, tag)\n  } catch {\n    throw new TenantDataEncryptionError(\n      TenantDataEncryptionErrorCode.AUTH_FAILED,\n      'AES-GCM authentication tag verification failed',\n    )\n  }\n}\n"],
-  "mappings": "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",
+  "sourcesContent": ["import crypto from 'node:crypto'\nimport { isEncryptionDebugEnabled } from './toggles'\nimport { createLogger } from '../logger'\n\nconst logger = createLogger('shared').child({ component: 'encryption' })\n\nexport type EncryptionPayload = {\n  value: string | null\n  raw: string\n  version: string\n}\n\nexport enum TenantDataEncryptionErrorCode {\n  AUTH_FAILED = 'AUTH_FAILED',\n  MALFORMED_PAYLOAD = 'MALFORMED_PAYLOAD',\n  KMS_UNAVAILABLE = 'KMS_UNAVAILABLE',\n  WRONG_KEY = 'WRONG_KEY',\n  DECRYPT_INTERNAL = 'DECRYPT_INTERNAL',\n}\n\nexport class TenantDataEncryptionError extends Error {\n  code: TenantDataEncryptionErrorCode\n  constructor(code: TenantDataEncryptionErrorCode, message: string) {\n    super(message)\n    this.name = 'TenantDataEncryptionError'\n    this.code = code\n  }\n}\n\nconst BASE64_PART = /^[A-Za-z0-9+/]+={0,2}$/\n\n/**\n * Keyless structural check for the `base64(iv):base64(ciphertext):base64(tag):v1` envelope\n * {@link encryptWithAesGcm} emits.\n *\n * Answers \"is this column holding ciphertext?\" without a DEK, which is the only question\n * available once encryption has been switched off \u2014 the KMS is a noop by then, so\n * {@link decryptWithAesGcm} cannot distinguish ciphertext from plaintext. A 12-byte IV and a\n * 16-byte tag encode to exactly 16 and 24 base64 characters, so the shape is specific enough\n * that plaintext colliding with it by accident is not a practical concern.\n *\n * Deliberate collision is, though: writing `<16 b64>:<b64>:<24 b64>:v1` is trivial, and\n * `TenantDataEncryptionService` dropped a structural check of exactly this shape for that\n * reason (#2720). So this is only safe on values the SERVER wrote \u2014 never as a test applied to\n * attacker-supplied input while a DEK is reachable, where `isEncryptedWithDek` is the test to use.\n * Callers that must run it over user-controlled data are responsible for confirming first that no\n * DEK is reachable, which is what makes forgery pointless: there is nothing to impersonate.\n */\nexport function looksLikeEncryptedPayload(value: unknown): boolean {\n  if (typeof value !== 'string') return false\n  const parts = value.split(':')\n  if (parts.length !== 4 || parts[3] !== 'v1') return false\n  const [iv, ciphertext, tag] = parts as [string, string, string, string]\n  return iv.length === 16\n    && tag.length === 24\n    && ciphertext.length > 0\n    && BASE64_PART.test(iv)\n    && BASE64_PART.test(ciphertext)\n    && BASE64_PART.test(tag)\n}\n\nexport function generateDek(): string {\n  return crypto.randomBytes(32).toString('base64')\n}\n\nfunction logDebug(event: string, payload: Record<string, unknown>) {\n  if (!isEncryptionDebugEnabled()) return\n  try {\n    logger.debug(event, payload)\n  } catch {\n    // ignore\n  }\n}\n\nexport function encryptWithAesGcm(value: string, dekBase64: string): EncryptionPayload {\n  const dek = Buffer.from(dekBase64, 'base64')\n  const iv = crypto.randomBytes(12)\n  const cipher = crypto.createCipheriv('aes-256-gcm', dek, iv)\n  const ciphertext = Buffer.concat([cipher.update(value, 'utf8'), cipher.final()])\n  const tag = cipher.getAuthTag()\n  const payload = [\n    iv.toString('base64'),\n    ciphertext.toString('base64'),\n    tag.toString('base64'),\n    'v1',\n  ].join(':')\n  logDebug('encrypt', { length: ciphertext.length })\n  return { value: payload, raw: payload, version: 'v1' }\n}\n\nfunction runAesGcmDecrypt(dek: Buffer, iv: Buffer, ciphertext: Buffer, tag: Buffer): string {\n  const decipher = crypto.createDecipheriv('aes-256-gcm', dek, iv)\n  decipher.setAuthTag(tag)\n  return Buffer.concat([decipher.update(ciphertext), decipher.final()]).toString('utf8')\n}\n\nexport function decryptWithAesGcm(payload: string, dekBase64: string): string | null {\n  if (!payload) return null\n  const parts = payload.split(':')\n  if (parts.length !== 4) return null\n  const [ivB64, ciphertextB64, tagB64, version] = parts\n  if (version !== 'v1') return null\n  const dek = Buffer.from(dekBase64, 'base64')\n  const iv = Buffer.from(ivB64, 'base64')\n  const ciphertext = Buffer.from(ciphertextB64, 'base64')\n  const tag = Buffer.from(tagB64, 'base64')\n  try {\n    const result = runAesGcmDecrypt(dek, iv, ciphertext, tag)\n    logDebug('decrypt', { iv: ivB64, tag: tagB64 })\n    return result\n  } catch (err) {\n    logDebug('decrypt_error', { message: (err as Error)?.message || String(err) })\n    return null\n  }\n}\n\nconst LOOKUP_HASH_V2_PREFIX = 'v2:'\n\nfunction normalizeLookupValue(value: string): string {\n  return value.toLowerCase().trim()\n}\n\n/**\n * Legacy, unkeyed lookup digest (`sha256(lower(trim(value)))`).\n *\n * @deprecated Unkeyed digests are vulnerable to offline rainbow-table attacks and\n * cross-installation correlation (issue #2718). New writes use {@link hashForLookup},\n * which emits a keyed `v2:` HMAC when a lookup pepper is configured. This helper is\n * retained only so existing `*_hash` columns written before the keyed format can still\n * be matched (see {@link lookupHashCandidates}) until a backfill migration recomputes them.\n */\nexport function legacyHashForLookup(value: string): string {\n  return crypto.createHash('sha256').update(normalizeLookupValue(value)).digest('hex')\n}\n\n/**\n * Resolve the installation-wide lookup pepper used to key lookup hashes.\n *\n * Order of precedence (never `AUTH_SECRET`, per issue #2718):\n * 1. `LOOKUP_HASH_PEPPER` \u2014 dedicated secret for lookup hashing\n * 2. `TENANT_DATA_ENCRYPTION_FALLBACK_KEY` \u2014 existing encryption fallback secret\n * 3. `TENANT_DATA_ENCRYPTION_KEY` \u2014 existing encryption secret\n *\n * Returns `null` when no secret is configured, in which case {@link hashForLookup}\n * falls back to the legacy unkeyed digest so deployments without any configured key\n * keep working unchanged.\n */\nfunction resolveLookupPepper(): string | null {\n  const candidates = [\n    process.env.LOOKUP_HASH_PEPPER,\n    process.env.TENANT_DATA_ENCRYPTION_FALLBACK_KEY,\n    process.env.TENANT_DATA_ENCRYPTION_KEY,\n  ]\n  for (const candidate of candidates) {\n    if (typeof candidate !== 'string') continue\n    const normalized = candidate.trim().replace(/(?:^['\"]|['\"]$)/g, '')\n    if (normalized) return normalized\n  }\n  return null\n}\n\n/**\n * Compute a deterministic lookup hash for a low-entropy PII value (email, phone, \u2026).\n *\n * When a lookup pepper is configured the result is a keyed HMAC-SHA-256 prefixed with\n * `v2:` and bound to the optional `context` (entity/field) so digests are not portable\n * across columns, installations, or tenants without the secret. When no pepper is\n * configured it falls back to the legacy unkeyed digest for backward compatibility.\n *\n * The `context` MUST be supplied identically on both the write and the read side for a\n * given column; callers that do not pass one stay mutually consistent.\n */\nexport function hashForLookup(value: string, context?: string): string {\n  const pepper = resolveLookupPepper()\n  const normalized = normalizeLookupValue(value)\n  if (!pepper) {\n    return legacyHashForLookup(value)\n  }\n  const message = context ? `${context}:${normalized}` : normalized\n  const digest = crypto.createHmac('sha256', pepper).update(message).digest('hex')\n  return `${LOOKUP_HASH_V2_PREFIX}${digest}`\n}\n\n/**\n * Candidate lookup hashes for matching a value against `*_hash` columns that may hold\n * either the new keyed (`v2:`) digest or a legacy unkeyed digest. Use this in `$in` /\n * `IN (...)` filters during the migration window so reads keep matching rows written\n * before the keyed format. Once a backfill has recomputed all columns this can collapse\n * back to a single {@link hashForLookup} value.\n */\nexport function lookupHashCandidates(value: string, context?: string): string[] {\n  const primary = hashForLookup(value, context)\n  const legacy = legacyHashForLookup(value)\n  return primary === legacy ? [primary] : [primary, legacy]\n}\n\n/**\n * Strict variant of decryptWithAesGcm that throws typed TenantDataEncryptionError.\n * - Format mismatch (not iv:ct:tag:v1): throws AUTH_FAILED (treat as plaintext).\n * - Valid format but invalid buffer sizes (bad base64): throws MALFORMED_PAYLOAD.\n * - AES-GCM auth tag failure: throws AUTH_FAILED.\n * - Unexpected crypto error: throws DECRYPT_INTERNAL.\n */\nexport function decryptWithAesGcmStrict(payload: string, dekBase64: string): string {\n  const parts = payload.split(':')\n  if (parts.length !== 4 || parts[3] !== 'v1') {\n    throw new TenantDataEncryptionError(\n      TenantDataEncryptionErrorCode.AUTH_FAILED,\n      'Value is not an encrypted payload (format mismatch)',\n    )\n  }\n  const [ivB64, ciphertextB64, tagB64] = parts as [string, string, string, string]\n  let dek: Buffer, iv: Buffer, ciphertext: Buffer, tag: Buffer\n  try {\n    dek = Buffer.from(dekBase64, 'base64')\n    iv = Buffer.from(ivB64, 'base64')\n    ciphertext = Buffer.from(ciphertextB64, 'base64')\n    tag = Buffer.from(tagB64, 'base64')\n  } catch {\n    throw new TenantDataEncryptionError(\n      TenantDataEncryptionErrorCode.MALFORMED_PAYLOAD,\n      'Failed to decode base64 components',\n    )\n  }\n  if (iv.length !== 12 || tag.length !== 16 || ciphertext.length === 0) {\n    throw new TenantDataEncryptionError(\n      TenantDataEncryptionErrorCode.MALFORMED_PAYLOAD,\n      'Invalid AES-GCM payload: unexpected IV, tag, or ciphertext size',\n    )\n  }\n  try {\n    return runAesGcmDecrypt(dek, iv, ciphertext, tag)\n  } catch {\n    throw new TenantDataEncryptionError(\n      TenantDataEncryptionErrorCode.AUTH_FAILED,\n      'AES-GCM authentication tag verification failed',\n    )\n  }\n}\n"],
+  "mappings": "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",
   "names": ["TenantDataEncryptionErrorCode"]
 }

package/dist/lib/encryption/kms.js

@@ -330,6 +330,10 @@ function logDerivedKeyFallbackBanner(opts) {
     secretFingerprint: fingerprintSecret(opts.secret)
   });
 }
+function resolveEncryptionMode(kms) {
+  if (!isTenantDataEncryptionEnabled()) return "disabled";
+  return kms.isHealthy() ? "active" : "unavailable";
+}
 function createKmsService() {
   if (!isTenantDataEncryptionEnabled()) return new NoopKmsService();
   const primary = new HashicorpVaultKmsService();
@@ -356,6 +360,7 @@ export {
   NoopKmsService,
   buildDerivedKeyFallbackBannerLines,
   createKmsService,
-  hashForLookup
+  hashForLookup,
+  resolveEncryptionMode
 };
 //# sourceMappingURL=kms.js.map

package/dist/lib/encryption/kms.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../src/lib/encryption/kms.ts"],
-  "sourcesContent": ["import crypto from 'node:crypto'\nimport { generateDek, hashForLookup } from './aes'\nimport { isEncryptionDebugEnabled, isTenantDataEncryptionEnabled } from './toggles'\nimport { parseBooleanToken } from '../boolean'\nimport { createLogger } from '../logger'\nimport { fetchWithTimeout, resolveTimeoutMs } from '../http/fetchWithTimeout'\n\nconst logger = createLogger('shared').child({ component: 'kms' })\n\nconst DEFAULT_VAULT_REQUEST_TIMEOUT_MS = 1_000\nconst DEFAULT_VAULT_RECOVERY_COOLDOWN_MS = 30_000\n\nfunction resolveVaultRequestTimeoutMs(): number {\n  const raw = process.env.VAULT_REQUEST_TIMEOUT_MS\n  const parsed = raw ? Number.parseInt(raw, 10) : undefined\n  return resolveTimeoutMs(parsed, DEFAULT_VAULT_REQUEST_TIMEOUT_MS)\n}\n\nfunction resolveVaultRecoveryCooldownMs(): number {\n  const raw = process.env.VAULT_RECOVERY_COOLDOWN_MS\n  const parsed = raw ? Number.parseInt(raw, 10) : undefined\n  return resolveTimeoutMs(parsed, DEFAULT_VAULT_RECOVERY_COOLDOWN_MS)\n}\n\nexport type TenantDek = {\n  tenantId: string\n  key: string // base64\n  fetchedAt: number\n}\n\nexport interface KmsService {\n  getTenantDek(tenantId: string): Promise<TenantDek | null>\n  createTenantDek(tenantId: string): Promise<TenantDek | null>\n  isHealthy(): boolean\n  invalidateDek?(tenantId: string): void\n}\n\nclass FallbackKmsService implements KmsService {\n  private notified = false\n  constructor(\n    private readonly primary: KmsService,\n    private readonly fallback: KmsService | null,\n    private readonly onFallback?: () => void,\n  ) {}\n\n  isHealthy(): boolean {\n    return this.primary.isHealthy() || Boolean(this.fallback?.isHealthy?.())\n  }\n\n  private notifyFallback() {\n    if (this.notified) return\n    this.notified = true\n    this.onFallback?.()\n  }\n\n  private async fromPrimary<T>(op: () => Promise<T | null>): Promise<T | null> {\n    try {\n      return await op()\n    } catch (err) {\n      logger.warn('Primary KMS failed, will try fallback', { err })\n      return null\n    }\n  }\n\n  async getTenantDek(tenantId: string): Promise<TenantDek | null> {\n    if (this.primary.isHealthy()) {\n      const dek = await this.fromPrimary(() => this.primary.getTenantDek(tenantId))\n      if (dek) return dek\n    }\n    if (this.fallback?.isHealthy()) {\n      this.notifyFallback()\n      return this.fallback.getTenantDek(tenantId)\n    }\n    return null\n  }\n\n  async createTenantDek(tenantId: string): Promise<TenantDek | null> {\n    if (this.primary.isHealthy()) {\n      const dek = await this.fromPrimary(() => this.primary.createTenantDek(tenantId))\n      if (dek) return dek\n    }\n    if (this.fallback?.isHealthy()) {\n      this.notifyFallback()\n      return this.fallback.createTenantDek(tenantId)\n    }\n    return null\n  }\n\n  invalidateDek(tenantId: string): void {\n    this.primary.invalidateDek?.(tenantId)\n    this.fallback?.invalidateDek?.(tenantId)\n  }\n}\n\ntype VaultClientOpts = {\n  vaultAddr?: string\n  vaultToken?: string\n  mountPath?: string\n  ttlMs?: number\n  requestTimeoutMs?: number\n  recoveryCooldownMs?: number\n}\n\ntype VaultReadResponse = {\n  data?: { data?: { key?: string; version?: number }; metadata?: Record<string, unknown> }\n}\n\n// 'conflict' = a check-and-set write lost to a concurrent writer (normal race\n// outcome, Vault still healthy); 'error' = the write genuinely failed.\ntype VaultWriteOutcome = 'ok' | 'conflict' | 'error'\n\nfunction normalizeEnv(value: string | undefined): string {\n  if (!value) return ''\n  return value.trim().replace(/(?:^['\"]|['\"]$)/g, '')\n}\n\ntype DerivedSecret = { secret: string; source: 'explicit' | 'dev-default'; envName: string }\n\nfunction resolveDerivedKeySecret(): DerivedSecret | null {\n  const candidates: Array<{ value: string | null; envName: string }> = [\n    { value: process.env.TENANT_DATA_ENCRYPTION_FALLBACK_KEY ?? null, envName: 'TENANT_DATA_ENCRYPTION_FALLBACK_KEY' },\n    { value: process.env.TENANT_DATA_ENCRYPTION_KEY ?? null, envName: 'TENANT_DATA_ENCRYPTION_KEY' },\n  ]\n  for (const raw of candidates) {\n    const normalized = normalizeEnv(raw.value ?? undefined)\n    if (normalized) return { secret: normalized, source: 'explicit', envName: raw.envName }\n  }\n  if (\n    process.env.NODE_ENV !== 'production'\n    && parseBooleanToken(process.env.ALLOW_DERIVED_KMS_FALLBACK) === true\n  ) {\n    return { secret: 'om-dev-tenant-encryption', source: 'dev-default', envName: 'DEV_DEFAULT' }\n  }\n  return null\n}\n\nexport class NoopKmsService implements KmsService {\n  isHealthy(): boolean { return !isTenantDataEncryptionEnabled() }\n  async getTenantDek(): Promise<TenantDek | null> { return null }\n  async createTenantDek(): Promise<TenantDek | null> { return null }\n}\n\nclass DerivedKmsService implements KmsService {\n  private root: Buffer\n  constructor(secret: string) {\n    // Derive a stable root key from the provided secret so derived tenant keys are deterministic\n    this.root = crypto.createHash('sha256').update(secret).digest()\n  }\n\n  isHealthy(): boolean {\n    return true\n  }\n\n  private deriveKey(tenantId: string): string {\n    const iterations = 310_000\n    const keyLength = 32\n    const derived = crypto.pbkdf2Sync(this.root, tenantId, iterations, keyLength, 'sha512')\n    return derived.toString('base64')\n  }\n\n  async getTenantDek(tenantId: string): Promise<TenantDek | null> {\n    if (!tenantId) return null\n    return { tenantId, key: this.deriveKey(tenantId), fetchedAt: Date.now() }\n  }\n\n  async createTenantDek(tenantId: string): Promise<TenantDek | null> {\n    return this.getTenantDek(tenantId)\n  }\n}\n\nexport class HashicorpVaultKmsService implements KmsService {\n  private cache = new Map<string, TenantDek>()\n  private readonly vaultAddr: string\n  private readonly vaultToken: string\n  private readonly mountPath: string\n  private readonly ttlMs: number\n  private readonly requestTimeoutMs: number\n  private readonly recoveryCooldownMs: number\n  private healthy = true\n  // Sticky terminal failure (missing VAULT_ADDR/VAULT_TOKEN): no amount of\n  // re-probing fixes a misconfiguration, so this never self-heals \u2014 only a\n  // restart with corrected config does.\n  private misconfigured = false\n  // Timestamp of the last transient failure (timeout / network blip / 5xx).\n  // Drives the half-open circuit breaker in isHealthy(): after the cooldown the\n  // instance reports healthy again so the next call re-probes Vault.\n  private lastTransientFailureAt: number | null = null\n  private readonly debugEnabled: boolean\n  private static loggedInit = false\n\n  constructor(opts: VaultClientOpts = {}) {\n    this.vaultAddr = normalizeEnv(opts.vaultAddr || process.env.VAULT_ADDR || '')\n    this.vaultToken = normalizeEnv(opts.vaultToken || process.env.VAULT_TOKEN || '')\n    this.mountPath = (opts.mountPath || process.env.VAULT_KV_PATH || 'secret/data').replace(/\\/+$/, '')\n    this.ttlMs = opts.ttlMs ?? 15 * 60 * 1000\n    this.requestTimeoutMs = resolveTimeoutMs(opts.requestTimeoutMs, resolveVaultRequestTimeoutMs())\n    this.recoveryCooldownMs = resolveTimeoutMs(opts.recoveryCooldownMs, resolveVaultRecoveryCooldownMs())\n    this.debugEnabled = isEncryptionDebugEnabled()\n    if (!this.vaultAddr || !this.vaultToken) {\n      this.healthy = false\n      this.misconfigured = true\n      if (this.debugEnabled) {\n        logger.warn('Vault misconfigured (missing VAULT_ADDR or VAULT_TOKEN)')\n      }\n    }\n    if (this.healthy && !HashicorpVaultKmsService.loggedInit && this.debugEnabled) {\n      HashicorpVaultKmsService.loggedInit = true\n      if (this.debugEnabled) {\n        logger.info('Hashicorp Vault KMS enabled')\n      }\n    }\n  }\n\n  isHealthy(): boolean {\n    // A missing-config failure is terminal \u2014 never report healthy again.\n    if (this.misconfigured) return false\n    if (this.healthy) return true\n    // Half-open circuit breaker: once the cooldown since the last transient\n    // failure has elapsed, report healthy so the next read/write re-probes\n    // Vault. A successful probe flips `healthy` back on; a failing one records a\n    // fresh failure timestamp and re-opens the breaker for another cooldown.\n    if (this.lastTransientFailureAt === null) return false\n    return this.now() - this.lastTransientFailureAt >= this.recoveryCooldownMs\n  }\n\n  private now(): number {\n    return Date.now()\n  }\n\n  // Vault responded successfully (or is provably reachable): close the breaker.\n  private markHealthy(): void {\n    this.healthy = true\n    this.lastTransientFailureAt = null\n  }\n\n  // Transient infra failure (timeout / network blip / 5xx): open the breaker and\n  // start the recovery cooldown so a later call can re-probe and self-heal.\n  private markTransientFailure(): void {\n    this.healthy = false\n    this.lastTransientFailureAt = this.now()\n  }\n\n  private cacheHit(tenantId: string): TenantDek | null {\n    const entry = this.cache.get(tenantId)\n    if (!entry) return null\n    if (this.now() - entry.fetchedAt > this.ttlMs) {\n      this.cache.delete(tenantId)\n      return null\n    }\n    return entry\n  }\n\n  private async readVault(path: string): Promise<VaultReadResponse | null> {\n    if (!this.vaultAddr || !this.vaultToken) {\n      this.healthy = false\n      this.misconfigured = true\n      return null\n    }\n    try {\n      const res = await fetchWithTimeout(`${this.vaultAddr}/v1/${path}`, {\n        method: 'GET',\n        headers: { 'X-Vault-Token': this.vaultToken },\n        timeoutMs: this.requestTimeoutMs,\n      })\n      if (!res.ok) {\n        // 5xx = Vault down/erroring (transient). <500 (auth/not-found/etc.) means\n        // Vault is reachable and answered, so keep it healthy \u2014 a 404 for a\n        // not-yet-created tenant DEK is the normal read-before-write path.\n        if (res.status >= 500) this.markTransientFailure()\n        else this.markHealthy()\n        logger.warn('Vault read failed', { path, status: res.status })\n        return null\n      }\n      this.markHealthy()\n      if (this.debugEnabled) {\n        logger.info('Vault read ok', { path })\n      }\n      return (await res.json()) as VaultReadResponse\n    } catch (err) {\n      this.markTransientFailure()\n      logger.warn('Vault read error', { path, err, timeoutMs: this.requestTimeoutMs })\n      return null\n    }\n  }\n\n  private async writeVault(path: string, key: string, opts?: { cas?: number }): Promise<VaultWriteOutcome> {\n    if (!this.vaultAddr || !this.vaultToken) {\n      this.healthy = false\n      this.misconfigured = true\n      return 'error'\n    }\n    const body: { data: { key: string }; options?: { cas: number } } = { data: { key } }\n    if (typeof opts?.cas === 'number') body.options = { cas: opts.cas }\n    try {\n      const res = await fetchWithTimeout(`${this.vaultAddr}/v1/${path}`, {\n        method: 'POST',\n        headers: {\n          'X-Vault-Token': this.vaultToken,\n          'Content-Type': 'application/json',\n        },\n        body: JSON.stringify(body),\n        timeoutMs: this.requestTimeoutMs,\n      })\n      if (res.ok) {\n        this.markHealthy()\n        return 'ok'\n      }\n      // KV v2 returns 400 when a check-and-set write loses to a concurrent\n      // writer (path already at a newer version). That is a normal race outcome,\n      // not an unhealthy Vault \u2014 Vault is reachable, so close the breaker.\n      if (typeof opts?.cas === 'number' && res.status === 400) {\n        this.markHealthy()\n        logger.warn('Vault write CAS conflict (concurrent DEK create)', { path, status: res.status })\n        return 'conflict'\n      }\n      this.markTransientFailure()\n      logger.warn('Vault write failed', { path, status: res.status })\n      return 'error'\n    } catch (err) {\n      this.markTransientFailure()\n      logger.warn('Vault write error', { path, err, timeoutMs: this.requestTimeoutMs })\n      return 'error'\n    }\n  }\n\n  private buildKeyPath(tenantId: string): string {\n    const suffix = `tenant_key_${tenantId}`\n    const normalizedMount = this.mountPath.replace(/^\\/+/, '')\n    return `${normalizedMount}/${suffix}`\n  }\n\n  private remember(entry: TenantDek): TenantDek {\n    this.cache.set(entry.tenantId, entry)\n    return entry\n  }\n\n  async getTenantDek(tenantId: string): Promise<TenantDek | null> {\n    const cached = this.cacheHit(tenantId)\n    if (cached) return cached\n    const path = this.buildKeyPath(tenantId)\n    const res = await this.readVault(path)\n    const key = res?.data?.data?.key\n    if (!key) {\n      logger.warn('No tenant DEK found in Vault', { tenantId, path })\n      return null\n    }\n    const dek: TenantDek = { tenantId, key, fetchedAt: this.now() }\n    return this.remember(dek)\n  }\n\n  async createTenantDek(tenantId: string): Promise<TenantDek | null> {\n    const path = this.buildKeyPath(tenantId)\n    // Read-before-write: if a DEK already exists for this tenant (another request\n    // or process created it first), adopt it instead of overwriting the active\n    // key \u2014 overwriting orphans every row already encrypted under it (#2746).\n    const existing = await this.readVault(path)\n    const existingKey = existing?.data?.data?.key\n    if (existingKey) {\n      return this.remember({ tenantId, key: existingKey, fetchedAt: this.now() })\n    }\n    // A read failure (timeout / 5xx) flips `healthy` off; don't blind-write a new\n    // key over a possibly-existing one we just couldn't read \u2014 let the caller fall back.\n    if (!this.healthy) return null\n    const key = generateDek()\n    const outcome = await this.writeVault(path, key, { cas: 0 })\n    if (outcome === 'ok') {\n      logger.info('Stored tenant DEK in Vault', { tenantId, path })\n      return this.remember({ tenantId, key, fetchedAt: this.now() })\n    }\n    if (outcome === 'conflict') {\n      // A concurrent create won the CAS race \u2014 adopt the winner's key so both\n      // callers encrypt under the same DEK.\n      const winner = await this.readVault(path)\n      const winnerKey = winner?.data?.data?.key\n      if (winnerKey) {\n        logger.info('Adopted concurrently-created tenant DEK', { tenantId, path })\n        return this.remember({ tenantId, key: winnerKey, fetchedAt: this.now() })\n      }\n    }\n    logger.warn('Failed to store tenant DEK in Vault', { tenantId, path })\n    return null\n  }\n\n  invalidateDek(tenantId: string): void {\n    this.cache.delete(tenantId)\n  }\n}\n\nlet loggedDerivedKeyFallbackBanner = false\n\nfunction fingerprintSecret(secret: string): string {\n  return crypto.createHash('sha256').update(secret, 'utf8').digest('hex').slice(0, 16)\n}\n\nexport function buildDerivedKeyFallbackBannerLines(opts: DerivedSecret): string[] {\n  const sourceLine =\n    opts.source === 'explicit' ? `Source: ${opts.envName}` : 'Source: dev default secret (do NOT use in production)'\n  return [\n    '\uD83D\uDEA8 Using derived tenant encryption keys (Vault unavailable / no DEK)',\n    sourceLine,\n    `Secret fingerprint (sha256, truncated): ${fingerprintSecret(opts.secret)}`,\n    'Persist this secret securely. Without it, encrypted tenant data cannot be recovered after restart.',\n  ]\n}\n\nfunction logDerivedKeyFallbackBanner(opts: DerivedSecret): void {\n  if (process.env.NODE_ENV === 'test' || loggedDerivedKeyFallbackBanner) return\n  loggedDerivedKeyFallbackBanner = true\n  const redBg = '\\x1b[41m'\n  const white = '\\x1b[97m'\n  const reset = '\\x1b[0m'\n  const width = 110\n  const border = `${redBg}${white}${'\u2501'.repeat(width)}${reset}`\n  const body = buildDerivedKeyFallbackBannerLines(opts)\n  const bannerLines = [\n    border,\n    ...body.map((line) => `${redBg}${white} ${line.padEnd(width - 2, ' ')} ${reset}`),\n    border,\n  ]\n  process.stderr.write(bannerLines.join('\\n') + '\\n')\n  logger.warn('Using derived tenant encryption keys (Vault unavailable / no DEK)', {\n    secretFingerprint: fingerprintSecret(opts.secret),\n  })\n}\n\nexport function createKmsService(): KmsService {\n  if (!isTenantDataEncryptionEnabled()) return new NoopKmsService()\n  const primary = new HashicorpVaultKmsService()\n\n  const derived = resolveDerivedKeySecret()\n  const fallback = derived ? new DerivedKmsService(derived.secret) : null\n  const notifyFallback = derived\n    ? () => {\n        logDerivedKeyFallbackBanner(derived)\n      }\n    : undefined\n\n  if (!primary.isHealthy()) {\n    if (fallback) {\n      notifyFallback?.()\n      return fallback\n    }\n    logger.warn('Vault not healthy or misconfigured (missing VAULT_ADDR/VAULT_TOKEN) and no fallback secret provided; falling back to noop KMS')\n    return new NoopKmsService()\n  }\n\n  if (fallback) {\n    return new FallbackKmsService(primary, fallback, notifyFallback)\n  }\n\n  return primary\n}\n\nexport { hashForLookup }\n"],
-  "mappings": "AAAA,OAAO,YAAY;AACnB,SAAS,aAAa,qBAAqB;AAC3C,SAAS,0BAA0B,qCAAqC;AACxE,SAAS,yBAAyB;AAClC,SAAS,oBAAoB;AAC7B,SAAS,kBAAkB,wBAAwB;AAEnD,MAAM,SAAS,aAAa,QAAQ,EAAE,MAAM,EAAE,WAAW,MAAM,CAAC;AAEhE,MAAM,mCAAmC;AACzC,MAAM,qCAAqC;AAE3C,SAAS,+BAAuC;AAC9C,QAAM,MAAM,QAAQ,IAAI;AACxB,QAAM,SAAS,MAAM,OAAO,SAAS,KAAK,EAAE,IAAI;AAChD,SAAO,iBAAiB,QAAQ,gCAAgC;AAClE;AAEA,SAAS,iCAAyC;AAChD,QAAM,MAAM,QAAQ,IAAI;AACxB,QAAM,SAAS,MAAM,OAAO,SAAS,KAAK,EAAE,IAAI;AAChD,SAAO,iBAAiB,QAAQ,kCAAkC;AACpE;AAeA,MAAM,mBAAyC;AAAA,EAE7C,YACmB,SACA,UACA,YACjB;AAHiB;AACA;AACA;AAJnB,SAAQ,WAAW;AAAA,EAKhB;AAAA,EAEH,YAAqB;AACnB,WAAO,KAAK,QAAQ,UAAU,KAAK,QAAQ,KAAK,UAAU,YAAY,CAAC;AAAA,EACzE;AAAA,EAEQ,iBAAiB;AACvB,QAAI,KAAK,SAAU;AACnB,SAAK,WAAW;AAChB,SAAK,aAAa;AAAA,EACpB;AAAA,EAEA,MAAc,YAAe,IAAgD;AAC3E,QAAI;AACF,aAAO,MAAM,GAAG;AAAA,IAClB,SAAS,KAAK;AACZ,aAAO,KAAK,yCAAyC,EAAE,IAAI,CAAC;AAC5D,aAAO;AAAA,IACT;AAAA,EACF;AAAA,EAEA,MAAM,aAAa,UAA6C;AAC9D,QAAI,KAAK,QAAQ,UAAU,GAAG;AAC5B,YAAM,MAAM,MAAM,KAAK,YAAY,MAAM,KAAK,QAAQ,aAAa,QAAQ,CAAC;AAC5E,UAAI,IAAK,QAAO;AAAA,IAClB;AACA,QAAI,KAAK,UAAU,UAAU,GAAG;AAC9B,WAAK,eAAe;AACpB,aAAO,KAAK,SAAS,aAAa,QAAQ;AAAA,IAC5C;AACA,WAAO;AAAA,EACT;AAAA,EAEA,MAAM,gBAAgB,UAA6C;AACjE,QAAI,KAAK,QAAQ,UAAU,GAAG;AAC5B,YAAM,MAAM,MAAM,KAAK,YAAY,MAAM,KAAK,QAAQ,gBAAgB,QAAQ,CAAC;AAC/E,UAAI,IAAK,QAAO;AAAA,IAClB;AACA,QAAI,KAAK,UAAU,UAAU,GAAG;AAC9B,WAAK,eAAe;AACpB,aAAO,KAAK,SAAS,gBAAgB,QAAQ;AAAA,IAC/C;AACA,WAAO;AAAA,EACT;AAAA,EAEA,cAAc,UAAwB;AACpC,SAAK,QAAQ,gBAAgB,QAAQ;AACrC,SAAK,UAAU,gBAAgB,QAAQ;AAAA,EACzC;AACF;AAmBA,SAAS,aAAa,OAAmC;AACvD,MAAI,CAAC,MAAO,QAAO;AACnB,SAAO,MAAM,KAAK,EAAE,QAAQ,oBAAoB,EAAE;AACpD;AAIA,SAAS,0BAAgD;AACvD,QAAM,aAA+D;AAAA,IACnE,EAAE,OAAO,QAAQ,IAAI,uCAAuC,MAAM,SAAS,sCAAsC;AAAA,IACjH,EAAE,OAAO,QAAQ,IAAI,8BAA8B,MAAM,SAAS,6BAA6B;AAAA,EACjG;AACA,aAAW,OAAO,YAAY;AAC5B,UAAM,aAAa,aAAa,IAAI,SAAS,MAAS;AACtD,QAAI,WAAY,QAAO,EAAE,QAAQ,YAAY,QAAQ,YAAY,SAAS,IAAI,QAAQ;AAAA,EACxF;AACA,MACE,QAAQ,IAAI,aAAa,gBACtB,kBAAkB,QAAQ,IAAI,0BAA0B,MAAM,MACjE;AACA,WAAO,EAAE,QAAQ,4BAA4B,QAAQ,eAAe,SAAS,cAAc;AAAA,EAC7F;AACA,SAAO;AACT;AAEO,MAAM,eAAqC;AAAA,EAChD,YAAqB;AAAE,WAAO,CAAC,8BAA8B;AAAA,EAAE;AAAA,EAC/D,MAAM,eAA0C;AAAE,WAAO;AAAA,EAAK;AAAA,EAC9D,MAAM,kBAA6C;AAAE,WAAO;AAAA,EAAK;AACnE;AAEA,MAAM,kBAAwC;AAAA,EAE5C,YAAY,QAAgB;AAE1B,SAAK,OAAO,OAAO,WAAW,QAAQ,EAAE,OAAO,MAAM,EAAE,OAAO;AAAA,EAChE;AAAA,EAEA,YAAqB;AACnB,WAAO;AAAA,EACT;AAAA,EAEQ,UAAU,UAA0B;AAC1C,UAAM,aAAa;AACnB,UAAM,YAAY;AAClB,UAAM,UAAU,OAAO,WAAW,KAAK,MAAM,UAAU,YAAY,WAAW,QAAQ;AACtF,WAAO,QAAQ,SAAS,QAAQ;AAAA,EAClC;AAAA,EAEA,MAAM,aAAa,UAA6C;AAC9D,QAAI,CAAC,SAAU,QAAO;AACtB,WAAO,EAAE,UAAU,KAAK,KAAK,UAAU,QAAQ,GAAG,WAAW,KAAK,IAAI,EAAE;AAAA,EAC1E;AAAA,EAEA,MAAM,gBAAgB,UAA6C;AACjE,WAAO,KAAK,aAAa,QAAQ;AAAA,EACnC;AACF;AAEO,MAAM,yBAA+C;AAAA,EAoB1D,YAAY,OAAwB,CAAC,GAAG;AAnBxC,SAAQ,QAAQ,oBAAI,IAAuB;AAO3C,SAAQ,UAAU;AAIlB;AAAA;AAAA;AAAA,SAAQ,gBAAgB;AAIxB;AAAA;AAAA;AAAA,SAAQ,yBAAwC;AAK9C,SAAK,YAAY,aAAa,KAAK,aAAa,QAAQ,IAAI,cAAc,EAAE;AAC5E,SAAK,aAAa,aAAa,KAAK,cAAc,QAAQ,IAAI,eAAe,EAAE;AAC/E,SAAK,aAAa,KAAK,aAAa,QAAQ,IAAI,iBAAiB,eAAe,QAAQ,QAAQ,EAAE;AAClG,SAAK,QAAQ,KAAK,SAAS,KAAK,KAAK;AACrC,SAAK,mBAAmB,iBAAiB,KAAK,kBAAkB,6BAA6B,CAAC;AAC9F,SAAK,qBAAqB,iBAAiB,KAAK,oBAAoB,+BAA+B,CAAC;AACpG,SAAK,eAAe,yBAAyB;AAC7C,QAAI,CAAC,KAAK,aAAa,CAAC,KAAK,YAAY;AACvC,WAAK,UAAU;AACf,WAAK,gBAAgB;AACrB,UAAI,KAAK,cAAc;AACrB,eAAO,KAAK,yDAAyD;AAAA,MACvE;AAAA,IACF;AACA,QAAI,KAAK,WAAW,CAAC,yBAAyB,cAAc,KAAK,cAAc;AAC7E,+BAAyB,aAAa;AACtC,UAAI,KAAK,cAAc;AACrB,eAAO,KAAK,6BAA6B;AAAA,MAC3C;AAAA,IACF;AAAA,EACF;AAAA,EAvBA;AAAA,SAAe,aAAa;AAAA;AAAA,EAyB5B,YAAqB;AAEnB,QAAI,KAAK,cAAe,QAAO;AAC/B,QAAI,KAAK,QAAS,QAAO;AAKzB,QAAI,KAAK,2BAA2B,KAAM,QAAO;AACjD,WAAO,KAAK,IAAI,IAAI,KAAK,0BAA0B,KAAK;AAAA,EAC1D;AAAA,EAEQ,MAAc;AACpB,WAAO,KAAK,IAAI;AAAA,EAClB;AAAA;AAAA,EAGQ,cAAoB;AAC1B,SAAK,UAAU;AACf,SAAK,yBAAyB;AAAA,EAChC;AAAA;AAAA;AAAA,EAIQ,uBAA6B;AACnC,SAAK,UAAU;AACf,SAAK,yBAAyB,KAAK,IAAI;AAAA,EACzC;AAAA,EAEQ,SAAS,UAAoC;AACnD,UAAM,QAAQ,KAAK,MAAM,IAAI,QAAQ;AACrC,QAAI,CAAC,MAAO,QAAO;AACnB,QAAI,KAAK,IAAI,IAAI,MAAM,YAAY,KAAK,OAAO;AAC7C,WAAK,MAAM,OAAO,QAAQ;AAC1B,aAAO;AAAA,IACT;AACA,WAAO;AAAA,EACT;AAAA,EAEA,MAAc,UAAU,MAAiD;AACvE,QAAI,CAAC,KAAK,aAAa,CAAC,KAAK,YAAY;AACvC,WAAK,UAAU;AACf,WAAK,gBAAgB;AACrB,aAAO;AAAA,IACT;AACA,QAAI;AACF,YAAM,MAAM,MAAM,iBAAiB,GAAG,KAAK,SAAS,OAAO,IAAI,IAAI;AAAA,QACjE,QAAQ;AAAA,QACR,SAAS,EAAE,iBAAiB,KAAK,WAAW;AAAA,QAC5C,WAAW,KAAK;AAAA,MAClB,CAAC;AACD,UAAI,CAAC,IAAI,IAAI;AAIX,YAAI,IAAI,UAAU,IAAK,MAAK,qBAAqB;AAAA,YAC5C,MAAK,YAAY;AACtB,eAAO,KAAK,qBAAqB,EAAE,MAAM,QAAQ,IAAI,OAAO,CAAC;AAC7D,eAAO;AAAA,MACT;AACA,WAAK,YAAY;AACjB,UAAI,KAAK,cAAc;AACrB,eAAO,KAAK,iBAAiB,EAAE,KAAK,CAAC;AAAA,MACvC;AACA,aAAQ,MAAM,IAAI,KAAK;AAAA,IACzB,SAAS,KAAK;AACZ,WAAK,qBAAqB;AAC1B,aAAO,KAAK,oBAAoB,EAAE,MAAM,KAAK,WAAW,KAAK,iBAAiB,CAAC;AAC/E,aAAO;AAAA,IACT;AAAA,EACF;AAAA,EAEA,MAAc,WAAW,MAAc,KAAa,MAAqD;AACvG,QAAI,CAAC,KAAK,aAAa,CAAC,KAAK,YAAY;AACvC,WAAK,UAAU;AACf,WAAK,gBAAgB;AACrB,aAAO;AAAA,IACT;AACA,UAAM,OAA6D,EAAE,MAAM,EAAE,IAAI,EAAE;AACnF,QAAI,OAAO,MAAM,QAAQ,SAAU,MAAK,UAAU,EAAE,KAAK,KAAK,IAAI;AAClE,QAAI;AACF,YAAM,MAAM,MAAM,iBAAiB,GAAG,KAAK,SAAS,OAAO,IAAI,IAAI;AAAA,QACjE,QAAQ;AAAA,QACR,SAAS;AAAA,UACP,iBAAiB,KAAK;AAAA,UACtB,gBAAgB;AAAA,QAClB;AAAA,QACA,MAAM,KAAK,UAAU,IAAI;AAAA,QACzB,WAAW,KAAK;AAAA,MAClB,CAAC;AACD,UAAI,IAAI,IAAI;AACV,aAAK,YAAY;AACjB,eAAO;AAAA,MACT;AAIA,UAAI,OAAO,MAAM,QAAQ,YAAY,IAAI,WAAW,KAAK;AACvD,aAAK,YAAY;AACjB,eAAO,KAAK,oDAAoD,EAAE,MAAM,QAAQ,IAAI,OAAO,CAAC;AAC5F,eAAO;AAAA,MACT;AACA,WAAK,qBAAqB;AAC1B,aAAO,KAAK,sBAAsB,EAAE,MAAM,QAAQ,IAAI,OAAO,CAAC;AAC9D,aAAO;AAAA,IACT,SAAS,KAAK;AACZ,WAAK,qBAAqB;AAC1B,aAAO,KAAK,qBAAqB,EAAE,MAAM,KAAK,WAAW,KAAK,iBAAiB,CAAC;AAChF,aAAO;AAAA,IACT;AAAA,EACF;AAAA,EAEQ,aAAa,UAA0B;AAC7C,UAAM,SAAS,cAAc,QAAQ;AACrC,UAAM,kBAAkB,KAAK,UAAU,QAAQ,QAAQ,EAAE;AACzD,WAAO,GAAG,eAAe,IAAI,MAAM;AAAA,EACrC;AAAA,EAEQ,SAAS,OAA6B;AAC5C,SAAK,MAAM,IAAI,MAAM,UAAU,KAAK;AACpC,WAAO;AAAA,EACT;AAAA,EAEA,MAAM,aAAa,UAA6C;AAC9D,UAAM,SAAS,KAAK,SAAS,QAAQ;AACrC,QAAI,OAAQ,QAAO;AACnB,UAAM,OAAO,KAAK,aAAa,QAAQ;AACvC,UAAM,MAAM,MAAM,KAAK,UAAU,IAAI;AACrC,UAAM,MAAM,KAAK,MAAM,MAAM;AAC7B,QAAI,CAAC,KAAK;AACR,aAAO,KAAK,gCAAgC,EAAE,UAAU,KAAK,CAAC;AAC9D,aAAO;AAAA,IACT;AACA,UAAM,MAAiB,EAAE,UAAU,KAAK,WAAW,KAAK,IAAI,EAAE;AAC9D,WAAO,KAAK,SAAS,GAAG;AAAA,EAC1B;AAAA,EAEA,MAAM,gBAAgB,UAA6C;AACjE,UAAM,OAAO,KAAK,aAAa,QAAQ;AAIvC,UAAM,WAAW,MAAM,KAAK,UAAU,IAAI;AAC1C,UAAM,cAAc,UAAU,MAAM,MAAM;AAC1C,QAAI,aAAa;AACf,aAAO,KAAK,SAAS,EAAE,UAAU,KAAK,aAAa,WAAW,KAAK,IAAI,EAAE,CAAC;AAAA,IAC5E;AAGA,QAAI,CAAC,KAAK,QAAS,QAAO;AAC1B,UAAM,MAAM,YAAY;AACxB,UAAM,UAAU,MAAM,KAAK,WAAW,MAAM,KAAK,EAAE,KAAK,EAAE,CAAC;AAC3D,QAAI,YAAY,MAAM;AACpB,aAAO,KAAK,8BAA8B,EAAE,UAAU,KAAK,CAAC;AAC5D,aAAO,KAAK,SAAS,EAAE,UAAU,KAAK,WAAW,KAAK,IAAI,EAAE,CAAC;AAAA,IAC/D;AACA,QAAI,YAAY,YAAY;AAG1B,YAAM,SAAS,MAAM,KAAK,UAAU,IAAI;AACxC,YAAM,YAAY,QAAQ,MAAM,MAAM;AACtC,UAAI,WAAW;AACb,eAAO,KAAK,2CAA2C,EAAE,UAAU,KAAK,CAAC;AACzE,eAAO,KAAK,SAAS,EAAE,UAAU,KAAK,WAAW,WAAW,KAAK,IAAI,EAAE,CAAC;AAAA,MAC1E;AAAA,IACF;AACA,WAAO,KAAK,uCAAuC,EAAE,UAAU,KAAK,CAAC;AACrE,WAAO;AAAA,EACT;AAAA,EAEA,cAAc,UAAwB;AACpC,SAAK,MAAM,OAAO,QAAQ;AAAA,EAC5B;AACF;AAEA,IAAI,iCAAiC;AAErC,SAAS,kBAAkB,QAAwB;AACjD,SAAO,OAAO,WAAW,QAAQ,EAAE,OAAO,QAAQ,MAAM,EAAE,OAAO,KAAK,EAAE,MAAM,GAAG,EAAE;AACrF;AAEO,SAAS,mCAAmC,MAA+B;AAChF,QAAM,aACJ,KAAK,WAAW,aAAa,WAAW,KAAK,OAAO,KAAK;AAC3D,SAAO;AAAA,IACL;AAAA,IACA;AAAA,IACA,2CAA2C,kBAAkB,KAAK,MAAM,CAAC;AAAA,IACzE;AAAA,EACF;AACF;AAEA,SAAS,4BAA4B,MAA2B;AAC9D,MAAI,QAAQ,IAAI,aAAa,UAAU,+BAAgC;AACvE,mCAAiC;AACjC,QAAM,QAAQ;AACd,QAAM,QAAQ;AACd,QAAM,QAAQ;AACd,QAAM,QAAQ;AACd,QAAM,SAAS,GAAG,KAAK,GAAG,KAAK,GAAG,SAAI,OAAO,KAAK,CAAC,GAAG,KAAK;AAC3D,QAAM,OAAO,mCAAmC,IAAI;AACpD,QAAM,cAAc;AAAA,IAClB;AAAA,IACA,GAAG,KAAK,IAAI,CAAC,SAAS,GAAG,KAAK,GAAG,KAAK,IAAI,KAAK,OAAO,QAAQ,GAAG,GAAG,CAAC,IAAI,KAAK,EAAE;AAAA,IAChF;AAAA,EACF;AACA,UAAQ,OAAO,MAAM,YAAY,KAAK,IAAI,IAAI,IAAI;AAClD,SAAO,KAAK,qEAAqE;AAAA,IAC/E,mBAAmB,kBAAkB,KAAK,MAAM;AAAA,EAClD,CAAC;AACH;AAEO,SAAS,mBAA+B;AAC7C,MAAI,CAAC,8BAA8B,EAAG,QAAO,IAAI,eAAe;AAChE,QAAM,UAAU,IAAI,yBAAyB;AAE7C,QAAM,UAAU,wBAAwB;AACxC,QAAM,WAAW,UAAU,IAAI,kBAAkB,QAAQ,MAAM,IAAI;AACnE,QAAM,iBAAiB,UACnB,MAAM;AACJ,gCAA4B,OAAO;AAAA,EACrC,IACA;AAEJ,MAAI,CAAC,QAAQ,UAAU,GAAG;AACxB,QAAI,UAAU;AACZ,uBAAiB;AACjB,aAAO;AAAA,IACT;AACA,WAAO,KAAK,+HAA+H;AAC3I,WAAO,IAAI,eAAe;AAAA,EAC5B;AAEA,MAAI,UAAU;AACZ,WAAO,IAAI,mBAAmB,SAAS,UAAU,cAAc;AAAA,EACjE;AAEA,SAAO;AACT;",
+  "sourcesContent": ["import crypto from 'node:crypto'\nimport { generateDek, hashForLookup } from './aes'\nimport { isEncryptionDebugEnabled, isTenantDataEncryptionEnabled } from './toggles'\nimport { parseBooleanToken } from '../boolean'\nimport { createLogger } from '../logger'\nimport { fetchWithTimeout, resolveTimeoutMs } from '../http/fetchWithTimeout'\n\nconst logger = createLogger('shared').child({ component: 'kms' })\n\nconst DEFAULT_VAULT_REQUEST_TIMEOUT_MS = 1_000\nconst DEFAULT_VAULT_RECOVERY_COOLDOWN_MS = 30_000\n\nfunction resolveVaultRequestTimeoutMs(): number {\n  const raw = process.env.VAULT_REQUEST_TIMEOUT_MS\n  const parsed = raw ? Number.parseInt(raw, 10) : undefined\n  return resolveTimeoutMs(parsed, DEFAULT_VAULT_REQUEST_TIMEOUT_MS)\n}\n\nfunction resolveVaultRecoveryCooldownMs(): number {\n  const raw = process.env.VAULT_RECOVERY_COOLDOWN_MS\n  const parsed = raw ? Number.parseInt(raw, 10) : undefined\n  return resolveTimeoutMs(parsed, DEFAULT_VAULT_RECOVERY_COOLDOWN_MS)\n}\n\nexport type TenantDek = {\n  tenantId: string\n  key: string // base64\n  fetchedAt: number\n}\n\nexport interface KmsService {\n  getTenantDek(tenantId: string): Promise<TenantDek | null>\n  createTenantDek(tenantId: string): Promise<TenantDek | null>\n  isHealthy(): boolean\n  invalidateDek?(tenantId: string): void\n}\n\nclass FallbackKmsService implements KmsService {\n  private notified = false\n  constructor(\n    private readonly primary: KmsService,\n    private readonly fallback: KmsService | null,\n    private readonly onFallback?: () => void,\n  ) {}\n\n  isHealthy(): boolean {\n    return this.primary.isHealthy() || Boolean(this.fallback?.isHealthy?.())\n  }\n\n  private notifyFallback() {\n    if (this.notified) return\n    this.notified = true\n    this.onFallback?.()\n  }\n\n  private async fromPrimary<T>(op: () => Promise<T | null>): Promise<T | null> {\n    try {\n      return await op()\n    } catch (err) {\n      logger.warn('Primary KMS failed, will try fallback', { err })\n      return null\n    }\n  }\n\n  async getTenantDek(tenantId: string): Promise<TenantDek | null> {\n    if (this.primary.isHealthy()) {\n      const dek = await this.fromPrimary(() => this.primary.getTenantDek(tenantId))\n      if (dek) return dek\n    }\n    if (this.fallback?.isHealthy()) {\n      this.notifyFallback()\n      return this.fallback.getTenantDek(tenantId)\n    }\n    return null\n  }\n\n  async createTenantDek(tenantId: string): Promise<TenantDek | null> {\n    if (this.primary.isHealthy()) {\n      const dek = await this.fromPrimary(() => this.primary.createTenantDek(tenantId))\n      if (dek) return dek\n    }\n    if (this.fallback?.isHealthy()) {\n      this.notifyFallback()\n      return this.fallback.createTenantDek(tenantId)\n    }\n    return null\n  }\n\n  invalidateDek(tenantId: string): void {\n    this.primary.invalidateDek?.(tenantId)\n    this.fallback?.invalidateDek?.(tenantId)\n  }\n}\n\ntype VaultClientOpts = {\n  vaultAddr?: string\n  vaultToken?: string\n  mountPath?: string\n  ttlMs?: number\n  requestTimeoutMs?: number\n  recoveryCooldownMs?: number\n}\n\ntype VaultReadResponse = {\n  data?: { data?: { key?: string; version?: number }; metadata?: Record<string, unknown> }\n}\n\n// 'conflict' = a check-and-set write lost to a concurrent writer (normal race\n// outcome, Vault still healthy); 'error' = the write genuinely failed.\ntype VaultWriteOutcome = 'ok' | 'conflict' | 'error'\n\nfunction normalizeEnv(value: string | undefined): string {\n  if (!value) return ''\n  return value.trim().replace(/(?:^['\"]|['\"]$)/g, '')\n}\n\ntype DerivedSecret = { secret: string; source: 'explicit' | 'dev-default'; envName: string }\n\nfunction resolveDerivedKeySecret(): DerivedSecret | null {\n  const candidates: Array<{ value: string | null; envName: string }> = [\n    { value: process.env.TENANT_DATA_ENCRYPTION_FALLBACK_KEY ?? null, envName: 'TENANT_DATA_ENCRYPTION_FALLBACK_KEY' },\n    { value: process.env.TENANT_DATA_ENCRYPTION_KEY ?? null, envName: 'TENANT_DATA_ENCRYPTION_KEY' },\n  ]\n  for (const raw of candidates) {\n    const normalized = normalizeEnv(raw.value ?? undefined)\n    if (normalized) return { secret: normalized, source: 'explicit', envName: raw.envName }\n  }\n  if (\n    process.env.NODE_ENV !== 'production'\n    && parseBooleanToken(process.env.ALLOW_DERIVED_KMS_FALLBACK) === true\n  ) {\n    return { secret: 'om-dev-tenant-encryption', source: 'dev-default', envName: 'DEV_DEFAULT' }\n  }\n  return null\n}\n\nexport class NoopKmsService implements KmsService {\n  isHealthy(): boolean { return !isTenantDataEncryptionEnabled() }\n  async getTenantDek(): Promise<TenantDek | null> { return null }\n  async createTenantDek(): Promise<TenantDek | null> { return null }\n}\n\nclass DerivedKmsService implements KmsService {\n  private root: Buffer\n  constructor(secret: string) {\n    // Derive a stable root key from the provided secret so derived tenant keys are deterministic\n    this.root = crypto.createHash('sha256').update(secret).digest()\n  }\n\n  isHealthy(): boolean {\n    return true\n  }\n\n  private deriveKey(tenantId: string): string {\n    const iterations = 310_000\n    const keyLength = 32\n    const derived = crypto.pbkdf2Sync(this.root, tenantId, iterations, keyLength, 'sha512')\n    return derived.toString('base64')\n  }\n\n  async getTenantDek(tenantId: string): Promise<TenantDek | null> {\n    if (!tenantId) return null\n    return { tenantId, key: this.deriveKey(tenantId), fetchedAt: Date.now() }\n  }\n\n  async createTenantDek(tenantId: string): Promise<TenantDek | null> {\n    return this.getTenantDek(tenantId)\n  }\n}\n\nexport class HashicorpVaultKmsService implements KmsService {\n  private cache = new Map<string, TenantDek>()\n  private readonly vaultAddr: string\n  private readonly vaultToken: string\n  private readonly mountPath: string\n  private readonly ttlMs: number\n  private readonly requestTimeoutMs: number\n  private readonly recoveryCooldownMs: number\n  private healthy = true\n  // Sticky terminal failure (missing VAULT_ADDR/VAULT_TOKEN): no amount of\n  // re-probing fixes a misconfiguration, so this never self-heals \u2014 only a\n  // restart with corrected config does.\n  private misconfigured = false\n  // Timestamp of the last transient failure (timeout / network blip / 5xx).\n  // Drives the half-open circuit breaker in isHealthy(): after the cooldown the\n  // instance reports healthy again so the next call re-probes Vault.\n  private lastTransientFailureAt: number | null = null\n  private readonly debugEnabled: boolean\n  private static loggedInit = false\n\n  constructor(opts: VaultClientOpts = {}) {\n    this.vaultAddr = normalizeEnv(opts.vaultAddr || process.env.VAULT_ADDR || '')\n    this.vaultToken = normalizeEnv(opts.vaultToken || process.env.VAULT_TOKEN || '')\n    this.mountPath = (opts.mountPath || process.env.VAULT_KV_PATH || 'secret/data').replace(/\\/+$/, '')\n    this.ttlMs = opts.ttlMs ?? 15 * 60 * 1000\n    this.requestTimeoutMs = resolveTimeoutMs(opts.requestTimeoutMs, resolveVaultRequestTimeoutMs())\n    this.recoveryCooldownMs = resolveTimeoutMs(opts.recoveryCooldownMs, resolveVaultRecoveryCooldownMs())\n    this.debugEnabled = isEncryptionDebugEnabled()\n    if (!this.vaultAddr || !this.vaultToken) {\n      this.healthy = false\n      this.misconfigured = true\n      if (this.debugEnabled) {\n        logger.warn('Vault misconfigured (missing VAULT_ADDR or VAULT_TOKEN)')\n      }\n    }\n    if (this.healthy && !HashicorpVaultKmsService.loggedInit && this.debugEnabled) {\n      HashicorpVaultKmsService.loggedInit = true\n      if (this.debugEnabled) {\n        logger.info('Hashicorp Vault KMS enabled')\n      }\n    }\n  }\n\n  isHealthy(): boolean {\n    // A missing-config failure is terminal \u2014 never report healthy again.\n    if (this.misconfigured) return false\n    if (this.healthy) return true\n    // Half-open circuit breaker: once the cooldown since the last transient\n    // failure has elapsed, report healthy so the next read/write re-probes\n    // Vault. A successful probe flips `healthy` back on; a failing one records a\n    // fresh failure timestamp and re-opens the breaker for another cooldown.\n    if (this.lastTransientFailureAt === null) return false\n    return this.now() - this.lastTransientFailureAt >= this.recoveryCooldownMs\n  }\n\n  private now(): number {\n    return Date.now()\n  }\n\n  // Vault responded successfully (or is provably reachable): close the breaker.\n  private markHealthy(): void {\n    this.healthy = true\n    this.lastTransientFailureAt = null\n  }\n\n  // Transient infra failure (timeout / network blip / 5xx): open the breaker and\n  // start the recovery cooldown so a later call can re-probe and self-heal.\n  private markTransientFailure(): void {\n    this.healthy = false\n    this.lastTransientFailureAt = this.now()\n  }\n\n  private cacheHit(tenantId: string): TenantDek | null {\n    const entry = this.cache.get(tenantId)\n    if (!entry) return null\n    if (this.now() - entry.fetchedAt > this.ttlMs) {\n      this.cache.delete(tenantId)\n      return null\n    }\n    return entry\n  }\n\n  private async readVault(path: string): Promise<VaultReadResponse | null> {\n    if (!this.vaultAddr || !this.vaultToken) {\n      this.healthy = false\n      this.misconfigured = true\n      return null\n    }\n    try {\n      const res = await fetchWithTimeout(`${this.vaultAddr}/v1/${path}`, {\n        method: 'GET',\n        headers: { 'X-Vault-Token': this.vaultToken },\n        timeoutMs: this.requestTimeoutMs,\n      })\n      if (!res.ok) {\n        // 5xx = Vault down/erroring (transient). <500 (auth/not-found/etc.) means\n        // Vault is reachable and answered, so keep it healthy \u2014 a 404 for a\n        // not-yet-created tenant DEK is the normal read-before-write path.\n        if (res.status >= 500) this.markTransientFailure()\n        else this.markHealthy()\n        logger.warn('Vault read failed', { path, status: res.status })\n        return null\n      }\n      this.markHealthy()\n      if (this.debugEnabled) {\n        logger.info('Vault read ok', { path })\n      }\n      return (await res.json()) as VaultReadResponse\n    } catch (err) {\n      this.markTransientFailure()\n      logger.warn('Vault read error', { path, err, timeoutMs: this.requestTimeoutMs })\n      return null\n    }\n  }\n\n  private async writeVault(path: string, key: string, opts?: { cas?: number }): Promise<VaultWriteOutcome> {\n    if (!this.vaultAddr || !this.vaultToken) {\n      this.healthy = false\n      this.misconfigured = true\n      return 'error'\n    }\n    const body: { data: { key: string }; options?: { cas: number } } = { data: { key } }\n    if (typeof opts?.cas === 'number') body.options = { cas: opts.cas }\n    try {\n      const res = await fetchWithTimeout(`${this.vaultAddr}/v1/${path}`, {\n        method: 'POST',\n        headers: {\n          'X-Vault-Token': this.vaultToken,\n          'Content-Type': 'application/json',\n        },\n        body: JSON.stringify(body),\n        timeoutMs: this.requestTimeoutMs,\n      })\n      if (res.ok) {\n        this.markHealthy()\n        return 'ok'\n      }\n      // KV v2 returns 400 when a check-and-set write loses to a concurrent\n      // writer (path already at a newer version). That is a normal race outcome,\n      // not an unhealthy Vault \u2014 Vault is reachable, so close the breaker.\n      if (typeof opts?.cas === 'number' && res.status === 400) {\n        this.markHealthy()\n        logger.warn('Vault write CAS conflict (concurrent DEK create)', { path, status: res.status })\n        return 'conflict'\n      }\n      this.markTransientFailure()\n      logger.warn('Vault write failed', { path, status: res.status })\n      return 'error'\n    } catch (err) {\n      this.markTransientFailure()\n      logger.warn('Vault write error', { path, err, timeoutMs: this.requestTimeoutMs })\n      return 'error'\n    }\n  }\n\n  private buildKeyPath(tenantId: string): string {\n    const suffix = `tenant_key_${tenantId}`\n    const normalizedMount = this.mountPath.replace(/^\\/+/, '')\n    return `${normalizedMount}/${suffix}`\n  }\n\n  private remember(entry: TenantDek): TenantDek {\n    this.cache.set(entry.tenantId, entry)\n    return entry\n  }\n\n  async getTenantDek(tenantId: string): Promise<TenantDek | null> {\n    const cached = this.cacheHit(tenantId)\n    if (cached) return cached\n    const path = this.buildKeyPath(tenantId)\n    const res = await this.readVault(path)\n    const key = res?.data?.data?.key\n    if (!key) {\n      logger.warn('No tenant DEK found in Vault', { tenantId, path })\n      return null\n    }\n    const dek: TenantDek = { tenantId, key, fetchedAt: this.now() }\n    return this.remember(dek)\n  }\n\n  async createTenantDek(tenantId: string): Promise<TenantDek | null> {\n    const path = this.buildKeyPath(tenantId)\n    // Read-before-write: if a DEK already exists for this tenant (another request\n    // or process created it first), adopt it instead of overwriting the active\n    // key \u2014 overwriting orphans every row already encrypted under it (#2746).\n    const existing = await this.readVault(path)\n    const existingKey = existing?.data?.data?.key\n    if (existingKey) {\n      return this.remember({ tenantId, key: existingKey, fetchedAt: this.now() })\n    }\n    // A read failure (timeout / 5xx) flips `healthy` off; don't blind-write a new\n    // key over a possibly-existing one we just couldn't read \u2014 let the caller fall back.\n    if (!this.healthy) return null\n    const key = generateDek()\n    const outcome = await this.writeVault(path, key, { cas: 0 })\n    if (outcome === 'ok') {\n      logger.info('Stored tenant DEK in Vault', { tenantId, path })\n      return this.remember({ tenantId, key, fetchedAt: this.now() })\n    }\n    if (outcome === 'conflict') {\n      // A concurrent create won the CAS race \u2014 adopt the winner's key so both\n      // callers encrypt under the same DEK.\n      const winner = await this.readVault(path)\n      const winnerKey = winner?.data?.data?.key\n      if (winnerKey) {\n        logger.info('Adopted concurrently-created tenant DEK', { tenantId, path })\n        return this.remember({ tenantId, key: winnerKey, fetchedAt: this.now() })\n      }\n    }\n    logger.warn('Failed to store tenant DEK in Vault', { tenantId, path })\n    return null\n  }\n\n  invalidateDek(tenantId: string): void {\n    this.cache.delete(tenantId)\n  }\n}\n\nlet loggedDerivedKeyFallbackBanner = false\n\nfunction fingerprintSecret(secret: string): string {\n  return crypto.createHash('sha256').update(secret, 'utf8').digest('hex').slice(0, 16)\n}\n\nexport function buildDerivedKeyFallbackBannerLines(opts: DerivedSecret): string[] {\n  const sourceLine =\n    opts.source === 'explicit' ? `Source: ${opts.envName}` : 'Source: dev default secret (do NOT use in production)'\n  return [\n    '\uD83D\uDEA8 Using derived tenant encryption keys (Vault unavailable / no DEK)',\n    sourceLine,\n    `Secret fingerprint (sha256, truncated): ${fingerprintSecret(opts.secret)}`,\n    'Persist this secret securely. Without it, encrypted tenant data cannot be recovered after restart.',\n  ]\n}\n\nfunction logDerivedKeyFallbackBanner(opts: DerivedSecret): void {\n  if (process.env.NODE_ENV === 'test' || loggedDerivedKeyFallbackBanner) return\n  loggedDerivedKeyFallbackBanner = true\n  const redBg = '\\x1b[41m'\n  const white = '\\x1b[97m'\n  const reset = '\\x1b[0m'\n  const width = 110\n  const border = `${redBg}${white}${'\u2501'.repeat(width)}${reset}`\n  const body = buildDerivedKeyFallbackBannerLines(opts)\n  const bannerLines = [\n    border,\n    ...body.map((line) => `${redBg}${white} ${line.padEnd(width - 2, ' ')} ${reset}`),\n    border,\n  ]\n  process.stderr.write(bannerLines.join('\\n') + '\\n')\n  logger.warn('Using derived tenant encryption keys (Vault unavailable / no DEK)', {\n    secretFingerprint: fingerprintSecret(opts.secret),\n  })\n}\n\n/**\n * What the runtime should do about tenant data encryption right now.\n *\n * `isHealthy()` alone cannot answer this: {@link NoopKmsService} reports healthy precisely when\n * encryption is switched OFF, so `enabled && healthy` collapses correctly but a bare\n * `if (!kms.isHealthy())` guard reads the two opposite situations as the same one. They call for\n * opposite handling, so name them:\n *\n * - `disabled`    \u2014 the operator set `TENANT_DATA_ENCRYPTION=no`. Plaintext is the intended\n *                   outcome; degrade to it rather than failing.\n * - `active`      \u2014 encryption is on and a DEK is reachable. Encrypt.\n * - `unavailable` \u2014 encryption is on but no DEK is reachable (Vault down, no fallback secret).\n *                   Data that is meant to be ciphertext MUST NOT be written as plaintext; callers\n *                   holding secrets fail closed here (spec 2026-05-29, security finding #7).\n */\nexport type TenantDataEncryptionMode = 'disabled' | 'active' | 'unavailable'\n\nexport function resolveEncryptionMode(kms: Pick<KmsService, 'isHealthy'>): TenantDataEncryptionMode {\n  if (!isTenantDataEncryptionEnabled()) return 'disabled'\n  return kms.isHealthy() ? 'active' : 'unavailable'\n}\n\nexport function createKmsService(): KmsService {\n  if (!isTenantDataEncryptionEnabled()) return new NoopKmsService()\n  const primary = new HashicorpVaultKmsService()\n\n  const derived = resolveDerivedKeySecret()\n  const fallback = derived ? new DerivedKmsService(derived.secret) : null\n  const notifyFallback = derived\n    ? () => {\n        logDerivedKeyFallbackBanner(derived)\n      }\n    : undefined\n\n  if (!primary.isHealthy()) {\n    if (fallback) {\n      notifyFallback?.()\n      return fallback\n    }\n    logger.warn('Vault not healthy or misconfigured (missing VAULT_ADDR/VAULT_TOKEN) and no fallback secret provided; falling back to noop KMS')\n    return new NoopKmsService()\n  }\n\n  if (fallback) {\n    return new FallbackKmsService(primary, fallback, notifyFallback)\n  }\n\n  return primary\n}\n\nexport { hashForLookup }\n"],
+  "mappings": "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",
   "names": []
 }

package/dist/lib/telemetry/error-code.js

@@ -0,0 +1,10 @@
+const ERROR_CODE_SHAPE = /^[a-z0-9_]+\.[a-z0-9_]+$/;
+function groupableCode(value, fallback) {
+  const code = typeof value === "string" ? value.trim() : "";
+  return ERROR_CODE_SHAPE.test(code) ? code : fallback;
+}
+export {
+  ERROR_CODE_SHAPE,
+  groupableCode
+};
+//# sourceMappingURL=error-code.js.map

package/dist/lib/telemetry/error-code.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/lib/telemetry/error-code.ts"],
+  "sourcesContent": ["/**\n * The `module.reason` shape a failure fingerprint must have to be used as a\n * metric label (`data_sync.item_failed`, `queue.job_failed`).\n *\n * Enforced rather than documented because a `code` frequently originates outside\n * the framework \u2014 an adapter's `data.errorCode`, a third-party module's\n * `integrationLogService.write({ code })`. An interpolated `` `http_${status}_${url}` ``\n * would open one `om.errors` series per URL, and metric labels \u2014 unlike\n * attributes \u2014 never pass through redaction, so an interpolated customer email\n * would egress unredacted.\n */\nexport const ERROR_CODE_SHAPE = /^[a-z0-9_]+\\.[a-z0-9_]+$/\n\n/**\n * Narrow an untrusted value to a usable fingerprint, or to `fallback`.\n *\n * The fallback is a real code rather than `unknown` wherever a caller has one, so\n * grouping still works for a writer that supplies nothing or supplies rubbish.\n */\nexport function groupableCode(value: unknown, fallback: string): string\nexport function groupableCode(value: unknown, fallback?: undefined): string | undefined\nexport function groupableCode(value: unknown, fallback?: string): string | undefined {\n  const code = typeof value === 'string' ? value.trim() : ''\n  return ERROR_CODE_SHAPE.test(code) ? code : fallback\n}\n"],
+  "mappings": "AAWO,MAAM,mBAAmB;AAUzB,SAAS,cAAc,OAAgB,UAAuC;AACnF,QAAM,OAAO,OAAO,UAAU,WAAW,MAAM,KAAK,IAAI;AACxD,SAAO,iBAAiB,KAAK,IAAI,IAAI,OAAO;AAC9C;",
+  "names": []
+}

package/dist/lib/telemetry/runtime.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../src/lib/telemetry/runtime.ts"],
-  "sourcesContent": ["export type TelemetryTraceCarrier = Record<string, string>\n\nexport type TelemetrySpanAttributes = Record<string, string | number | boolean | undefined>\n\nexport type TelemetrySpanKind = 'internal' | 'server' | 'client' | 'producer' | 'consumer'\n\n/** The subset of the telemetry package's `Span` that bridge consumers need. */\nexport type TelemetrySpan = {\n  setAttributes(attributes: TelemetrySpanAttributes): void\n  /**\n   * Rename an in-flight span whose identity is only known once it has run.\n   * Optional so a bootstrap predating it still satisfies the contract \u2014 call it\n   * as `span.updateName?.(\u2026)`.\n   */\n  updateName?(name: string): void\n}\n\nexport type TelemetrySpanOptions = {\n  kind?: TelemetrySpanKind\n  attributes?: TelemetrySpanAttributes\n  /** Start a new trace so the sampler decides for this span alone. */\n  root?: boolean\n  /** Causal links to other traces, as W3C carriers. */\n  links?: TelemetryTraceCarrier[]\n}\n\nexport type TelemetryRuntime = {\n  /**\n   * True only when the active SDK may safely use the process-global W3C\n   * propagator for cross-boundary extraction.\n   */\n  canUseGlobalTracePropagation(): boolean\n  captureTraceContext(): TelemetryTraceCarrier\n  continueTrace<T>(\n    carrier: TelemetryTraceCarrier | undefined,\n    name: string,\n    fn: () => T,\n    options?: { kind?: 'internal' | 'server' | 'client' | 'producer' | 'consumer' },\n  ): T\n  /**\n   * Optional so an older bootstrap that predates span support still satisfies\n   * the contract; consumers go through `withTelemetrySpan` and degrade to\n   * running `fn` untraced.\n   */\n  withSpan?<T>(name: string, fn: (span: TelemetrySpan) => T, options?: TelemetrySpanOptions): T\n  recordHttpDuration(method: string, route: string, status: number, startedAt: number): void\n  reportError(\n    error: unknown,\n    context?: {\n      module?: string\n      attributes?: Record<string, string | number | boolean | undefined>\n    },\n  ): void\n  shutdown(): Promise<void>\n}\n\nconst GLOBAL_KEY = Symbol.for('@open-mercato/shared.telemetryRuntime')\nconst ENABLED_BACKENDS = new Set(['console', 'signoz', 'newrelic', 'otlp'])\n\ntype TelemetryRuntimeStore = {\n  active?: TelemetryRuntime\n}\n\nfunction store(): TelemetryRuntimeStore {\n  const globalStore = globalThis as unknown as Record<symbol, TelemetryRuntimeStore | undefined>\n  let current = globalStore[GLOBAL_KEY]\n  if (!current) {\n    current = {}\n    globalStore[GLOBAL_KEY] = current\n  }\n  return current\n}\n\n/**\n * This check is intentionally owned by shared code so hosts can decide whether\n * to dynamically import the telemetry package without evaluating that package.\n */\nexport function isTelemetryBackendEnabled(raw?: string): boolean {\n  const value = raw ?? (\n    typeof process === 'undefined'\n      ? undefined\n      : process.env.TELEMETRY_BACKEND\n  )\n  return ENABLED_BACKENDS.has((value ?? '').trim().toLowerCase())\n}\n\nexport function registerTelemetryRuntime(runtime: TelemetryRuntime): () => void {\n  store().active = runtime\n  return () => {\n    const current = store()\n    if (current.active === runtime) current.active = undefined\n  }\n}\n\nexport function getTelemetryRuntime(): TelemetryRuntime | undefined {\n  return store().active\n}\n\n/** Test-only: clear the process-wide telemetry bridge. */\nexport function resetTelemetryRuntime(): void {\n  store().active = undefined\n}\n\nconst NOOP_SPAN: TelemetrySpan = { setAttributes() {} }\n\n/**\n * Run `fn` inside a span, from a package that must not depend on\n * `@open-mercato/telemetry`. With telemetry off this is `fn` plus one global\n * lookup \u2014 no span object is allocated and the OTEL SDK is never reached.\n *\n * Pass `root: true` for the unit of work a long-lived job should be sampled and\n * rendered by (a batch, a page) so the job is not one trace under one sampling\n * decision, and `links` to keep the causal chain back to what triggered it.\n */\nexport function withTelemetrySpan<T>(\n  name: string,\n  fn: (span: TelemetrySpan) => T,\n  options?: TelemetrySpanOptions,\n): T {\n  const runtime = getTelemetryRuntime()\n  if (!runtime?.withSpan) return fn(NOOP_SPAN)\n  return runtime.withSpan(name, fn, options)\n}\n\n/**\n * The active trace as a carrier, for use as a `links` entry. `undefined` when\n * telemetry is off or nothing is active, which `withTelemetrySpan` treats as\n * \"no link\" rather than an invalid one.\n */\nexport function captureTelemetryTrace(): TelemetryTraceCarrier | undefined {\n  const carrier = getTelemetryRuntime()?.captureTraceContext()\n  return carrier && Object.keys(carrier).length > 0 ? carrier : undefined\n}\n"],
-  "mappings": "AAwDA,MAAM,aAAa,uBAAO,IAAI,uCAAuC;AACrE,MAAM,mBAAmB,oBAAI,IAAI,CAAC,WAAW,UAAU,YAAY,MAAM,CAAC;AAM1E,SAAS,QAA+B;AACtC,QAAM,cAAc;AACpB,MAAI,UAAU,YAAY,UAAU;AACpC,MAAI,CAAC,SAAS;AACZ,cAAU,CAAC;AACX,gBAAY,UAAU,IAAI;AAAA,EAC5B;AACA,SAAO;AACT;AAMO,SAAS,0BAA0B,KAAuB;AAC/D,QAAM,QAAQ,QACZ,OAAO,YAAY,cACf,SACA,QAAQ,IAAI;AAElB,SAAO,iBAAiB,KAAK,SAAS,IAAI,KAAK,EAAE,YAAY,CAAC;AAChE;AAEO,SAAS,yBAAyB,SAAuC;AAC9E,QAAM,EAAE,SAAS;AACjB,SAAO,MAAM;AACX,UAAM,UAAU,MAAM;AACtB,QAAI,QAAQ,WAAW,QAAS,SAAQ,SAAS;AAAA,EACnD;AACF;AAEO,SAAS,sBAAoD;AAClE,SAAO,MAAM,EAAE;AACjB;AAGO,SAAS,wBAA8B;AAC5C,QAAM,EAAE,SAAS;AACnB;AAEA,MAAM,YAA2B,EAAE,gBAAgB;AAAC,EAAE;AAW/C,SAAS,kBACd,MACA,IACA,SACG;AACH,QAAM,UAAU,oBAAoB;AACpC,MAAI,CAAC,SAAS,SAAU,QAAO,GAAG,SAAS;AAC3C,SAAO,QAAQ,SAAS,MAAM,IAAI,OAAO;AAC3C;AAOO,SAAS,wBAA2D;AACzE,QAAM,UAAU,oBAAoB,GAAG,oBAAoB;AAC3D,SAAO,WAAW,OAAO,KAAK,OAAO,EAAE,SAAS,IAAI,UAAU;AAChE;",
+  "sourcesContent": ["export type TelemetryTraceCarrier = Record<string, string>\n\nexport type TelemetrySpanAttributes = Record<string, string | number | boolean | undefined>\n\nexport type TelemetrySpanKind = 'internal' | 'server' | 'client' | 'producer' | 'consumer'\n\n/** The subset of the telemetry package's `Span` that bridge consumers need. */\nexport type TelemetrySpan = {\n  setAttributes(attributes: TelemetrySpanAttributes): void\n  /**\n   * Rename an in-flight span whose identity is only known once it has run.\n   * Optional so a bootstrap predating it still satisfies the contract \u2014 call it\n   * as `span.updateName?.(\u2026)`.\n   */\n  updateName?(name: string): void\n}\n\nexport type TelemetrySpanOptions = {\n  kind?: TelemetrySpanKind\n  attributes?: TelemetrySpanAttributes\n  /** Start a new trace so the sampler decides for this span alone. */\n  root?: boolean\n  /** Causal links to other traces, as W3C carriers. */\n  links?: TelemetryTraceCarrier[]\n}\n\nexport type TelemetryRuntime = {\n  /**\n   * True only when the active SDK may safely use the process-global W3C\n   * propagator for cross-boundary extraction.\n   */\n  canUseGlobalTracePropagation(): boolean\n  captureTraceContext(): TelemetryTraceCarrier\n  continueTrace<T>(\n    carrier: TelemetryTraceCarrier | undefined,\n    name: string,\n    fn: () => T,\n    options?: { kind?: 'internal' | 'server' | 'client' | 'producer' | 'consumer' },\n  ): T\n  /**\n   * Optional so an older bootstrap that predates span support still satisfies\n   * the contract; consumers go through `withTelemetrySpan` and degrade to\n   * running `fn` untraced.\n   */\n  withSpan?<T>(name: string, fn: (span: TelemetrySpan) => T, options?: TelemetrySpanOptions): T\n  recordHttpDuration(method: string, route: string, status: number, startedAt: number): void\n  reportError(\n    error: unknown,\n    context?: {\n      module?: string\n      /**\n       * Stable, enumerated fingerprint (`module.reason`) the backend groups on.\n       * Optional so a bootstrap predating it still satisfies the contract \u2014 an\n       * older bridge simply ignores the field.\n       */\n      code?: string\n      attributes?: Record<string, string | number | boolean | undefined>\n    },\n  ): void\n  shutdown(): Promise<void>\n}\n\nconst GLOBAL_KEY = Symbol.for('@open-mercato/shared.telemetryRuntime')\nconst ENABLED_BACKENDS = new Set(['console', 'signoz', 'newrelic', 'otlp'])\n\ntype TelemetryRuntimeStore = {\n  active?: TelemetryRuntime\n}\n\nfunction store(): TelemetryRuntimeStore {\n  const globalStore = globalThis as unknown as Record<symbol, TelemetryRuntimeStore | undefined>\n  let current = globalStore[GLOBAL_KEY]\n  if (!current) {\n    current = {}\n    globalStore[GLOBAL_KEY] = current\n  }\n  return current\n}\n\n/**\n * This check is intentionally owned by shared code so hosts can decide whether\n * to dynamically import the telemetry package without evaluating that package.\n */\nexport function isTelemetryBackendEnabled(raw?: string): boolean {\n  const value = raw ?? (\n    typeof process === 'undefined'\n      ? undefined\n      : process.env.TELEMETRY_BACKEND\n  )\n  return ENABLED_BACKENDS.has((value ?? '').trim().toLowerCase())\n}\n\nexport function registerTelemetryRuntime(runtime: TelemetryRuntime): () => void {\n  store().active = runtime\n  return () => {\n    const current = store()\n    if (current.active === runtime) current.active = undefined\n  }\n}\n\nexport function getTelemetryRuntime(): TelemetryRuntime | undefined {\n  return store().active\n}\n\n/** Test-only: clear the process-wide telemetry bridge. */\nexport function resetTelemetryRuntime(): void {\n  store().active = undefined\n}\n\nconst NOOP_SPAN: TelemetrySpan = { setAttributes() {} }\n\n/**\n * Run `fn` inside a span, from a package that must not depend on\n * `@open-mercato/telemetry`. With telemetry off this is `fn` plus one global\n * lookup \u2014 no span object is allocated and the OTEL SDK is never reached.\n *\n * Pass `root: true` for the unit of work a long-lived job should be sampled and\n * rendered by (a batch, a page) so the job is not one trace under one sampling\n * decision, and `links` to keep the causal chain back to what triggered it.\n */\nexport function withTelemetrySpan<T>(\n  name: string,\n  fn: (span: TelemetrySpan) => T,\n  options?: TelemetrySpanOptions,\n): T {\n  const runtime = getTelemetryRuntime()\n  if (!runtime?.withSpan) return fn(NOOP_SPAN)\n  return runtime.withSpan(name, fn, options)\n}\n\n/**\n * The active trace as a carrier, for use as a `links` entry. `undefined` when\n * telemetry is off or nothing is active, which `withTelemetrySpan` treats as\n * \"no link\" rather than an invalid one.\n */\nexport function captureTelemetryTrace(): TelemetryTraceCarrier | undefined {\n  const carrier = getTelemetryRuntime()?.captureTraceContext()\n  return carrier && Object.keys(carrier).length > 0 ? carrier : undefined\n}\n"],
+  "mappings": "AA8DA,MAAM,aAAa,uBAAO,IAAI,uCAAuC;AACrE,MAAM,mBAAmB,oBAAI,IAAI,CAAC,WAAW,UAAU,YAAY,MAAM,CAAC;AAM1E,SAAS,QAA+B;AACtC,QAAM,cAAc;AACpB,MAAI,UAAU,YAAY,UAAU;AACpC,MAAI,CAAC,SAAS;AACZ,cAAU,CAAC;AACX,gBAAY,UAAU,IAAI;AAAA,EAC5B;AACA,SAAO;AACT;AAMO,SAAS,0BAA0B,KAAuB;AAC/D,QAAM,QAAQ,QACZ,OAAO,YAAY,cACf,SACA,QAAQ,IAAI;AAElB,SAAO,iBAAiB,KAAK,SAAS,IAAI,KAAK,EAAE,YAAY,CAAC;AAChE;AAEO,SAAS,yBAAyB,SAAuC;AAC9E,QAAM,EAAE,SAAS;AACjB,SAAO,MAAM;AACX,UAAM,UAAU,MAAM;AACtB,QAAI,QAAQ,WAAW,QAAS,SAAQ,SAAS;AAAA,EACnD;AACF;AAEO,SAAS,sBAAoD;AAClE,SAAO,MAAM,EAAE;AACjB;AAGO,SAAS,wBAA8B;AAC5C,QAAM,EAAE,SAAS;AACnB;AAEA,MAAM,YAA2B,EAAE,gBAAgB;AAAC,EAAE;AAW/C,SAAS,kBACd,MACA,IACA,SACG;AACH,QAAM,UAAU,oBAAoB;AACpC,MAAI,CAAC,SAAS,SAAU,QAAO,GAAG,SAAS;AAC3C,SAAO,QAAQ,SAAS,MAAM,IAAI,OAAO;AAC3C;AAOO,SAAS,wBAA2D;AACzE,QAAM,UAAU,oBAAoB,GAAG,oBAAoB;AAC3D,SAAO,WAAW,OAAO,KAAK,OAAO,EAAE,SAAS,IAAI,UAAU;AAChE;",
   "names": []
 }

package/dist/lib/version.js

@@ -1,4 +1,4 @@
-const APP_VERSION = "0.7.1-develop.7183.1.db9678eeb8";
+const APP_VERSION = "0.7.1-develop.7186.1.6e080a5017";
 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.7.1-develop.7183.1.db9678eeb8';\nexport const appVersion = APP_VERSION;\n"],
+  "sourcesContent": ["// Build-time generated version\nexport const APP_VERSION = '0.7.1-develop.7186.1.6e080a5017';\nexport const appVersion = APP_VERSION;\n"],
   "mappings": "AACO,MAAM,cAAc;AACpB,MAAM,aAAa;",
   "names": []
 }

package/dist/modules/registry.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/modules/registry.ts"],
-  "sourcesContent": ["import type { ReactNode } from 'react'\nimport type { OpenApiRouteDoc, OpenApiMethodDoc } from '@open-mercato/shared/lib/openapi/types'\nimport type { SyncCrudEventResult } from '../lib/crud/sync-event-types'\nimport type { DashboardWidgetModule } from './dashboard/widgets'\nimport type { InjectionAnyWidgetModule, ModuleInjectionTable } from './widgets/injection'\nimport type { IntegrationBundle, IntegrationDefinition } from './integrations/types'\nimport { createLogger } from '../lib/logger'\nimport {\n  applyApiOverridesToManifests,\n  applyModuleOverridesToModules,\n  applyPageOverridesToManifests,\n  composeApiRouteOverrides,\n  composePageRouteOverrides,\n} from './overrides'\n\nconst logger = createLogger('shared').child({ component: 'cli-registry' })\n\n// Context passed to dynamic metadata guards\nexport type RouteVisibilityContext = { path?: string; auth?: any }\n\n/**\n * Portal sidebar navigation hint. When declared on a portal page's metadata,\n * the page is auto-listed in the portal sidebar (subject to RBAC) by the\n * `/api/customer_accounts/portal/nav` endpoint.\n *\n * Absence of `nav` means the page is routable but not auto-listed (useful for\n * detail pages, create forms, etc.).\n */\nexport type PortalNavMetadata = {\n  label: string\n  labelKey?: string\n  group?: 'main' | 'account'\n  order?: number\n  icon?: string\n}\n\n// Metadata you can export from page.meta.ts or directly from a server page\nexport type PageMetadata = {\n  requireAuth?: boolean\n  /** @deprecated Use `requireFeatures` instead \u2014 role names are mutable and can be spoofed */\n  requireRoles?: readonly string[]\n  // Optional fine-grained feature requirements\n  requireFeatures?: readonly string[]\n  // Portal: require customer (portal user) authentication instead of staff auth\n  requireCustomerAuth?: boolean\n  // Portal: require customer-specific features (checked against CustomerRbacService)\n  requireCustomerFeatures?: readonly string[]\n  // Portal: optional sidebar presentation hint (auto-listed by portal nav endpoint)\n  nav?: PortalNavMetadata\n  // Titles and grouping (aliases supported)\n  title?: string\n  titleKey?: string\n  pageTitle?: string\n  pageTitleKey?: string\n  group?: string\n  groupKey?: string\n  pageGroup?: string\n  pageGroupKey?: string\n  // Ordering and visuals\n  order?: number\n  pageOrder?: number\n  priority?: number\n  pagePriority?: number\n  icon?: ReactNode\n  navHidden?: boolean\n  // Dynamic flags\n  visible?: (ctx: RouteVisibilityContext) => boolean | Promise<boolean>\n  enabled?: (ctx: RouteVisibilityContext) => boolean | Promise<boolean>\n  // Optional static breadcrumb trail for header\n  breadcrumb?: Array<{ label: string; labelKey?: string; href?: string }>\n  // Navigation context for tiered navigation:\n  // - 'main' (default): Main sidebar business operations\n  // - 'admin': Collapsible \"Settings & Admin\" section at bottom of sidebar\n  // - 'settings': Hidden from sidebar, only accessible via Settings hub page\n  // - 'profile': Profile dropdown items\n  pageContext?: 'main' | 'admin' | 'settings' | 'profile'\n  placement?: {\n    section: string\n    sectionLabel?: string\n    sectionLabelKey?: string\n    order?: number\n  }\n}\n\nexport type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'\n\nexport type ApiHandler = (req: Request, ctx?: any) => Promise<Response> | Response\n\nexport type ModuleSubscriberHandler = (\n  payload: any,\n  ctx: any\n) => Promise<void | SyncCrudEventResult> | void | SyncCrudEventResult\n\nexport type ModuleWorkerHandler = (job: unknown, ctx: unknown) => Promise<void> | void\n\nexport type ModuleRoute = {\n  pattern?: string\n  path?: string\n  requireAuth?: boolean\n  /** @deprecated Use `requireFeatures` instead \u2014 role names are mutable and can be spoofed */\n  requireRoles?: string[]\n  // Optional fine-grained feature requirements\n  requireFeatures?: string[]\n  // Portal: require customer (portal user) authentication instead of staff auth\n  requireCustomerAuth?: boolean\n  // Portal: require customer-specific features (checked against CustomerRbacService)\n  requireCustomerFeatures?: string[]\n  // Portal: optional sidebar presentation hint (auto-listed by portal nav endpoint)\n  nav?: PortalNavMetadata\n  title?: string\n  titleKey?: string\n  group?: string\n  groupKey?: string\n  icon?: ReactNode\n  order?: number\n  priority?: number\n  navHidden?: boolean\n  visible?: (ctx: RouteVisibilityContext) => boolean | Promise<boolean>\n  enabled?: (ctx: RouteVisibilityContext) => boolean | Promise<boolean>\n  breadcrumb?: Array<{ label: string; labelKey?: string; href?: string }>\n  pageContext?: 'main' | 'admin' | 'settings' | 'profile'\n  placement?: {\n    section: string\n    sectionLabel?: string\n    sectionLabelKey?: string\n    order?: number\n  }\n  Component: (props: any) => ReactNode | Promise<ReactNode>\n}\n\nexport type ModuleRouteMetadata = Omit<ModuleRoute, 'Component'>\n\nexport type ModuleApiLegacy = {\n  method: HttpMethod\n  path: string\n  handler: ApiHandler\n  metadata?: Record<string, unknown>\n  docs?: OpenApiMethodDoc\n}\n\nexport type ModuleApiRouteFile = {\n  path: string\n  handlers: Partial<Record<HttpMethod, ApiHandler>>\n  requireAuth?: boolean\n  /** @deprecated Use `requireFeatures` instead \u2014 role names are mutable and can be spoofed */\n  requireRoles?: string[]\n  // Optional fine-grained feature requirements for the entire route file\n  // Note: per-method feature requirements should be expressed inside metadata\n  requireFeatures?: string[]\n  docs?: OpenApiRouteDoc\n  metadata?: Partial<Record<HttpMethod, unknown>>\n}\n\nexport type ModuleApi = ModuleApiLegacy | ModuleApiRouteFile\n\nexport type RouteMatchParams = Record<string, string | string[]>\n\nexport type FrontendRouteManifestEntry = Omit<ModuleRoute, 'Component'> & {\n  moduleId: string\n  load: () => Promise<ModuleRoute['Component']>\n}\n\nexport type BackendRouteManifestEntry = Omit<ModuleRoute, 'Component'> & {\n  moduleId: string\n  load: () => Promise<ModuleRoute['Component']>\n}\n\nexport type ApiRouteManifestEntry = {\n  moduleId: string\n  kind: 'route-file' | 'legacy'\n  path: string\n  methods: HttpMethod[]\n  method?: HttpMethod\n  load: () => Promise<Record<string, unknown>>\n}\n\nexport type ModuleCli = {\n  command: string\n  run: (argv: string[]) => Promise<void> | void\n}\n\nexport type ModuleSubscriber = {\n  id: string\n  moduleId?: string\n  event: string\n  persistent?: boolean\n  sync?: boolean\n  priority?: number\n  handler: ModuleSubscriberHandler\n}\n\nexport type ModuleWorker = {\n  id: string\n  moduleId?: string\n  queue: string\n  concurrency: number\n  lockDuration?: number\n  maxStalledCount?: number\n  /**\n   * Reports a job the queue abandoned without running the handler.\n   *\n   * Present only for workers whose metadata declares it; the generator emits it as a lazy import\n   * beside the handler, because the registry serializes metadata as literals and a function cannot\n   * survive that.\n   */\n  onJobAbandoned?: (payload: unknown, info: { jobId: string | null; reason: string }) => void | Promise<void>\n  handler: ModuleWorkerHandler\n  /** Opt-in flag exposing this queue as a user-facing scheduler target (issue #5213). */\n  schedulerSafe?: boolean\n  /** Creator features required beyond scheduler.jobs.manage when schedulerSafe is set. */\n  schedulerRequiredFeatures?: string[]\n}\n\nexport type ModuleInfo = {\n  name?: string\n  title?: string\n  version?: string\n  description?: string\n  author?: string\n  license?: string\n  homepage?: string\n  copyright?: string\n  // Optional hard dependencies: module ids that must be enabled\n  requires?: string[]\n  // Whether this module can be ejected into the app's src/modules/ for customization\n  ejectable?: boolean\n}\n\nexport type ModuleDashboardWidgetEntry = {\n  moduleId: string\n  key: string\n  source: 'app' | 'package'\n  loader: () => Promise<DashboardWidgetModule<any>>\n}\n\nexport type ModuleInjectionWidgetEntry = {\n  moduleId: string\n  key: string\n  source: 'app' | 'package'\n  widgetId?: string\n  loader: () => Promise<InjectionAnyWidgetModule<any, any>>\n}\n\nexport type Module = {\n  id: string\n  info?: ModuleInfo\n  backendRoutes?: ModuleRoute[]\n  frontendRoutes?: ModuleRoute[]\n  apis?: ModuleApi[]\n  cli?: ModuleCli[]\n  translations?: Record<string, Record<string, string>>\n  // Optional: per-module feature declarations discovered from acl.ts (module root)\n  features?: Array<{ id: string; title: string; module: string }>\n  // Auto-discovered event subscribers\n  subscribers?: ModuleSubscriber[]\n  // Auto-discovered queue workers\n  workers?: ModuleWorker[]\n  // Optional: per-module declared entity extensions and custom fields (static)\n  // Extensions discovered from data/extensions.ts; Custom fields discovered from ce.ts (entities[].fields)\n  entityExtensions?: import('./entities').EntityExtension[]\n  customFieldSets?: import('./entities').CustomFieldSet[]\n  // Optional: per-module declared custom entities (virtual/logical entities)\n  // Discovered from ce.ts (module root). Each entry represents an entityId with optional label/description.\n  customEntities?: Array<{ id: string; label?: string; description?: string }>\n  dashboardWidgets?: ModuleDashboardWidgetEntry[]\n  injectionWidgets?: ModuleInjectionWidgetEntry[]\n  injectionTable?: ModuleInjectionTable\n  // Optional: per-module vector search configuration (discovered from vector.ts)\n  vector?: import('./vector').VectorModuleConfig\n  // Optional: module-specific tenant setup configuration (from setup.ts)\n  setup?: import('./setup').ModuleSetupConfig\n  // Optional: default encryption maps owned by the module (from encryption.ts)\n  defaultEncryptionMaps?: import('./encryption').ModuleEncryptionMap[]\n  // Optional: integration marketplace declarations discovered from integration.ts\n  integrations?: IntegrationDefinition[]\n  bundles?: IntegrationBundle[]\n}\n\nfunction normPath(s: string) {\n  return (s.startsWith('/') ? s : '/' + s).replace(/\\/+$/, '') || '/'\n}\n\n// 0 = literal (most specific), 1 = dynamic [param], 2 = catch-all [...param] or [[...param]]\nfunction segmentSpecificity(seg: string): 0 | 1 | 2 {\n  if (seg.startsWith('[[...') || seg.startsWith('[...')) return 2\n  if (seg.startsWith('[')) return 1\n  return 0\n}\n\nfunction compareRouteSpecificity(aPattern: string, bPattern: string): number {\n  const aSegs = aPattern.split('/')\n  const bSegs = bPattern.split('/')\n  const len = Math.max(aSegs.length, bSegs.length)\n  for (let i = 0; i < len; i++) {\n    const av = i < aSegs.length ? segmentSpecificity(aSegs[i]) : -1\n    const bv = i < bSegs.length ? segmentSpecificity(bSegs[i]) : -1\n    if (av !== bv) return av - bv\n  }\n  return 0\n}\n\nexport function sortRoutesBySpecificity<T extends { pattern?: string; path?: string }>(routes: T[]): T[] {\n  return [...routes].sort((a, b) =>\n    compareRouteSpecificity(a.pattern ?? a.path ?? '/', b.pattern ?? b.path ?? '/'),\n  )\n}\n\n// Memoized per-array sorted view, so direct callers (e.g., the Next.js catch-all\n// routes that import generated `frontendRoutes`/`backendRoutes`/`apiRoutes`\n// arrays) match against a specificity-sorted view even if they never call\n// `register*RouteManifests`. Keyed by array reference; generated arrays are\n// module-level constants so this caches once per process.\nconst sortedRoutesCache = new WeakMap<object, readonly unknown[]>()\n\nfunction ensureSortedRoutes<T extends { pattern?: string; path?: string }>(routes: readonly T[]): readonly T[] {\n  const cached = sortedRoutesCache.get(routes) as readonly T[] | undefined\n  if (cached) return cached\n  const sorted = sortRoutesBySpecificity([...routes])\n  sortedRoutesCache.set(routes, sorted)\n  return sorted\n}\n\nexport function matchRoutePattern(pattern: string, pathname: string): RouteMatchParams | undefined {\n  const p = normPath(pattern)\n  const u = normPath(pathname)\n  const pSegs = p.split('/').slice(1)\n  const uSegs = u.split('/').slice(1)\n  const params: Record<string, string | string[]> = {}\n  let i = 0\n  for (let j = 0; j < pSegs.length; j++, i++) {\n    const seg = pSegs[j]\n    const mCatchAll = seg.match(/^\\[\\.\\.\\.(.+)\\]$/)\n    const mOptCatch = seg.match(/^\\[\\[\\.\\.\\.(.+)\\]\\]$/)\n    const mDyn = seg.match(/^\\[(.+)\\]$/)\n    if (mCatchAll) {\n      const key = mCatchAll[1]\n      if (i >= uSegs.length) return undefined\n      params[key] = uSegs.slice(i)\n      return params\n    } else if (mOptCatch) {\n      const key = mOptCatch[1]\n      params[key] = i < uSegs.length ? uSegs.slice(i) : []\n      return params\n    } else if (mDyn) {\n      if (i >= uSegs.length) return undefined\n      params[mDyn[1]] = uSegs[i]\n    } else {\n      if (i >= uSegs.length || uSegs[i].toLowerCase() !== seg.toLowerCase()) return undefined\n    }\n  }\n  if (i !== uSegs.length) return undefined\n  return params\n}\n\nfunction getPattern(r: ModuleRoute) {\n  return r.pattern ?? r.path ?? '/'\n}\n\nexport function findFrontendMatch(modules: Module[], pathname: string): { route: ModuleRoute; params: Record<string, string | string[]> } | undefined {\n  for (const m of modules) {\n    const routes = m.frontendRoutes ?? []\n    for (const r of routes) {\n      const params = matchRoutePattern(getPattern(r), pathname)\n      if (params) return { route: r, params }\n    }\n  }\n}\n\nexport function findBackendMatch(modules: Module[], pathname: string): { route: ModuleRoute; params: Record<string, string | string[]> } | undefined {\n  for (const m of modules) {\n    const routes = m.backendRoutes ?? []\n    for (const r of routes) {\n      const params = matchRoutePattern(getPattern(r), pathname)\n      if (params) return { route: r, params }\n    }\n  }\n}\n\nexport function findApi(modules: Module[], method: HttpMethod, pathname: string): { handler: ApiHandler; params: Record<string, string | string[]>; requireAuth?: boolean; requireRoles?: string[]; metadata?: any } | undefined {\n  for (const m of modules) {\n    const apis = m.apis ?? []\n    for (const a of apis) {\n      if ('handlers' in a) {\n        const params = matchRoutePattern(a.path, pathname)\n        const handler = (a.handlers as any)[method]\n        if (params && handler) return { handler, params, requireAuth: a.requireAuth, requireRoles: (a as any).requireRoles, metadata: (a as any).metadata }\n      } else {\n        const al = a as ModuleApiLegacy\n        if (al.method !== method) continue\n        const params = matchRoutePattern(al.path, pathname)\n        if (params) {\n          return { handler: al.handler, params, metadata: al.metadata }\n        }\n      }\n    }\n  }\n}\n\nexport function findRouteManifestMatch<T extends { pattern?: string; path?: string }>(\n  routes: T[],\n  pathname: string\n): { route: T; params: RouteMatchParams } | undefined {\n  for (const route of ensureSortedRoutes(routes)) {\n    const params = matchRoutePattern(route.pattern ?? route.path ?? '/', pathname)\n    if (params) {\n      return { route, params }\n    }\n  }\n}\n\nexport function findApiRouteManifestMatch<T extends { path: string; methods: HttpMethod[] }>(\n  routes: T[],\n  method: HttpMethod,\n  pathname: string\n): { route: T; params: RouteMatchParams } | undefined {\n  for (const route of ensureSortedRoutes(routes)) {\n    if (!route.methods.includes(method)) continue\n    const params = matchRoutePattern(route.path, pathname)\n    if (params) {\n      return { route, params }\n    }\n  }\n}\n\nexport { resolvePageRouteMetadata } from './pageRouteMetadata'\n\nlet _backendRouteManifests: BackendRouteManifestEntry[] | null = null\n\nexport function registerBackendRouteManifests(routes: BackendRouteManifestEntry[]) {\n  const pageOverrides = composePageRouteOverrides()\n  const finalRoutes = Object.keys(pageOverrides).length === 0\n    ? routes\n    : applyPageOverridesToManifests(routes, pageOverrides, 'backend')\n  _backendRouteManifests = sortRoutesBySpecificity(finalRoutes)\n}\n\nexport function getBackendRouteManifests(): BackendRouteManifestEntry[] {\n  return _backendRouteManifests ?? []\n}\n\nlet _frontendRouteManifests: FrontendRouteManifestEntry[] | null = null\n\nexport function registerFrontendRouteManifests(routes: FrontendRouteManifestEntry[]) {\n  const pageOverrides = composePageRouteOverrides()\n  const finalRoutes = Object.keys(pageOverrides).length === 0\n    ? routes\n    : applyPageOverridesToManifests(routes, pageOverrides, 'frontend')\n  _frontendRouteManifests = sortRoutesBySpecificity(finalRoutes)\n}\n\nexport function getFrontendRouteManifests(): FrontendRouteManifestEntry[] {\n  return _frontendRouteManifests ?? []\n}\n\nlet _apiRouteManifests: ApiRouteManifestEntry[] | null = null\n\nexport function registerApiRouteManifests(routes: ApiRouteManifestEntry[]) {\n  // Apply any `entry.overrides.routes.api` overrides registered through the\n  // unified `modules.ts` dispatcher or programmatic API before storing the\n  // manifest. The composer is cheap and returns an empty object when no\n  // overrides exist, so this is a no-op for apps that do not opt in.\n  const routeOverrides = composeApiRouteOverrides()\n  const finalRoutes = Object.keys(routeOverrides).length === 0\n    ? routes\n    : applyApiOverridesToManifests(routes, routeOverrides)\n  _apiRouteManifests = sortRoutesBySpecificity(finalRoutes)\n}\n\nexport function getApiRouteManifests(): ApiRouteManifestEntry[] {\n  return _apiRouteManifests ?? []\n}\n\n// CLI modules registry - populated ONLY by the `mercato` bin (packages/cli/src/bin.ts\n// plus the `init` and `seed:defaults` commands). Runtime code MUST NOT read it: it\n// fails open (see getCliModules below), so outside a CLI process a reader gets an\n// empty list and silently does nothing. The events worker made exactly that mistake\n// and dropped every persistent subscriber. Runtime code uses the app registry\n// (`getModules` from ../lib/modules/registry) or a DI-resolved service.\n// Enforced by src/modules/__tests__/cli-registry-boundary.test.ts.\nlet _cliModules: Module[] | null = null\n\nexport function registerCliModules(modules: Module[]) {\n  if (_cliModules !== null && process.env.NODE_ENV === 'development') {\n    logger.debug('CLI modules re-registered (this may occur during HMR)')\n  }\n  _cliModules = applyModuleOverridesToModules(modules)\n}\n\nexport function getCliModules(): Module[] {\n  // Return empty array if not registered - allows generate command to work without bootstrap\n  return _cliModules ?? []\n}\n\nexport function hasCliModules(): boolean {\n  return _cliModules !== null && _cliModules.length > 0\n}\n\nexport function getDefaultEncryptionMaps(modules: Module[]): import('./encryption').ModuleEncryptionMap[] {\n  const byEntityId = new Map<string, { moduleId: string; map: import('./encryption').ModuleEncryptionMap }>()\n\n  for (const mod of modules) {\n    for (const entry of mod.defaultEncryptionMaps ?? []) {\n      const previous = byEntityId.get(entry.entityId)\n      if (previous) {\n        throw new Error(\n          `[registry] Duplicate default encryption map for \"${entry.entityId}\" declared by \"${previous.moduleId}\" and \"${mod.id}\"`\n        )\n      }\n      byEntityId.set(entry.entityId, {\n        moduleId: mod.id,\n        map: {\n          entityId: entry.entityId,\n          ...(entry.keyScope ? { keyScope: entry.keyScope } : {}),\n          fields: entry.fields.map((field) => ({\n            field: field.field,\n            hashField: field.hashField ?? null,\n          })),\n        },\n      })\n    }\n  }\n\n  return Array.from(byEntityId.values(), ({ map }) => map)\n}\n\nfunction ensureLazyHandler<T extends (...args: any[]) => any>(\n  loaded: unknown,\n  kind: 'subscriber' | 'worker',\n  id: string\n): T {\n  const handler = typeof loaded === 'function'\n    ? loaded\n    : loaded && typeof loaded === 'object' && 'default' in loaded\n      ? (loaded as Record<string, unknown>).default\n      : null\n  if (typeof handler !== 'function') {\n    throw new Error(`[registry] Invalid ${kind} module \"${id}\" (missing default export handler)`)\n  }\n  return handler as T\n}\n\nexport function createLazyModuleSubscriber(\n  loadModule: () => Promise<unknown>,\n  id: string\n): ModuleSubscriberHandler {\n  let handlerPromise: Promise<ModuleSubscriberHandler> | null = null\n  return async (payload, ctx) => {\n    handlerPromise ??= loadModule().then((loaded) =>\n      ensureLazyHandler<ModuleSubscriberHandler>(loaded, 'subscriber', id)\n    )\n    const handler = await handlerPromise\n    return handler(payload, ctx)\n  }\n}\n\nexport function createLazyModuleWorker(\n  loadModule: () => Promise<unknown>,\n  id: string\n): ModuleWorkerHandler {\n  let handlerPromise: Promise<ModuleWorkerHandler> | null = null\n  return async (job, ctx) => {\n    handlerPromise ??= loadModule().then((loaded) =>\n      ensureLazyHandler<ModuleWorkerHandler>(loaded, 'worker', id)\n    )\n    const handler = await handlerPromise\n    return handler(job, ctx)\n  }\n}\n\n/**\n * Resolves a worker's `metadata.onJobAbandoned` on first use.\n *\n * The generator serializes worker metadata as literals, so a function declared there cannot be\n * emitted inline the way `concurrency` or `lockDuration` are. It is emitted as this thunk instead \u2014\n * the same lazy-import treatment the handler already gets \u2014 and only for workers whose metadata\n * declares the callback, so no other queue acquires one (and with it, a sweep) by accident.\n */\nexport function createLazyModuleWorkerAbandonHook(\n  loadModule: () => Promise<unknown>,\n  id: string\n): (payload: unknown, info: { jobId: string | null; reason: string }) => Promise<void> {\n  let hookPromise: Promise<((payload: unknown, info: { jobId: string | null; reason: string }) => unknown) | null> | null = null\n  return async (payload, info) => {\n    hookPromise ??= loadModule().then((loaded) => {\n      const metadata = (loaded as { metadata?: { onJobAbandoned?: unknown } } | null)?.metadata\n      return typeof metadata?.onJobAbandoned === 'function'\n        ? (metadata.onJobAbandoned as (payload: unknown, info: { jobId: string | null; reason: string }) => unknown)\n        : null\n    })\n    const hook = await hookPromise\n    if (!hook) {\n      throw new Error(`[registry] Worker \"${id}\" was registered with an abandoned-job hook but its metadata no longer declares one`)\n    }\n    await hook(payload, info)\n  }\n}\n"],
-  "mappings": "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",
+  "sourcesContent": ["import type { ReactNode } from 'react'\nimport type { OpenApiRouteDoc, OpenApiMethodDoc } from '@open-mercato/shared/lib/openapi/types'\nimport type { SyncCrudEventResult } from '../lib/crud/sync-event-types'\nimport type { DashboardWidgetModule } from './dashboard/widgets'\nimport type { InjectionAnyWidgetModule, ModuleInjectionTable } from './widgets/injection'\nimport type { IntegrationBundle, IntegrationDefinition } from './integrations/types'\nimport { createLogger } from '../lib/logger'\nimport {\n  applyApiOverridesToManifests,\n  applyModuleOverridesToModules,\n  applyPageOverridesToManifests,\n  composeApiRouteOverrides,\n  composePageRouteOverrides,\n} from './overrides'\n\nconst logger = createLogger('shared').child({ component: 'cli-registry' })\n\n// Context passed to dynamic metadata guards\nexport type RouteVisibilityContext = { path?: string; auth?: any }\n\n/**\n * Portal sidebar navigation hint. When declared on a portal page's metadata,\n * the page is auto-listed in the portal sidebar (subject to RBAC) by the\n * `/api/customer_accounts/portal/nav` endpoint.\n *\n * Absence of `nav` means the page is routable but not auto-listed (useful for\n * detail pages, create forms, etc.).\n */\nexport type PortalNavMetadata = {\n  label: string\n  labelKey?: string\n  group?: 'main' | 'account'\n  order?: number\n  icon?: string\n}\n\n// Metadata you can export from page.meta.ts or directly from a server page\nexport type PageMetadata = {\n  requireAuth?: boolean\n  /** @deprecated Use `requireFeatures` instead \u2014 role names are mutable and can be spoofed */\n  requireRoles?: readonly string[]\n  // Optional fine-grained feature requirements\n  requireFeatures?: readonly string[]\n  // Portal: require customer (portal user) authentication instead of staff auth\n  requireCustomerAuth?: boolean\n  // Portal: require customer-specific features (checked against CustomerRbacService)\n  requireCustomerFeatures?: readonly string[]\n  // Portal: optional sidebar presentation hint (auto-listed by portal nav endpoint)\n  nav?: PortalNavMetadata\n  // Titles and grouping (aliases supported)\n  title?: string\n  titleKey?: string\n  pageTitle?: string\n  pageTitleKey?: string\n  group?: string\n  groupKey?: string\n  pageGroup?: string\n  pageGroupKey?: string\n  // Ordering and visuals\n  order?: number\n  pageOrder?: number\n  priority?: number\n  pagePriority?: number\n  icon?: ReactNode\n  navHidden?: boolean\n  // Dynamic flags\n  visible?: (ctx: RouteVisibilityContext) => boolean | Promise<boolean>\n  enabled?: (ctx: RouteVisibilityContext) => boolean | Promise<boolean>\n  // Optional static breadcrumb trail for header\n  breadcrumb?: Array<{ label: string; labelKey?: string; href?: string }>\n  // Navigation context for tiered navigation:\n  // - 'main' (default): Main sidebar business operations\n  // - 'admin': Collapsible \"Settings & Admin\" section at bottom of sidebar\n  // - 'settings': Hidden from sidebar, only accessible via Settings hub page\n  // - 'profile': Profile dropdown items\n  pageContext?: 'main' | 'admin' | 'settings' | 'profile'\n  placement?: {\n    section: string\n    sectionLabel?: string\n    sectionLabelKey?: string\n    order?: number\n  }\n}\n\nexport type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'\n\nexport type ApiHandler = (req: Request, ctx?: any) => Promise<Response> | Response\n\nexport type ModuleSubscriberHandler = (\n  payload: any,\n  ctx: any\n) => Promise<void | SyncCrudEventResult> | void | SyncCrudEventResult\n\nexport type ModuleWorkerHandler = (job: unknown, ctx: unknown) => Promise<void> | void\n\nexport type ModuleRoute = {\n  pattern?: string\n  path?: string\n  requireAuth?: boolean\n  /** @deprecated Use `requireFeatures` instead \u2014 role names are mutable and can be spoofed */\n  requireRoles?: string[]\n  // Optional fine-grained feature requirements\n  requireFeatures?: string[]\n  // Portal: require customer (portal user) authentication instead of staff auth\n  requireCustomerAuth?: boolean\n  // Portal: require customer-specific features (checked against CustomerRbacService)\n  requireCustomerFeatures?: string[]\n  // Portal: optional sidebar presentation hint (auto-listed by portal nav endpoint)\n  nav?: PortalNavMetadata\n  title?: string\n  titleKey?: string\n  group?: string\n  groupKey?: string\n  icon?: ReactNode\n  order?: number\n  priority?: number\n  navHidden?: boolean\n  visible?: (ctx: RouteVisibilityContext) => boolean | Promise<boolean>\n  enabled?: (ctx: RouteVisibilityContext) => boolean | Promise<boolean>\n  breadcrumb?: Array<{ label: string; labelKey?: string; href?: string }>\n  pageContext?: 'main' | 'admin' | 'settings' | 'profile'\n  placement?: {\n    section: string\n    sectionLabel?: string\n    sectionLabelKey?: string\n    order?: number\n  }\n  Component: (props: any) => ReactNode | Promise<ReactNode>\n}\n\nexport type ModuleRouteMetadata = Omit<ModuleRoute, 'Component'>\n\nexport type ModuleApiLegacy = {\n  method: HttpMethod\n  path: string\n  handler: ApiHandler\n  metadata?: Record<string, unknown>\n  docs?: OpenApiMethodDoc\n}\n\nexport type ModuleApiRouteFile = {\n  path: string\n  handlers: Partial<Record<HttpMethod, ApiHandler>>\n  requireAuth?: boolean\n  /** @deprecated Use `requireFeatures` instead \u2014 role names are mutable and can be spoofed */\n  requireRoles?: string[]\n  // Optional fine-grained feature requirements for the entire route file\n  // Note: per-method feature requirements should be expressed inside metadata\n  requireFeatures?: string[]\n  docs?: OpenApiRouteDoc\n  metadata?: Partial<Record<HttpMethod, unknown>>\n}\n\nexport type ModuleApi = ModuleApiLegacy | ModuleApiRouteFile\n\nexport type RouteMatchParams = Record<string, string | string[]>\n\nexport type FrontendRouteManifestEntry = Omit<ModuleRoute, 'Component'> & {\n  moduleId: string\n  load: () => Promise<ModuleRoute['Component']>\n}\n\nexport type BackendRouteManifestEntry = Omit<ModuleRoute, 'Component'> & {\n  moduleId: string\n  load: () => Promise<ModuleRoute['Component']>\n}\n\nexport type ApiRouteManifestEntry = {\n  moduleId: string\n  kind: 'route-file' | 'legacy'\n  path: string\n  methods: HttpMethod[]\n  method?: HttpMethod\n  load: () => Promise<Record<string, unknown>>\n}\n\nexport type ModuleCli = {\n  command: string\n  run: (argv: string[]) => Promise<void> | void\n}\n\nexport type ModuleSubscriber = {\n  id: string\n  moduleId?: string\n  event: string\n  persistent?: boolean\n  sync?: boolean\n  priority?: number\n  handler: ModuleSubscriberHandler\n}\n\nexport type ModuleWorker = {\n  id: string\n  moduleId?: string\n  queue: string\n  concurrency: number\n  lockDuration?: number\n  maxStalledCount?: number\n  /**\n   * Reports a job the queue abandoned without running the handler.\n   *\n   * Present only for workers whose metadata declares it; the generator emits it as a lazy import\n   * beside the handler, because the registry serializes metadata as literals and a function cannot\n   * survive that.\n   */\n  onJobAbandoned?: (payload: unknown, info: { jobId: string | null; reason: string }) => void | Promise<void>\n  handler: ModuleWorkerHandler\n  /** Opt-in flag exposing this queue as a user-facing scheduler target (issue #5213). */\n  schedulerSafe?: boolean\n  /** Creator features required beyond scheduler.jobs.manage when schedulerSafe is set. */\n  schedulerRequiredFeatures?: string[]\n}\n\nexport type ModuleInfo = {\n  name?: string\n  title?: string\n  version?: string\n  description?: string\n  author?: string\n  license?: string\n  homepage?: string\n  copyright?: string\n  // Optional hard dependencies: module ids that must be enabled\n  requires?: string[]\n  // Whether this module can be ejected into the app's src/modules/ for customization\n  ejectable?: boolean\n}\n\nexport type ModuleDashboardWidgetEntry = {\n  moduleId: string\n  key: string\n  source: 'app' | 'package'\n  loader: () => Promise<DashboardWidgetModule<any>>\n}\n\nexport type ModuleInjectionWidgetEntry = {\n  moduleId: string\n  key: string\n  source: 'app' | 'package'\n  widgetId?: string\n  loader: () => Promise<InjectionAnyWidgetModule<any, any>>\n}\n\nexport type Module = {\n  id: string\n  info?: ModuleInfo\n  backendRoutes?: ModuleRoute[]\n  frontendRoutes?: ModuleRoute[]\n  apis?: ModuleApi[]\n  cli?: ModuleCli[]\n  translations?: Record<string, Record<string, string>>\n  // Optional: per-module feature declarations discovered from acl.ts (module root)\n  features?: Array<{ id: string; title: string; module: string }>\n  // Auto-discovered event subscribers\n  subscribers?: ModuleSubscriber[]\n  // Auto-discovered queue workers\n  workers?: ModuleWorker[]\n  // Optional: per-module declared entity extensions and custom fields (static)\n  // Extensions discovered from data/extensions.ts; Custom fields discovered from ce.ts (entities[].fields)\n  entityExtensions?: import('./entities').EntityExtension[]\n  customFieldSets?: import('./entities').CustomFieldSet[]\n  // Optional: per-module declared custom entities (virtual/logical entities)\n  // Discovered from ce.ts (module root). Each entry represents an entityId with optional label/description.\n  customEntities?: Array<{ id: string; label?: string; description?: string }>\n  dashboardWidgets?: ModuleDashboardWidgetEntry[]\n  injectionWidgets?: ModuleInjectionWidgetEntry[]\n  injectionTable?: ModuleInjectionTable\n  // Optional: per-module vector search configuration (discovered from vector.ts)\n  vector?: import('./vector').VectorModuleConfig\n  // Optional: module-specific tenant setup configuration (from setup.ts)\n  setup?: import('./setup').ModuleSetupConfig\n  // Optional: a long-lived process-wide runtime the module starts itself (from runtime.ts).\n  // Invoked once per process by `mercato server start` and `mercato queue worker`.\n  runtime?: import('./runtime').ModuleRuntime\n  // Optional: default encryption maps owned by the module (from encryption.ts)\n  defaultEncryptionMaps?: import('./encryption').ModuleEncryptionMap[]\n  // Optional: integration marketplace declarations discovered from integration.ts\n  integrations?: IntegrationDefinition[]\n  bundles?: IntegrationBundle[]\n}\n\nfunction normPath(s: string) {\n  return (s.startsWith('/') ? s : '/' + s).replace(/\\/+$/, '') || '/'\n}\n\n// 0 = literal (most specific), 1 = dynamic [param], 2 = catch-all [...param] or [[...param]]\nfunction segmentSpecificity(seg: string): 0 | 1 | 2 {\n  if (seg.startsWith('[[...') || seg.startsWith('[...')) return 2\n  if (seg.startsWith('[')) return 1\n  return 0\n}\n\nfunction compareRouteSpecificity(aPattern: string, bPattern: string): number {\n  const aSegs = aPattern.split('/')\n  const bSegs = bPattern.split('/')\n  const len = Math.max(aSegs.length, bSegs.length)\n  for (let i = 0; i < len; i++) {\n    const av = i < aSegs.length ? segmentSpecificity(aSegs[i]) : -1\n    const bv = i < bSegs.length ? segmentSpecificity(bSegs[i]) : -1\n    if (av !== bv) return av - bv\n  }\n  return 0\n}\n\nexport function sortRoutesBySpecificity<T extends { pattern?: string; path?: string }>(routes: T[]): T[] {\n  return [...routes].sort((a, b) =>\n    compareRouteSpecificity(a.pattern ?? a.path ?? '/', b.pattern ?? b.path ?? '/'),\n  )\n}\n\n// Memoized per-array sorted view, so direct callers (e.g., the Next.js catch-all\n// routes that import generated `frontendRoutes`/`backendRoutes`/`apiRoutes`\n// arrays) match against a specificity-sorted view even if they never call\n// `register*RouteManifests`. Keyed by array reference; generated arrays are\n// module-level constants so this caches once per process.\nconst sortedRoutesCache = new WeakMap<object, readonly unknown[]>()\n\nfunction ensureSortedRoutes<T extends { pattern?: string; path?: string }>(routes: readonly T[]): readonly T[] {\n  const cached = sortedRoutesCache.get(routes) as readonly T[] | undefined\n  if (cached) return cached\n  const sorted = sortRoutesBySpecificity([...routes])\n  sortedRoutesCache.set(routes, sorted)\n  return sorted\n}\n\nexport function matchRoutePattern(pattern: string, pathname: string): RouteMatchParams | undefined {\n  const p = normPath(pattern)\n  const u = normPath(pathname)\n  const pSegs = p.split('/').slice(1)\n  const uSegs = u.split('/').slice(1)\n  const params: Record<string, string | string[]> = {}\n  let i = 0\n  for (let j = 0; j < pSegs.length; j++, i++) {\n    const seg = pSegs[j]\n    const mCatchAll = seg.match(/^\\[\\.\\.\\.(.+)\\]$/)\n    const mOptCatch = seg.match(/^\\[\\[\\.\\.\\.(.+)\\]\\]$/)\n    const mDyn = seg.match(/^\\[(.+)\\]$/)\n    if (mCatchAll) {\n      const key = mCatchAll[1]\n      if (i >= uSegs.length) return undefined\n      params[key] = uSegs.slice(i)\n      return params\n    } else if (mOptCatch) {\n      const key = mOptCatch[1]\n      params[key] = i < uSegs.length ? uSegs.slice(i) : []\n      return params\n    } else if (mDyn) {\n      if (i >= uSegs.length) return undefined\n      params[mDyn[1]] = uSegs[i]\n    } else {\n      if (i >= uSegs.length || uSegs[i].toLowerCase() !== seg.toLowerCase()) return undefined\n    }\n  }\n  if (i !== uSegs.length) return undefined\n  return params\n}\n\nfunction getPattern(r: ModuleRoute) {\n  return r.pattern ?? r.path ?? '/'\n}\n\nexport function findFrontendMatch(modules: Module[], pathname: string): { route: ModuleRoute; params: Record<string, string | string[]> } | undefined {\n  for (const m of modules) {\n    const routes = m.frontendRoutes ?? []\n    for (const r of routes) {\n      const params = matchRoutePattern(getPattern(r), pathname)\n      if (params) return { route: r, params }\n    }\n  }\n}\n\nexport function findBackendMatch(modules: Module[], pathname: string): { route: ModuleRoute; params: Record<string, string | string[]> } | undefined {\n  for (const m of modules) {\n    const routes = m.backendRoutes ?? []\n    for (const r of routes) {\n      const params = matchRoutePattern(getPattern(r), pathname)\n      if (params) return { route: r, params }\n    }\n  }\n}\n\nexport function findApi(modules: Module[], method: HttpMethod, pathname: string): { handler: ApiHandler; params: Record<string, string | string[]>; requireAuth?: boolean; requireRoles?: string[]; metadata?: any } | undefined {\n  for (const m of modules) {\n    const apis = m.apis ?? []\n    for (const a of apis) {\n      if ('handlers' in a) {\n        const params = matchRoutePattern(a.path, pathname)\n        const handler = (a.handlers as any)[method]\n        if (params && handler) return { handler, params, requireAuth: a.requireAuth, requireRoles: (a as any).requireRoles, metadata: (a as any).metadata }\n      } else {\n        const al = a as ModuleApiLegacy\n        if (al.method !== method) continue\n        const params = matchRoutePattern(al.path, pathname)\n        if (params) {\n          return { handler: al.handler, params, metadata: al.metadata }\n        }\n      }\n    }\n  }\n}\n\nexport function findRouteManifestMatch<T extends { pattern?: string; path?: string }>(\n  routes: T[],\n  pathname: string\n): { route: T; params: RouteMatchParams } | undefined {\n  for (const route of ensureSortedRoutes(routes)) {\n    const params = matchRoutePattern(route.pattern ?? route.path ?? '/', pathname)\n    if (params) {\n      return { route, params }\n    }\n  }\n}\n\nexport function findApiRouteManifestMatch<T extends { path: string; methods: HttpMethod[] }>(\n  routes: T[],\n  method: HttpMethod,\n  pathname: string\n): { route: T; params: RouteMatchParams } | undefined {\n  for (const route of ensureSortedRoutes(routes)) {\n    if (!route.methods.includes(method)) continue\n    const params = matchRoutePattern(route.path, pathname)\n    if (params) {\n      return { route, params }\n    }\n  }\n}\n\nexport { resolvePageRouteMetadata } from './pageRouteMetadata'\n\nlet _backendRouteManifests: BackendRouteManifestEntry[] | null = null\n\nexport function registerBackendRouteManifests(routes: BackendRouteManifestEntry[]) {\n  const pageOverrides = composePageRouteOverrides()\n  const finalRoutes = Object.keys(pageOverrides).length === 0\n    ? routes\n    : applyPageOverridesToManifests(routes, pageOverrides, 'backend')\n  _backendRouteManifests = sortRoutesBySpecificity(finalRoutes)\n}\n\nexport function getBackendRouteManifests(): BackendRouteManifestEntry[] {\n  return _backendRouteManifests ?? []\n}\n\nlet _frontendRouteManifests: FrontendRouteManifestEntry[] | null = null\n\nexport function registerFrontendRouteManifests(routes: FrontendRouteManifestEntry[]) {\n  const pageOverrides = composePageRouteOverrides()\n  const finalRoutes = Object.keys(pageOverrides).length === 0\n    ? routes\n    : applyPageOverridesToManifests(routes, pageOverrides, 'frontend')\n  _frontendRouteManifests = sortRoutesBySpecificity(finalRoutes)\n}\n\nexport function getFrontendRouteManifests(): FrontendRouteManifestEntry[] {\n  return _frontendRouteManifests ?? []\n}\n\nlet _apiRouteManifests: ApiRouteManifestEntry[] | null = null\n\nexport function registerApiRouteManifests(routes: ApiRouteManifestEntry[]) {\n  // Apply any `entry.overrides.routes.api` overrides registered through the\n  // unified `modules.ts` dispatcher or programmatic API before storing the\n  // manifest. The composer is cheap and returns an empty object when no\n  // overrides exist, so this is a no-op for apps that do not opt in.\n  const routeOverrides = composeApiRouteOverrides()\n  const finalRoutes = Object.keys(routeOverrides).length === 0\n    ? routes\n    : applyApiOverridesToManifests(routes, routeOverrides)\n  _apiRouteManifests = sortRoutesBySpecificity(finalRoutes)\n}\n\nexport function getApiRouteManifests(): ApiRouteManifestEntry[] {\n  return _apiRouteManifests ?? []\n}\n\n// CLI modules registry - populated ONLY by the `mercato` bin (packages/cli/src/bin.ts\n// plus the `init` and `seed:defaults` commands). Runtime code MUST NOT read it: it\n// fails open (see getCliModules below), so outside a CLI process a reader gets an\n// empty list and silently does nothing. The events worker made exactly that mistake\n// and dropped every persistent subscriber. Runtime code uses the app registry\n// (`getModules` from ../lib/modules/registry) or a DI-resolved service.\n// Enforced by src/modules/__tests__/cli-registry-boundary.test.ts.\nlet _cliModules: Module[] | null = null\n\nexport function registerCliModules(modules: Module[]) {\n  if (_cliModules !== null && process.env.NODE_ENV === 'development') {\n    logger.debug('CLI modules re-registered (this may occur during HMR)')\n  }\n  _cliModules = applyModuleOverridesToModules(modules)\n}\n\nexport function getCliModules(): Module[] {\n  // Return empty array if not registered - allows generate command to work without bootstrap\n  return _cliModules ?? []\n}\n\nexport function hasCliModules(): boolean {\n  return _cliModules !== null && _cliModules.length > 0\n}\n\nexport function getDefaultEncryptionMaps(modules: Module[]): import('./encryption').ModuleEncryptionMap[] {\n  const byEntityId = new Map<string, { moduleId: string; map: import('./encryption').ModuleEncryptionMap }>()\n\n  for (const mod of modules) {\n    for (const entry of mod.defaultEncryptionMaps ?? []) {\n      const previous = byEntityId.get(entry.entityId)\n      if (previous) {\n        throw new Error(\n          `[registry] Duplicate default encryption map for \"${entry.entityId}\" declared by \"${previous.moduleId}\" and \"${mod.id}\"`\n        )\n      }\n      byEntityId.set(entry.entityId, {\n        moduleId: mod.id,\n        map: {\n          entityId: entry.entityId,\n          ...(entry.keyScope ? { keyScope: entry.keyScope } : {}),\n          fields: entry.fields.map((field) => ({\n            field: field.field,\n            hashField: field.hashField ?? null,\n          })),\n        },\n      })\n    }\n  }\n\n  return Array.from(byEntityId.values(), ({ map }) => map)\n}\n\nfunction ensureLazyHandler<T extends (...args: any[]) => any>(\n  loaded: unknown,\n  kind: 'subscriber' | 'worker',\n  id: string\n): T {\n  const handler = typeof loaded === 'function'\n    ? loaded\n    : loaded && typeof loaded === 'object' && 'default' in loaded\n      ? (loaded as Record<string, unknown>).default\n      : null\n  if (typeof handler !== 'function') {\n    throw new Error(`[registry] Invalid ${kind} module \"${id}\" (missing default export handler)`)\n  }\n  return handler as T\n}\n\nexport function createLazyModuleSubscriber(\n  loadModule: () => Promise<unknown>,\n  id: string\n): ModuleSubscriberHandler {\n  let handlerPromise: Promise<ModuleSubscriberHandler> | null = null\n  return async (payload, ctx) => {\n    handlerPromise ??= loadModule().then((loaded) =>\n      ensureLazyHandler<ModuleSubscriberHandler>(loaded, 'subscriber', id)\n    )\n    const handler = await handlerPromise\n    return handler(payload, ctx)\n  }\n}\n\nexport function createLazyModuleWorker(\n  loadModule: () => Promise<unknown>,\n  id: string\n): ModuleWorkerHandler {\n  let handlerPromise: Promise<ModuleWorkerHandler> | null = null\n  return async (job, ctx) => {\n    handlerPromise ??= loadModule().then((loaded) =>\n      ensureLazyHandler<ModuleWorkerHandler>(loaded, 'worker', id)\n    )\n    const handler = await handlerPromise\n    return handler(job, ctx)\n  }\n}\n\n/**\n * Resolves a worker's `metadata.onJobAbandoned` on first use.\n *\n * The generator serializes worker metadata as literals, so a function declared there cannot be\n * emitted inline the way `concurrency` or `lockDuration` are. It is emitted as this thunk instead \u2014\n * the same lazy-import treatment the handler already gets \u2014 and only for workers whose metadata\n * declares the callback, so no other queue acquires one (and with it, a sweep) by accident.\n */\nexport function createLazyModuleWorkerAbandonHook(\n  loadModule: () => Promise<unknown>,\n  id: string\n): (payload: unknown, info: { jobId: string | null; reason: string }) => Promise<void> {\n  let hookPromise: Promise<((payload: unknown, info: { jobId: string | null; reason: string }) => unknown) | null> | null = null\n  return async (payload, info) => {\n    hookPromise ??= loadModule().then((loaded) => {\n      const metadata = (loaded as { metadata?: { onJobAbandoned?: unknown } } | null)?.metadata\n      return typeof metadata?.onJobAbandoned === 'function'\n        ? (metadata.onJobAbandoned as (payload: unknown, info: { jobId: string | null; reason: string }) => unknown)\n        : null\n    })\n    const hook = await hookPromise\n    if (!hook) {\n      throw new Error(`[registry] Worker \"${id}\" was registered with an abandoned-job hook but its metadata no longer declares one`)\n    }\n    await hook(payload, info)\n  }\n}\n"],
+  "mappings": "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",
   "names": []
 }

package/dist/modules/runtime.js

@@ -0,0 +1,10 @@
+const DEFAULT_MODULE_RUNTIME_ROLES = ["worker"];
+function moduleRuntimeAppliesTo(runtime, role) {
+  const roles = runtime.roles ?? DEFAULT_MODULE_RUNTIME_ROLES;
+  return roles.includes(role);
+}
+export {
+  DEFAULT_MODULE_RUNTIME_ROLES,
+  moduleRuntimeAppliesTo
+};
+//# sourceMappingURL=runtime.js.map

package/dist/modules/runtime.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/modules/runtime.ts"],
+  "sourcesContent": ["// A module's long-lived, process-wide runtime.\n//\n// Everything else a module contributes is either declarative (routes, ACL, entities) or runs per\n// unit of work (a request, an event, a job). This is the one thing that is neither: something that\n// must exist for as long as the process does \u2014 a worker loop, a broker subscription, a poller, a\n// watcher.\n//\n// `di.ts` is the closest existing point and is the wrong one: a container is built per request in\n// the web tier, so a runtime started there starts per request, or \u2014 with a module-scoped guard \u2014\n// on whichever request happens to arrive first, never on a replica that receives none.\n//\n// See .ai/specs/SPEC-072-2026-09-11-module-runtime-start-hook.md.\n\nimport type { AppContainer } from '../lib/di/container'\n\n/**\n * Which process is starting.\n *\n * `server` is the application process; `worker` runs queue workers; `scheduler` runs the\n * scheduler. A module that must not run its runtime twice in one deployment narrows to one.\n *\n * Only `worker` starts runtimes today (`mercato queue worker --all`). The other two are named so\n * the contract is complete, and start nothing until their process calls `startModuleRuntimes`.\n */\nexport type ModuleRuntimeRole = 'server' | 'worker' | 'scheduler'\n\nexport type ModuleRuntimeContext = {\n  /** The process-wide container, already bootstrapped: DI registrars have run. */\n  container: AppContainer\n  /** Which process this is. */\n  role: ModuleRuntimeRole\n  /**\n   * Aborted when the process begins shutting down \u2014 before `stop()` is awaited, so a runtime can\n   * react at a boundary of its own choosing rather than being interrupted between two writes.\n   */\n  signal: AbortSignal\n}\n\nexport type ModuleRuntimeHandle = {\n  /** Release what `start` acquired. Awaited on shutdown, bounded by a timeout. */\n  stop(): Promise<void>\n}\n\nexport type ModuleRuntime = {\n  /**\n   * Roles this runtime belongs in. Defaults to `['worker']` \u2014 the only role wired today.\n   *\n   * The default promises no more than is implemented: a module taking it gets a runtime that\n   * actually runs. `'server'` and `'scheduler'` can be named explicitly, and will start once those\n   * processes call `startModuleRuntimes` \u2014 widening the default then is additive, whereas shipping\n   * a default that silently does nothing and narrowing it later would be a breaking change to a\n   * frozen surface.\n   */\n  roles?: ModuleRuntimeRole[]\n\n  /**\n   * Start the runtime. Should return promptly: it starts things, it is not itself the thing. A\n   * runtime needing a loop owns that loop and returns a handle.\n   *\n   * A throw fails process startup \u2014 unlike a subscriber, whose throw is logged and swallowed. A\n   * module that cannot start its runtime is a broken deployment, and the alternative is a process\n   * that looks healthy while silently doing nothing.\n   */\n  start(ctx: ModuleRuntimeContext): Promise<ModuleRuntimeHandle | void>\n}\n\nexport const DEFAULT_MODULE_RUNTIME_ROLES: ModuleRuntimeRole[] = ['worker']\n\nexport function moduleRuntimeAppliesTo(runtime: ModuleRuntime, role: ModuleRuntimeRole): boolean {\n  const roles = runtime.roles ?? DEFAULT_MODULE_RUNTIME_ROLES\n  return roles.includes(role)\n}\n"],
+  "mappings": "AAkEO,MAAM,+BAAoD,CAAC,QAAQ;AAEnE,SAAS,uBAAuB,SAAwB,MAAkC;AAC/F,QAAM,QAAQ,QAAQ,SAAS;AAC/B,SAAO,MAAM,SAAS,IAAI;AAC5B;",
+  "names": []
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/shared",
-  "version": "0.7.1-develop.7183.1.db9678eeb8",
+  "version": "0.7.1-develop.7186.1.6e080a5017",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
@@ -113,7 +113,7 @@
     "@mikro-orm/core": "^7.1.14",
     "@mikro-orm/decorators": "^7.1.14",
     "@mikro-orm/postgresql": "^7.1.14",
-    "@open-mercato/cache": "0.7.1-develop.7183.1.db9678eeb8",
+    "@open-mercato/cache": "0.7.1-develop.7186.1.6e080a5017",
     "@types/html-to-text": "^9.0.4",
     "@types/sanitize-html": "^2.16.1",
     "dotenv": "^17.4.2",

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

@@ -0,0 +1,72 @@
+import { encryptWithAesGcm, generateDek, looksLikeEncryptedPayload } from '../aes'
+import { NoopKmsService, resolveEncryptionMode } from '../kms'
+
+const originalEnv = { ...process.env }
+
+afterEach(() => {
+  process.env = { ...originalEnv }
+})
+
+/**
+ * Once encryption is switched off the KMS is a noop, so `decryptWithAesGcm` cannot tell ciphertext
+ * from plaintext — it returns null for both. Every caller that has to answer "is this column still
+ * holding an envelope?" in that state depends on the shape check instead.
+ */
+describe('looksLikeEncryptedPayload', () => {
+  it('recognises what encryptWithAesGcm produces', () => {
+    const payload = encryptWithAesGcm('sk_live_secret', generateDek()).value
+    expect(looksLikeEncryptedPayload(payload)).toBe(true)
+  })
+
+  it.each([
+    ['plain text', 'Renewal for ACME Ltd'],
+    ['empty string', ''],
+    ['a colon-separated value with the wrong arity', 'a:b:v1'],
+    ['a four-part value with the wrong version', 'aaaaaaaaaaaaaaaa:Y2lwaGVy:aaaaaaaaaaaaaaaaaaaaaaaa:v2'],
+    ['a time-like string', '12:30:00:v1'],
+    ['non-base64 components of the right length', '****************:Y2lwaGVy:************************:v1'],
+    ['an empty ciphertext component', 'YWJjZGVmZ2hpamtsbW5v:' + ':YWJjZGVmZ2hpamtsbW5vcHFyc3R1:v1'],
+  ])('rejects %s', (_label, value) => {
+    expect(looksLikeEncryptedPayload(value)).toBe(false)
+  })
+
+  it.each([[null], [undefined], [42], [{}], [[]]])('rejects the non-string %p', (value) => {
+    expect(looksLikeEncryptedPayload(value)).toBe(false)
+  })
+})
+
+/**
+ * The distinction this type exists to make. `NoopKmsService.isHealthy()` is deliberately inverted
+ * — it reports healthy exactly when encryption is OFF — so that `enabled && healthy` collapses
+ * correctly. The cost is that a bare `if (!kms.isHealthy())` reads "operator opted out" and "Vault
+ * is down" as the same condition, and they need opposite handling.
+ */
+describe('resolveEncryptionMode', () => {
+  it('reports disabled when the operator opted out, however the KMS answers', () => {
+    process.env.TENANT_DATA_ENCRYPTION = 'no'
+    expect(resolveEncryptionMode(new NoopKmsService())).toBe('disabled')
+    expect(resolveEncryptionMode({ isHealthy: () => true })).toBe('disabled')
+    expect(resolveEncryptionMode({ isHealthy: () => false })).toBe('disabled')
+  })
+
+  it('reports active when encryption is on and a DEK is reachable', () => {
+    delete process.env.TENANT_DATA_ENCRYPTION
+    expect(resolveEncryptionMode({ isHealthy: () => true })).toBe('active')
+  })
+
+  it('separates an unreachable KMS from an operator opt-out', () => {
+    process.env.TENANT_DATA_ENCRYPTION = 'yes'
+    expect(resolveEncryptionMode({ isHealthy: () => false })).toBe('unavailable')
+    // Same KMS object, same `isHealthy()` answer, opposite mode — the toggle is what differs.
+    expect(new NoopKmsService().isHealthy()).toBe(false)
+    process.env.TENANT_DATA_ENCRYPTION = 'no'
+    expect(new NoopKmsService().isHealthy()).toBe(true)
+    expect(resolveEncryptionMode(new NoopKmsService())).toBe('disabled')
+  })
+
+  it('defaults to encrypting when the toggle is unset', () => {
+    delete process.env.TENANT_DATA_ENCRYPTION
+    expect(resolveEncryptionMode({ isHealthy: () => true })).toBe('active')
+    expect(resolveEncryptionMode({ isHealthy: () => false })).toBe('unavailable')
+  })
+})

package/src/lib/encryption/aes.ts

@@ -27,6 +27,38 @@ export class TenantDataEncryptionError extends Error {
   }
 }
 
+const BASE64_PART = /^[A-Za-z0-9+/]+={0,2}$/
+
+/**
+ * Keyless structural check for the `base64(iv):base64(ciphertext):base64(tag):v1` envelope
+ * {@link encryptWithAesGcm} emits.
+ *
+ * Answers "is this column holding ciphertext?" without a DEK, which is the only question
+ * available once encryption has been switched off — the KMS is a noop by then, so
+ * {@link decryptWithAesGcm} cannot distinguish ciphertext from plaintext. A 12-byte IV and a
+ * 16-byte tag encode to exactly 16 and 24 base64 characters, so the shape is specific enough
+ * that plaintext colliding with it by accident is not a practical concern.
+ *
+ * Deliberate collision is, though: writing `<16 b64>:<b64>:<24 b64>:v1` is trivial, and
+ * `TenantDataEncryptionService` dropped a structural check of exactly this shape for that
+ * reason (#2720). So this is only safe on values the SERVER wrote — never as a test applied to
+ * attacker-supplied input while a DEK is reachable, where `isEncryptedWithDek` is the test to use.
+ * Callers that must run it over user-controlled data are responsible for confirming first that no
+ * DEK is reachable, which is what makes forgery pointless: there is nothing to impersonate.
+ */
+export function looksLikeEncryptedPayload(value: unknown): boolean {
+  if (typeof value !== 'string') return false
+  const parts = value.split(':')
+  if (parts.length !== 4 || parts[3] !== 'v1') return false
+  const [iv, ciphertext, tag] = parts as [string, string, string, string]
+  return iv.length === 16
+    && tag.length === 24
+    && ciphertext.length > 0
+    && BASE64_PART.test(iv)
+    && BASE64_PART.test(ciphertext)
+    && BASE64_PART.test(tag)
+}
+
 export function generateDek(): string {
   return crypto.randomBytes(32).toString('base64')
 }

package/src/lib/encryption/kms.ts

@@ -423,6 +423,28 @@ function logDerivedKeyFallbackBanner(opts: DerivedSecret): void {
   })
 }
 
+/**
+ * What the runtime should do about tenant data encryption right now.
+ *
+ * `isHealthy()` alone cannot answer this: {@link NoopKmsService} reports healthy precisely when
+ * encryption is switched OFF, so `enabled && healthy` collapses correctly but a bare
+ * `if (!kms.isHealthy())` guard reads the two opposite situations as the same one. They call for
+ * opposite handling, so name them:
+ *
+ * - `disabled`    — the operator set `TENANT_DATA_ENCRYPTION=no`. Plaintext is the intended
+ *                   outcome; degrade to it rather than failing.
+ * - `active`      — encryption is on and a DEK is reachable. Encrypt.
+ * - `unavailable` — encryption is on but no DEK is reachable (Vault down, no fallback secret).
+ *                   Data that is meant to be ciphertext MUST NOT be written as plaintext; callers
+ *                   holding secrets fail closed here (spec 2026-05-29, security finding #7).
+ */
+export type TenantDataEncryptionMode = 'disabled' | 'active' | 'unavailable'
+
+export function resolveEncryptionMode(kms: Pick<KmsService, 'isHealthy'>): TenantDataEncryptionMode {
+  if (!isTenantDataEncryptionEnabled()) return 'disabled'
+  return kms.isHealthy() ? 'active' : 'unavailable'
+}
+
 export function createKmsService(): KmsService {
   if (!isTenantDataEncryptionEnabled()) return new NoopKmsService()
   const primary = new HashicorpVaultKmsService()

package/src/lib/telemetry/error-code.ts

@@ -0,0 +1,25 @@
+/**
+ * The `module.reason` shape a failure fingerprint must have to be used as a
+ * metric label (`data_sync.item_failed`, `queue.job_failed`).
+ *
+ * Enforced rather than documented because a `code` frequently originates outside
+ * the framework — an adapter's `data.errorCode`, a third-party module's
+ * `integrationLogService.write({ code })`. An interpolated `` `http_${status}_${url}` ``
+ * would open one `om.errors` series per URL, and metric labels — unlike
+ * attributes — never pass through redaction, so an interpolated customer email
+ * would egress unredacted.
+ */
+export const ERROR_CODE_SHAPE = /^[a-z0-9_]+\.[a-z0-9_]+$/
+
+/**
+ * Narrow an untrusted value to a usable fingerprint, or to `fallback`.
+ *
+ * The fallback is a real code rather than `unknown` wherever a caller has one, so
+ * grouping still works for a writer that supplies nothing or supplies rubbish.
+ */
+export function groupableCode(value: unknown, fallback: string): string
+export function groupableCode(value: unknown, fallback?: undefined): string | undefined
+export function groupableCode(value: unknown, fallback?: string): string | undefined {
+  const code = typeof value === 'string' ? value.trim() : ''
+  return ERROR_CODE_SHAPE.test(code) ? code : fallback
+}

package/src/lib/telemetry/runtime.ts

@@ -48,6 +48,12 @@ export type TelemetryRuntime = {
     error: unknown,
     context?: {
       module?: string
+      /**
+       * Stable, enumerated fingerprint (`module.reason`) the backend groups on.
+       * Optional so a bootstrap predating it still satisfies the contract — an
+       * older bridge simply ignores the field.
+       */
+      code?: string
       attributes?: Record<string, string | number | boolean | undefined>
     },
   ): void

package/src/modules/registry.ts

@@ -269,6 +269,9 @@ export type Module = {
   vector?: import('./vector').VectorModuleConfig
   // Optional: module-specific tenant setup configuration (from setup.ts)
   setup?: import('./setup').ModuleSetupConfig
+  // Optional: a long-lived process-wide runtime the module starts itself (from runtime.ts).
+  // Invoked once per process by `mercato server start` and `mercato queue worker`.
+  runtime?: import('./runtime').ModuleRuntime
   // Optional: default encryption maps owned by the module (from encryption.ts)
   defaultEncryptionMaps?: import('./encryption').ModuleEncryptionMap[]
   // Optional: integration marketplace declarations discovered from integration.ts

package/src/modules/runtime.ts

@@ -0,0 +1,72 @@
+// A module's long-lived, process-wide runtime.
+//
+// Everything else a module contributes is either declarative (routes, ACL, entities) or runs per
+// unit of work (a request, an event, a job). This is the one thing that is neither: something that
+// must exist for as long as the process does — a worker loop, a broker subscription, a poller, a
+// watcher.
+//
+// `di.ts` is the closest existing point and is the wrong one: a container is built per request in
+// the web tier, so a runtime started there starts per request, or — with a module-scoped guard —
+// on whichever request happens to arrive first, never on a replica that receives none.
+//
+// See .ai/specs/SPEC-072-2026-09-11-module-runtime-start-hook.md.
+
+import type { AppContainer } from '../lib/di/container'
+
+/**
+ * Which process is starting.
+ *
+ * `server` is the application process; `worker` runs queue workers; `scheduler` runs the
+ * scheduler. A module that must not run its runtime twice in one deployment narrows to one.
+ *
+ * Only `worker` starts runtimes today (`mercato queue worker --all`). The other two are named so
+ * the contract is complete, and start nothing until their process calls `startModuleRuntimes`.
+ */
+export type ModuleRuntimeRole = 'server' | 'worker' | 'scheduler'
+
+export type ModuleRuntimeContext = {
+  /** The process-wide container, already bootstrapped: DI registrars have run. */
+  container: AppContainer
+  /** Which process this is. */
+  role: ModuleRuntimeRole
+  /**
+   * Aborted when the process begins shutting down — before `stop()` is awaited, so a runtime can
+   * react at a boundary of its own choosing rather than being interrupted between two writes.
+   */
+  signal: AbortSignal
+}
+
+export type ModuleRuntimeHandle = {
+  /** Release what `start` acquired. Awaited on shutdown, bounded by a timeout. */
+  stop(): Promise<void>
+}
+
+export type ModuleRuntime = {
+  /**
+   * Roles this runtime belongs in. Defaults to `['worker']` — the only role wired today.
+   *
+   * The default promises no more than is implemented: a module taking it gets a runtime that
+   * actually runs. `'server'` and `'scheduler'` can be named explicitly, and will start once those
+   * processes call `startModuleRuntimes` — widening the default then is additive, whereas shipping
+   * a default that silently does nothing and narrowing it later would be a breaking change to a
+   * frozen surface.
+   */
+  roles?: ModuleRuntimeRole[]
+
+  /**
+   * Start the runtime. Should return promptly: it starts things, it is not itself the thing. A
+   * runtime needing a loop owns that loop and returns a handle.
+   *
+   * A throw fails process startup — unlike a subscriber, whose throw is logged and swallowed. A
+   * module that cannot start its runtime is a broken deployment, and the alternative is a process
+   * that looks healthy while silently doing nothing.
+   */
+  start(ctx: ModuleRuntimeContext): Promise<ModuleRuntimeHandle | void>
+}
+
+export const DEFAULT_MODULE_RUNTIME_ROLES: ModuleRuntimeRole[] = ['worker']
+
+export function moduleRuntimeAppliesTo(runtime: ModuleRuntime, role: ModuleRuntimeRole): boolean {
+  const roles = runtime.roles ?? DEFAULT_MODULE_RUNTIME_ROLES
+  return roles.includes(role)
+}