@emilia-protocol/gate 0.1.0 → 0.7.0

package/retention.js

@@ -0,0 +1,85 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * EMILIA Gate — evidence retention policy (production audit custody).
+ *
+ * The evidence log is the compliance/insurance artifact. Production custody adds
+ * a retention POLICY over it: classify each decision/execution record as HOT
+ * (recent, fast access), COLD (older, archival), or EXPIRED (past the retention
+ * horizon, eligible for deletion) — and honor a LEGAL HOLD that pins records so
+ * they are never expired. `EP_AUDIT_HOT_DAYS` / `EP_AUDIT_COLD_DAYS` set the
+ * horizons; legal hold is a set of evidence hashes.
+ *
+ * Pure functions over the evidence entries (each has `.at` ISO and `.hash`); the
+ * gate never deletes anything itself — it tells the operator what is eligible.
+ */
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+function ageDays(atISO, nowMs) {
+  const t = Date.parse(atISO);
+  if (!Number.isFinite(t)) return null;
+  return (nowMs - t) / DAY_MS;
+}
+
+/**
+ * Classify evidence entries into retention buckets.
+ * @param {Array<{at:string, hash?:string}>} entries  evidence.all()
+ * @param {object} o
+ * @param {number} [o.hotDays=365]
+ * @param {number} [o.coldDays=2190]   (6y)
+ * @param {number} [o.now=Date.now()]
+ * @param {Set<string>|string[]} [o.legalHold]  hashes pinned indefinitely
+ * @returns {{hot:object[], cold:object[], expired:object[], legal_hold:object[], unknown:object[], summary:object}}
+ */
+export function classifyRetention(entries = [], {
+  hotDays = 365, coldDays = 2190, now = Date.now(), legalHold,
+} = {}) {
+  const held = legalHold instanceof Set ? legalHold : new Set(legalHold || []);
+  const buckets = { hot: [], cold: [], expired: [], legal_hold: [], unknown: [] };
+  for (const e of entries) {
+    const tagged = { hash: e.hash ?? null, at: e.at ?? null, kind: e.kind ?? null };
+    if (e.hash && held.has(e.hash)) { buckets.legal_hold.push(tagged); continue; }
+    const age = ageDays(e.at, now);
+    if (age == null) { buckets.unknown.push(tagged); continue; }
+    if (age <= hotDays) buckets.hot.push(tagged);
+    else if (age <= coldDays) buckets.cold.push(tagged);
+    else buckets.expired.push(tagged);
+  }
+  return {
+    ...buckets,
+    summary: {
+      total: entries.length,
+      hot: buckets.hot.length,
+      cold: buckets.cold.length,
+      expired: buckets.expired.length,
+      legal_hold: buckets.legal_hold.length,
+      unknown: buckets.unknown.length,
+      hot_days: hotDays,
+      cold_days: coldDays,
+    },
+  };
+}
+
+/**
+ * Build an export manifest (the artifact handed to an auditor / SIEM). Includes
+ * the evidence head so the export is verifiably tied to a chain state.
+ */
+export function buildRetentionExport(entries = [], opts = {}) {
+  const cls = classifyRetention(entries, opts);
+  const last = entries[entries.length - 1] || null;
+  return {
+    '@version': 'EP-GATE-RETENTION-EXPORT-v1',
+    generated_at: new Date(opts.now || Date.now()).toISOString(),
+    hot_days: cls.summary.hot_days,
+    cold_days: cls.summary.cold_days,
+    evidence_head: last?.hash ?? null,
+    counts: {
+      total: cls.summary.total, hot: cls.summary.hot, cold: cls.summary.cold,
+      expired: cls.summary.expired, legal_hold: cls.summary.legal_hold, unknown: cls.summary.unknown,
+    },
+    entries: entries.map((e) => ({ hash: e.hash ?? null, at: e.at ?? null, kind: e.kind ?? null })),
+  };
+}
+
+export const RETENTION_EXPORT_VERSION = 'EP-GATE-RETENTION-EXPORT-v1';
+export default { classifyRetention, buildRetentionExport, RETENTION_EXPORT_VERSION };

package/store.js

@@ -10,17 +10,38 @@
 export class MemoryConsumptionStore {
   constructor() {
     this.seen = new Set();
+    this.reserved = new Set();
   }
 
   /** Returns true the FIRST time a key is seen, false on every replay. */
   async consume(key) {
-    if (this.seen.has(key)) return false;
+    if (this.seen.has(key) || this.reserved.has(key)) return false;
     this.seen.add(key);
     return true;
   }
 
+  /** Reserve an id while an action is in flight; blocks concurrent replay. */
+  async reserve(key) {
+    if (this.seen.has(key) || this.reserved.has(key)) return false;
+    this.reserved.add(key);
+    return true;
+  }
+
+  /** Commit a reserved id after the action succeeds. */
+  async commit(key) {
+    this.reserved.delete(key);
+    this.seen.add(key);
+    return true;
+  }
+
+  /** Release a reserved id after the action fails; approval stays retryable. */
+  async release(key) {
+    this.reserved.delete(key);
+    return true;
+  }
+
   async has(key) {
-    return this.seen.has(key);
+    return this.seen.has(key) || this.reserved.has(key);
   }
 
   get size() {
@@ -28,4 +49,55 @@ export class MemoryConsumptionStore {
   }
 }
 
-export default { MemoryConsumptionStore };
+/**
+ * Production custody for replay defense: a durable consumption store backed by
+ * any shared key-value backend (Redis, Postgres, DynamoDB, ...), so a receipt
+ * consumed on one pod/lambda cannot be replayed on another.
+ *
+ * The backend MUST provide an ATOMIC insert-if-absent — this is the single
+ * correctness primitive that makes replay defense sound under concurrency:
+ *
+ *   backend = {
+ *     async addIfAbsent(key, value): boolean  // true iff it inserted (Redis SET NX,
+ *                                             // Postgres INSERT .. ON CONFLICT DO NOTHING)
+ *     async set(key, value): void             // overwrite
+ *     async delete(key): void
+ *     async has(key): boolean
+ *   }
+ *
+ * State per receipt id is a single key: 'reserved' while in flight, 'committed'
+ * once the action succeeded. reserve() is the atomic gate; a second reserve()
+ * (concurrent replay) loses the race and is refused. Optional `ttlSeconds` is
+ * passed through to the backend so consumed ids can expire after the receipt's
+ * own max age (the gate already rejects stale receipts on freshness).
+ */
+export function createDurableConsumptionStore(backend, { ttlSeconds } = {}) {
+  for (const m of ['addIfAbsent', 'set', 'delete', 'has']) {
+    if (typeof backend?.[m] !== 'function') {
+      throw new Error(`createDurableConsumptionStore: backend must implement async ${m}(). `
+        + 'addIfAbsent MUST be atomic (e.g. Redis SET NX) or replay defense is not fleet-safe.');
+    }
+  }
+  const opt = ttlSeconds ? { ttlSeconds } : undefined;
+  return {
+    async reserve(key) { return (await backend.addIfAbsent(key, 'reserved', opt)) === true; },
+    async commit(key) { await backend.set(key, 'committed', opt); return true; },
+    async release(key) { await backend.delete(key); return true; },
+    async consume(key) { return (await backend.addIfAbsent(key, 'committed', opt)) === true; },
+    async has(key) { return (await backend.has(key)) === true; },
+  };
+}
+
+/** In-memory reference backend (for tests/single-process). addIfAbsent is atomic in a single thread. */
+export function createMemoryBackend() {
+  const map = new Map();
+  return {
+    async addIfAbsent(key, value) { if (map.has(key)) return false; map.set(key, value); return true; },
+    async set(key, value) { map.set(key, value); },
+    async delete(key) { map.delete(key); },
+    async has(key) { return map.has(key); },
+    get size() { return map.size; },
+  };
+}
+
+export default { MemoryConsumptionStore, createDurableConsumptionStore, createMemoryBackend };