@emilia-protocol/gate 0.11.0 → 0.13.0

package/src/settlement.ts

@@ -0,0 +1,313 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Deterministic evidence-completeness decision for settlement workflows.
+ *
+ * This is not a payment rail and does not decide legal liability. It answers a
+ * narrower question: does a relying-party-pinned profile have every verified,
+ * digest-joined artifact it required before its own settlement system acts?
+ */
+import { canonicalize, hashCanonical } from './execution-binding.js';
+import {
+  NETWORK_WITNESS_EVENTS,
+  acceptNetworkWitnessStatement,
+  networkWitnessDigest,
+  validateTrustedNetworkWitnessAcceptance,
+} from './network-witness.js';
+
+export const SETTLEMENT_PROFILE_VERSION = 'EP-GATE-SETTLEMENT-PROFILE-v1';
+export const SETTLEMENT_RESULT_VERSION = 'EP-GATE-SETTLEMENT-RESULT-v1';
+export const SETTLEMENT_VERDICTS = Object.freeze([
+  'eligible',
+  'refuse_profile_invalid',
+  'refuse_authorization',
+  'refuse_execution',
+  'refuse_witness',
+  'refuse_outcome',
+  'refuse_coverage',
+  'refuse_binding',
+]);
+
+const DIGEST_RE = /^sha256:[0-9a-f]{64}$/;
+
+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;
+}
+
+function exactKeys(value, allowed) {
+  return isPlainObject(value) && Object.keys(value).every((key) => allowed.has(key));
+}
+
+function string(value, max = 512) {
+  return typeof value === 'string' && value.length > 0 && value.length <= max && !/[\u0000-\u001f\u007f]/.test(value);
+}
+
+function digest(value) {
+  return typeof value === 'string' && DIGEST_RE.test(value);
+}
+
+function canonicalSnapshot(value) {
+  return JSON.parse(canonicalize(value));
+}
+
+function validateProfile(profile) {
+  if (!exactKeys(profile, new Set([
+    '@version', 'profile_id', 'require_witness', 'require_outcome', 'require_coverage',
+    'required_witness_event', 'required_witness_id', 'required_capture_point_id',
+    'required_coverage_state', 'required_surface_id',
+  ]))) return 'profile_shape_invalid';
+  if (profile['@version'] !== SETTLEMENT_PROFILE_VERSION || !string(profile.profile_id)) return 'profile_identity_invalid';
+  for (const field of ['require_witness', 'require_outcome', 'require_coverage']) {
+    if (profile[field] !== true && profile[field] !== false) return `profile_${field}_invalid`;
+  }
+  if (profile.require_witness && (!string(profile.required_witness_event)
+      || !NETWORK_WITNESS_EVENTS.includes(profile.required_witness_event)
+      || !string(profile.required_witness_id) || !string(profile.required_capture_point_id))) {
+    return 'profile_witness_binding_invalid';
+  }
+  if (!profile.require_witness && (profile.required_witness_event !== undefined
+      || profile.required_witness_id !== undefined || profile.required_capture_point_id !== undefined)) {
+    return 'profile_witness_fields_forbidden';
+  }
+  if (profile.require_coverage && (profile.required_coverage_state !== 'gated'
+      || !string(profile.required_surface_id))) return 'profile_coverage_binding_invalid';
+  if (!profile.require_coverage && (profile.required_coverage_state !== undefined
+      || profile.required_surface_id !== undefined)) return 'profile_coverage_fields_forbidden';
+  try { canonicalize(profile); } catch { return 'profile_canonicalization_invalid'; }
+  return null;
+}
+
+export function settlementProfileDigest(profile) {
+  const invalid = validateProfile(profile);
+  if (invalid) throw new TypeError(invalid);
+  return `sha256:${hashCanonical(profile)}`;
+}
+
+function refused(verdict, reason, profileHash, checks, actionDigest = null) {
+  const body = {
+    '@version': SETTLEMENT_RESULT_VERSION,
+    verdict,
+    eligible: false,
+    reason,
+    profile_hash: profileHash,
+    action_digest: actionDigest,
+    checks,
+    limitations: [
+      'This result is evidence-completeness input to a relying party; it is not a legal settlement instruction or warranty.',
+      'A valid evidence bundle does not establish physical truth beyond the separately verified outcome source.',
+    ],
+  };
+  return Object.freeze({ ...body, result_hash: `sha256:${hashCanonical(body)}` });
+}
+
+async function invokeVerifier(verifier, artifact, context) {
+  if (typeof verifier !== 'function') return { accepted: false, reason: 'pinned_verifier_missing' };
+  try {
+    const result = await verifier(artifact, Object.freeze({ ...context }));
+    if (!isPlainObject(result)) return { accepted: false, reason: 'verifier_result_invalid' };
+    return canonicalSnapshot(result);
+  } catch {
+    return { accepted: false, reason: 'pinned_verifier_error' };
+  }
+}
+
+/**
+ * Evaluate a raw evidence bundle. Authorization, execution, outcome, and
+ * coverage are interpreted only by verifier functions pinned in code by the
+ * relying party; no artifact may select its own verifier.
+ */
+export async function evaluateSettlementEligibility(bundle = {}, options: {
+  profile?: Record<string, any>;
+  verifyAuthorization?: (...args: any[]) => any;
+  verifyExecution?: (...args: any[]) => any;
+  verifyOutcome?: (...args: any[]) => any;
+  verifyCoverage?: (...args: any[]) => any;
+  pinnedWitnesses?: any[];
+  trustedWitnessAcceptance?: Record<string, any>;
+  witnessSequenceStore?: Record<string, any>;
+  allowEphemeralWitnessStore?: boolean;
+  now?: number | (() => number);
+  witnessMaxAgeSec?: number;
+  maxFutureSkewSec?: number;
+} = {}) {
+  let profileInput;
+  let profileInputInvalid = false;
+  try { profileInput = canonicalSnapshot(options.profile); } catch { profileInputInvalid = true; }
+  let verifyAuthorization;
+  let verifyExecution;
+  let verifyOutcome;
+  let verifyCoverage;
+  let pinnedWitnesses;
+  let trustedWitnessAcceptance = null;
+  let hasTrustedWitnessAcceptance = false;
+  let witnessSequenceStore;
+  let allowEphemeralWitnessStore = false;
+  let witnessNow;
+  let witnessMaxAgeSec;
+  let maxFutureSkewSec;
+  try {
+    verifyAuthorization = options.verifyAuthorization;
+    verifyExecution = options.verifyExecution;
+    verifyOutcome = options.verifyOutcome;
+    verifyCoverage = options.verifyCoverage;
+    pinnedWitnesses = options.pinnedWitnesses === undefined
+      ? undefined
+      : canonicalSnapshot(options.pinnedWitnesses);
+    hasTrustedWitnessAcceptance = Object.hasOwn(options, 'trustedWitnessAcceptance');
+    if (hasTrustedWitnessAcceptance) {
+      trustedWitnessAcceptance = canonicalSnapshot(options.trustedWitnessAcceptance);
+    }
+    witnessSequenceStore = options.witnessSequenceStore;
+    allowEphemeralWitnessStore = options.allowEphemeralWitnessStore === true;
+    witnessNow = options.now;
+    witnessMaxAgeSec = options.witnessMaxAgeSec;
+    maxFutureSkewSec = options.maxFutureSkewSec;
+  } catch {
+    pinnedWitnesses = [];
+    hasTrustedWitnessAcceptance = true;
+    trustedWitnessAcceptance = null;
+  }
+  let profile;
+  let invalid;
+  if (profileInputInvalid) {
+    invalid = 'profile_hostile_input';
+    profile = null;
+  } else {
+    invalid = validateProfile(profileInput);
+    profile = profileInput;
+  }
+  const baseChecks = {
+    profile: !invalid,
+    authorization: false,
+    execution: false,
+    witness: profile?.require_witness === false,
+    outcome: profile?.require_outcome === false,
+    coverage: profile?.require_coverage === false,
+    digest_join: false,
+  };
+  if (invalid) return refused('refuse_profile_invalid', invalid, null, baseChecks);
+  const profileHash = settlementProfileDigest(profile);
+  let evidence;
+  try {
+    evidence = JSON.parse(canonicalize(bundle));
+  } catch {
+    return refused('refuse_binding', 'evidence_bundle_not_canonical_json', profileHash, baseChecks);
+  }
+  const actionDigest = evidence.action_digest;
+  if (!digest(actionDigest)) {
+    return refused('refuse_binding', 'action_digest_invalid', profileHash, baseChecks);
+  }
+  const context = { action_digest: actionDigest, profile_hash: profileHash };
+
+  const authorization = await invokeVerifier(verifyAuthorization, evidence.authorization, context);
+  if (authorization.accepted !== true || authorization.action_digest !== actionDigest
+      || !digest(authorization.decision_digest)) {
+    return refused('refuse_authorization', authorization.reason ?? 'authorization_not_verified', profileHash, baseChecks, actionDigest);
+  }
+  baseChecks.authorization = true;
+
+  const execution = await invokeVerifier(verifyExecution, evidence.execution, {
+    ...context,
+    authorization_digest: authorization.decision_digest,
+  });
+  if (execution.accepted !== true || execution.outcome !== 'executed'
+      || execution.action_digest !== actionDigest || !digest(execution.execution_digest)) {
+    return refused('refuse_execution', execution.reason ?? 'execution_not_verified', profileHash, baseChecks, actionDigest);
+  }
+  baseChecks.execution = true;
+  if (execution.authorization_digest !== authorization.decision_digest) {
+    return refused('refuse_binding', 'execution_authorization_digest_mismatch', profileHash, baseChecks, actionDigest);
+  }
+
+  let witness: Record<string, any> | null = null;
+  if (profile.require_witness) {
+    const witnessOptions = {
+      expectedActionDigest: actionDigest,
+      expectedEvent: profile.required_witness_event,
+      maxAgeSec: witnessMaxAgeSec,
+      maxFutureSkewSec,
+      now: witnessNow,
+      allowEphemeralStore: allowEphemeralWitnessStore,
+    };
+    if (hasTrustedWitnessAcceptance) {
+      let expectedStatementDigest;
+      try { expectedStatementDigest = networkWitnessDigest(evidence.witness); } catch {
+        return refused('refuse_witness', 'witness_statement_digest_invalid', profileHash, baseChecks, actionDigest);
+      }
+      witness = validateTrustedNetworkWitnessAcceptance(trustedWitnessAcceptance, {
+        ...witnessOptions,
+        expectedStatementDigest,
+      });
+    } else {
+      witness = await acceptNetworkWitnessStatement(evidence.witness, {
+        ...witnessOptions,
+        pinnedWitnesses,
+        sequenceStore: witnessSequenceStore,
+      });
+    }
+    if (!witness || !witness.accepted) {
+      return refused('refuse_witness', witness?.reason ?? 'witness_not_verified', profileHash, baseChecks, actionDigest);
+    }
+    if (witness.witness_id !== profile.required_witness_id
+        || witness.capture_point_id !== profile.required_capture_point_id) {
+      return refused('refuse_binding', 'witness_capture_point_mismatch', profileHash, baseChecks, actionDigest);
+    }
+    baseChecks.witness = true;
+  }
+
+  let outcome: Record<string, any> | null = null;
+  if (profile.require_outcome) {
+    outcome = await invokeVerifier(verifyOutcome, evidence.outcome, {
+      ...context,
+      execution_digest: execution.execution_digest,
+    });
+    if (!outcome || outcome.accepted !== true || outcome.within_tolerance !== true
+        || outcome.action_digest !== actionDigest || !digest(outcome.outcome_digest)
+        || outcome.execution_digest !== execution.execution_digest) {
+      return refused('refuse_outcome', outcome?.reason ?? 'outcome_not_verified', profileHash, baseChecks, actionDigest);
+    }
+    baseChecks.outcome = true;
+  }
+
+  let coverage: Record<string, any> | null = null;
+  if (profile.require_coverage) {
+    coverage = await invokeVerifier(verifyCoverage, evidence.coverage, context);
+    if (!coverage || coverage.accepted !== true || coverage.state !== profile.required_coverage_state
+        || coverage.surface_id !== profile.required_surface_id || !digest(coverage.report_hash)) {
+      return refused('refuse_coverage', coverage?.reason ?? 'coverage_not_verified', profileHash, baseChecks, actionDigest);
+    }
+    baseChecks.coverage = true;
+  }
+
+  baseChecks.digest_join = true;
+  const body = {
+    '@version': SETTLEMENT_RESULT_VERSION,
+    verdict: 'eligible',
+    eligible: true,
+    reason: null,
+    profile_hash: profileHash,
+    action_digest: actionDigest,
+    evidence: {
+      authorization_digest: authorization.decision_digest,
+      execution_digest: execution.execution_digest,
+      ...(witness ? { witness_digest: witness.statement_digest } : {}),
+      ...(outcome ? { outcome_digest: outcome.outcome_digest } : {}),
+      ...(coverage ? { coverage_report_hash: coverage.report_hash, surface_id: coverage.surface_id } : {}),
+    },
+    checks: baseChecks,
+    limitations: [
+      'Eligible means the relying party\'s pinned evidence profile was satisfied; the relying party still owns pricing, legal effect, and payment execution.',
+      'The witness proves observation, not authorization or physical outcome; those are separate verified rows.',
+    ],
+  };
+  return Object.freeze({ ...body, result_hash: `sha256:${hashCanonical(body)}` });
+}
+
+export default {
+  SETTLEMENT_PROFILE_VERSION,
+  SETTLEMENT_RESULT_VERSION,
+  SETTLEMENT_VERDICTS,
+  settlementProfileDigest,
+  evaluateSettlementEligibility,
+};

package/src/siem.ts

@@ -0,0 +1,247 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * EMILIA Gate — SIEM export of the evidence log (EP-GATE-SIEM-EXPORT-v1).
+ *
+ * Gate decisions must land where the SOC already looks: Splunk, Sentinel,
+ * Datadog. Two static, offline mappings over evidence-log entries:
+ *   - OCSF (JSON object) for OCSF-native pipelines (Amazon Security Lake,
+ *     Splunk CIM-OCSF, Sentinel ASIM ingestion);
+ *   - CEF (single line) as the lowest-common-denominator syslog fallback.
+ * Pure functions: entry in, event out — no network, no wall clock. Every
+ * timestamp in the output comes from the entry itself, so a fixed entry maps
+ * to a byte-identical event on every call and every host.
+ *
+ * OCSF class choice — class_uid 6003 (API Activity, category 6 Application
+ * Activity). The gate is a policy-enforcement point in front of a tool/API
+ * call: each evidence entry is one attempted API operation with an
+ * allow/deny (or executed/failed) disposition, which is exactly what 6003
+ * models via status_id. The IAM alternatives fit worse: 3003 Authorize
+ * Session models session-privilege grants (no deny activity), and 6004 Web
+ * Resource Access Activity is deprecated in current OCSF.
+ *
+ * Mapping table (evidence entry → OCSF 6003):
+ *   entry.at (ISO)          → time (epoch ms; 0 sentinel if unparseable)
+ *   entry.kind              → activity_name ('decision'|'execution'), activity_id 99 (Other)
+ *   entry.action            → api.operation
+ *   entry.allow / outcome   → status_id 1 Success / 2 Failure (+ status)
+ *   entry.reason / outcome  → status_detail
+ *   entry.subject           → actor.user.uid
+ *   entry.receipt_id        → metadata.correlation_uid
+ *   entry.hash              → metadata.uid (ties the event to the evidence chain)
+ *   allow                   → severity_id 1 Informational; refuse/fail → 3 Medium
+ *   required_tier, selector, seq, prev_hash → unmapped.* (no OCSF slot)
+ *
+ * A malformed entry NEVER throws out of the mappers: it becomes a structured
+ * error event (status Failure, status_detail 'malformed_evidence_entry') so
+ * the corruption itself is visible in the SIEM instead of silently dropped.
+ */
+
+export const SIEM_EXPORT_VERSION = 'EP-GATE-SIEM-EXPORT-v1';
+export const SIEM_OCSF_CLASS_UID = 6003; // API Activity
+const OCSF_SCHEMA_VERSION = '1.1.0';
+const CATEGORY_UID = 6; // Application Activity
+const PRODUCT = { name: 'EMILIA Gate', vendor_name: 'Emilia Protocol' };
+const PREVIEW_MAX = 256;
+
+/**
+ * Shape-check an evidence entry and derive the disposition. An entry is
+ * mappable only if it carries a parseable timestamp AND a verdict (a decision's
+ * `allow` boolean or an execution's `outcome` string) — anything else is
+ * treated as malformed and surfaced as an error event, never a throw.
+ */
+function classifyEntry(entry) {
+  if (!entry || typeof entry !== 'object' || Array.isArray(entry)) return { valid: false };
+  const timeMs = typeof entry.at === 'string' ? Date.parse(entry.at) : NaN;
+  const hasVerdict = typeof entry.allow === 'boolean' || typeof entry.outcome === 'string';
+  if (!Number.isFinite(timeMs) || !hasVerdict) return { valid: false };
+  const kind = entry.kind === 'execution' ? 'execution' : 'decision';
+  const success = typeof entry.allow === 'boolean' ? entry.allow === true : entry.outcome === 'executed';
+  return { valid: true, kind, success, timeMs };
+}
+
+/** Bounded, throw-proof rendering of an unmappable entry for the error event. */
+function safePreview(entry) {
+  let s;
+  try {
+    s = typeof entry === 'string' ? entry : JSON.stringify(entry);
+  } catch {
+    s = '[unserializable]';
+  }
+  if (s == null) s = String(entry);
+  return s.replace(/[\r\n]+/g, ' ').slice(0, PREVIEW_MAX);
+}
+
+/**
+ * Map an evidence-log entry to an OCSF API Activity (6003) event object.
+ * Static and deterministic: same entry, same object, always. Malformed input
+ * yields a structured error event rather than throwing (see module doc).
+ * @param {object} entry  one record from evidence.all()
+ * @returns {object} OCSF-shaped event
+ */
+export function toOCSF(entry) {
+  const c = classifyEntry(entry);
+  if (!c.valid) {
+    return {
+      activity_id: 0,
+      activity_name: 'Unknown',
+      category_uid: CATEGORY_UID,
+      category_name: 'Application Activity',
+      class_uid: SIEM_OCSF_CLASS_UID,
+      class_name: 'API Activity',
+      type_uid: SIEM_OCSF_CLASS_UID * 100 + 0,
+      // No trustworthy timestamp inside the entry; 0 sentinel, never the wall
+      // clock — the mapping stays pure and the bad entry stays evident.
+      time: 0,
+      severity_id: 3,
+      severity: 'Medium',
+      status_id: 2,
+      status: 'Failure',
+      status_detail: 'malformed_evidence_entry',
+      metadata: { version: OCSF_SCHEMA_VERSION, log_name: SIEM_EXPORT_VERSION, product: PRODUCT, uid: null, correlation_uid: null },
+      actor: { user: { uid: null } },
+      api: { operation: null },
+      unmapped: { error: 'malformed_evidence_entry', entry_preview: safePreview(entry) },
+    };
+  }
+  return {
+    activity_id: 99,
+    activity_name: c.kind,
+    category_uid: CATEGORY_UID,
+    category_name: 'Application Activity',
+    class_uid: SIEM_OCSF_CLASS_UID,
+    class_name: 'API Activity',
+    type_uid: SIEM_OCSF_CLASS_UID * 100 + 99,
+    time: c.timeMs,
+    severity_id: c.success ? 1 : 3,
+    severity: c.success ? 'Informational' : 'Medium',
+    status_id: c.success ? 1 : 2,
+    status: c.success ? 'Success' : 'Failure',
+    status_detail: entry.reason ?? entry.outcome ?? null,
+    metadata: {
+      version: OCSF_SCHEMA_VERSION,
+      log_name: SIEM_EXPORT_VERSION,
+      product: PRODUCT,
+      uid: entry.hash ?? null,
+      correlation_uid: entry.receipt_id ?? null,
+    },
+    actor: { user: { uid: entry.subject ?? null } },
+    api: { operation: entry.action ?? null },
+    unmapped: {
+      kind: c.kind,
+      required_tier: entry.required_tier ?? null,
+      selector: entry.selector ?? null,
+      evidence_seq: Number.isFinite(entry.seq) ? entry.seq : null,
+      prev_hash: entry.prev_hash ?? null,
+    },
+  };
+}
+
+// CEF escaping per the ArcSight CEF spec: prefix fields escape backslash and
+// pipe; extension values escape backslash and equals. Newlines are collapsed
+// in both — a CEF record is one line, always.
+function escPrefix(v) {
+  return String(v).replace(/\\/g, '\\\\').replace(/\|/g, '\\|').replace(/[\r\n]+/g, ' ');
+}
+function escExt(v) {
+  return String(v).replace(/\\/g, '\\\\').replace(/=/g, '\\=').replace(/[\r\n]+/g, ' ');
+}
+
+/**
+ * Map an evidence-log entry to a one-line CEF string (syslog fallback for
+ * SIEMs without OCSF ingestion). Same determinism and malformed-input
+ * contract as toOCSF.
+ * @param {object} entry  one record from evidence.all()
+ * @returns {string} `CEF:0|...` single line
+ */
+export function toCEF(entry) {
+  const c = classifyEntry(entry);
+  if (!c.valid) {
+    const ext = [
+      'act=error',
+      'outcome=malformed_evidence_entry',
+      `msg=${escExt(safePreview(entry))}`,
+      `cs4=${escExt(SIEM_EXPORT_VERSION)}`, 'cs4Label=export_version',
+    ].join(' ');
+    return `CEF:0|EmiliaProtocol|Gate|1|gate.malformed|malformed evidence entry|5|${ext}`;
+  }
+  const verdictWord = c.kind === 'execution'
+    ? (c.success ? 'executed' : 'failed')
+    : (c.success ? 'allowed' : 'refused');
+  const signatureId = `gate.${c.kind}.${c.success ? 'allow' : 'deny'}`;
+  const name = `${entry.action ?? 'unknown_action'} ${verdictWord}`;
+  const severity = c.success ? 3 : 7;
+  const ext = [`end=${c.timeMs}`, `act=${c.success ? 'allow' : 'deny'}`];
+  const reason = entry.reason ?? entry.outcome;
+  if (reason != null) ext.push(`outcome=${escExt(reason)}`);
+  if (entry.subject != null) ext.push(`suser=${escExt(entry.subject)}`);
+  if (entry.receipt_id != null) ext.push(`cs1=${escExt(entry.receipt_id)}`, 'cs1Label=receipt_id');
+  if (entry.hash != null) ext.push(`cs2=${escExt(entry.hash)}`, 'cs2Label=evidence_hash');
+  if (entry.required_tier != null) ext.push(`cs3=${escExt(entry.required_tier)}`, 'cs3Label=required_tier');
+  ext.push(`cs4=${escExt(SIEM_EXPORT_VERSION)}`, 'cs4Label=export_version');
+  if (Number.isFinite(entry.seq)) ext.push(`cn1=${entry.seq}`, 'cn1Label=evidence_seq');
+  return `CEF:0|EmiliaProtocol|Gate|1|${escPrefix(signatureId)}|${escPrefix(name)}|${severity}|${ext.join(' ')}`;
+}
+
+/**
+ * Create a forwarder that ships evidence entries to a SIEM sink.
+ *
+ * INVARIANT: SIEM export must NEVER block or crash enforcement. The gate path
+ * calls forward() fire-and-forget; a sink that throws, rejects, or is down is
+ * recorded on the internal `dropped` counter (exposed via stats()) and NOTHING
+ * propagates back to the caller — forward() always resolves, never rejects.
+ * This is the inverse of the evidence log's strict mode: the evidence log is
+ * the authoritative record and fails closed; the SIEM copy is telemetry and
+ * fails open, silently, with an auditable drop count.
+ *
+ * Configuration errors (unknown format, missing sink) DO throw — at
+ * construction time, before anything is on the gate path.
+ *
+ * @param {object} [o]
+ * @param {'ocsf'|'cef'} [o.format='ocsf']
+ * @param {function} [o.sink]  receives the mapped event (object for ocsf, string for cef); may be async
+ * @returns {{ forward(entry): Promise<{delivered:boolean, event:object|string|null}>, stats(): object }}
+ */
+export function createSiemForwarder({ format = 'ocsf', sink }: {
+  format?: 'ocsf' | 'cef';
+  sink?: (event: any) => any;
+} = {}) {
+  if (format !== 'ocsf' && format !== 'cef') {
+    throw new Error(`EMILIA Gate SIEM: unknown format "${format}" (expected 'ocsf' or 'cef')`);
+  }
+  if (typeof sink !== 'function') {
+    throw new Error('EMILIA Gate SIEM: a sink function is required');
+  }
+  // Rebind to a locally-scoped const: `sink` the parameter is typed
+  // `function|undefined` (it's optional in the JSDoc signature above), and
+  // that widened type is what closures below would otherwise capture even
+  // though the throw guard just proved it's a function for the lifetime of
+  // this forwarder. No behavior change, just handing the closure the type
+  // the guard already guarantees.
+  /** @type {function} */
+  const sinkFn = sink;
+  const counts = { forwarded: 0, dropped: 0, malformed: 0 };
+
+  async function forward(entry) {
+    let event: string | ReturnType<typeof toOCSF> | null = null;
+    try {
+      if (!classifyEntry(entry).valid) counts.malformed += 1;
+      event = format === 'cef' ? toCEF(entry) : toOCSF(entry);
+      await sinkFn(event);
+      counts.forwarded += 1;
+      return { delivered: true, event };
+    } catch {
+      // Sink failure (or any unexpected mapper failure): counted, never
+      // propagated — enforcement must not depend on SIEM availability.
+      counts.dropped += 1;
+      return { delivered: false, event };
+    }
+  }
+
+  function stats() {
+    return { format, forwarded: counts.forwarded, dropped: counts.dropped, malformed: counts.malformed };
+  }
+
+  return { forward, stats };
+}
+
+export default { SIEM_EXPORT_VERSION, SIEM_OCSF_CLASS_UID, toOCSF, toCEF, createSiemForwarder };