@forklaunch/core 1.5.19 → 1.6.0

package/lib/persistence/index.mjs

@@ -166,7 +166,7 @@ import { p, Type as Type2 } from "@mikro-orm/core";
 // src/persistence/encryptedType.ts
 import { Type } from "@mikro-orm/core";
 import { AsyncLocalStorage } from "async_hooks";
-var ENCRYPTED_PREFIXES = ["v1:", "v2:"];
+var ENCRYPTED_PREFIXES = ["v1:", "v2:", "v3:"];
 function isEncrypted(value) {
   return ENCRYPTED_PREFIXES.some((p3) => value.startsWith(p3));
 }
@@ -573,26 +573,122 @@ var IV_BYTES = 12;
 var KEY_BYTES = 32;
 var HKDF_HASH = "sha256";
 var HKDF_SALT = Buffer.alloc(0);
-var FieldEncryptor = class {
-  masterKey;
-  constructor(masterKey) {
+var KEY_ID_HEX_CHARS = 12;
+var DERIVED_KEY_CACHE_LIMIT = 4096;
+var ENCRYPTED_PREFIXES2 = ["v1:", "v2:", "v3:"];
+function isEncryptedCiphertext(value) {
+  return typeof value === "string" && ENCRYPTED_PREFIXES2.some((p3) => value.startsWith(p3));
+}
+var ENCRYPTION_KEY_ENV = "ENCRYPTION_KEY";
+var LEGACY_ENCRYPTION_KEYS_ENV = "LEGACY_ENCRYPTION_KEYS";
+var LEGACY_ENCRYPTION_KEY_ENV = "LEGACY_ENCRYPTION_KEY";
+var ENCRYPTION_FORMAT_ENV = "ENCRYPTION_FORMAT";
+function parseEncryptionKeyList(...sources) {
+  const keys = [];
+  for (const source of sources) {
+    for (const part of (source ?? "").split(/[\s,;]+/)) {
+      const key = part.trim().replace(/^["']|["']$/g, "");
+      if (key && !keys.includes(key)) keys.push(key);
+    }
+  }
+  return keys;
+}
+function encryptionKeyId(masterKey) {
+  return crypto.createHash("sha256").update(masterKey).digest("hex").slice(0, KEY_ID_HEX_CHARS);
+}
+function stampedKeyId(ciphertext) {
+  if (!ciphertext.startsWith("v3:")) return null;
+  const parts = ciphertext.split(":");
+  return parts.length === 5 ? parts[1] : null;
+}
+function stampedPrefix(keyId) {
+  return `v3:${keyId}:`;
+}
+var FieldEncryptor = class _FieldEncryptor {
+  ring;
+  byId;
+  derived = /* @__PURE__ */ new Map();
+  format;
+  constructor(masterKey, options = {}) {
     if (!masterKey) {
       throw new MissingEncryptionKeyError();
     }
-    this.masterKey = masterKey;
+    const ring = [{ id: encryptionKeyId(masterKey), masterKey }];
+    for (const key of options.previousKeys ?? []) {
+      if (!key || ring.some((k) => k.masterKey === key)) continue;
+      ring.push({ id: encryptionKeyId(key), masterKey: key });
+    }
+    this.ring = ring;
+    this.byId = new Map(ring.map((k) => [k.id, k]));
+    this.format = options.format ?? "v2";
+  }
+  /**
+   * Build the ring from the environment: `ENCRYPTION_KEY` plus
+   * `LEGACY_ENCRYPTION_KEYS` (comma separated) and the older
+   * `LEGACY_ENCRYPTION_KEY`; `ENCRYPTION_FORMAT` selects the envelope.
+   */
+  static fromEnv(env = process.env) {
+    const masterKey = env[ENCRYPTION_KEY_ENV];
+    if (!masterKey) {
+      throw new MissingEncryptionKeyError(`${ENCRYPTION_KEY_ENV} must be set`);
+    }
+    const format = env[ENCRYPTION_FORMAT_ENV]?.trim().toLowerCase();
+    if (format && format !== "v2" && format !== "v3") {
+      throw new Error(
+        `${ENCRYPTION_FORMAT_ENV} must be "v2" or "v3", got "${format}"`
+      );
+    }
+    return new _FieldEncryptor(masterKey, {
+      previousKeys: parseEncryptionKeyList(
+        env[LEGACY_ENCRYPTION_KEYS_ENV],
+        env[LEGACY_ENCRYPTION_KEY_ENV]
+      ),
+      format: format ?? "v2"
+    });
+  }
+  /** Fingerprints of the ring, current first. Safe to log. */
+  get keyIds() {
+    return {
+      current: this.ring[0].id,
+      previous: this.ring.slice(1).map((k) => k.id)
+    };
+  }
+  /** A copy of this encryptor with a different set of previous keys. */
+  withPreviousKeys(previousKeys) {
+    return new _FieldEncryptor(this.ring[0].masterKey, {
+      previousKeys,
+      format: this.format
+    });
+  }
+  /** A copy of this encryptor writing a different envelope. */
+  withFormat(format) {
+    return new _FieldEncryptor(this.ring[0].masterKey, {
+      previousKeys: this.ring.slice(1).map((k) => k.masterKey),
+      format
+    });
   }
   /**
-   * Derive a per-tenant 32-byte key using HKDF-SHA256.
-   * The master key is used as input key material and the tenantId as info context.
+   * Derive a per-tenant 32-byte key using HKDF-SHA256 from the CURRENT
+   * master key. The master key is the input key material and the tenantId
+   * the info context.
    */
   deriveKey(tenantId) {
-    return Buffer.from(
-      crypto.hkdfSync(HKDF_HASH, this.masterKey, HKDF_SALT, tenantId, KEY_BYTES)
+    return this.deriveKeyFor(this.ring[0], tenantId);
+  }
+  deriveKeyFor(key, tenantId) {
+    const cacheKey = `${key.id} ${tenantId}`;
+    const cached = this.derived.get(cacheKey);
+    if (cached) return cached;
+    const derived = Buffer.from(
+      crypto.hkdfSync(HKDF_HASH, key.masterKey, HKDF_SALT, tenantId, KEY_BYTES)
     );
+    if (this.derived.size >= DERIVED_KEY_CACHE_LIMIT) this.derived.clear();
+    this.derived.set(cacheKey, derived);
+    return derived;
   }
   /**
    * Derive a deterministic IV from the key and plaintext using HMAC-SHA256,
-   * truncated to IV_BYTES. Same plaintext + same key → same IV → same
+   * truncated to IV_BYTES. Same plaintext + same key -> same IV -> same
    * ciphertext. This enables WHERE clause matching on encrypted columns
    * while maintaining AES-256-GCM authenticated encryption.
    *
@@ -613,39 +709,95 @@ var FieldEncryptor = class {
       cipher.final()
     ]);
     const authTag = cipher.getAuthTag();
-    return [
-      "v2",
+    const body = [
       iv.toString("base64"),
       authTag.toString("base64"),
       encrypted.toString("base64")
-    ].join(":");
+    ];
+    return this.format === "v3" ? ["v3", this.ring[0].id, ...body].join(":") : ["v2", ...body].join(":");
   }
   decrypt(ciphertext, tenantId) {
     if (ciphertext === null || ciphertext === void 0) {
       return null;
     }
+    return this.open(ciphertext, tenantId ?? "").plaintext;
+  }
+  /**
+   * Decrypt and report which key opened the value and whether a rewrite
+   * would change it. Throws {@link DecryptionError} when no key in the
+   * ring does.
+   */
+  open(ciphertext, tenantId = "") {
     const parts = ciphertext.split(":");
-    if (parts.length !== 4 || parts[0] !== "v1" && parts[0] !== "v2") {
+    const version = parts[0];
+    let candidates;
+    let body;
+    if (version === "v3" && parts.length === 5) {
+      const key = this.byId.get(parts[1]);
+      if (!key) {
+        throw new DecryptionError(
+          `Decryption failed: value is stamped with key ${parts[1]}, which is not in the ring (current ${this.ring[0].id}; previous ${this.ring.slice(1).map((k) => k.id).join(", ") || "none"}). Add it to ${LEGACY_ENCRYPTION_KEYS_ENV}.`
+        );
+      }
+      candidates = [key];
+      body = parts.slice(2);
+    } else if ((version === "v1" || version === "v2") && parts.length === 4) {
+      candidates = this.ring;
+      body = parts.slice(1);
+    } else {
       throw new DecryptionError(
         `Unknown ciphertext version or malformed format`
       );
     }
-    const [, ivB64, authTagB64, encryptedB64] = parts;
+    const [ivB64, authTagB64, encryptedB64] = body;
     const iv = Buffer.from(ivB64, "base64");
     const authTag = Buffer.from(authTagB64, "base64");
     const encrypted = Buffer.from(encryptedB64, "base64");
-    const key = this.deriveKey(tenantId ?? "");
-    try {
-      const decipher = crypto.createDecipheriv(ALGORITHM, key, iv);
-      decipher.setAuthTag(authTag);
-      const decrypted = Buffer.concat([
-        decipher.update(encrypted),
-        decipher.final()
-      ]);
-      return decrypted.toString("utf8");
-    } catch {
-      throw new DecryptionError();
+    for (const key of candidates) {
+      try {
+        const decipher = crypto.createDecipheriv(
+          ALGORITHM,
+          this.deriveKeyFor(key, tenantId),
+          iv
+        );
+        decipher.setAuthTag(authTag);
+        const decrypted = Buffer.concat([
+          decipher.update(encrypted),
+          decipher.final()
+        ]);
+        const current = key === this.ring[0];
+        return {
+          plaintext: decrypted.toString("utf8"),
+          keyId: key.id,
+          current,
+          version,
+          stale: !current || this.format === "v3" && version !== "v3"
+        };
+      } catch {
+      }
     }
+    throw new DecryptionError(
+      candidates.length > 1 ? `Decryption failed: none of the ${candidates.length} keys in the ring opens this value (ciphertext corrupted, wrong tenant, or the key it was written with is not in ${LEGACY_ENCRYPTION_KEYS_ENV})` : `Decryption failed: key ${candidates[0].id} does not open this value (ciphertext corrupted or wrong tenant)`
+    );
+  }
+  /**
+   * True when a rewrite would change the stored bytes: the value is under
+   * a previous key, or unstamped while this encryptor writes `v3`. Throws
+   * when no key opens it.
+   */
+  needsRotation(ciphertext, tenantId = "") {
+    return this.open(ciphertext, tenantId).stale;
+  }
+  /**
+   * Rewrite a value under the current key in the current format. Returns
+   * the input unchanged when nothing would change, so callers can compare
+   * to detect writes.
+   */
+  rotate(ciphertext, tenantId = "") {
+    if (ciphertext === null || ciphertext === void 0) return null;
+    const opened = this.open(ciphertext, tenantId);
+    if (!opened.stale) return ciphertext;
+    return this.encrypt(opened.plaintext, tenantId);
   }
 };
 
@@ -703,6 +855,201 @@ function resolveEntityName2(entityNameOrEntity) {
   return void 0;
 }
 
+// src/persistence/keyRotation.ts
+var ENCRYPTED_LEVELS4 = /* @__PURE__ */ new Set(["pii", "phi", "pci"]);
+var isEncryptedValue = isEncryptedCiphertext;
+var tryOpen = (encryptor, value, tenantId) => {
+  try {
+    return encryptor.open(value, tenantId);
+  } catch {
+    return null;
+  }
+};
+function classifyEncryptedValue(value, encryptor, tenantIds, fallbackTenantIds = []) {
+  if (!isEncryptedValue(value)) return { kind: "plaintext" };
+  const primary = tenantIds.length ? tenantIds : [""];
+  const candidates = [
+    ...primary,
+    ...fallbackTenantIds.filter((t) => !primary.includes(t))
+  ];
+  for (const tenantId of candidates) {
+    const opened = tryOpen(encryptor, value, tenantId);
+    if (!opened) continue;
+    if (!opened.stale) {
+      return { kind: "current", tenantId, keyId: opened.keyId };
+    }
+    const next = encryptor.encrypt(opened.plaintext, tenantId);
+    return next ? { kind: "rewritten", tenantId, keyId: opened.keyId, next } : { kind: "unreadable" };
+  }
+  return { kind: "unreadable" };
+}
+function defaultTenantIdsFor(_entityName, row) {
+  const candidates = [];
+  for (const key of ["organization_id", "organizationId"]) {
+    const v = row[key];
+    if (typeof v === "string" && v) candidates.push(v);
+  }
+  candidates.push("");
+  return [...new Set(candidates)];
+}
+var quote = (id) => `"${id.replace(/"/g, '""')}"`;
+async function collectFallbackTenantIds(execute) {
+  const ids = /* @__PURE__ */ new Set();
+  const tables = await execute(
+    `select table_name from information_schema.columns where table_schema = current_schema() and column_name = 'organization_id'`
+  );
+  for (const { table_name } of tables) {
+    const rows = await execute(
+      `select distinct "organization_id" as id from ${quote(table_name)} where "organization_id" is not null`
+    );
+    for (const { id } of rows) if (typeof id === "string" && id) ids.add(id);
+  }
+  const org = await execute(`select to_regclass('"organization"') as t`);
+  if (org[0]?.t) {
+    const rows = await execute(`select "id" from "organization"`);
+    for (const { id } of rows) if (typeof id === "string" && id) ids.add(id);
+  }
+  return [...ids];
+}
+function entityMetadataList(em) {
+  const all = em.getMetadata().getAll();
+  if (all instanceof Map) return [...all.values()];
+  if (Array.isArray(all)) return all;
+  if (all && typeof all === "object")
+    return Object.values(all);
+  return [];
+}
+async function reencryptEncryptedColumns(options) {
+  const { em, encryptor, dryRun = false, log = () => void 0 } = options;
+  const tenantIdsFor = options.tenantIdsFor ?? defaultTenantIdsFor;
+  const fallbackTenantIds = options.fallbackTenantIds ?? [];
+  const connection = em.getConnection();
+  const execute = options.execute ?? ((sql, params) => connection.execute(sql, params));
+  const reports = [];
+  const ids = encryptor.keyIds;
+  log(
+    `[key-rotation] current key ${ids.current}; previous: ${ids.previous.join(", ") || "none"}; ${fallbackTenantIds.length} fallback tenant(s)${dryRun ? "; DRY RUN" : ""}`
+  );
+  const metas = entityMetadataList(em);
+  if (metas.length === 0) {
+    throw new Error(
+      "[key-rotation] MikroORM reported no entities; refusing to report a sweep over nothing"
+    );
+  }
+  for (const meta of metas) {
+    if (meta.abstract || meta.embeddable || !meta.tableName) continue;
+    const fields = getEntityComplianceFields(meta.className);
+    if (!fields) continue;
+    const props = meta.properties;
+    const encryptedProps = [...fields.entries()].filter(([, level]) => ENCRYPTED_LEVELS4.has(level)).map(([prop]) => props[prop]).filter(
+      (p3) => !!p3 && Array.isArray(p3.fieldNames) && p3.fieldNames.length === 1
+    );
+    if (encryptedProps.length === 0) continue;
+    const pkProp = props[meta.primaryKeys[0]];
+    if (!pkProp) continue;
+    const pkColumn = pkProp.fieldNames[0];
+    const columns = encryptedProps.map((p3) => p3.fieldNames[0]);
+    const report = {
+      table: meta.tableName,
+      columns,
+      scanned: 0,
+      plaintext: 0,
+      current: 0,
+      rewritten: 0,
+      unreadable: 0,
+      unreadableIds: [],
+      byKeyId: {},
+      missingKeyIds: {}
+    };
+    const exists = await execute(`select to_regclass(?) as t`, [
+      quote(meta.tableName)
+    ]);
+    if (!exists[0]?.t) {
+      log(
+        `[key-rotation] ${meta.tableName}: table does not exist yet, skipped`
+      );
+      continue;
+    }
+    const rows = await execute(
+      `select * from ${quote(meta.tableName)}`
+    );
+    for (const row of rows) {
+      report.scanned += 1;
+      const tenantIds = tenantIdsFor(meta.className, row);
+      const updates = [];
+      let rowUnreadable = false;
+      for (const prop of encryptedProps) {
+        const column = prop.fieldNames[0];
+        const outcome = classifyEncryptedValue(
+          row[column],
+          encryptor,
+          tenantIds,
+          fallbackTenantIds
+        );
+        if (outcome.kind === "plaintext") report.plaintext += 1;
+        else if (outcome.kind === "current") report.current += 1;
+        else if (outcome.kind === "rewritten") {
+          report.rewritten += 1;
+          report.byKeyId[outcome.keyId] = (report.byKeyId[outcome.keyId] ?? 0) + 1;
+          updates.push({
+            column,
+            next: outcome.next,
+            jsonb: (prop.columnTypes?.[0] ?? "").toLowerCase().startsWith("json")
+          });
+        } else {
+          report.unreadable += 1;
+          rowUnreadable = true;
+          const missing2 = stampedKeyId(String(row[column]));
+          if (missing2)
+            report.missingKeyIds[missing2] = (report.missingKeyIds[missing2] ?? 0) + 1;
+        }
+      }
+      if (rowUnreadable) report.unreadableIds.push(String(row[pkColumn]));
+      if (updates.length && !dryRun) {
+        const sets = updates.map(
+          (u) => `${quote(u.column)} = ${u.jsonb ? "to_jsonb(?::text)" : "?"}`
+        );
+        await execute(
+          `update ${quote(meta.tableName)} set ${sets.join(", ")} where ${quote(pkColumn)} = ?`,
+          [...updates.map((u) => u.next), row[pkColumn]]
+        );
+      }
+    }
+    const byKey = Object.entries(report.byKeyId).map(([k, n]) => `${k}: ${n}`).join(", ");
+    const missing = Object.entries(report.missingKeyIds).map(([k, n]) => `${k}: ${n}`).join(", ");
+    log(
+      `[key-rotation] ${meta.tableName}: scanned ${report.scanned} rows, ${report.rewritten} values ${dryRun ? "would be " : ""}rewritten${byKey ? ` (from ${byKey})` : ""}, ${report.current} already current, ${report.plaintext} plaintext, ${report.unreadable} unreadable${missing ? ` (stamped with keys not in the ring: ${missing})` : ""}${report.unreadableIds.length ? ` (rows ${report.unreadableIds.slice(0, 10).join(", ")}${report.unreadableIds.length > 10 ? ", ..." : ""})` : ""}`
+    );
+    reports.push(report);
+  }
+  return reports;
+}
+async function countValuesByKeyId(execute, table, column) {
+  const rows = await execute(
+    `select case when ${quote(column)} like 'v3:%' then split_part(${quote(column)}, ':', 2) when ${quote(column)} like 'v1:%' or ${quote(column)} like 'v2:%' then '' else null end as key_id, count(*)::int as n from ${quote(table)} group by 1`
+  );
+  const byKeyId = {};
+  let unstamped = 0;
+  let plaintext = 0;
+  for (const { key_id, n } of rows) {
+    if (key_id === null) plaintext += Number(n);
+    else if (key_id === "") unstamped += Number(n);
+    else byKeyId[key_id] = (byKeyId[key_id] ?? 0) + Number(n);
+  }
+  return { byKeyId, unstamped, plaintext };
+}
+function rotationTotals(reports) {
+  const sum = (pick) => reports.reduce((n, r) => n + pick(r), 0);
+  return {
+    tables: reports.length,
+    scanned: sum((r) => r.scanned),
+    rewritten: sum((r) => r.rewritten),
+    current: sum((r) => r.current),
+    plaintext: sum((r) => r.plaintext),
+    unreadable: sum((r) => r.unreadable)
+  };
+}
+
 // src/persistence/tenantFilter.ts
 var TENANT_FILTER_NAME = "tenant";
 function createTenantFilterDef(column = "organizationId", relationName) {
@@ -870,18 +1217,29 @@ function wrapEmWithTenantContext(em, tenantId) {
 export {
   ComplianceLevel,
   DecryptionError,
+  ENCRYPTED_PREFIXES2 as ENCRYPTED_PREFIXES,
+  ENCRYPTION_FORMAT_ENV,
+  ENCRYPTION_KEY_ENV,
   EncryptedType,
   EncryptionRequiredError,
   FieldEncryptor,
+  LEGACY_ENCRYPTION_KEYS_ENV,
+  LEGACY_ENCRYPTION_KEY_ENV,
   MissingEncryptionKeyError,
   RetentionAction,
   RetentionDuration,
   RlsEventSubscriber,
   TENANT_FILTER_NAME,
   asEncryptionSafe,
+  classifyEncryptedValue,
+  collectFallbackTenantIds,
+  countValuesByKeyId,
   createTenantFilterDef,
+  defaultTenantIdsFor,
   defineComplianceEntity,
+  encryptionKeyId,
   entityHasEncryptedFields,
+  entityMetadataList,
   fp,
   getAllRetentionPolicies,
   getAllUserIdFields,
@@ -891,11 +1249,18 @@ export {
   getEntityRetention,
   getEntityUserIdField,
   getSuperAdminContext,
+  isEncryptedCiphertext,
+  isEncryptedValue,
   parseDuration,
+  parseEncryptionKeyList,
+  reencryptEncryptedColumns,
   registerEncryptor,
+  rotationTotals,
   setEncryptionTenantId,
   setupRls,
   setupTenantFilter,
+  stampedKeyId,
+  stampedPrefix,
   subtractDuration,
   withEncryptionContext,
   wrapEmWithForgivingDecryption,