@open-mercato/shared 0.8.1-develop.7215.1.60786cf836 → 0.8.1-develop.7218.1.9f22882799

package/dist/lib/encryption/customFieldValues.js

@@ -1,5 +1,8 @@
+import { createLogger } from "../logger/index.js";
 import { encryptWithAesGcm, decryptWithAesGcm } from "./aes.js";
 import { TenantDataEncryptionService } from "./tenantDataEncryptionService.js";
+import { isTenantDataEncryptionEnabled } from "./toggles.js";
+const logger = createLogger("shared").child({ component: "encryption" });
 const STRING_TYPED_CUSTOM_FIELD_KINDS = /* @__PURE__ */ new Set([
   "text",
   "multiline",
@@ -37,10 +40,51 @@ async function resolveDekKey(service, tenantId, cache, opts) {
   cache?.set(scopedTenantId, key);
   return key;
 }
-async function encryptCustomFieldValue(value, tenantId, service, cache) {
+function isEncryptionExpected(service, tenantId) {
+  if (!service || !(tenantId ?? null)) return false;
+  return isTenantDataEncryptionEnabled();
+}
+const PLAINTEXT_FALLBACK_WARN_CAP = 5e3;
+const plaintextFallbackWarned = /* @__PURE__ */ new Set();
+function resetEncryptedFieldPlaintextFallbackWarnCache() {
+  plaintextFallbackWarned.clear();
+}
+function clearPlaintextFallbackWarnings(tenantId) {
+  if (!plaintextFallbackWarned.size) return;
+  const prefix = `${tenantId ?? null}|`;
+  for (const warnKey of plaintextFallbackWarned) {
+    if (warnKey.startsWith(prefix)) plaintextFallbackWarned.delete(warnKey);
+  }
+}
+function warnOnPlaintextFallback(tenantId, options) {
+  try {
+    const scopedTenantId = tenantId ?? null;
+    const entity = options?.entityId ?? null;
+    const field = options?.fieldKey ?? null;
+    const warnKey = `${scopedTenantId}|${entity ?? "unknown"}|${field ?? "unknown"}`;
+    if (plaintextFallbackWarned.has(warnKey)) return;
+    if (plaintextFallbackWarned.size >= PLAINTEXT_FALLBACK_WARN_CAP) {
+      const oldest = plaintextFallbackWarned.values().next().value;
+      if (oldest !== void 0) plaintextFallbackWarned.delete(oldest);
+    }
+    plaintextFallbackWarned.add(warnKey);
+    logger.warn("Custom field configured as encrypted was stored as plaintext", {
+      tenantId: scopedTenantId,
+      entity,
+      field,
+      hint: "The tenant data encryption key could not be read or created (KMS/Vault unavailable, or DEK creation failed), so the value was written unencrypted. Restore key access and re-save the affected records."
+    });
+  } catch {
+  }
+}
+async function encryptCustomFieldValue(value, tenantId, service, cache, options) {
   if (value === void 0 || value === null) return value;
   const key = await resolveDekKey(service, tenantId, cache, { createIfMissing: true });
-  if (!key) return value;
+  if (!key) {
+    if (isEncryptionExpected(service, tenantId)) warnOnPlaintextFallback(tenantId, options);
+    return value;
+  }
+  clearPlaintextFallbackWarnings(tenantId);
   const serialized = typeof value === "string" ? value : JSON.stringify(value);
   return encryptWithAesGcm(serialized, key).value;
 }
@@ -60,6 +104,7 @@ async function decryptCustomFieldValue(value, tenantId, service, cache, options)
 export {
   decryptCustomFieldValue,
   encryptCustomFieldValue,
+  resetEncryptedFieldPlaintextFallbackWarnCache,
   resolveTenantEncryptionService
 };
 //# sourceMappingURL=customFieldValues.js.map

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

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../src/lib/encryption/customFieldValues.ts"],
-  "sourcesContent": ["import type { EntityManager } from '@mikro-orm/core'\nimport { encryptWithAesGcm, decryptWithAesGcm } from './aes'\nimport { TenantDataEncryptionService } from './tenantDataEncryptionService'\n\n/**\n * Custom field kinds that ALWAYS round-trip as a string. The encrypt path\n * stores raw strings unwrapped, so blindly running `JSON.parse` on the\n * decrypted payload coerces text values like `\"123\"` or `\"true\"` back into\n * numbers/booleans (issue #1734). For these kinds, callers MUST pass the\n * `kind` option so we keep the decrypted value as a string.\n *\n * Numeric (`integer`/`float`) and `boolean` kinds rely on JSON round-trip\n * because the encrypt path JSON-stringifies the typed value before storage.\n * Omitting the kind preserves legacy round-trip behavior for backward\n * compatibility.\n */\nconst STRING_TYPED_CUSTOM_FIELD_KINDS = new Set([\n  'text',\n  'multiline',\n  'select',\n  'currency',\n  'dictionary',\n  'phone',\n  'email',\n  'url',\n  'string',\n])\n\nexport type DecryptCustomFieldOptions = {\n  /** Field kind, e.g. from `CustomFieldDef.kind`. When string-typed, the helper preserves the decrypted string verbatim. */\n  kind?: string | null\n}\n\nfunction shouldPreserveAsString(kind: string | null | undefined): boolean {\n  if (!kind) return false\n  return STRING_TYPED_CUSTOM_FIELD_KINDS.has(kind)\n}\n\nconst serviceCache = new WeakMap<EntityManager, TenantDataEncryptionService>()\n\nexport function resolveTenantEncryptionService(\n  em: EntityManager,\n  provided?: TenantDataEncryptionService | null,\n): TenantDataEncryptionService | null {\n  if (provided) return provided\n  const cached = serviceCache.get(em)\n  if (cached) return cached\n  const service = new TenantDataEncryptionService(em as any)\n  serviceCache.set(em, service)\n  return service\n}\n\nasync function resolveDekKey(\n  service: TenantDataEncryptionService | null,\n  tenantId: string | null | undefined,\n  cache?: Map<string | null, string | null>,\n  opts?: { createIfMissing?: boolean },\n): Promise<string | null> {\n  const scopedTenantId = tenantId ?? null\n  if (!service || !service.isEnabled() || !scopedTenantId) return null\n  if (cache?.has(scopedTenantId)) return cache.get(scopedTenantId) ?? null\n  const dek = await service.getDek(scopedTenantId)\n  let key = dek?.key ?? null\n  if (!key && opts?.createIfMissing && typeof service.createDek === 'function') {\n    const created = await service.createDek(scopedTenantId)\n    key = created?.key ?? null\n  }\n  cache?.set(scopedTenantId, key)\n  return key\n}\n\nexport async function encryptCustomFieldValue(\n  value: unknown,\n  tenantId: string | null | undefined,\n  service: TenantDataEncryptionService | null,\n  cache?: Map<string | null, string | null>,\n): Promise<unknown> {\n  if (value === undefined || value === null) return value\n  const key = await resolveDekKey(service, tenantId, cache, { createIfMissing: true })\n  if (!key) return value\n  const serialized = typeof value === 'string' ? value : JSON.stringify(value)\n  return encryptWithAesGcm(serialized, key).value\n}\n\nexport async function decryptCustomFieldValue(\n  value: unknown,\n  tenantId: string | null | undefined,\n  service: TenantDataEncryptionService | null,\n  cache?: Map<string | null, string | null>,\n  options?: DecryptCustomFieldOptions,\n): Promise<unknown> {\n  if (value === undefined || value === null || typeof value !== 'string') return value\n  const key = await resolveDekKey(service, tenantId, cache)\n  if (!key) return value\n  const decrypted = decryptWithAesGcm(value, key)\n  if (decrypted === null) return value\n  if (shouldPreserveAsString(options?.kind ?? null)) return decrypted\n  try {\n    return JSON.parse(decrypted)\n  } catch {\n    return decrypted\n  }\n}\n"],
-  "mappings": "AACA,SAAS,mBAAmB,yBAAyB;AACrD,SAAS,mCAAmC;AAc5C,MAAM,kCAAkC,oBAAI,IAAI;AAAA,EAC9C;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,CAAC;AAOD,SAAS,uBAAuB,MAA0C;AACxE,MAAI,CAAC,KAAM,QAAO;AAClB,SAAO,gCAAgC,IAAI,IAAI;AACjD;AAEA,MAAM,eAAe,oBAAI,QAAoD;AAEtE,SAAS,+BACd,IACA,UACoC;AACpC,MAAI,SAAU,QAAO;AACrB,QAAM,SAAS,aAAa,IAAI,EAAE;AAClC,MAAI,OAAQ,QAAO;AACnB,QAAM,UAAU,IAAI,4BAA4B,EAAS;AACzD,eAAa,IAAI,IAAI,OAAO;AAC5B,SAAO;AACT;AAEA,eAAe,cACb,SACA,UACA,OACA,MACwB;AACxB,QAAM,iBAAiB,YAAY;AACnC,MAAI,CAAC,WAAW,CAAC,QAAQ,UAAU,KAAK,CAAC,eAAgB,QAAO;AAChE,MAAI,OAAO,IAAI,cAAc,EAAG,QAAO,MAAM,IAAI,cAAc,KAAK;AACpE,QAAM,MAAM,MAAM,QAAQ,OAAO,cAAc;AAC/C,MAAI,MAAM,KAAK,OAAO;AACtB,MAAI,CAAC,OAAO,MAAM,mBAAmB,OAAO,QAAQ,cAAc,YAAY;AAC5E,UAAM,UAAU,MAAM,QAAQ,UAAU,cAAc;AACtD,UAAM,SAAS,OAAO;AAAA,EACxB;AACA,SAAO,IAAI,gBAAgB,GAAG;AAC9B,SAAO;AACT;AAEA,eAAsB,wBACpB,OACA,UACA,SACA,OACkB;AAClB,MAAI,UAAU,UAAa,UAAU,KAAM,QAAO;AAClD,QAAM,MAAM,MAAM,cAAc,SAAS,UAAU,OAAO,EAAE,iBAAiB,KAAK,CAAC;AACnF,MAAI,CAAC,IAAK,QAAO;AACjB,QAAM,aAAa,OAAO,UAAU,WAAW,QAAQ,KAAK,UAAU,KAAK;AAC3E,SAAO,kBAAkB,YAAY,GAAG,EAAE;AAC5C;AAEA,eAAsB,wBACpB,OACA,UACA,SACA,OACA,SACkB;AAClB,MAAI,UAAU,UAAa,UAAU,QAAQ,OAAO,UAAU,SAAU,QAAO;AAC/E,QAAM,MAAM,MAAM,cAAc,SAAS,UAAU,KAAK;AACxD,MAAI,CAAC,IAAK,QAAO;AACjB,QAAM,YAAY,kBAAkB,OAAO,GAAG;AAC9C,MAAI,cAAc,KAAM,QAAO;AAC/B,MAAI,uBAAuB,SAAS,QAAQ,IAAI,EAAG,QAAO;AAC1D,MAAI;AACF,WAAO,KAAK,MAAM,SAAS;AAAA,EAC7B,QAAQ;AACN,WAAO;AAAA,EACT;AACF;",
+  "sourcesContent": ["import type { EntityManager } from '@mikro-orm/core'\nimport { createLogger } from '../logger'\nimport { encryptWithAesGcm, decryptWithAesGcm } from './aes'\nimport { TenantDataEncryptionService } from './tenantDataEncryptionService'\nimport { isTenantDataEncryptionEnabled } from './toggles'\n\nconst logger = createLogger('shared').child({ component: 'encryption' })\n\n/**\n * Custom field kinds that ALWAYS round-trip as a string. The encrypt path\n * stores raw strings unwrapped, so blindly running `JSON.parse` on the\n * decrypted payload coerces text values like `\"123\"` or `\"true\"` back into\n * numbers/booleans (issue #1734). For these kinds, callers MUST pass the\n * `kind` option so we keep the decrypted value as a string.\n *\n * Numeric (`integer`/`float`) and `boolean` kinds rely on JSON round-trip\n * because the encrypt path JSON-stringifies the typed value before storage.\n * Omitting the kind preserves legacy round-trip behavior for backward\n * compatibility.\n */\nconst STRING_TYPED_CUSTOM_FIELD_KINDS = new Set([\n  'text',\n  'multiline',\n  'select',\n  'currency',\n  'dictionary',\n  'phone',\n  'email',\n  'url',\n  'string',\n])\n\nexport type DecryptCustomFieldOptions = {\n  /** Field kind, e.g. from `CustomFieldDef.kind`. When string-typed, the helper preserves the decrypted string verbatim. */\n  kind?: string | null\n}\n\nfunction shouldPreserveAsString(kind: string | null | undefined): boolean {\n  if (!kind) return false\n  return STRING_TYPED_CUSTOM_FIELD_KINDS.has(kind)\n}\n\nconst serviceCache = new WeakMap<EntityManager, TenantDataEncryptionService>()\n\nexport function resolveTenantEncryptionService(\n  em: EntityManager,\n  provided?: TenantDataEncryptionService | null,\n): TenantDataEncryptionService | null {\n  if (provided) return provided\n  const cached = serviceCache.get(em)\n  if (cached) return cached\n  const service = new TenantDataEncryptionService(em as any)\n  serviceCache.set(em, service)\n  return service\n}\n\nasync function resolveDekKey(\n  service: TenantDataEncryptionService | null,\n  tenantId: string | null | undefined,\n  cache?: Map<string | null, string | null>,\n  opts?: { createIfMissing?: boolean },\n): Promise<string | null> {\n  const scopedTenantId = tenantId ?? null\n  if (!service || !service.isEnabled() || !scopedTenantId) return null\n  if (cache?.has(scopedTenantId)) return cache.get(scopedTenantId) ?? null\n  const dek = await service.getDek(scopedTenantId)\n  let key = dek?.key ?? null\n  if (!key && opts?.createIfMissing && typeof service.createDek === 'function') {\n    const created = await service.createDek(scopedTenantId)\n    key = created?.key ?? null\n  }\n  cache?.set(scopedTenantId, key)\n  return key\n}\n\n/**\n * Whether the caller asked for a write that is supposed to end up encrypted.\n *\n * `resolveDekKey` returns `null` for several situations. Two are intentional\n * no-ops \u2014 no encryption service is wired, or the record has no tenant scope \u2014\n * and one is the operator deliberately running unencrypted\n * (`TENANT_DATA_ENCRYPTION=no`). Anything else means the caller asked for an\n * encrypted write that could not be performed, which is worth reporting.\n *\n * This deliberately checks the `TENANT_DATA_ENCRYPTION` env toggle rather than\n * `service.isEnabled()`. `isEnabled()` folds the toggle together with KMS\n * health, and an unreachable Vault with no fallback secret resolves to\n * `NoopKmsService`, whose `isHealthy()` is false whenever encryption is on \u2014 so\n * gating on it would stay silent during exactly the outage this warning exists\n * to surface. The env toggle alone expresses the operator's intent.\n */\nfunction isEncryptionExpected(\n  service: TenantDataEncryptionService | null,\n  tenantId: string | null | undefined,\n): boolean {\n  if (!service || !(tenantId ?? null)) return false\n  return isTenantDataEncryptionEnabled()\n}\n\n// One warning per tenant/entity/field per OUTAGE. A key-store outage makes this\n// branch run for every field of every write, so the warning is throttled \u2014 but\n// the entries for a tenant are dropped again as soon as one of its writes\n// encrypts successfully. Throttling for the lifetime of the process instead\n// would report the first outage and silently swallow every later one, which is\n// the failure this warning exists to make visible.\nconst PLAINTEXT_FALLBACK_WARN_CAP = 5000\nconst plaintextFallbackWarned = new Set<string>()\n\n/** Test seam: the warn-once cache is process-global by design. */\nexport function resetEncryptedFieldPlaintextFallbackWarnCache(): void {\n  plaintextFallbackWarned.clear()\n}\n\n/**\n * Forget a tenant's plaintext-fallback warnings once its key resolves again, so\n * a later outage is reported instead of being throttled away by the previous\n * one. The `size` guard keeps the healthy path \u2014 an empty set \u2014 at O(1).\n */\nfunction clearPlaintextFallbackWarnings(tenantId: string | null | undefined): void {\n  if (!plaintextFallbackWarned.size) return\n  const prefix = `${tenantId ?? null}|`\n  for (const warnKey of plaintextFallbackWarned) {\n    if (warnKey.startsWith(prefix)) plaintextFallbackWarned.delete(warnKey)\n  }\n}\n\nfunction warnOnPlaintextFallback(\n  tenantId: string | null | undefined,\n  options?: EncryptCustomFieldOptions,\n): void {\n  try {\n    const scopedTenantId = tenantId ?? null\n    const entity = options?.entityId ?? null\n    const field = options?.fieldKey ?? null\n    const warnKey = `${scopedTenantId}|${entity ?? 'unknown'}|${field ?? 'unknown'}`\n    if (plaintextFallbackWarned.has(warnKey)) return\n    if (plaintextFallbackWarned.size >= PLAINTEXT_FALLBACK_WARN_CAP) {\n      const oldest = plaintextFallbackWarned.values().next().value\n      if (oldest !== undefined) plaintextFallbackWarned.delete(oldest)\n    }\n    plaintextFallbackWarned.add(warnKey)\n    logger.warn('Custom field configured as encrypted was stored as plaintext', {\n      tenantId: scopedTenantId,\n      entity,\n      field,\n      hint: 'The tenant data encryption key could not be read or created (KMS/Vault unavailable, or DEK creation failed), so the value was written unencrypted. Restore key access and re-save the affected records.',\n    })\n  } catch {\n    // A diagnostic must never break the write it is diagnosing.\n  }\n}\n\nexport type EncryptCustomFieldOptions = {\n  /** Entity the value belongs to, e.g. `customers:person`. Used only to identify the field in diagnostics. */\n  entityId?: string | null\n  /** Custom field key, e.g. from `CustomFieldDef.key`. Used only to identify the field in diagnostics. */\n  fieldKey?: string | null\n}\n\nexport async function encryptCustomFieldValue(\n  value: unknown,\n  tenantId: string | null | undefined,\n  service: TenantDataEncryptionService | null,\n  cache?: Map<string | null, string | null>,\n  options?: EncryptCustomFieldOptions,\n): Promise<unknown> {\n  if (value === undefined || value === null) return value\n  const key = await resolveDekKey(service, tenantId, cache, { createIfMissing: true })\n  if (!key) {\n    // Key resolution failed for a field the operator configured as encrypted.\n    // The write still goes through as plaintext (failing it would drop data on\n    // a transient outage), but it must not be silent \u2014 issue #5921.\n    if (isEncryptionExpected(service, tenantId)) warnOnPlaintextFallback(tenantId, options)\n    return value\n  }\n  clearPlaintextFallbackWarnings(tenantId)\n  const serialized = typeof value === 'string' ? value : JSON.stringify(value)\n  return encryptWithAesGcm(serialized, key).value\n}\n\nexport async function decryptCustomFieldValue(\n  value: unknown,\n  tenantId: string | null | undefined,\n  service: TenantDataEncryptionService | null,\n  cache?: Map<string | null, string | null>,\n  options?: DecryptCustomFieldOptions,\n): Promise<unknown> {\n  if (value === undefined || value === null || typeof value !== 'string') return value\n  const key = await resolveDekKey(service, tenantId, cache)\n  if (!key) return value\n  const decrypted = decryptWithAesGcm(value, key)\n  if (decrypted === null) return value\n  if (shouldPreserveAsString(options?.kind ?? null)) return decrypted\n  try {\n    return JSON.parse(decrypted)\n  } catch {\n    return decrypted\n  }\n}\n"],
+  "mappings": "AACA,SAAS,oBAAoB;AAC7B,SAAS,mBAAmB,yBAAyB;AACrD,SAAS,mCAAmC;AAC5C,SAAS,qCAAqC;AAE9C,MAAM,SAAS,aAAa,QAAQ,EAAE,MAAM,EAAE,WAAW,aAAa,CAAC;AAcvE,MAAM,kCAAkC,oBAAI,IAAI;AAAA,EAC9C;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,CAAC;AAOD,SAAS,uBAAuB,MAA0C;AACxE,MAAI,CAAC,KAAM,QAAO;AAClB,SAAO,gCAAgC,IAAI,IAAI;AACjD;AAEA,MAAM,eAAe,oBAAI,QAAoD;AAEtE,SAAS,+BACd,IACA,UACoC;AACpC,MAAI,SAAU,QAAO;AACrB,QAAM,SAAS,aAAa,IAAI,EAAE;AAClC,MAAI,OAAQ,QAAO;AACnB,QAAM,UAAU,IAAI,4BAA4B,EAAS;AACzD,eAAa,IAAI,IAAI,OAAO;AAC5B,SAAO;AACT;AAEA,eAAe,cACb,SACA,UACA,OACA,MACwB;AACxB,QAAM,iBAAiB,YAAY;AACnC,MAAI,CAAC,WAAW,CAAC,QAAQ,UAAU,KAAK,CAAC,eAAgB,QAAO;AAChE,MAAI,OAAO,IAAI,cAAc,EAAG,QAAO,MAAM,IAAI,cAAc,KAAK;AACpE,QAAM,MAAM,MAAM,QAAQ,OAAO,cAAc;AAC/C,MAAI,MAAM,KAAK,OAAO;AACtB,MAAI,CAAC,OAAO,MAAM,mBAAmB,OAAO,QAAQ,cAAc,YAAY;AAC5E,UAAM,UAAU,MAAM,QAAQ,UAAU,cAAc;AACtD,UAAM,SAAS,OAAO;AAAA,EACxB;AACA,SAAO,IAAI,gBAAgB,GAAG;AAC9B,SAAO;AACT;AAkBA,SAAS,qBACP,SACA,UACS;AACT,MAAI,CAAC,WAAW,EAAE,YAAY,MAAO,QAAO;AAC5C,SAAO,8BAA8B;AACvC;AAQA,MAAM,8BAA8B;AACpC,MAAM,0BAA0B,oBAAI,IAAY;AAGzC,SAAS,gDAAsD;AACpE,0BAAwB,MAAM;AAChC;AAOA,SAAS,+BAA+B,UAA2C;AACjF,MAAI,CAAC,wBAAwB,KAAM;AACnC,QAAM,SAAS,GAAG,YAAY,IAAI;AAClC,aAAW,WAAW,yBAAyB;AAC7C,QAAI,QAAQ,WAAW,MAAM,EAAG,yBAAwB,OAAO,OAAO;AAAA,EACxE;AACF;AAEA,SAAS,wBACP,UACA,SACM;AACN,MAAI;AACF,UAAM,iBAAiB,YAAY;AACnC,UAAM,SAAS,SAAS,YAAY;AACpC,UAAM,QAAQ,SAAS,YAAY;AACnC,UAAM,UAAU,GAAG,cAAc,IAAI,UAAU,SAAS,IAAI,SAAS,SAAS;AAC9E,QAAI,wBAAwB,IAAI,OAAO,EAAG;AAC1C,QAAI,wBAAwB,QAAQ,6BAA6B;AAC/D,YAAM,SAAS,wBAAwB,OAAO,EAAE,KAAK,EAAE;AACvD,UAAI,WAAW,OAAW,yBAAwB,OAAO,MAAM;AAAA,IACjE;AACA,4BAAwB,IAAI,OAAO;AACnC,WAAO,KAAK,gEAAgE;AAAA,MAC1E,UAAU;AAAA,MACV;AAAA,MACA;AAAA,MACA,MAAM;AAAA,IACR,CAAC;AAAA,EACH,QAAQ;AAAA,EAER;AACF;AASA,eAAsB,wBACpB,OACA,UACA,SACA,OACA,SACkB;AAClB,MAAI,UAAU,UAAa,UAAU,KAAM,QAAO;AAClD,QAAM,MAAM,MAAM,cAAc,SAAS,UAAU,OAAO,EAAE,iBAAiB,KAAK,CAAC;AACnF,MAAI,CAAC,KAAK;AAIR,QAAI,qBAAqB,SAAS,QAAQ,EAAG,yBAAwB,UAAU,OAAO;AACtF,WAAO;AAAA,EACT;AACA,iCAA+B,QAAQ;AACvC,QAAM,aAAa,OAAO,UAAU,WAAW,QAAQ,KAAK,UAAU,KAAK;AAC3E,SAAO,kBAAkB,YAAY,GAAG,EAAE;AAC5C;AAEA,eAAsB,wBACpB,OACA,UACA,SACA,OACA,SACkB;AAClB,MAAI,UAAU,UAAa,UAAU,QAAQ,OAAO,UAAU,SAAU,QAAO;AAC/E,QAAM,MAAM,MAAM,cAAc,SAAS,UAAU,KAAK;AACxD,MAAI,CAAC,IAAK,QAAO;AACjB,QAAM,YAAY,kBAAkB,OAAO,GAAG;AAC9C,MAAI,cAAc,KAAM,QAAO;AAC/B,MAAI,uBAAuB,SAAS,QAAQ,IAAI,EAAG,QAAO;AAC1D,MAAI;AACF,WAAO,KAAK,MAAM,SAAS;AAAA,EAC7B,QAAQ;AACN,WAAO;AAAA,EACT;AACF;",
   "names": []
 }

package/dist/lib/version.js

@@ -1,4 +1,4 @@
-const APP_VERSION = "0.8.1-develop.7215.1.60786cf836";
+const APP_VERSION = "0.8.1-develop.7218.1.9f22882799";
 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.8.1-develop.7215.1.60786cf836';\nexport const appVersion = APP_VERSION;\n"],
+  "sourcesContent": ["// Build-time generated version\nexport const APP_VERSION = '0.8.1-develop.7218.1.9f22882799';\nexport const appVersion = APP_VERSION;\n"],
   "mappings": "AACO,MAAM,cAAc;AACpB,MAAM,aAAa;",
   "names": []
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/shared",
-  "version": "0.8.1-develop.7215.1.60786cf836",
+  "version": "0.8.1-develop.7218.1.9f22882799",
   "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.8.1-develop.7215.1.60786cf836",
+    "@open-mercato/cache": "0.8.1-develop.7218.1.9f22882799",
     "@types/html-to-text": "^9.0.4",
     "@types/sanitize-html": "^2.16.1",
     "dotenv": "^17.4.2",

package/src/lib/encryption/__tests__/customFieldValues.plaintext-fallback.test.ts

@@ -0,0 +1,208 @@
+import {
+  encryptCustomFieldValue,
+  resetEncryptedFieldPlaintextFallbackWarnCache,
+} from '../customFieldValues'
+
+jest.mock('../../logger', () => {
+  const warn = jest.fn()
+  const debug = jest.fn()
+  const info = jest.fn()
+  const error = jest.fn()
+  const child = jest.fn(() => ({ warn, debug, info, error }))
+  return { createLogger: jest.fn(() => ({ child })), __warn: warn }
+})
+
+const loggerModule = jest.requireMock('../../logger') as { __warn: jest.Mock }
+
+const WARN_MESSAGE = 'Custom field configured as encrypted was stored as plaintext'
+
+const warnCalls = () =>
+  loggerModule.__warn.mock.calls.filter(([message]) => message === WARN_MESSAGE)
+
+const fixedKey = Buffer.alloc(32, 1).toString('base64')
+
+/** Encryption is on and the tenant is scoped, but no DEK can be read or created. */
+function unresolvableDekService(overrides: Record<string, unknown> = {}) {
+  return {
+    isEnabled: () => true,
+    getDek: jest.fn(async () => null),
+    createDek: jest.fn(async () => null),
+    ...overrides,
+  } as any
+}
+
+describe('encryptCustomFieldValue plaintext fallback (regression: issue #5921)', () => {
+  const previousToggle = process.env.TENANT_DATA_ENCRYPTION
+
+  beforeEach(() => {
+    resetEncryptedFieldPlaintextFallbackWarnCache()
+    loggerModule.__warn.mockClear()
+    delete process.env.TENANT_DATA_ENCRYPTION
+  })
+
+  afterAll(() => {
+    if (previousToggle === undefined) delete process.env.TENANT_DATA_ENCRYPTION
+    else process.env.TENANT_DATA_ENCRYPTION = previousToggle
+  })
+
+  it('warns when an encrypted field falls back to plaintext because the DEK is unavailable', async () => {
+    const service = unresolvableDekService()
+
+    const stored = await encryptCustomFieldValue('secret', 'tenant-1', service, undefined, {
+      entityId: 'customers:person',
+      fieldKey: 'national_id',
+    })
+
+    expect(stored).toBe('secret')
+    expect(service.createDek).toHaveBeenCalledTimes(1)
+    expect(warnCalls()).toHaveLength(1)
+    const [, payload] = warnCalls()[0]
+    expect(payload).toMatchObject({
+      tenantId: 'tenant-1',
+      entity: 'customers:person',
+      field: 'national_id',
+    })
+    expect(typeof payload.hint).toBe('string')
+  })
+
+  it('never puts the field value in the warning payload', async () => {
+    await encryptCustomFieldValue('super-secret-value', 'tenant-1', unresolvableDekService(), undefined, {
+      entityId: 'customers:person',
+      fieldKey: 'national_id',
+    })
+
+    expect(JSON.stringify(warnCalls()[0])).not.toContain('super-secret-value')
+  })
+
+  it('still warns when the caller does not identify the field', async () => {
+    await encryptCustomFieldValue('secret', 'tenant-1', unresolvableDekService())
+
+    expect(warnCalls()).toHaveLength(1)
+    expect(warnCalls()[0][1]).toMatchObject({ tenantId: 'tenant-1', entity: null, field: null })
+  })
+
+  // The issue's own reproduction: VAULT_ADDR points at an unreachable Vault and
+  // no fallback secret is set, so createKmsService() hands back a NoopKmsService
+  // whose isHealthy() is false while TENANT_DATA_ENCRYPTION is on — which makes
+  // service.isEnabled() false. Gating the warning on isEnabled() would go silent
+  // in exactly this case, so it must be driven by the env toggle instead.
+  it('warns when the KMS is unhealthy and the service therefore reports itself disabled', async () => {
+    const unhealthyKms = {
+      isEnabled: () => false,
+      getDek: jest.fn(async () => null),
+      createDek: jest.fn(async () => null),
+    } as any
+
+    const stored = await encryptCustomFieldValue('secret', 'tenant-1', unhealthyKms, undefined, {
+      entityId: 'customers:person',
+      fieldKey: 'national_id',
+    })
+
+    expect(stored).toBe('secret')
+    expect(warnCalls()).toHaveLength(1)
+  })
+
+  it('stays silent for the intentional plaintext cases', async () => {
+    // Operator deliberately runs unencrypted, so a plaintext write is correct.
+    process.env.TENANT_DATA_ENCRYPTION = 'no'
+    expect(await encryptCustomFieldValue('plain', 'tenant-1', unresolvableDekService())).toBe('plain')
+    delete process.env.TENANT_DATA_ENCRYPTION
+
+    // No tenant scope, so there is no tenant DEK to resolve.
+    expect(await encryptCustomFieldValue('plain', null, unresolvableDekService())).toBe('plain')
+    expect(await encryptCustomFieldValue('plain', undefined, unresolvableDekService())).toBe('plain')
+    // No encryption service wired at all.
+    expect(await encryptCustomFieldValue('plain', 'tenant-1', null)).toBe('plain')
+    // Null/undefined values are skipped before key resolution.
+    expect(await encryptCustomFieldValue(null, 'tenant-1', unresolvableDekService())).toBe(null)
+
+    expect(warnCalls()).toHaveLength(0)
+  })
+
+  it('warns once per tenant/entity/field so a key outage cannot flood the log', async () => {
+    const service = unresolvableDekService()
+    const field = { entityId: 'customers:person', fieldKey: 'national_id' }
+
+    await encryptCustomFieldValue('a', 'tenant-1', service, undefined, field)
+    await encryptCustomFieldValue('b', 'tenant-1', service, undefined, field)
+    await encryptCustomFieldValue('c', 'tenant-1', service, undefined, field)
+
+    expect(warnCalls()).toHaveLength(1)
+  })
+
+  it('reports each degraded field and tenant separately', async () => {
+    const service = unresolvableDekService()
+
+    await encryptCustomFieldValue('a', 'tenant-1', service, undefined, {
+      entityId: 'customers:person',
+      fieldKey: 'national_id',
+    })
+    await encryptCustomFieldValue('b', 'tenant-1', service, undefined, {
+      entityId: 'customers:person',
+      fieldKey: 'passport_no',
+    })
+    await encryptCustomFieldValue('c', 'tenant-2', service, undefined, {
+      entityId: 'customers:person',
+      fieldKey: 'national_id',
+    })
+
+    expect(warnCalls()).toHaveLength(3)
+  })
+
+  // Throttling for the whole process lifetime would report the first outage and
+  // hide every later one — the exact blind spot this warning exists to remove.
+  it('reports a second outage after the key has recovered in between', async () => {
+    const field = { entityId: 'customers:person', fieldKey: 'national_id' }
+    const recovered = { isEnabled: () => true, getDek: async () => ({ key: fixedKey }) } as any
+
+    await encryptCustomFieldValue('a', 'tenant-1', unresolvableDekService(), undefined, field)
+    expect(warnCalls()).toHaveLength(1)
+
+    const encrypted = await encryptCustomFieldValue('b', 'tenant-1', recovered, undefined, field)
+    expect(encrypted).not.toBe('b')
+
+    await encryptCustomFieldValue('c', 'tenant-1', unresolvableDekService(), undefined, field)
+    expect(warnCalls()).toHaveLength(2)
+  })
+
+  // Regression: hitting the cap used to `.clear()` the whole set, un-throttling
+  // every already-reported field at once (worst possible time — the log flood
+  // the cap exists to prevent). It must evict only the single oldest entry.
+  it('evicts only the oldest entry when the throttle cap is reached, not the whole set', async () => {
+    const service = unresolvableDekService()
+    const WARN_CAP = 5000
+    const fieldAt = (i: number) => ({ entityId: 'customers:person', fieldKey: `field-${i}` })
+
+    for (let i = 0; i < WARN_CAP; i += 1) {
+      await encryptCustomFieldValue('v', 'tenant-1', service, undefined, fieldAt(i))
+    }
+    expect(warnCalls()).toHaveLength(WARN_CAP)
+
+    // One more distinct field crosses the cap and evicts field-0 (the oldest).
+    await encryptCustomFieldValue('v', 'tenant-1', service, undefined, fieldAt(WARN_CAP))
+    expect(warnCalls()).toHaveLength(WARN_CAP + 1)
+
+    // A still-degraded field reported well before the cap stays throttled.
+    await encryptCustomFieldValue('v', 'tenant-1', service, undefined, fieldAt(WARN_CAP - 1))
+    expect(warnCalls()).toHaveLength(WARN_CAP + 1)
+
+    // The evicted oldest entry is the one exception: it reports again.
+    await encryptCustomFieldValue('v', 'tenant-1', service, undefined, fieldAt(0))
+    expect(warnCalls()).toHaveLength(WARN_CAP + 2)
+  })
+
+  it('does not let one tenant recovering unthrottle another tenant still degraded', async () => {
+    const field = { entityId: 'customers:person', fieldKey: 'national_id' }
+    const recovered = { isEnabled: () => true, getDek: async () => ({ key: fixedKey }) } as any
+
+    await encryptCustomFieldValue('a', 'tenant-1', unresolvableDekService(), undefined, field)
+    await encryptCustomFieldValue('b', 'tenant-2', unresolvableDekService(), undefined, field)
+    expect(warnCalls()).toHaveLength(2)
+
+    await encryptCustomFieldValue('c', 'tenant-1', recovered, undefined, field)
+
+    // tenant-2 never recovered, so its warning stays throttled.
+    await encryptCustomFieldValue('d', 'tenant-2', unresolvableDekService(), undefined, field)
+    expect(warnCalls()).toHaveLength(2)
+  })
+})

package/src/lib/encryption/customFieldValues.ts

@@ -1,6 +1,10 @@
 import type { EntityManager } from '@mikro-orm/core'
+import { createLogger } from '../logger'
 import { encryptWithAesGcm, decryptWithAesGcm } from './aes'
 import { TenantDataEncryptionService } from './tenantDataEncryptionService'
+import { isTenantDataEncryptionEnabled } from './toggles'
+
+const logger = createLogger('shared').child({ component: 'encryption' })
 
 /**
  * Custom field kinds that ALWAYS round-trip as a string. The encrypt path
@@ -69,15 +73,107 @@ async function resolveDekKey(
   return key
 }
 
+/**
+ * Whether the caller asked for a write that is supposed to end up encrypted.
+ *
+ * `resolveDekKey` returns `null` for several situations. Two are intentional
+ * no-ops — no encryption service is wired, or the record has no tenant scope —
+ * and one is the operator deliberately running unencrypted
+ * (`TENANT_DATA_ENCRYPTION=no`). Anything else means the caller asked for an
+ * encrypted write that could not be performed, which is worth reporting.
+ *
+ * This deliberately checks the `TENANT_DATA_ENCRYPTION` env toggle rather than
+ * `service.isEnabled()`. `isEnabled()` folds the toggle together with KMS
+ * health, and an unreachable Vault with no fallback secret resolves to
+ * `NoopKmsService`, whose `isHealthy()` is false whenever encryption is on — so
+ * gating on it would stay silent during exactly the outage this warning exists
+ * to surface. The env toggle alone expresses the operator's intent.
+ */
+function isEncryptionExpected(
+  service: TenantDataEncryptionService | null,
+  tenantId: string | null | undefined,
+): boolean {
+  if (!service || !(tenantId ?? null)) return false
+  return isTenantDataEncryptionEnabled()
+}
+
+// One warning per tenant/entity/field per OUTAGE. A key-store outage makes this
+// branch run for every field of every write, so the warning is throttled — but
+// the entries for a tenant are dropped again as soon as one of its writes
+// encrypts successfully. Throttling for the lifetime of the process instead
+// would report the first outage and silently swallow every later one, which is
+// the failure this warning exists to make visible.
+const PLAINTEXT_FALLBACK_WARN_CAP = 5000
+const plaintextFallbackWarned = new Set<string>()
+
+/** Test seam: the warn-once cache is process-global by design. */
+export function resetEncryptedFieldPlaintextFallbackWarnCache(): void {
+  plaintextFallbackWarned.clear()
+}
+
+/**
+ * Forget a tenant's plaintext-fallback warnings once its key resolves again, so
+ * a later outage is reported instead of being throttled away by the previous
+ * one. The `size` guard keeps the healthy path — an empty set — at O(1).
+ */
+function clearPlaintextFallbackWarnings(tenantId: string | null | undefined): void {
+  if (!plaintextFallbackWarned.size) return
+  const prefix = `${tenantId ?? null}|`
+  for (const warnKey of plaintextFallbackWarned) {
+    if (warnKey.startsWith(prefix)) plaintextFallbackWarned.delete(warnKey)
+  }
+}
+
+function warnOnPlaintextFallback(
+  tenantId: string | null | undefined,
+  options?: EncryptCustomFieldOptions,
+): void {
+  try {
+    const scopedTenantId = tenantId ?? null
+    const entity = options?.entityId ?? null
+    const field = options?.fieldKey ?? null
+    const warnKey = `${scopedTenantId}|${entity ?? 'unknown'}|${field ?? 'unknown'}`
+    if (plaintextFallbackWarned.has(warnKey)) return
+    if (plaintextFallbackWarned.size >= PLAINTEXT_FALLBACK_WARN_CAP) {
+      const oldest = plaintextFallbackWarned.values().next().value
+      if (oldest !== undefined) plaintextFallbackWarned.delete(oldest)
+    }
+    plaintextFallbackWarned.add(warnKey)
+    logger.warn('Custom field configured as encrypted was stored as plaintext', {
+      tenantId: scopedTenantId,
+      entity,
+      field,
+      hint: 'The tenant data encryption key could not be read or created (KMS/Vault unavailable, or DEK creation failed), so the value was written unencrypted. Restore key access and re-save the affected records.',
+    })
+  } catch {
+    // A diagnostic must never break the write it is diagnosing.
+  }
+}
+
+export type EncryptCustomFieldOptions = {
+  /** Entity the value belongs to, e.g. `customers:person`. Used only to identify the field in diagnostics. */
+  entityId?: string | null
+  /** Custom field key, e.g. from `CustomFieldDef.key`. Used only to identify the field in diagnostics. */
+  fieldKey?: string | null
+}
+
 export async function encryptCustomFieldValue(
   value: unknown,
   tenantId: string | null | undefined,
   service: TenantDataEncryptionService | null,
   cache?: Map<string | null, string | null>,
+  options?: EncryptCustomFieldOptions,
 ): Promise<unknown> {
   if (value === undefined || value === null) return value
   const key = await resolveDekKey(service, tenantId, cache, { createIfMissing: true })
-  if (!key) return value
+  if (!key) {
+    // Key resolution failed for a field the operator configured as encrypted.
+    // The write still goes through as plaintext (failing it would drop data on
+    // a transient outage), but it must not be silent — issue #5921.
+    if (isEncryptionExpected(service, tenantId)) warnOnPlaintextFallback(tenantId, options)
+    return value
+  }
+  clearPlaintextFallbackWarnings(tenantId)
   const serialized = typeof value === 'string' ? value : JSON.stringify(value)
   return encryptWithAesGcm(serialized, key).value
 }