life-as-api 0.2.0

package/dist/persistence/in-memory-unit-of-work.js

@@ -0,0 +1,32 @@
+// InMemoryUnitOfWork — Slice-18.
+//
+// UNIT_OF_WORK_IN_MEMORY_ATOMIC_BEHAVIOR_001: snapshot all three InMemory stores before
+// the fn, restore all on throw — zero writes survive a failure mid-fn.
+//
+// This class imports concrete InMemory classes (not interfaces) because snapshot/restore
+// methods are internal to those classes and not part of any store interface.
+export class InMemoryUnitOfWork {
+    _docStore;
+    _srcReg;
+    _factStore;
+    constructor(_docStore, _srcReg, _factStore) {
+        this._docStore = _docStore;
+        this._srcReg = _srcReg;
+        this._factStore = _factStore;
+    }
+    async run(fn) {
+        const docSnap = this._docStore._uowSnapshot();
+        const srcSnap = this._srcReg._uowSnapshot();
+        const factSnap = this._factStore._uowSnapshot();
+        try {
+            return await fn();
+        }
+        catch (err) {
+            this._docStore._uowRestore(docSnap);
+            this._srcReg._uowRestore(srcSnap);
+            this._factStore._uowRestore(factSnap);
+            throw err;
+        }
+    }
+}
+//# sourceMappingURL=in-memory-unit-of-work.js.map

package/dist/persistence/in-memory-unit-of-work.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"in-memory-unit-of-work.js","sourceRoot":"","sources":["../../src/persistence/in-memory-unit-of-work.ts"],"names":[],"mappings":"AAAA,iCAAiC;AACjC,EAAE;AACF,wFAAwF;AACxF,uEAAuE;AACvE,EAAE;AACF,yFAAyF;AACzF,6EAA6E;AAO7E,MAAM,OAAO,kBAAkB;IAEV;IACA;IACA;IAHnB,YACmB,SAAoC,EACpC,OAAkC,EAClC,UAA6B;QAF7B,cAAS,GAAT,SAAS,CAA2B;QACpC,YAAO,GAAP,OAAO,CAA2B;QAClC,eAAU,GAAV,UAAU,CAAmB;IAC7C,CAAC;IAEJ,KAAK,CAAC,GAAG,CAAI,EAAoB;QAC/B,MAAM,OAAO,GAAI,IAAI,CAAC,SAAS,CAAC,YAAY,EAAE,CAAC;QAC/C,MAAM,OAAO,GAAI,IAAI,CAAC,OAAO,CAAC,YAAY,EAAE,CAAC;QAC7C,MAAM,QAAQ,GAAG,IAAI,CAAC,UAAU,CAAC,YAAY,EAAE,CAAC;QAChD,IAAI,CAAC;YACH,OAAO,MAAM,EAAE,EAAE,CAAC;QACpB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,CAAC,SAAS,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;YACpC,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;YAClC,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC;YACtC,MAAM,GAAG,CAAC;QACZ,CAAC;IACH,CAAC;CACF"}

package/dist/persistence/key-availability.d.ts

@@ -0,0 +1,9 @@
+import type { KeyProvider } from "../crypto/types.js";
+export interface KeyAvailabilityResult {
+    readonly status: "ok" | "failed";
+    readonly checkedAt: string;
+    readonly requiredKeyCount?: number;
+    readonly missingKeyCount?: number;
+    readonly errorName?: string;
+}
+export declare function validateBackupKeyAvailability(sourcePath: string, keyProvider: KeyProvider): Promise<KeyAvailabilityResult>;

package/dist/persistence/key-availability.js

@@ -0,0 +1,125 @@
+// D4b — Key Availability Validation boundary.
+//
+// PRODUCTION_KEY_INVENTORY_BOUNDARY_SPECIFIED_001: key inventory (which keyIds
+//   are referenced in the DB/backup), key availability (whether the provider
+//   resolves them), and decryptability (whether resolved key material actually
+//   decrypts stored ciphertext) are three separate concerns. This module covers
+//   inventory + availability only. Decryptability validation is deferred to D4c.
+// PRODUCTION_KEY_INVENTORY_NO_KEY_MATERIAL_EXPOSURE_001:
+//   validateBackupKeyAvailability never returns, logs, or exposes raw keyId
+//   strings, key bytes, CryptoKey objects, decrypted payloads, or entity IDs.
+//   KeyId enumeration is internal to the function — strings are used only to
+//   call keyProvider.getKey() and are never present in the result type.
+// PRODUCTION_RESTORE_KEY_AVAILABILITY_VALIDATION_SPECIFIED_001:
+//   validateBackupKeyAvailability(sourcePath, keyProvider) is the specified
+//   offline utility for confirming all referenced keyIds are resolvable before
+//   restore. Result is KeyAvailabilityResult with aggregate counts and status
+//   only — no raw keyId strings, no key material, no entity IDs.
+// PRODUCTION_KEY_INVENTORY_NOT_HEALTHCHECK_DEFAULT_001: key availability
+//   scanning is not part of the default healthCheck bundle method. This
+//   utility is an offline pre-restore operator tool only — not a live-system
+//   diagnostic.
+// PRODUCTION_KEY_INVENTORY_NOT_PRODUCT_API_001:
+//   validateBackupKeyAvailability is not on ProductionApiBundle,
+//   ProductionScopedLifeApi, or the package root export.
+// PRODUCTION_BACKUP_DECRYPTABILITY_NOT_RECOVERY_CLAIM_001: no combination of
+//   validateBackup, validateBackupKeyAvailability, and healthCheck constitutes
+//   a disaster recovery guarantee, SLA, or operational production readiness
+//   claim. Key availability does not prove correct key material.
+// PRODUCTION_RESTORE_DECRYPTABILITY_SCAN_DEFERRED_001: full decryptability
+//   validation (decrypt attempt on stored ciphertext) is deferred to D4c.
+//   A keyId that resolves in the provider may still have wrong key bytes —
+//   that failure surfaces only at decrypt time (CRYPTO_TAMPER_DETECTED_001).
+import Database from "better-sqlite3";
+// ─── Key inventory SQL ────────────────────────────────────────────────────────
+// Enumerates distinct referenced keyIds from all encrypted persistence columns:
+//   claims.encrypted_payload   — JSON EncryptedBlob with $.keyId
+//   raw_documents.encrypted_blob — JSON EncryptedBlob with $.keyId
+//   proposals.payload_key_id   — TEXT denormalized copy of the proposal keyId
+// KeyId strings are processed internally only — never returned to callers.
+const KEY_INVENTORY_SQL = `
+  SELECT key_id FROM (
+    SELECT DISTINCT JSON_EXTRACT(encrypted_payload, '$.keyId') AS key_id
+      FROM claims
+     UNION
+    SELECT DISTINCT JSON_EXTRACT(encrypted_blob,    '$.keyId') AS key_id
+      FROM raw_documents
+     UNION
+    SELECT DISTINCT payload_key_id                             AS key_id
+      FROM proposals
+  )
+  WHERE key_id IS NOT NULL
+`;
+// ─── validateBackupKeyAvailability ────────────────────────────────────────────
+// Opens a backup file (or any migrated SQLite file) read-only and verifies that
+// every referenced keyId can be resolved by the provided KeyProvider.
+//
+// Algorithm:
+//   1. Open the file read-only.
+//   2. Run KEY_INVENTORY_SQL to enumerate distinct referenced keyIds internally.
+//   3. For each keyId, call keyProvider.getKey(keyId).
+//      - undefined → count as missing.
+//      - getKey() throws (e.g. KMS unavailable) → count as missing.
+//   4. Return { status, checkedAt, requiredKeyCount, missingKeyCount }.
+//
+// Guarantees:
+//   - Never throws — all errors return { status: "failed", errorName }.
+//   - Closes the read-only connection before returning.
+//   - Does not decrypt any payload (D4c).
+//   - Does not write to any table or emit audit events.
+//   - Does not call logger or safeLog.
+//   - Does not return keyId strings, key bytes, or entity IDs.
+//   - requiredKeyCount and missingKeyCount are omitted when the inventory
+//     query fails (DB open error, SQL error) — per D4b spec §5.2.
+//   - Wrong key material (registered keyId but wrong bytes) is not detected
+//     here — that failure surfaces at decrypt time via CRYPTO_TAMPER_DETECTED_001.
+export async function validateBackupKeyAvailability(sourcePath, keyProvider) {
+    const checkedAt = new Date().toISOString();
+    let db;
+    try {
+        db = new Database(sourcePath, { readonly: true, fileMustExist: true });
+        // Enumerate distinct referenced keyIds internally — strings stay in-process.
+        const rows = db
+            .prepare(KEY_INVENTORY_SQL)
+            .all();
+        const requiredKeyCount = rows.length;
+        // Check each referenced keyId against the provider.
+        // Per-key getKey failures count as missing — they do not escalate to an
+        // inventory failure. Only the DB open and SQL step can produce the
+        // inventory-failure path (outer catch, counts omitted).
+        let missingKeyCount = 0;
+        for (const row of rows) {
+            let desc;
+            try {
+                desc = await keyProvider.getKey(row.key_id);
+            }
+            catch {
+                // Provider threw (e.g. KMS down) — treat as missing, fail closed.
+                missingKeyCount++;
+                continue;
+            }
+            if (desc === undefined) {
+                missingKeyCount++;
+            }
+        }
+        if (missingKeyCount > 0) {
+            return { status: "failed", checkedAt, requiredKeyCount, missingKeyCount };
+        }
+        return { status: "ok", checkedAt, requiredKeyCount, missingKeyCount: 0 };
+    }
+    catch (err) {
+        // DB open or inventory query failed — omit counts per D4b spec §5.2.
+        return {
+            status: "failed",
+            checkedAt,
+            ...(err instanceof Error ? { errorName: err.name } : {}),
+        };
+    }
+    finally {
+        try {
+            db?.close();
+        }
+        catch { /* ignore close errors */ }
+    }
+}
+//# sourceMappingURL=key-availability.js.map

package/dist/persistence/key-availability.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"key-availability.js","sourceRoot":"","sources":["../../src/persistence/key-availability.ts"],"names":[],"mappings":"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"}

package/dist/persistence/sqlite/migrations.d.ts

@@ -0,0 +1,9 @@
+import type { Database } from "better-sqlite3";
+export declare const CURRENT_SCHEMA_VERSION = 10;
+export declare function verifyCurrentSchema(db: Database): {
+    ok: true;
+} | {
+    ok: false;
+    missing: string[];
+};
+export declare function runMigrations(db: Database): void;