@emilia-protocol/gate 0.10.0 → 0.13.0

package/src/store-postgres.ts

@@ -0,0 +1,167 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * EMILIA Gate — reference DURABLE consumption backend: Postgres
+ * (EP-GATE-PG-CONSUMPTION-v2).
+ *
+ * Replay defense that survives restarts. This module implements the backend
+ * contract consumed by `createDurableConsumptionStore` in ./store.js:
+ *
+ *   backend = {
+ *     async addIfAbsent(key, value, { ttlSeconds }?) : boolean  // true iff inserted
+ *     async compareAndSet(key, expected, replacement, { ttlSeconds }?) : boolean
+ *     async deleteIfValue(key, expected)             : boolean
+ *     async has(key)                                 : boolean
+ *   }
+ *
+ * plus a `cleanupExpired(now)` garbage-collection statement.
+ *
+ * Each transition is one SQL statement. `addIfAbsent` decides first use;
+ * `compareAndSet` and `deleteIfValue` bind commit/release to the opaque owner of
+ * the current reservation. There is no read-then-write interval in which a
+ * delayed worker can overwrite or remove a newer worker's reservation.
+ *
+ * FAIL-CLOSED CONTRACT: if the injected `query` THROWS (connection down,
+ * timeout, constraint other than the PK, ...) the error PROPAGATES to the
+ * caller — nothing here catches it. The gate must refuse an action when
+ * one-time-use cannot be proven; a backend error is NEVER treated as
+ * not-consumed (which would admit replays during an outage) and never treated
+ * as consumed-silently (which would mask the outage as a replay verdict).
+ * Likewise, an EXPIRED row that cleanup has not yet removed still refuses:
+ * TTL expiry is garbage collection, never a grant — the gate already rejects
+ * stale receipts on freshness, so nothing is lost by refusing conservatively.
+ *
+ * Deterministic by construction: the pg-style `query(text, params)` function
+ * and the clock (`now`) are both injected, so tests run against an in-memory
+ * fake with real ON CONFLICT semantics — no network, no database.
+ */
+
+export const PG_CONSUMPTION_VERSION = 'EP-GATE-PG-CONSUMPTION-v2';
+
+/** Single consumption table. Timestamps are epoch milliseconds (BIGINT) so the
+ * injected JS clock maps 1:1 onto column values with no timezone ambiguity. */
+export const CONSUMPTION_TABLE = 'ep_gate_consumption';
+
+export const CONSUMPTION_TABLE_DDL = `CREATE TABLE IF NOT EXISTS ${CONSUMPTION_TABLE} (
+  consumption_key TEXT PRIMARY KEY,
+  state           TEXT NOT NULL,
+  consumed_at     BIGINT NOT NULL,
+  expires_at      BIGINT
+);
+CREATE INDEX IF NOT EXISTS ${CONSUMPTION_TABLE}_expires_idx
+  ON ${CONSUMPTION_TABLE} (expires_at) WHERE expires_at IS NOT NULL;`;
+
+/** The exact statements the backend issues — exported for transparency and so
+ * a fake client can implement them without parsing SQL. */
+export const CONSUMPTION_SQL = {
+  health: `SELECT
+  to_regclass('public.${CONSUMPTION_TABLE}') IS NOT NULL AS table_ready,
+  CASE WHEN to_regclass('public.${CONSUMPTION_TABLE}') IS NULL THEN FALSE
+    ELSE has_table_privilege(current_user, to_regclass('public.${CONSUMPTION_TABLE}'), 'SELECT,INSERT,UPDATE,DELETE') END AS can_use`,
+  /** $1 key, $2 state, $3 consumed_at ms, $4 expires_at ms|null. rowCount 1 = consumed, 0 = replay. */
+  addIfAbsent: `INSERT INTO ${CONSUMPTION_TABLE} (consumption_key, state, consumed_at, expires_at) `
+    + 'VALUES ($1, $2, $3, $4) ON CONFLICT (consumption_key) DO NOTHING',
+  /** $1 key, $2 expected state, $3 replacement, $4 consumed_at ms, $5 expires_at ms|null. */
+  compareAndSet: `UPDATE ${CONSUMPTION_TABLE} SET state = $3, consumed_at = $4, expires_at = $5 `
+    + 'WHERE consumption_key = $1 AND state = $2',
+  /** $1 key, $2 expected state. */
+  deleteIfValue: `DELETE FROM ${CONSUMPTION_TABLE} WHERE consumption_key = $1 AND state = $2`,
+  /** $1 key. Any row — even an expired one — counts as consumed until cleaned. */
+  has: `SELECT 1 FROM ${CONSUMPTION_TABLE} WHERE consumption_key = $1`,
+  /** $1 now ms. Removes ONLY rows whose TTL has elapsed; NULL expires_at never expires. */
+  cleanupExpired: `DELETE FROM ${CONSUMPTION_TABLE} WHERE state LIKE 'committed:%' `
+    + 'AND expires_at IS NOT NULL AND expires_at <= $1',
+};
+
+/**
+ * Create the Postgres consumption backend.
+ * @param {{ query?: (text: string, params: any[]) => Promise<{ rowCount: number, rows?: any[] }>, now?: number|function }} [o]
+ *   `query` is a pg-style query function (e.g. `pool.query.bind(pool)`). Injected
+ *   so tests need no database. MUST throw on failure — errors propagate (fail
+ *   closed). `now` is the injected clock (ms or () => ms).
+ * @returns backend conforming to createDurableConsumptionStore, plus cleanupExpired(now).
+ */
+export function createPostgresBackend({
+  query,
+  now = Date.now,
+}: {
+  query?: (text: string, params: any[]) => Promise<{ rowCount: number; rows?: any[] }>;
+  now?: number | (() => number);
+} = {}) {
+  if (typeof query !== 'function') {
+    throw new Error('createPostgresBackend: query must be an async (text, params) => { rowCount } function '
+      + '(e.g. pg pool.query). It must THROW on failure — a backend error must never look like a verdict.');
+  }
+  let lastObservedNow = Number.NEGATIVE_INFINITY;
+  const checkedNow = (candidate) => {
+    if (!Number.isSafeInteger(candidate) || candidate < 0) {
+      throw new Error('consumption clock must return a non-negative safe-integer epoch millisecond');
+    }
+    if (candidate < lastObservedNow) {
+      throw new Error(`consumption clock regression refused: ${candidate} < ${lastObservedNow}`);
+    }
+    lastObservedNow = candidate;
+    return candidate;
+  };
+  const nowMs = () => checkedNow(typeof now === 'function' ? now() : now);
+  const expiryFor = (opt) => {
+    const ttl = Number(opt?.ttlSeconds);
+    return Number.isFinite(ttl) && ttl > 0 ? nowMs() + ttl * 1000 : null;
+  };
+
+  return {
+    durable: true,
+    async health() {
+      const res = await query(CONSUMPTION_SQL.health, []);
+      if (!res || res.rowCount !== 1 || !Array.isArray(res.rows) || res.rows.length !== 1) {
+        throw new Error('consumption health: malformed Postgres result');
+      }
+      return {
+        ok: res.rows[0].table_ready === true && res.rows[0].can_use === true,
+        version: PG_CONSUMPTION_VERSION,
+      };
+    },
+    /** True iff THIS call inserted the row — the atomic consumed-vs-replay decision. */
+    async addIfAbsent(key, value, opt) {
+      const res = await query(CONSUMPTION_SQL.addIfAbsent, [key, value, nowMs(), expiryFor(opt)]);
+      // Fail closed on a malformed driver result: without a numeric rowCount we
+      // cannot PROVE first-use, so refuse loudly rather than guess.
+      if (!res || typeof res.rowCount !== 'number') {
+        throw new Error('addIfAbsent: query result has no numeric rowCount — cannot prove one-time use');
+      }
+      return res.rowCount === 1;
+    },
+
+    /** Ownership-fenced reserved -> committed transition. */
+    async compareAndSet(key, expected, replacement, opt) {
+      const res = await query(CONSUMPTION_SQL.compareAndSet, [key, expected, replacement, nowMs(), expiryFor(opt)]);
+      if (!res || typeof res.rowCount !== 'number') {
+        throw new Error('compareAndSet: query result has no numeric rowCount — cannot prove reservation ownership');
+      }
+      return res.rowCount === 1;
+    },
+
+    /** Remove only the reservation owned by the caller. */
+    async deleteIfValue(key, expected) {
+      const res = await query(CONSUMPTION_SQL.deleteIfValue, [key, expected]);
+      if (!res || typeof res.rowCount !== 'number') {
+        throw new Error('deleteIfValue: query result has no numeric rowCount — cannot prove reservation ownership');
+      }
+      return res.rowCount === 1;
+    },
+
+    /** Present = consumed. Expired-but-uncleaned rows still count (conservative). */
+    async has(key) {
+      const res = await query(CONSUMPTION_SQL.has, [key]);
+      return (res?.rows?.length ?? res?.rowCount ?? 0) > 0;
+    },
+
+    /** Garbage-collect rows whose TTL elapsed. Returns the number removed. */
+    async cleanupExpired(at) {
+      const cleanupAt = at === undefined ? nowMs() : checkedNow(at);
+      const res = await query(CONSUMPTION_SQL.cleanupExpired, [cleanupAt]);
+      return res?.rowCount ?? 0;
+    },
+  };
+}
+
+export default { createPostgresBackend, CONSUMPTION_TABLE_DDL, CONSUMPTION_TABLE, CONSUMPTION_SQL, PG_CONSUMPTION_VERSION };

package/src/store.ts

@@ -0,0 +1,214 @@
+/**
+ * @emilia-protocol/gate — consumption store (replay defense).
+ * @license Apache-2.0
+ *
+ * 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 in-memory store is an explicit
+ * test/demo opt-in; security-bearing gates use the durable contract below.
+ */
+export class MemoryConsumptionStore {
+  durable: boolean;
+  ownershipFenced: boolean;
+  permanentConsumption: boolean;
+  seen: Set<string>;
+  reserved: Set<string>;
+
+  constructor() {
+    this.durable = false;
+    this.ownershipFenced = false;
+    this.permanentConsumption = false;
+    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) || 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 an external-effect attempt begins. */
+  async commit(key) {
+    this.reserved.delete(key);
+    this.seen.add(key);
+    return true;
+  }
+
+  /** Release only when the caller can prove the external effect never began. */
+  async release(key) {
+    this.reserved.delete(key);
+    return true;
+  }
+
+  async has(key) {
+    return this.seen.has(key) || this.reserved.has(key);
+  }
+
+  get size() {
+    return this.seen.size;
+  }
+}
+
+export const DURABLE_CONSUMPTION_VERSION = 'EP-GATE-DURABLE-CONSUMPTION-v2';
+
+/** Capability contract required by security-bearing Gate execution paths. */
+export function isSecureConsumptionStore(store) {
+  if (!store || typeof store !== 'object') return false;
+  return store.durable === true
+    && store.ownershipFenced === true
+    && store.permanentConsumption === true
+    && typeof store.consume === 'function'
+    && typeof store.reserve === 'function'
+    && typeof store.commit === 'function';
+}
+
+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 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
+ *     async compareAndSet(key, expected, replacement): boolean
+ *     async deleteIfValue(key, expected): boolean
+ *     async has(key): boolean
+ *   }
+ *
+ * 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.
+ */
+/**
+ * @param {any} backend
+ * @param {{ ttlSeconds?: number, reservationTokenFactory?: () => string }} [options]
+ */
+export function createDurableConsumptionStore(
+  backend,
+  { ttlSeconds, reservationTokenFactory = defaultReservationToken }: {
+    ttlSeconds?: number | null;
+    reservationTokenFactory?: () => string;
+  } = {},
+) {
+  for (const m of ['addIfAbsent', 'compareAndSet', 'deleteIfValue', 'has']) {
+    if (typeof backend?.[m] !== 'function') {
+      throw new Error(`createDurableConsumptionStore: backend must implement async ${m}(). `
+        + '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 {
+    durable: backend.durable === true,
+    ownershipFenced: true,
+    permanentConsumption: ttlSeconds === undefined || ttlSeconds === null,
+    retentionSeconds: ttlSeconds ?? null,
+    async health() {
+      if (typeof backend.health !== 'function') return { ok: false, reason: 'backend_health_unavailable' };
+      return backend.health();
+    },
+    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; },
+  };
+}
+
+/** In-memory reference backend (for tests/single-process). addIfAbsent is atomic in a single thread. */
+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 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,
+  isSecureConsumptionStore,
+  DURABLE_CONSUMPTION_VERSION,
+};

package/src/strict-json.ts

@@ -0,0 +1,115 @@
+// SPDX-License-Identifier: Apache-2.0
+// Duplicate-name and Unicode-scalar gate for signed nested JSON such as
+// WebAuthn clientDataJSON. JSON.parse remains the syntax gate.
+
+export const MAX_JSON_DEPTH = 64;
+
+function hasUnpairedUtf16Surrogate(value) {
+  for (let index = 0; index < value.length; index += 1) {
+    const code = value.charCodeAt(index);
+    if (code >= 0xd800 && code <= 0xdbff) {
+      const next = value.charCodeAt(index + 1);
+      if (next < 0xdc00 || next > 0xdfff) return true;
+      index += 1;
+    } else if (code >= 0xdc00 && code <= 0xdfff) {
+      return true;
+    }
+  }
+  return false;
+}
+
+type JsonObjectFrame = { object: true; keys: Set<string>; expectsKey: boolean };
+type JsonArrayFrame = { object: false };
+type JsonFrame = JsonObjectFrame | JsonArrayFrame;
+
+export function strictJsonGate(raw) {
+  if (typeof raw !== 'string') return { ok: false, reason: 'JSON input must be text' };
+  if (hasUnpairedUtf16Surrogate(raw)) {
+    return { ok: false, reason: 'unpaired Unicode surrogate' };
+  }
+  try { JSON.parse(raw); } catch { return { ok: false, reason: 'invalid JSON syntax' }; }
+  let index = 0;
+  const stack: JsonFrame[] = [];
+  let reason: string | null = null;
+  const escapes = { '"': '"', '\\': '\\', '/': '/', b: '\b', f: '\f', n: '\n', r: '\r', t: '\t' };
+
+  function readString() {
+    index += 1;
+    let output = '';
+    while (index < raw.length) {
+      const character = raw[index];
+      if (character === '"') { index += 1; return output; }
+      if (character !== '\\') { output += character; index += 1; continue; }
+      const escape = raw[index + 1];
+      if (escape !== 'u') {
+        output += escapes[escape] ?? '';
+        index += 2;
+        continue;
+      }
+      const first = Number.parseInt(raw.slice(index + 2, index + 6), 16);
+      index += 6;
+      if (first >= 0xd800 && first <= 0xdbff) {
+        if (raw[index] === '\\' && raw[index + 1] === 'u') {
+          const second = Number.parseInt(raw.slice(index + 2, index + 6), 16);
+          if (second >= 0xdc00 && second <= 0xdfff) {
+            output += String.fromCharCode(first, second);
+            index += 6;
+            continue;
+          }
+        }
+        reason = 'unpaired high surrogate escape';
+        return null;
+      }
+      if (first >= 0xdc00 && first <= 0xdfff) {
+        reason = 'unpaired low surrogate escape';
+        return null;
+      }
+      output += String.fromCharCode(first);
+    }
+    reason = 'unterminated string';
+    return null;
+  }
+
+  while (index < raw.length) {
+    const character = raw[index];
+    if (character === '{') {
+      stack.push({ object: true, keys: new Set<string>(), expectsKey: true });
+      if (stack.length > MAX_JSON_DEPTH) return { ok: false, reason: `nesting depth exceeds ${MAX_JSON_DEPTH}` };
+      index += 1;
+    } else if (character === '[') {
+      stack.push({ object: false });
+      if (stack.length > MAX_JSON_DEPTH) return { ok: false, reason: `nesting depth exceeds ${MAX_JSON_DEPTH}` };
+      index += 1;
+    } else if (character === '}' || character === ']') {
+      stack.pop();
+      index += 1;
+    } else if (character === ',') {
+      const top = stack.at(-1);
+      if (top?.object) top.expectsKey = true;
+      index += 1;
+    } else if (character === '"') {
+      const top = stack.at(-1);
+      const isKey = Boolean(top?.object && top.expectsKey);
+      const value = readString();
+      if (reason) return { ok: false, reason };
+      if (isKey) {
+        // `isKey` is only true when `top?.object && top.expectsKey` held above,
+        // which guarantees `top` is a defined object-frame here; narrow the
+        // type for the compiler without altering the runtime reference.
+        const frame = top as JsonObjectFrame;
+        // `readString()` only ever returns null on a path that also sets
+        // `reason`, and the `if (reason) return` above already exited in
+        // that case, so `value` is guaranteed to be a string here.
+        const key = value as string;
+        if (frame.keys.has(key)) return { ok: false, reason: 'duplicate object member name' };
+        frame.keys.add(key);
+        frame.expectsKey = false;
+      }
+    } else {
+      index += 1;
+    }
+  }
+  return { ok: true };
+}
+
+export default { strictJsonGate, MAX_JSON_DEPTH };