@emilia-protocol/gate 0.10.0 → 0.13.0

package/evidence.js

@@ -1,360 +1,4 @@
-/**
- * @emilia-protocol/gate — evidence log (tamper-detecting audit of decisions).
- * @license Apache-2.0
- *
- * Every gate decision — allow or deny — appends a hash-chained record. Each
- * record commits to the previous one, so removing or altering any decision
- * breaks the chain and `verify()` catches it. This is the compliance and
- * insurance artifact: a provable account of exactly which consequential actions
- * were authorized, refused, and why. Default sink is in-memory; pass `sink` to
- * stream records to storage. This local chain detects alteration only when the
- * verifier receives its complete history from genesis; a sink alone cannot
- * prevent truncation, restart-from-genesis, or cross-replica forks. Use
- * createAtomicEvidenceLog for a shared production head.
- *
- * Hashing is over CANONICAL JSON (sorted keys) so the same logical record hashes
- * identically across systems and languages — a plain JSON.stringify is
- * insertion-order dependent and would make cross-system verification fragile.
- *
- * `strict` mode makes the log fail CLOSED: if a durable `sink` write fails, the
- * record is NOT appended and `record()` throws. The gate uses this so it never
- * authorizes an action it cannot durably account for. In non-strict (observe)
- * mode a sink failure is best-effort and swallowed.
- */
-import crypto from 'node:crypto';
-
-function sha256hex(s) {
-  return crypto.createHash('sha256').update(s).digest('hex');
-}
-
-/** Canonical JSON (recursive sorted keys) — matches @emilia-protocol/verify. */
-export function canonicalEvidenceJson(v) {
-  if (v === null || v === undefined) return JSON.stringify(v);
-  if (Array.isArray(v)) return `[${v.map(canonicalEvidenceJson).join(',')}]`;
-  if (typeof v === 'object') {
-    return `{${Object.keys(v).sort().map((k) => JSON.stringify(k) + ':' + canonicalEvidenceJson(v[k])).join(',')}}`;
-  }
-  return JSON.stringify(v);
-}
-
-const canonical = canonicalEvidenceJson;
-
-export function createEvidenceLog({ sink, strict = false } = {}) {
-  const records = [];
-  let prev = 'genesis';
-
-  return {
-    // A sink can persist this process-local chain, but it cannot make the head
-    // atomic across replicas or continue it after restart. Never advertise the
-    // local logger as a fleet-safe production ledger.
-    durable: false,
-    persisted: typeof sink === 'function' && strict === true,
-    strict: strict === true,
-    forkAware: false,
-    atomicAppend: false,
-    async record(entry) {
-      // Deep-copy the caller's entry: a shallow spread embeds live references to
-      // nested objects, so a caller mutating them after record() would silently
-      // corrupt the hash-chained evidence record (and anything a sink persisted).
-      const snapshot = entry && typeof entry === 'object' ? structuredClone(entry) : entry;
-      const body = { seq: records.length, prev_hash: prev, ...snapshot };
-      const hash = sha256hex(canonical(body));
-      const rec = { ...body, hash };
-      if (sink) {
-        try {
-          await sink(rec);
-        } catch (e) {
-          // Fail closed in strict mode: do NOT advance the chain, surface the
-          // failure so the caller (the gate) can refuse the action. The seq is
-          // left unconsumed so a retry produces a consistent chain.
-          if (strict) {
-            const err = new Error('evidence_sink_failed');
-            err.cause = e;
-            throw err;
-          }
-          /* non-strict (observe): best-effort, swallow — never break the gate */
-        }
-      }
-      records.push(rec);
-      prev = hash;
-      return rec;
-    },
-
-    all() {
-      return records.slice();
-    },
-
-    /** Recompute the chain; detects any altered or removed record. */
-    verify() {
-      let p = 'genesis';
-      for (const r of records) {
-        const { hash, ...body } = r;
-        if (body.prev_hash !== p) return { ok: false, at: r.seq, reason: 'prev_hash_mismatch' };
-        if (sha256hex(canonical(body)) !== hash) return { ok: false, at: r.seq, reason: 'hash_mismatch' };
-        p = hash;
-      }
-      return { ok: true, length: records.length, head: p === 'genesis' ? null : p };
-    },
-  };
-}
-
-const LOG_HEX_256 = /^[0-9a-f]{64}$/;
-const LOG_RESERVED_FIELDS = new Set(['seq', 'prev_hash', 'record_id', 'hash']);
-
-/** Verify one logger acknowledgement independently of the logger that emitted it. */
-export function verifyEvidenceRecord(record, { atomicRequired = false, expectedEntry } = {}) {
-  try {
-    if (!record || typeof record !== 'object' || Array.isArray(record)
-        || !Number.isSafeInteger(record.seq) || record.seq < 0
-        || (record.prev_hash !== 'genesis' && !LOG_HEX_256.test(record.prev_hash))
-        || !LOG_HEX_256.test(record.hash)) return false;
-    const hasRecordId = Object.prototype.hasOwnProperty.call(record, 'record_id');
-    if ((atomicRequired && !hasRecordId)
-        || (hasRecordId && (typeof record.record_id !== 'string'
-          || record.record_id.length < 16 || record.record_id.length > 256))) return false;
-    const { hash, ...body } = record;
-    if (sha256hex(canonical(body)) !== hash) return false;
-    if (expectedEntry !== undefined) {
-      if (!expectedEntry || typeof expectedEntry !== 'object' || Array.isArray(expectedEntry)) return false;
-      const entry = Object.fromEntries(
-        Object.entries(record).filter(([key]) => !LOG_RESERVED_FIELDS.has(key)),
-      );
-      if (canonical(entry) !== canonical(expectedEntry)) return false;
-    }
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-function assertLogEntry(entry) {
-  if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
-    throw new Error('atomic evidence entry must be an object');
-  }
-  for (const field of LOG_RESERVED_FIELDS) {
-    if (Object.prototype.hasOwnProperty.call(entry, field)) {
-      throw new Error(`atomic evidence entry must not supply reserved field ${field}`);
-    }
-  }
-  const stack = [{ value: entry, depth: 0 }];
-  const seen = new WeakSet();
-  let nodes = 0;
-  let stringBytes = 0;
-  while (stack.length) {
-    const { value, depth } = stack.pop();
-    if (++nodes > 50000 || depth > 64) throw new Error('atomic evidence entry exceeds resource limits');
-    if (value === null || typeof value === 'boolean') continue;
-    if (typeof value === 'number') {
-      if (!Number.isSafeInteger(value)) throw new Error('atomic evidence entry contains a non-safe integer');
-      continue;
-    }
-    if (typeof value === 'string') {
-      stringBytes += Buffer.byteLength(value, 'utf8');
-      if (stringBytes > 1024 * 1024) throw new Error('atomic evidence entry exceeds string limit');
-      continue;
-    }
-    if (typeof value !== 'object') throw new Error('atomic evidence entry is not canonical JSON');
-    if (seen.has(value)) throw new Error('atomic evidence entry contains a cycle or alias');
-    seen.add(value);
-    if (Array.isArray(value)) {
-      for (const child of value) stack.push({ value: child, depth: depth + 1 });
-    } else {
-      for (const [key, child] of Object.entries(value)) {
-        stringBytes += Buffer.byteLength(key, 'utf8');
-        if (stringBytes > 1024 * 1024) throw new Error('atomic evidence entry exceeds string limit');
-        stack.push({ value: child, depth: depth + 1 });
-      }
-    }
-  }
-}
-
-function validateAtomicRecord(record, expectedId, expectedEntry, expectedRecord = null) {
-  return record?.record_id === expectedId
-    && verifyEvidenceRecord(record, { atomicRequired: true, expectedEntry })
-    && (expectedRecord === null || canonical(record) === canonical(expectedRecord));
-}
-
-function validHead(head) {
-  return head === null || Boolean(head && Number.isSafeInteger(head.seq) && head.seq >= 0 && LOG_HEX_256.test(head.hash));
-}
-
-/**
- * Fleet-safe, fail-closed evidence log over an atomic shared-head backend.
- *
- * Backend contract (all operations are scoped by streamId):
- *   readHead(streamId) -> null | { seq, hash }
- *   getById(streamId, recordId) -> null | record
- *   appendIfHead(streamId, expectedHeadHash|null, record) -> boolean
- *   readAll(streamId) -> record[]                    // optional, for verify/all
- *
- * appendIfHead MUST atomically compare the current head, append the immutable
- * record, reject duplicate record_id, and advance the head in one durable
- * transaction. A true return MUST provide immediate read-after-write visibility
- * through getById. `backend.durable === true` is a deployment capability
- * assertion; this module tests the protocol but cannot prove storage hardware
- * semantics.
- */
-export function createAtomicEvidenceLog(backend, {
-  streamId = 'emilia-gate',
-  maxRetries = 32,
-  recordIdFactory = () => crypto.randomUUID(),
-} = {}) {
-  for (const method of ['readHead', 'getById', 'appendIfHead']) {
-    if (typeof backend?.[method] !== 'function') {
-      throw new Error(`createAtomicEvidenceLog: backend must implement async ${method}()`);
-    }
-  }
-  if (typeof streamId !== 'string' || !streamId || streamId.length > 256) {
-    throw new Error('createAtomicEvidenceLog: streamId must be a non-empty string of at most 256 characters');
-  }
-  if (!Number.isSafeInteger(maxRetries) || maxRetries < 1 || maxRetries > 1024) {
-    throw new Error('createAtomicEvidenceLog: maxRetries must be an integer from 1 to 1024');
-  }
-  if (typeof recordIdFactory !== 'function') {
-    throw new Error('createAtomicEvidenceLog: recordIdFactory must be a function');
-  }
-
-  async function recover(recordId, snapshot, expectedRecord = null) {
-    const existing = await backend.getById(streamId, recordId);
-    if (existing === null || existing === undefined) return null;
-    if (!validateAtomicRecord(existing, recordId, snapshot, expectedRecord)) {
-      throw new Error('atomic evidence backend returned a conflicting record_id');
-    }
-    return structuredClone(existing);
-  }
-
-  return {
-    durable: backend.durable === true,
-    persisted: backend.durable === true,
-    strict: true,
-    forkAware: true,
-    atomicAppend: true,
-    streamId,
-
-    async health() {
-      if (typeof backend.health !== 'function') return { ok: false, reason: 'backend_health_unavailable' };
-      return backend.health();
-    },
-
-    async record(entry) {
-      const snapshot = structuredClone(entry);
-      assertLogEntry(snapshot);
-      const recordId = recordIdFactory();
-      if (typeof recordId !== 'string' || recordId.length < 16 || recordId.length > 256) {
-        throw new Error('atomic evidence record id must be a string of 16 to 256 characters');
-      }
-
-      for (let attempt = 0; attempt < maxRetries; attempt++) {
-        const recovered = await recover(recordId, snapshot);
-        if (recovered) return recovered;
-
-        const head = await backend.readHead(streamId);
-        if (!validHead(head)) throw new Error('atomic evidence backend returned a malformed head');
-        const seq = head === null ? 0 : head.seq + 1;
-        const prevHash = head === null ? 'genesis' : head.hash;
-        const body = { seq, prev_hash: prevHash, record_id: recordId, ...snapshot };
-        const record = { ...body, hash: sha256hex(canonical(body)) };
-        try {
-          if ((await backend.appendIfHead(streamId, head?.hash ?? null, record)) === true) {
-            const persisted = await recover(recordId, snapshot, record);
-            if (persisted) return persisted;
-            throw new Error('atomic_evidence_append_not_observable');
-          }
-        } catch (error) {
-          // The append may have linearized before its response was lost. Recover
-          // by stable id; if no record is visible, fail closed and let the caller
-          // retain/freeze its execution reservation.
-          const afterError = await recover(recordId, snapshot, record);
-          if (afterError) return afterError;
-          const wrapped = new Error('atomic_evidence_append_indeterminate');
-          wrapped.cause = error;
-          throw wrapped;
-        }
-      }
-      throw new Error('atomic_evidence_contention_limit');
-    },
-
-    async all() {
-      if (typeof backend.readAll !== 'function') throw new Error('atomic evidence backend does not expose readAll()');
-      const records = await backend.readAll(streamId);
-      if (!Array.isArray(records)) throw new Error('atomic evidence backend returned malformed history');
-      return structuredClone(records);
-    },
-
-    async verify() {
-      try {
-        if (typeof backend.readAll !== 'function') return { ok: false, reason: 'read_all_unavailable' };
-        const records = await backend.readAll(streamId);
-        if (!Array.isArray(records)) return { ok: false, reason: 'malformed_history' };
-        let prev = 'genesis';
-        const ids = new Set();
-        for (let index = 0; index < records.length; index++) {
-          const record = records[index];
-          if (!record || typeof record !== 'object' || Array.isArray(record)
-              || record.seq !== index || record.prev_hash !== prev
-              || typeof record.record_id !== 'string' || ids.has(record.record_id)) {
-            return { ok: false, at: index, reason: 'sequence_or_predecessor_mismatch' };
-          }
-          const { hash, ...body } = record;
-          if (!LOG_HEX_256.test(hash) || sha256hex(canonical(body)) !== hash) {
-            return { ok: false, at: index, reason: 'hash_mismatch' };
-          }
-          ids.add(record.record_id);
-          prev = hash;
-        }
-        const head = await backend.readHead(streamId);
-        const expectedHead = records.length === 0 ? null : { seq: records.length - 1, hash: prev };
-        if (canonical(head) !== canonical(expectedHead)) return { ok: false, reason: 'head_mismatch' };
-        return { ok: true, length: records.length, head: expectedHead?.hash ?? null };
-      } catch {
-        return { ok: false, reason: 'backend_read_failed_or_malformed' };
-      }
-    },
-  };
-}
-
-/** In-memory contract model for tests. It is intentionally not durable. */
-export function createMemoryAtomicEvidenceBackend() {
-  const streams = new Map();
-  const state = (streamId) => {
-    if (!streams.has(streamId)) streams.set(streamId, { records: [], byId: new Map() });
-    return streams.get(streamId);
-  };
-  return {
-    durable: false,
-    async readHead(streamId) {
-      const records = state(streamId).records;
-      const record = records[records.length - 1];
-      return record ? { seq: record.seq, hash: record.hash } : null;
-    },
-    async getById(streamId, recordId) {
-      return structuredClone(state(streamId).byId.get(recordId) ?? null);
-    },
-    async appendIfHead(streamId, expectedHeadHash, record) {
-      const s = state(streamId);
-      const head = s.records[s.records.length - 1] ?? null;
-      const actual = head?.hash ?? null;
-      if (actual !== expectedHeadHash || s.byId.has(record.record_id)
-          || record.seq !== s.records.length || record.prev_hash !== (head?.hash ?? 'genesis')) return false;
-      const snapshot = structuredClone(record);
-      s.records.push(snapshot);
-      s.byId.set(snapshot.record_id, snapshot);
-      return true;
-    },
-    async readAll(streamId) { return structuredClone(state(streamId).records); },
-  };
-}
-
-export const __atomicEvidenceSecurityInternals = Object.freeze({
-  canonical,
-  assertLogEntry,
-  validateAtomicRecord,
-  validHead,
-});
-
-export default {
-  createEvidenceLog,
-  verifyEvidenceRecord,
-  createAtomicEvidenceLog,
-  createMemoryAtomicEvidenceBackend,
-};
+// SPDX-License-Identifier: Apache-2.0
+// Compatibility entry point for the TypeScript evidence module.
+export * from './dist/evidence.js';
+export { default } from './dist/evidence.js';

package/execution-binding.js

@@ -1,213 +1,4 @@
 // SPDX-License-Identifier: Apache-2.0
-// Execution-field binding for EMILIA Gate. This is the executor-side control
-// that prevents "the signed claim said X, the system mutated Y".
-
-import crypto from 'node:crypto';
-
-export const EXECUTION_BINDING_VERSION = 'EP-GATE-EXECUTION-BINDING-v1';
-
-const MAX_JSON_DEPTH = 64;
-const MAX_JSON_NODES = 50000;
-const MAX_JSON_STRING_BYTES = 1024 * 1024;
-
-function validUnicodeString(value) {
-  for (let i = 0; i < value.length; i++) {
-    const unit = value.charCodeAt(i);
-    if (unit >= 0xd800 && unit <= 0xdbff) {
-      const next = value.charCodeAt(++i);
-      if (!(next >= 0xdc00 && next <= 0xdfff)) return false;
-    } else if (unit >= 0xdc00 && unit <= 0xdfff) return false;
-  }
-  return true;
-}
-
-function isPlainObject(value) {
-  if (value === null || typeof value !== 'object' || Array.isArray(value)) return false;
-  const prototype = Object.getPrototypeOf(value);
-  return prototype === Object.prototype || prototype === null;
-}
-
-/**
- * Match the hardened EP canonical JSON safety profile: valid Unicode strings,
- * booleans, null, safe integers, dense arrays, and plain data objects. Object
- * identity is unique across the graph, so cycles and aliases both refuse.
- */
-function assertCanonicalJson(value) {
-  const stack = [{ value, depth: 0 }];
-  const seen = new WeakSet();
-  let nodes = 0;
-  let stringBytes = 0;
-
-  while (stack.length) {
-    const current = stack.pop();
-    if (++nodes > MAX_JSON_NODES || current.depth > MAX_JSON_DEPTH) {
-      throw new TypeError('value exceeds the EP canonical JSON resource profile');
-    }
-    const v = current.value;
-    if (v === null || typeof v === 'boolean') continue;
-    if (typeof v === 'string') {
-      if (!validUnicodeString(v)) throw new TypeError('value contains invalid Unicode');
-      stringBytes += Buffer.byteLength(v, 'utf8');
-      if (stringBytes > MAX_JSON_STRING_BYTES) throw new TypeError('value exceeds the EP canonical JSON string limit');
-      continue;
-    }
-    if (typeof v === 'number') {
-      if (!Number.isSafeInteger(v)) throw new TypeError('value contains a non-safe integer');
-      continue;
-    }
-    if (!Array.isArray(v) && !isPlainObject(v)) {
-      throw new TypeError('value contains a non-plain JSON object');
-    }
-    if (seen.has(v)) throw new TypeError('value contains a cycle or alias');
-    seen.add(v);
-
-    if (Array.isArray(v)) {
-      const ownKeys = Reflect.ownKeys(v);
-      if (ownKeys.length !== v.length + 1 || !ownKeys.includes('length')) {
-        throw new TypeError('value contains a sparse or extended array');
-      }
-      for (let i = 0; i < v.length; i++) {
-        const descriptor = Object.getOwnPropertyDescriptor(v, String(i));
-        if (!descriptor || descriptor.enumerable !== true || !Object.hasOwn(descriptor, 'value')) {
-          throw new TypeError('value contains a sparse or accessor array');
-        }
-        stack.push({ value: descriptor.value, depth: current.depth + 1 });
-      }
-      continue;
-    }
-
-    for (const key of Reflect.ownKeys(v)) {
-      if (typeof key !== 'string' || !validUnicodeString(key)) {
-        throw new TypeError('value contains a non-JSON object key');
-      }
-      const descriptor = Object.getOwnPropertyDescriptor(v, key);
-      if (!descriptor || descriptor.enumerable !== true || !Object.hasOwn(descriptor, 'value')) {
-        throw new TypeError('value contains a non-data JSON property');
-      }
-      stringBytes += Buffer.byteLength(key, 'utf8');
-      if (stringBytes > MAX_JSON_STRING_BYTES) throw new TypeError('value exceeds the EP canonical JSON string limit');
-      stack.push({ value: descriptor.value, depth: current.depth + 1 });
-    }
-  }
-}
-
-function canonicalizeValidated(v) {
-  if (v === null) return 'null';
-  if (Array.isArray(v)) return `[${v.map(canonicalizeValidated).join(',')}]`;
-  if (typeof v === 'object') {
-    return `{${Object.keys(v).sort().map((k) => JSON.stringify(k) + ':' + canonicalizeValidated(v[k])).join(',')}}`;
-  }
-  return JSON.stringify(v);
-}
-
-export function canonicalize(v) {
-  assertCanonicalJson(v);
-  return canonicalizeValidated(v);
-}
-
-export function hashCanonical(v) {
-  return crypto.createHash('sha256').update(canonicalize(v)).digest('hex');
-}
-
-function fieldValue(container, field) {
-  if (!isPlainObject(container)) return { state: 'invalid' };
-  const descriptor = Object.getOwnPropertyDescriptor(container, field);
-  if (!descriptor) return { state: 'missing' };
-  if (descriptor.enumerable !== true || !Object.hasOwn(descriptor, 'value')) return { state: 'invalid' };
-  if (descriptor.value === null) return { state: 'missing' };
-  try {
-    assertCanonicalJson(descriptor.value);
-    return { state: 'valid', value: descriptor.value };
-  } catch {
-    return { state: 'invalid' };
-  }
-}
-
-function equalValue(a, b) {
-  return canonicalize(a) === canonicalize(b);
-}
-
-export function materialFieldsFor(requirement) {
-  const fields = requirement?.execution_binding?.required_fields;
-  return Array.isArray(fields) ? [...new Set(fields.filter(Boolean))] : [];
-}
-
-/**
- * Verifies that the signed claim and the executor-observed mutation fields
- * match for the action pack. The executor must pass `observedAction` from the
- * system of record, not from the agent request body.
- */
-export function verifyExecutionBinding({ requirement, receipt, observedAction } = {}) {
-  const requiredFields = materialFieldsFor(requirement);
-  if (requiredFields.length === 0) {
-    return { ok: true, required: false, required_fields: [], signed_hash: null, observed_hash: null };
-  }
-
-  const signed = receipt?.payload?.claim || {};
-  const observed = observedAction || {};
-  const missingSigned = [];
-  const missingObserved = [];
-  const invalidSigned = [];
-  const invalidObserved = [];
-  const mismatched = [];
-  const signedValues = {};
-  const observedValues = {};
-
-  for (const field of requiredFields) {
-    const expected = fieldValue(signed, field);
-    const actual = fieldValue(observed, field);
-    if (expected.state === 'missing') {
-      missingSigned.push(field);
-    } else if (expected.state === 'invalid') {
-      invalidSigned.push(field);
-    } else {
-      signedValues[field] = expected.value;
-    }
-    if (actual.state === 'missing') {
-      missingObserved.push(field);
-    } else if (actual.state === 'invalid') {
-      invalidObserved.push(field);
-    } else {
-      observedValues[field] = actual.value;
-    }
-    if (expected.state === 'valid' && actual.state === 'valid'
-        && !equalValue(expected.value, actual.value)) mismatched.push(field);
-  }
-
-  // Per-field checks do not see one object reused by two required fields.
-  // Validate the aggregate graphs before computing either digest.
-  try { assertCanonicalJson(signedValues); } catch {
-    for (const field of Object.keys(signedValues)) {
-      if (!invalidSigned.includes(field)) invalidSigned.push(field);
-    }
-  }
-  try { assertCanonicalJson(observedValues); } catch {
-    for (const field of Object.keys(observedValues)) {
-      if (!invalidObserved.includes(field)) invalidObserved.push(field);
-    }
-  }
-
-  return {
-    '@version': EXECUTION_BINDING_VERSION,
-    ok: missingSigned.length === 0 && missingObserved.length === 0
-      && invalidSigned.length === 0 && invalidObserved.length === 0 && mismatched.length === 0,
-    required: true,
-    required_fields: requiredFields,
-    missing_signed_fields: missingSigned,
-    missing_observed_fields: missingObserved,
-    invalid_signed_fields: invalidSigned,
-    invalid_observed_fields: invalidObserved,
-    mismatched_fields: mismatched,
-    signed_hash: invalidSigned.length === 0 ? hashCanonical(signedValues) : null,
-    observed_hash: invalidObserved.length === 0 ? hashCanonical(observedValues) : null,
-    note: 'Executor MUST provide observedAction from the system of record; request-body fields are not a trust source.',
-  };
-}
-
-export default {
-  EXECUTION_BINDING_VERSION,
-  canonicalize,
-  hashCanonical,
-  materialFieldsFor,
-  verifyExecutionBinding,
-};
+// Compatibility entry point for the TypeScript execution-binding module.
+export * from './dist/execution-binding.js';
+export { default } from './dist/execution-binding.js';

package/formal-runtime-map.js

@@ -0,0 +1,4 @@
+// SPDX-License-Identifier: Apache-2.0
+// Compatibility entry point for the TypeScript formal-runtime-map module.
+export * from './dist/formal-runtime-map.js';
+export { default } from './dist/formal-runtime-map.js';