@emilia-protocol/gate 0.9.2 → 0.9.4

package/store.js

@@ -4,11 +4,14 @@
  *
  * A receipt authorizes ONE action, once. The gate consumes a receipt's
  * identifier the first time it is used; any later presentation of the same
- * receipt is a replay and is refused. The default store is in-memory; swap in a
- * Redis/DB-backed store with the same `consume(key)` contract for a fleet.
+ * receipt is a replay and is refused. The default store is in-memory; fleets
+ * use the ownership-fenced durable contract below.
  */
 export class MemoryConsumptionStore {
   constructor() {
+    this.durable = false;
+    this.ownershipFenced = false;
+    this.permanentConsumption = false;
     this.seen = new Set();
     this.reserved = new Set();
   }
@@ -49,41 +52,103 @@ export class MemoryConsumptionStore {
   }
 }
 
+export const DURABLE_CONSUMPTION_VERSION = 'EP-GATE-DURABLE-CONSUMPTION-v2';
+
+const COMMITTED_VALUE = 'committed:v2';
+const RESERVED_PREFIX = 'reserved:v2:';
+
+function defaultReservationToken() {
+  if (typeof globalThis.crypto?.randomUUID !== 'function') {
+    throw new Error('secure crypto.randomUUID() is required for durable reservation fencing');
+  }
+  return globalThis.crypto.randomUUID();
+}
+
 /**
  * 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:
+ * The backend MUST provide atomic insert-if-absent plus atomic conditional
+ * transition and delete. Together they make replay defense and reservation
+ * ownership 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 addIfAbsent(key, value): boolean
+ *     async compareAndSet(key, expected, replacement): boolean
+ *     async deleteIfValue(key, expected): boolean
  *     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).
+ * State per receipt id is a single ownership-fenced value. A reservation is
+ * `reserved:v2:<random token>` and only the store instance holding that token
+ * can commit or release it. This prevents a delayed worker from deleting or
+ * committing a newer worker's reservation after timeout/failover.
+ *
+ * Reservations deliberately receive NO TTL. A crash after an external effect
+ * has begun is an indeterminate outcome, and automatically reopening the key
+ * would permit a duplicate effect. Operators must reconcile abandoned
+ * reservations. `ttlSeconds` applies only after a value is committed, when the
+ * receipt's own freshness window independently prevents reuse.
  */
-export function createDurableConsumptionStore(backend, { ttlSeconds } = {}) {
-  for (const m of ['addIfAbsent', 'set', 'delete', 'has']) {
+export function createDurableConsumptionStore(backend, { ttlSeconds, reservationTokenFactory = defaultReservationToken } = {}) {
+  for (const m of ['addIfAbsent', 'compareAndSet', 'deleteIfValue', '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.');
+        + 'addIfAbsent and conditional transitions MUST be atomic or replay defense is not fleet-safe.');
     }
   }
+  if (typeof reservationTokenFactory !== 'function') {
+    throw new Error('createDurableConsumptionStore: reservationTokenFactory must be a function');
+  }
+  if (ttlSeconds !== undefined && ttlSeconds !== null
+      && (!Number.isSafeInteger(ttlSeconds) || ttlSeconds <= 0)) {
+    throw new Error('createDurableConsumptionStore: ttlSeconds must be a positive safe integer when supplied');
+  }
   const opt = ttlSeconds ? { ttlSeconds } : undefined;
+  const ownedReservations = new Map();
+
+  function ownedValue(key) {
+    const token = ownedReservations.get(key);
+    if (!token) {
+      throw new Error(`durable consumption transition refused: this store does not own reservation ${key}`);
+    }
+    return `${RESERVED_PREFIX}${token}`;
+  }
+
   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; },
+    durable: backend.durable === true,
+    ownershipFenced: true,
+    permanentConsumption: ttlSeconds === undefined || ttlSeconds === null,
+    retentionSeconds: ttlSeconds ?? null,
+    async reserve(key) {
+      const token = reservationTokenFactory();
+      if (typeof token !== 'string' || token.length < 16) {
+        throw new Error('reservationTokenFactory must return an unpredictable string of at least 16 characters');
+      }
+      const inserted = (await backend.addIfAbsent(key, `${RESERVED_PREFIX}${token}`)) === true;
+      if (inserted) ownedReservations.set(key, token);
+      return inserted;
+    },
+    async commit(key) {
+      const expected = ownedValue(key);
+      const changed = await backend.compareAndSet(key, expected, COMMITTED_VALUE, opt);
+      if (changed !== true) {
+        throw new Error(`durable consumption commit refused: reservation ownership was lost for ${key}`);
+      }
+      ownedReservations.delete(key);
+      return true;
+    },
+    async release(key) {
+      const expected = ownedValue(key);
+      const deleted = await backend.deleteIfValue(key, expected);
+      ownedReservations.delete(key);
+      if (deleted !== true) {
+        throw new Error(`durable consumption release refused: reservation ownership was lost for ${key}`);
+      }
+      return true;
+    },
+    async consume(key) { return (await backend.addIfAbsent(key, COMMITTED_VALUE, opt)) === true; },
     async has(key) { return (await backend.has(key)) === true; },
   };
 }
@@ -92,12 +157,21 @@ export function createDurableConsumptionStore(backend, { ttlSeconds } = {}) {
 export function createMemoryBackend() {
   const map = new Map();
   return {
+    durable: false,
     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 compareAndSet(key, expected, replacement) {
+      if (map.get(key) !== expected) return false;
+      map.set(key, replacement);
+      return true;
+    },
+    async deleteIfValue(key, expected) {
+      if (map.get(key) !== expected) return false;
+      return map.delete(key);
+    },
     async has(key) { return map.has(key); },
+    async get(key) { return map.get(key); },
     get size() { return map.size; },
   };
 }
 
-export default { MemoryConsumptionStore, createDurableConsumptionStore, createMemoryBackend };
+export default { MemoryConsumptionStore, createDurableConsumptionStore, createMemoryBackend, DURABLE_CONSUMPTION_VERSION };