@gate-forge/core 0.1.0

package/dist/provenance.d.ts

@@ -0,0 +1,170 @@
+import type { RecordOrigin } from './schemas/evidence.js';
+/** The record identity a witness hashes into the service-issued id. */
+export interface RecordIdentity {
+    /** Run manifest identity the record was issued under. */
+    runId: string;
+    /** Obligation the record evidences. */
+    obligationId: string;
+    /** Evidence kind (e.g. `ui.action`, `persistence.entity`). */
+    kind: string;
+    /** Witness-issued test attribution. */
+    testId: string;
+    /** Where the contents came from (drives the trust stamp at issuance). */
+    origin: RecordOrigin;
+    /** JSON-representable evidence payload. */
+    payload: unknown;
+}
+/**
+ * Derives the service-issued record id: sha256 over the GF-canonical
+ * JSON of exactly the identity fields (pin #1/#7). Deterministic and
+ * stable across runs.
+ *
+ * Args:
+ *   identity: runId, obligationId, kind, testId, origin, and payload.
+ *
+ * Returns:
+ *   string: 64-char lowercase hex digest.
+ *
+ * Throws:
+ *   TypeError: when the payload is not JSON-representable (the witness
+ *   refuses to issue such records; callers issuing must too).
+ */
+export declare function recordIdOf(identity: {
+    runId: string;
+    obligationId: string;
+    kind: string;
+    testId: string;
+    origin: RecordOrigin;
+    payload: unknown;
+}): string;
+/**
+ * Verifies a lenient record view against its own provenance (check 1):
+ * the recordId must be 64-hex, every identity field present, and the
+ * id must recompute from the contents. Adversary-controlled input can
+ * never throw — any structural problem is `false` (the record then
+ * demotes to claimed tier, GF-23).
+ *
+ * Args:
+ *   record: an arbitrary record-shaped value (e.g. a `records.json`
+ *     entry or a witness ledger row).
+ *
+ * Returns:
+ *   boolean: true only when the record's own contents hash to its id.
+ */
+export declare function isProvenancedRecord(record: unknown): boolean;
+/**
+ * True when a record asserts the witnessed tier AND its provenance
+ * verifies ({@link isProvenancedRecord}). The single witnessed-tier
+ * predicate for the engine and the reporter's trust display, so a
+ * record can never display as witnessed while the engine would demote
+ * it (or vice versa).
+ *
+ * Args:
+ *   record: an arbitrary record-shaped value.
+ *
+ * Returns:
+ *   boolean: witnessed tier with verified provenance.
+ */
+export declare function isWitnessedRecord(record: unknown): boolean;
+/** Domain tag binding v2 attestation MACs to the ledger envelope format. */
+export declare const ATTESTATION_DOMAIN = "gateforge.ledger.v2";
+/** The only attestation envelope version this code produces or honors. */
+export declare const ATTESTATION_VERSION = 2;
+/**
+ * The unsigned v2 attestation body: the witness run identity, the fresh
+ * trusted invocation identity, the tested input digest, and the issued
+ * record set. The MAC covers exactly these fields plus the domain tag —
+ * never `mac` itself.
+ */
+export interface AttestationBody {
+    /** Witness run UUID. */
+    runId: string;
+    /** Fresh UUID minted by the trusted test-gates caller per invocation. */
+    invocationId: string;
+    /** 64-char lowercase hex digest of the canonical input snapshot. */
+    inputDigest: string;
+    /** Issued record ids (normalized internally: sorted, unique). */
+    recordIds: readonly string[];
+}
+/**
+ * Computes the witness-ledger MAC (pin #7): HMAC-SHA256 over the
+ * GF-canonical JSON of `{runId, recordIds}` keyed by the witness's
+ * VERIFIER KEY — a secret handed to the witness and the verifying CLI
+ * by the run orchestrator, never to the tested suite (the suite's run
+ * token authorizes submissions; it must not authorize attestation).
+ * The MAC makes the durable, suite-writable manifest append tamper-
+ * evident: changing one id, adding a forged id, or transplanting the
+ * set across runs invalidates it.
+ *
+ * Args:
+ *   verifierKey: the witness verifier secret (non-empty).
+ *   runId: the run manifest identity binding the set to THIS run.
+ *   recordIds: the issued record ids (normalized internally).
+ *
+ * Returns:
+ *   string: 64-char lowercase hex HMAC.
+ *
+ * Throws:
+ *   TypeError: when the verifier key is empty.
+ */
+export declare function ledgerMac(verifierKey: string, runId: string, recordIds: readonly string[]): string;
+/**
+ * Verifies a ledger MAC ({@link ledgerMac}) in constant time where the
+ * inputs allow it. Adversary-controlled input never throws.
+ *
+ * Args:
+ *   verifierKey: the witness verifier secret (non-empty).
+ *   runId: the run manifest identity the set claims.
+ *   recordIds: the record-id set the MAC must cover (normalized
+ *     internally, exactly like the witness computed it).
+ *   mac: the claimed MAC (64-char lowercase hex).
+ *
+ * Returns:
+ *   boolean: true only when the MAC verifies over the exact set.
+ */
+export declare function verifyLedgerMac(verifierKey: string, runId: string, recordIds: readonly string[], mac: unknown): boolean;
+/**
+ * Computes the v2 attestation MAC (plan §11.3): HMAC-SHA256 over the
+ * GF-canonical JSON of `{domain, attestationVersion: 2, runId,
+ * invocationId, inputDigest, recordIds}` keyed by the witness's VERIFIER
+ * KEY — a secret the tested suite never receives. The fixed domain tag
+ * prevents cross-format signature acceptance: a legacy `{runId,
+ * recordIds}` MAC can never verify as a v2 attestation, and a v2 MAC
+ * can never verify as anything else.
+ *
+ * Args:
+ *   verifierKey: the witness verifier secret (non-empty).
+ *   body: runId, invocationId, 64-hex inputDigest, and issued record ids
+ *     (normalized internally: deduplicated, codepoint-sorted).
+ *
+ * Returns:
+ *   string: 64-char lowercase hex HMAC.
+ *
+ * Throws:
+ *   TypeError: when the verifier key is empty, an identity is empty, or
+ *   the input digest is not 64-char lowercase hex.
+ */
+export declare function attestationMac(verifierKey: string, body: AttestationBody): string;
+/**
+ * Verifies a v2 attestation MAC ({@link attestationMac}) in constant
+ * time where the inputs allow it. Adversary-controlled input never
+ * throws. A legacy `{runId, recordIds}` MAC is structurally incapable
+ * of verifying here — the domain tag and the extra fields change the
+ * signed bytes — so old evidence can never authorize through this path.
+ *
+ * Args:
+ *   verifierKey: the witness verifier secret (non-empty).
+ *   body: the claimed attestation body (runId, invocationId,
+ *     inputDigest, recordIds).
+ *   mac: the claimed MAC (64-char lowercase hex).
+ *
+ * Returns:
+ *   boolean: true only when the MAC verifies over the exact v2 body.
+ */
+export declare function verifyAttestationMac(verifierKey: string, body: {
+    runId: unknown;
+    invocationId: unknown;
+    inputDigest: unknown;
+    recordIds: unknown;
+}, mac: unknown): boolean;
+//# sourceMappingURL=provenance.d.ts.map

package/dist/provenance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provenance.d.ts","sourceRoot":"","sources":["../src/provenance.ts"],"names":[],"mappings":"AAyCA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAE1D,uEAAuE;AACvE,MAAM,WAAW,cAAc;IAC7B,yDAAyD;IACzD,KAAK,EAAE,MAAM,CAAC;IACd,uCAAuC;IACvC,YAAY,EAAE,MAAM,CAAC;IACrB,8DAA8D;IAC9D,IAAI,EAAE,MAAM,CAAC;IACb,uCAAuC;IACvC,MAAM,EAAE,MAAM,CAAC;IACf,yEAAyE;IACzE,MAAM,EAAE,YAAY,CAAC;IACrB,2CAA2C;IAC3C,OAAO,EAAE,OAAO,CAAC;CAClB;AAKD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,YAAY,CAAC;IACrB,OAAO,EAAE,OAAO,CAAC;CAClB,GAAG,MAAM,CAeT;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAyC5D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAQ1D;AAKD,4EAA4E;AAC5E,eAAO,MAAM,kBAAkB,wBAAwB,CAAC;AAExD,0EAA0E;AAC1E,eAAO,MAAM,mBAAmB,IAAI,CAAC;AAKrC;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,wBAAwB;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,yEAAyE;IACzE,YAAY,EAAE,MAAM,CAAC;IACrB,oEAAoE;IACpE,WAAW,EAAE,MAAM,CAAC;IACpB,iEAAiE;IACjE,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;CAC9B;AAWD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,SAAS,CACvB,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,SAAS,MAAM,EAAE,GAC3B,MAAM,CAUR;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAC7B,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,SAAS,MAAM,EAAE,EAC5B,GAAG,EAAE,OAAO,GACX,OAAO,CAST;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,eAAe,GAAG,MAAM,CAyBjF;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,oBAAoB,CAClC,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,YAAY,EAAE,OAAO,CAAC;IAAC,WAAW,EAAE,OAAO,CAAC;IAAC,SAAS,EAAE,OAAO,CAAA;CAAE,EACzF,GAAG,EAAE,OAAO,GACX,OAAO,CAmBT"}

package/dist/provenance.js

@@ -0,0 +1,306 @@
+/**
+ * Witness provenance verification (pin #7, ADR 0001 D2c, GF-23).
+ *
+ * The witness derives every record id as `sha256(canonicalJson({
+ * runId, obligationId, kind, testId, payload }))` (pin #1) — a
+ * deterministic function of the record's identity alone. That makes
+ * provenance CHECKABLE by any consumer without contacting the witness:
+ * an entry that never passed through the service cannot carry a record
+ * id that both recomputes correctly and appears in an AUTHENTICATED
+ * copy of the witness-issued set.
+ *
+ * Three independent checks exist, and all must pass for witnessed tier:
+ * 1. {@link isProvenancedRecord} — the record id recomputes from the
+ *    record's own contents (structural integrity; catches arbitrary or
+ *    transplanted hex ids). Verified here, in the engine, so every
+ *    consumer of `evaluateObligation` gets it.
+ * 2. Authenticated single-envelope membership (plan §11.5–§11.6) — the
+ *    id appears in a v2 attestation envelope ({@link attestationMac})
+ *    whose integrity is protected by a secret the tested suite never
+ *    receives: the witness's verifier key. The witness serves the live
+ *    envelope at `GET /ledger-attestation` (verifier-key header, bound
+ *    context only) and stamps the durable manifest append with the same
+ *    signed object. The envelope binds the run id, the fresh invocation
+ *    id, the tested input digest, and the issued set — one envelope must
+ *    match all four at once; contexts are never merged. Hash
+ *    recomputation is public, and the run manifest lives in the
+ *    suite-writable state directory, so PLAIN manifest membership is
+ *    trustworthiness-neutral: a hostile suite can fabricate both the
+ *    records and the id list, but it cannot produce a valid MAC for a
+ *    context the witness never attested. The legacy {@link ledgerMac}
+ *    over `{runId, recordIds}` stays readable for diagnostics but NEVER
+ *    authorizes evidence (it binds no input snapshot).
+ * 3. Run identity — record.runId equals the authorizing envelope's
+ *    runId, so ids cannot be transplanted across runs.
+ *
+ * Enforcement lives in the CLI's provenance gate (packages/cli), which
+ * owns the run manifest and the verifier key surface.
+ */
+import { createHmac, timingSafeEqual } from 'node:crypto';
+import { canonicalJson, isJsonValue, sha256Canonical } from './canonical-json.js';
+import { compareStrings } from './graph/util.js';
+/** Shape a 64-char lowercase hex record id must have. */
+const RECORD_ID_PATTERN = /^[0-9a-f]{64}$/;
+/**
+ * Derives the service-issued record id: sha256 over the GF-canonical
+ * JSON of exactly the identity fields (pin #1/#7). Deterministic and
+ * stable across runs.
+ *
+ * Args:
+ *   identity: runId, obligationId, kind, testId, origin, and payload.
+ *
+ * Returns:
+ *   string: 64-char lowercase hex digest.
+ *
+ * Throws:
+ *   TypeError: when the payload is not JSON-representable (the witness
+ *   refuses to issue such records; callers issuing must too).
+ */
+export function recordIdOf(identity) {
+    if (!isJsonValue(identity.payload)) {
+        throw new TypeError('recordIdOf: payload is not GF-canonical-JSON-representable');
+    }
+    if (identity.origin !== 'suite-submitted' && identity.origin !== 'engine-observed') {
+        throw new TypeError('recordIdOf: origin must be suite-submitted or engine-observed');
+    }
+    return sha256Canonical({
+        runId: identity.runId,
+        obligationId: identity.obligationId,
+        kind: identity.kind,
+        testId: identity.testId,
+        origin: identity.origin,
+        payload: identity.payload,
+    });
+}
+/**
+ * Verifies a lenient record view against its own provenance (check 1):
+ * the recordId must be 64-hex, every identity field present, and the
+ * id must recompute from the contents. Adversary-controlled input can
+ * never throw — any structural problem is `false` (the record then
+ * demotes to claimed tier, GF-23).
+ *
+ * Args:
+ *   record: an arbitrary record-shaped value (e.g. a `records.json`
+ *     entry or a witness ledger row).
+ *
+ * Returns:
+ *   boolean: true only when the record's own contents hash to its id.
+ */
+export function isProvenancedRecord(record) {
+    if (typeof record !== 'object' || record === null || Array.isArray(record)) {
+        return false;
+    }
+    const candidate = record;
+    const recordId = candidate['recordId'];
+    if (typeof recordId !== 'string' || !RECORD_ID_PATTERN.test(recordId))
+        return false;
+    const runId = candidate['runId'];
+    const obligationId = candidate['obligationId'];
+    const kind = candidate['kind'];
+    const testId = candidate['testId'];
+    if (typeof runId !== 'string' ||
+        runId.length === 0 ||
+        typeof obligationId !== 'string' ||
+        obligationId.length === 0 ||
+        typeof kind !== 'string' ||
+        kind.length === 0 ||
+        typeof testId !== 'string' ||
+        testId.length === 0) {
+        return false;
+    }
+    const payload = candidate['payload'];
+    if (!isJsonValue(payload))
+        return false;
+    const origin = candidate['origin'];
+    if (origin !== 'suite-submitted' && origin !== 'engine-observed')
+        return false;
+    try {
+        return (recordIdOf({
+            runId,
+            obligationId,
+            kind,
+            testId,
+            origin,
+            payload,
+        }) === recordId);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * True when a record asserts the witnessed tier AND its provenance
+ * verifies ({@link isProvenancedRecord}). The single witnessed-tier
+ * predicate for the engine and the reporter's trust display, so a
+ * record can never display as witnessed while the engine would demote
+ * it (or vice versa).
+ *
+ * Args:
+ *   record: an arbitrary record-shaped value.
+ *
+ * Returns:
+ *   boolean: witnessed tier with verified provenance.
+ */
+export function isWitnessedRecord(record) {
+    if (typeof record !== 'object' || record === null || Array.isArray(record)) {
+        return false;
+    }
+    return (record['trust'] === 'witnessed' &&
+        isProvenancedRecord(record));
+}
+/** Shape a 64-char lowercase hex MAC must have. */
+const MAC_PATTERN = /^[0-9a-f]{64}$/;
+/** Domain tag binding v2 attestation MACs to the ledger envelope format. */
+export const ATTESTATION_DOMAIN = 'gateforge.ledger.v2';
+/** The only attestation envelope version this code produces or honors. */
+export const ATTESTATION_VERSION = 2;
+/** Shape a 64-char lowercase hex input digest must have. */
+const INPUT_DIGEST_PATTERN = /^[0-9a-f]{64}$/;
+/**
+ * Normalizes a record-id set for MAC computation: deduplicated and
+ * sorted by codepoint, so the witness and every verifier hash the same
+ * canonical list regardless of insertion or serialization order.
+ */
+function canonicalIdSet(recordIds) {
+    return [...new Set(recordIds)].sort(compareStrings);
+}
+/**
+ * Computes the witness-ledger MAC (pin #7): HMAC-SHA256 over the
+ * GF-canonical JSON of `{runId, recordIds}` keyed by the witness's
+ * VERIFIER KEY — a secret handed to the witness and the verifying CLI
+ * by the run orchestrator, never to the tested suite (the suite's run
+ * token authorizes submissions; it must not authorize attestation).
+ * The MAC makes the durable, suite-writable manifest append tamper-
+ * evident: changing one id, adding a forged id, or transplanting the
+ * set across runs invalidates it.
+ *
+ * Args:
+ *   verifierKey: the witness verifier secret (non-empty).
+ *   runId: the run manifest identity binding the set to THIS run.
+ *   recordIds: the issued record ids (normalized internally).
+ *
+ * Returns:
+ *   string: 64-char lowercase hex HMAC.
+ *
+ * Throws:
+ *   TypeError: when the verifier key is empty.
+ */
+export function ledgerMac(verifierKey, runId, recordIds) {
+    if (typeof verifierKey !== 'string' || verifierKey.length === 0) {
+        throw new TypeError('ledgerMac: verifier key must be a non-empty string');
+    }
+    if (typeof runId !== 'string' || runId.length === 0) {
+        throw new TypeError('ledgerMac: runId must be a non-empty string');
+    }
+    return createHmac('sha256', verifierKey)
+        .update(canonicalJson({ runId, recordIds: canonicalIdSet(recordIds) }))
+        .digest('hex');
+}
+/**
+ * Verifies a ledger MAC ({@link ledgerMac}) in constant time where the
+ * inputs allow it. Adversary-controlled input never throws.
+ *
+ * Args:
+ *   verifierKey: the witness verifier secret (non-empty).
+ *   runId: the run manifest identity the set claims.
+ *   recordIds: the record-id set the MAC must cover (normalized
+ *     internally, exactly like the witness computed it).
+ *   mac: the claimed MAC (64-char lowercase hex).
+ *
+ * Returns:
+ *   boolean: true only when the MAC verifies over the exact set.
+ */
+export function verifyLedgerMac(verifierKey, runId, recordIds, mac) {
+    if (typeof mac !== 'string' || !MAC_PATTERN.test(mac))
+        return false;
+    try {
+        const expected = Buffer.from(ledgerMac(verifierKey, runId, recordIds), 'hex');
+        const claimed = Buffer.from(mac, 'hex');
+        return expected.length === claimed.length && timingSafeEqual(expected, claimed);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Computes the v2 attestation MAC (plan §11.3): HMAC-SHA256 over the
+ * GF-canonical JSON of `{domain, attestationVersion: 2, runId,
+ * invocationId, inputDigest, recordIds}` keyed by the witness's VERIFIER
+ * KEY — a secret the tested suite never receives. The fixed domain tag
+ * prevents cross-format signature acceptance: a legacy `{runId,
+ * recordIds}` MAC can never verify as a v2 attestation, and a v2 MAC
+ * can never verify as anything else.
+ *
+ * Args:
+ *   verifierKey: the witness verifier secret (non-empty).
+ *   body: runId, invocationId, 64-hex inputDigest, and issued record ids
+ *     (normalized internally: deduplicated, codepoint-sorted).
+ *
+ * Returns:
+ *   string: 64-char lowercase hex HMAC.
+ *
+ * Throws:
+ *   TypeError: when the verifier key is empty, an identity is empty, or
+ *   the input digest is not 64-char lowercase hex.
+ */
+export function attestationMac(verifierKey, body) {
+    if (typeof verifierKey !== 'string' || verifierKey.length === 0) {
+        throw new TypeError('attestationMac: verifier key must be a non-empty string');
+    }
+    if (typeof body.runId !== 'string' || body.runId.length === 0) {
+        throw new TypeError('attestationMac: runId must be a non-empty string');
+    }
+    if (typeof body.invocationId !== 'string' || body.invocationId.length === 0) {
+        throw new TypeError('attestationMac: invocationId must be a non-empty string');
+    }
+    if (typeof body.inputDigest !== 'string' || !INPUT_DIGEST_PATTERN.test(body.inputDigest)) {
+        throw new TypeError('attestationMac: inputDigest must be 64-char lowercase hex');
+    }
+    return createHmac('sha256', verifierKey)
+        .update(canonicalJson({
+        domain: ATTESTATION_DOMAIN,
+        attestationVersion: ATTESTATION_VERSION,
+        runId: body.runId,
+        invocationId: body.invocationId,
+        inputDigest: body.inputDigest,
+        recordIds: canonicalIdSet(body.recordIds),
+    }))
+        .digest('hex');
+}
+/**
+ * Verifies a v2 attestation MAC ({@link attestationMac}) in constant
+ * time where the inputs allow it. Adversary-controlled input never
+ * throws. A legacy `{runId, recordIds}` MAC is structurally incapable
+ * of verifying here — the domain tag and the extra fields change the
+ * signed bytes — so old evidence can never authorize through this path.
+ *
+ * Args:
+ *   verifierKey: the witness verifier secret (non-empty).
+ *   body: the claimed attestation body (runId, invocationId,
+ *     inputDigest, recordIds).
+ *   mac: the claimed MAC (64-char lowercase hex).
+ *
+ * Returns:
+ *   boolean: true only when the MAC verifies over the exact v2 body.
+ */
+export function verifyAttestationMac(verifierKey, body, mac) {
+    if (typeof mac !== 'string' || !MAC_PATTERN.test(mac))
+        return false;
+    if (typeof body !== 'object' ||
+        body === null ||
+        typeof body.runId !== 'string' ||
+        typeof body.invocationId !== 'string' ||
+        typeof body.inputDigest !== 'string' ||
+        !Array.isArray(body.recordIds)) {
+        return false;
+    }
+    try {
+        const expected = Buffer.from(attestationMac(verifierKey, body), 'hex');
+        const claimed = Buffer.from(mac, 'hex');
+        return expected.length === claimed.length && timingSafeEqual(expected, claimed);
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=provenance.js.map

package/dist/provenance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provenance.js","sourceRoot":"","sources":["../src/provenance.ts"],"names":[],"mappings":"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"}

package/dist/receipt/index.d.ts

@@ -0,0 +1,74 @@
+import { type GateReceipt } from '../schemas/gate-receipt.js';
+/** Domain tag binding receipt MACs to the gate-receipt envelope format. */
+export declare const RECEIPT_DOMAIN = "gateforge.receipt.v1";
+/** The only receipt envelope version this code produces or honors. */
+export declare const RECEIPT_VERSION = 1;
+/** The unsigned receipt body (everything the MAC covers). */
+export type GateReceiptBody = Omit<GateReceipt, 'mac'>;
+/**
+ * Computes the receipt MAC (ADR 0005 D3): HMAC-SHA256 over the GF-canonical
+ * JSON of `{domain: 'gateforge.receipt.v1', receiptVersion: 1, ...body}`
+ * keyed by the witness verifier key — the same secret the tested suite
+ * never receives for ledger attestations. The fixed domain tag prevents
+ * cross-format signature acceptance in BOTH directions: a v2 ledger MAC
+ * can never verify as a receipt, and a receipt MAC can never verify as a
+ * ledger attestation.
+ *
+ * Args:
+ *   verifierKey: the witness verifier secret (non-empty).
+ *   body: the unsigned receipt body.
+ *
+ * Returns:
+ *   string: 64-char lowercase hex HMAC.
+ *
+ * Throws:
+ *   TypeError: when the verifier key is empty.
+ */
+export declare function gateReceiptMac(verifierKey: string, body: GateReceiptBody): string;
+/** Typed reasons a receipt candidate failed verification (fail closed). */
+export type ReceiptRejection = 'missing' | 'malformed' | 'mac-fail' | 'input-digest-mismatch' | 'policy-digest-mismatch' | 'selection-digest-mismatch' | 'catalog-digest-mismatch' | 'execution-digest-mismatch' | 'attestation-digest-mismatch' | 'not-clean';
+/** The verification outcome: a validated receipt or a typed rejection. */
+export type ReceiptVerification = {
+    ok: true;
+    receipt: GateReceipt;
+} | {
+    ok: false;
+    rejection: ReceiptRejection;
+    detail: string;
+};
+/**
+ * Verifies a receipt candidate end-to-end (fail closed):
+ * 1. structural — the value must parse against the strict v1 schema;
+ * 2. authenticity — the HMAC must verify over the exact body (a forged
+ *    or tampered receipt is a `mac-fail`, never a downgrade);
+ * 3. binding — when an expected context is given, every supplied digest
+ *    must equal the receipt's (mismatches are typed, per-field);
+ * 4. content — the sealed verdict summary must be clean (blocking 0).
+ * Adversary-controlled input never throws.
+ *
+ * Args:
+ *   verifierKey: the witness verifier secret (non-empty).
+ *   candidate: an arbitrary value (e.g. a parsed receipt.json).
+ *   expected: optional digests the receipt must match for THIS use.
+ *
+ * Returns:
+ *   ReceiptVerification: the validated receipt or a typed rejection.
+ */
+export declare function verifyGateReceipt(verifierKey: string, candidate: unknown, expected?: {
+    inputDigest?: string;
+    trustedPolicyDigest?: string;
+    selectionDigest?: string;
+    catalogDigest?: string;
+    executionResultDigest?: string;
+    evidenceAttestationDigest?: string | null;
+}): ReceiptVerification;
+/** The expected-digest shape of {@link verifyGateReceipt} (named for docs). */
+export interface ReceiptVerificationExpectations {
+    inputDigest?: string;
+    trustedPolicyDigest?: string;
+    selectionDigest?: string;
+    catalogDigest?: string;
+    executionResultDigest?: string;
+    evidenceAttestationDigest?: string | null;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/receipt/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/receipt/index.ts"],"names":[],"mappings":"AAiBA,OAAO,EAAqB,KAAK,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAEjF,2EAA2E;AAC3E,eAAO,MAAM,cAAc,yBAAyB,CAAC;AAErD,sEAAsE;AACtE,eAAO,MAAM,eAAe,IAAI,CAAC;AAKjC,6DAA6D;AAC7D,MAAM,MAAM,eAAe,GAAG,IAAI,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC;AAEvD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,eAAe,GAAG,MAAM,CAYjF;AAED,2EAA2E;AAC3E,MAAM,MAAM,gBAAgB,GACxB,SAAS,GACT,WAAW,GACX,UAAU,GACV,uBAAuB,GACvB,wBAAwB,GACxB,2BAA2B,GAC3B,yBAAyB,GACzB,2BAA2B,GAC3B,6BAA6B,GAC7B,WAAW,CAAC;AAEhB,0EAA0E;AAC1E,MAAM,MAAM,mBAAmB,GAC3B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,WAAW,CAAA;CAAE,GAClC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,SAAS,EAAE,gBAAgB,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAE/D;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,iBAAiB,CAC/B,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,OAAO,EAClB,QAAQ,GAAE;IACR,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,yBAAyB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACtC,GACL,mBAAmB,CAuFrB;AAED,+EAA+E;AAC/E,MAAM,WAAW,+BAA+B;IAC9C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,yBAAyB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3C"}