attenu-guard 0.7.0 → 0.8.0

package/dist/esm/evidence.js

@@ -30,13 +30,14 @@
  * point. This is byte-compatible with the Python library's
  * `attenu_guard.evidence`.
  */
-import { canonicalBytes, compareCodePoints, parseJson, pyNumber, toPlain, } from "./canonical.js";
+import { canonicalBytes, compareCodePoints, parseJson, pyNumber, RawNumber, sortedStrings, toPlain, } from "./canonical.js";
 import { createHash } from "node:crypto";
 import { AuditLog, SCHEMA_VERSION, chainIdOf, hashEntry, GENESIS } from "./audit.js";
 import { Authority } from "./authority.js";
 import { describe as describeCeiling } from "./ceilings.js";
 import { CAPTURES, BODY_STATES, BodyState, Capture } from "./reasons.js";
 import { PARAMS_HASH_REASONS } from "./params.js";
+import { Ed25519Signer, Ed25519Verifier } from "./wire.js";
 /**
  * The COMPLETE set of top-level ledger field names the library emits. Custody
  * guarantee: an exported bundle may carry ONLY these — an unknown field is
@@ -178,8 +179,18 @@ export function anchorFor(entries, signer, ts = 0) {
  * only ever removes. With `strict`, the bundle is checked against
  * `LEDGER_FIELDS` (and `contextAllowlist` if given) and an `EvidenceLeakError`
  * is thrown on any field outside it.
+ *
+ * ORDER MATTERS with `redactTask`: redaction rewrites every entry hash, so envelopes signed
+ * over the unredacted ledger no longer bind to the entries that ship and would all fail
+ * `envelope_subject_mismatch`. Giving both throws `Error` rather than exporting a bundle that
+ * cannot verify. Export the redacted bundle first, then `signEnvelope` over ITS entries, then
+ * export again with those envelopes.
  */
 export function exportBundle(auditLog, signer, options = {}) {
+    if (options.redactTask && (options.envelopes?.length ?? 0) > 0) {
+        throw new Error("sign envelopes over the redacted ledger: export with redact_task=True first, then " +
+            "sign_envelope over the exported entries");
+    }
     const source = auditLog instanceof AuditLog ? auditLog.entries : auditLog;
     const entries = source.map((e) => ({ ...e }));
     if (options.redactTask) {
@@ -206,7 +217,7 @@ export function exportBundle(auditLog, signer, options = {}) {
     }
     const anchor = anchorFor(entries, signer, options.ts ?? 0);
     anchor.verified = AuditLog.verifyAnchor(entries, anchor, signer)[0];
-    return {
+    const bundle = {
         v: bundleVersion(entries),
         c14n: "JCS",
         chain_id: chainIdOf(entries),
@@ -215,6 +226,10 @@ export function exportBundle(auditLog, signer, options = {}) {
         redaction: report,
         note: "offline-verifiable: attenu_guard.evidence.verify_bundle(bundle, signer)",
     };
+    const envelopes = options.envelopes ?? null;
+    if (envelopes !== null && envelopes.length > 0)
+        bundle.envelopes = [...envelopes];
+    return bundle;
 }
 /**
  * A ledger field, or `null` when it is absent. Python's `dict.get` yields `None`
@@ -444,13 +459,580 @@ export function denials(bundle) {
 function pyRepr(value) {
     if (value === null)
         return "None";
+    if (typeof value === "boolean")
+        return value ? "True" : "False";
     if (typeof value === "number")
         return String(value);
     if (typeof value === "string")
         return `'${value}'`;
+    // Containers reach here only on hostile input — a subject member that is a list or an object
+    // where the contract wants a scalar. Rendered the way Python's repr renders them, because the
+    // two implementations report the same failure strings and a JSON spelling would not match.
+    if (Array.isArray(value))
+        return `[${value.map((v) => pyRepr(v)).join(", ")}]`;
+    if (typeof value === "object") {
+        const body = Object.entries(value)
+            .map(([k, v]) => `${pyRepr(k)}: ${pyRepr(v)}`)
+            .join(", ");
+        return `{${body}}`;
+    }
     return JSON.stringify(value);
 }
 // =============================================================================================
+// Observer envelopes (envelope v1) — the TypeScript half of `attenu_guard.evidence`'s.
+//
+// One question a reader of a bundle cannot answer today: was this delegation event signed by
+// something OUTSIDE the process that wrote it? An envelope is a witness's signature over the
+// IDENTITY of one committed ledger entry — never over its contents, which the entry's own hash
+// already covers. Envelopes travel beside the ledger in a top-level `envelopes` array; no entry
+// changes, so a bundle without them stays valid exactly as it is today.
+//
+// An envelope is never REQUIRED. An absent one is the status quo and changes nothing. A present
+// one has to verify: a broken envelope lands in the same failure list as the chain-level checks
+// and the bundle rejects. Byte-compatible with the Python implementation, and scored against the
+// same `envelope_vectors_v1.json`.
+// =============================================================================================
+/**
+ * The only envelope version this build knows. The version commits the exact signed member set of
+ * the WHOLE envelope, the subject included, so a member added anywhere is a new version and the
+ * digest cannot widen silently.
+ */
+export const ENVELOPE_VERSION = 1;
+/** The only `typ` at v1. A different one is a different contract, not a different envelope. */
+export const ENVELOPE_TYP = "delegation-event-observation";
+/** The envelope's own member set at v1. */
+export const ENVELOPE_MEMBERS = new Set([
+    "v",
+    "typ",
+    "subject",
+    "observed",
+    "witness",
+    "sig",
+]);
+/**
+ * The subject member set, keyed by `event`. v1 defines a subject for `spawn` and `allow` and for
+ * no other event. `entry_hash` is the BINDING member — the only evidence of WHICH entry the
+ * witness signed — and the rest are locators, whose job is to find the entry without hashing
+ * every entry.
+ */
+export const ENVELOPE_SUBJECT_MEMBERS = new Map([
+    ["spawn", new Set(["chain_id", "node", "seq", "entry_hash", "event"])],
+    ["allow", new Set(["chain_id", "node", "seq", "entry_hash", "event", "call_id"])],
+]);
+const ENVELOPE_OBSERVED_MEMBERS = new Set(["result", "at", "method"]);
+const ENVELOPE_WITNESS_MEMBERS = new Set(["kid", "alg"]);
+/**
+ * `observed.result`'s closed vocabulary. `not_matched` requires evidence that CONTRADICTS the
+ * event; `indeterminate` is the residual state, and covers thin or absent evidence. No verifier
+ * decision turns on the result: it is reported next to the state, never instead of it.
+ */
+export const ENVELOPE_RESULTS = ["matched", "not_matched", "indeterminate"];
+/** The JOSE identifier for Ed25519, and the only `witness.alg` v1 defines. */
+export const ENVELOPE_ALG = "EdDSA";
+/**
+ * A verifying envelope's state. It says where the signature came from and NOTHING about
+ * authority — the witness is whoever holds the key `witness.kid` names, which nothing in the
+ * envelope makes the delegation parent.
+ */
+export const WITNESS_SIGNED = "witness-signed";
+/**
+ * No envelope, or one that does not verify. It covers two facts a bundle does not separate — a
+ * hop nobody undertook to cover, and a hop a witness undertook to cover and never did — and v1
+ * takes the weaker reading of the two.
+ */
+export const PROCESS_ASSERTED = "process-asserted";
+/** The seven named envelope failures, in the order this build checks them. */
+export const ENVELOPE_FAILURES = [
+    "envelope_unknown_version",
+    "envelope_unknown_member",
+    "envelope_subject_mismatch",
+    "envelope_duplicate_subject",
+    "envelope_non_canonical",
+    "envelope_unknown_witness",
+    "envelope_bad_signature",
+];
+/**
+ * The bytes a witness signs: `JCS(envelope minus its "sig" member)`.
+ *
+ * The same RFC 8785 canonicalization the ledger has signed with since 0.7.0 — one
+ * implementation, not a second one for envelopes.
+ */
+export function envelopeSigningInput(envelope) {
+    const body = {};
+    for (const [k, v] of Object.entries(envelope))
+        if (k !== "sig")
+            body[k] = v;
+    return canonicalBytes(body);
+}
+/**
+ * seq -> the entry's hash RECOMPUTED from the bundle, never read off the entry.
+ *
+ * `entry_hash` in a subject is checked against this. The walk mirrors `AuditLog.verify`, so an
+ * entry whose stored `hash` was replaced does not get to supply the value it is compared against.
+ */
+function recomputedHashes(entries) {
+    const out = new Map();
+    let prev = GENESIS;
+    entries.forEach((e, i) => {
+        const payload = {};
+        for (const [k, v] of Object.entries(e))
+            if (k !== "hash")
+                payload[k] = v;
+        let computed;
+        try {
+            computed = hashEntry(prev, payload);
+        }
+        catch {
+            // An unhashable payload has no recomputable hash; that IS the break, at this entry.
+            computed = null;
+        }
+        out.set(orNull(e["seq"]) ?? i, computed);
+        prev = computed ?? GENESIS;
+    });
+    return out;
+}
+/**
+ * The v1 subject for the entry at `seq`, recomputed from the ledger.
+ *
+ * Throws when `seq` names no entry, or names one whose `event` v1 defines no subject for.
+ */
+export function envelopeSubject(entries, seq) {
+    const entry = entries.find((e) => toPlain(e["seq"]) === seq);
+    if (entry === undefined)
+        throw new Error(`no entry at seq ${seq}`);
+    const event = toPlain(entry["event"]);
+    if (!ENVELOPE_SUBJECT_MEMBERS.has(event)) {
+        throw new Error(`envelope v${ENVELOPE_VERSION} defines no subject for event '${event}'`);
+    }
+    const subject = {
+        chain_id: orNull(entry["chain_id"]),
+        node: orNull(entry["node"]),
+        seq,
+        entry_hash: recomputedHashes(entries).get(seq) ?? null,
+        event,
+    };
+    if (event === "allow")
+        subject["call_id"] = orNull(entry["call_id"]);
+    return subject;
+}
+/**
+ * An observer envelope over the entry at `seq`, signed with the 32-byte Ed25519 `seed`.
+ *
+ * `entries` is the ledger the subject is recomputed from — a witness signs the identity of an
+ * entry that already exists, never a claim it composes itself. That makes the ledger it is
+ * signed over part of the signature: sign over the entries AS THEY WILL SHIP. With
+ * `exportBundle({redactTask: true})` those are the redacted entries, so export first and sign
+ * over the exported bundle's `entries` — `exportBundle` refuses to redact and carry envelopes in
+ * one call for exactly this reason.
+ */
+export function signEnvelope(entries, seq, seed, kid, observed) {
+    const result = observed.result ?? "matched";
+    if (!ENVELOPE_RESULTS.includes(result)) {
+        throw new Error(`observed.result must be one of [${ENVELOPE_RESULTS.join(", ")}], got '${result}'`);
+    }
+    const body = {
+        v: ENVELOPE_VERSION,
+        typ: ENVELOPE_TYP,
+        subject: envelopeSubject(entries, seq),
+        observed: { result, at: observed.at, method: observed.method },
+        witness: { kid, alg: ENVELOPE_ALG },
+    };
+    const sig = Ed25519Signer.fromPrivateBytes(seed, kid).sign(envelopeSigningInput(body));
+    return { ...body, sig: sig.toString("hex") };
+}
+/**
+ * The 32-byte Ed25519 public key for `kid`, or an `Error` naming it.
+ *
+ * A trust set is CALLER CONFIGURATION, not bundle content, so a malformed row is a mistake in the
+ * deployment and failing loudly is the only way it does not become a silent downgrade: coercing a
+ * number would fabricate zero bytes, and every envelope from that witness would then fail on its
+ * SIGNATURE, reading as a witness who signed badly rather than as a trust set never configured.
+ */
+function witnessPublicKey(kid, value) {
+    if (typeof value === "string") {
+        if (value.length !== 64) {
+            throw new Error(`witness key '${kid}': public_key_hex must be 64 hex characters (a 32-byte Ed25519 key), ` +
+                `got ${value.length}`);
+        }
+        if (!/^[0-9a-fA-F]{64}$/.test(value)) {
+            throw new Error(`witness key '${kid}': public_key_hex is not hexadecimal`);
+        }
+        return Buffer.from(value, "hex");
+    }
+    if (value instanceof Uint8Array) {
+        if (value.length !== 32) {
+            throw new Error(`witness key '${kid}': an Ed25519 public key is 32 bytes, got ${value.length}`);
+        }
+        return Buffer.from(value);
+    }
+    throw new Error(`witness key '${kid}': expected 64 hex characters or 32 bytes`);
+}
+/**
+ * kid -> `[alg, raw public key]`, from the vector file's own `witness_keys` shape or from a plain
+ * `{kid: publicKeyBytes}` record.
+ *
+ * `null`/absent means no trust anchor is configured, which is an EMPTY set, not an absent check:
+ * an envelope naming a kid nobody trusts is `envelope_unknown_witness`, and that is the honest
+ * answer whether the trust set is empty or merely does not contain it.
+ *
+ * Every row is validated here and a bad one throws, naming its kid. This is the one envelope
+ * input that is NOT attacker-supplied — the deployment chose these keys — so a mistake in them is
+ * reported to the caller rather than folded into a finding about the bundle. v1 defines Ed25519
+ * and no other algorithm, so a row declaring anything else is refused too.
+ */
+function trustedWitnesses(witnessKeys) {
+    const trusted = new Map();
+    if (witnessKeys === null || witnessKeys === undefined)
+        return trusted;
+    const rows = Array.isArray(witnessKeys)
+        ? witnessKeys.map((k) => [isRecordLike(k) ? k["kid"] : undefined, k])
+        : Object.entries(witnessKeys);
+    for (const [kid, value] of rows) {
+        if (typeof kid !== "string")
+            throw new Error("witness key kid must be a string");
+        let key = value;
+        if (isRecordLike(value)) {
+            const alg = value["alg"];
+            if (alg !== ENVELOPE_ALG) {
+                throw new Error(`witness key '${kid}': alg must be '${ENVELOPE_ALG}', got ${pyRepr(alg)}`);
+            }
+            key = value["public_key_hex"];
+        }
+        trusted.set(kid, [ENVELOPE_ALG, witnessPublicKey(kid, key)]);
+    }
+    return trusted;
+}
+/** A plain object (not an array, not null, not a Buffer). */
+function isRecordLike(v) {
+    return v !== null && typeof v === "object" && !Array.isArray(v) && !(v instanceof Uint8Array);
+}
+/**
+ * One `envelopeBytes` element as bytes, or null when it is not bytes at all.
+ *
+ * Coercing a number would fabricate that many ZERO bytes, turning a caller's mistake into a
+ * canonicality finding about the bundle; hex that does not parse is the same mistake in a
+ * different shape. Neither is coerced.
+ */
+function receivedBytes(raw) {
+    if (typeof raw === "string") {
+        if (raw.length % 2 !== 0 || !/^[0-9a-fA-F]*$/.test(raw))
+            return null;
+        return Buffer.from(raw, "hex");
+    }
+    if (raw instanceof Uint8Array)
+        return Buffer.from(raw);
+    return null;
+}
+/**
+ * A subject `seq` this build will look an entry up by: a JSON integer, and never a boolean.
+ *
+ * The type check comes first and every use of `seq` is behind it — in Python an unguarded lookup
+ * raises on a list or an object and finds the entry at seq 1 for `true`, and the two
+ * implementations report the same failure for the same bundle.
+ */
+function isSeq(value) {
+    return typeof value === "number" && Number.isInteger(value);
+}
+/**
+ * The report line: the state and the result together, in the same form for all three results. A
+ * process-asserted entry gets no result.
+ */
+function envelopeLine(state, result) {
+    return state === WITNESS_SIGNED ? `${state} (${String(result)})` : state;
+}
+/**
+ * Score every envelope in the bundle and derive the per-entry state.
+ *
+ * Two rules bind where a failure may land: an envelope failure lands only on the hop that
+ * envelope covers, never on a hop coverage skipped; and no chain-level integrity failure is ever
+ * raised because an envelope failed — that one comes from a real anchor mismatch and from
+ * nothing else.
+ *
+ * One entry, at most one envelope. A second envelope naming a `subject.seq` an earlier one in
+ * this array already named is `envelope_duplicate_subject`, and the entry falls back to
+ * `process-asserted`: two observations of one event contradict each other by construction —
+ * whoever appends the second decides what the first said, and an entry whose coverage is
+ * disputed must not read as clean.
+ */
+function scoreEnvelopes(entries, envelopes, trusted, rawBytes) {
+    const fail = new FailureLog();
+    const states = {};
+    const results = {};
+    entries.forEach((e, i) => {
+        states[String(orNull(e["seq"]) ?? i)] = PROCESS_ASSERTED;
+    });
+    // The hash walk is what an envelope's binding member is checked against; a bundle carrying
+    // none does not pay for it. Every entry is process-asserted in that case, which is the status
+    // quo and exactly what this reports.
+    const bySeq = new Map();
+    let recomputed = new Map();
+    if (envelopes.length > 0) {
+        entries.forEach((e, i) => bySeq.set(orNull(e["seq"]) ?? i, e));
+        recomputed = recomputedHashes(entries);
+    }
+    // seq -> how many envelopes in this array named it, valid or not. `scoreEnvelope` counts an
+    // envelope in as soon as its subject names an entry this bundle has.
+    const claims = new Map();
+    envelopes.forEach((envelope, index) => {
+        const raw = rawBytes !== null && index < rawBytes.length ? rawBytes[index] ?? null : null;
+        const covered = scoreEnvelope(envelope, index, bySeq, recomputed, trusted, raw, fail, claims);
+        if (covered === null)
+            return;
+        states[String(covered.seq)] = WITNESS_SIGNED;
+        results[String(covered.seq)] = covered.result;
+    });
+    // The first envelope's result stands in `results` — it is what that witness said, and the
+    // duplicate does not erase it — but the STATE falls back, so a contradicted entry never
+    // reports witness-signed and the bundle rejects.
+    for (const [seq, count] of claims) {
+        if (count > 1)
+            states[seq] = PROCESS_ASSERTED;
+    }
+    const lines = {};
+    for (const [seq, state] of Object.entries(states)) {
+        lines[seq] = envelopeLine(state, results[seq] ?? null);
+    }
+    const summary = {
+        status: fail.length === 0 ? "verified" : "FAILED",
+        count: envelopes.length,
+        witness_signed: Object.entries(states)
+            .filter(([, state]) => state === WITNESS_SIGNED)
+            .map(([seq]) => Number(seq))
+            .sort((a, b) => a - b),
+        states,
+        results,
+        lines,
+        failures: [...fail.messages],
+    };
+    return [summary, fail];
+}
+/** Python `repr` for a member set, so both implementations print the same failure strings. */
+function reprList(values) {
+    return `[${values.map((v) => `'${v}'`).join(", ")}]`;
+}
+/**
+ * One envelope, checked in the order the seven named failures are defined in.
+ *
+ * Returns the covered entry for an envelope that verified, and `null` for one that did not.
+ * Every failure is positioned on the entry the envelope COVERS, found by `subject.seq` — the
+ * locators are checked against that entry, not used to find it.
+ *
+ * `claims` is the caller's seq -> count of the envelopes that have named each entry so far, and
+ * this function updates it. An envelope claims its entry as soon as `subject.seq` finds one,
+ * BEFORE the rest of the subject is checked, so a second envelope over an entry an earlier one
+ * already named is `envelope_duplicate_subject` whether either of them is otherwise sound: the
+ * point of the check is that no one can decide what an earlier witness said by appending after
+ * it.
+ */
+function scoreEnvelope(envelope, index, bySeq, recomputed, trusted, raw, fail, claims) {
+    const isRecord = (v) => v !== null && typeof v === "object" && !Array.isArray(v) && !(v instanceof RawNumber);
+    const subject = isRecord(envelope) ? envelope["subject"] : undefined;
+    function position() {
+        // Every failure is positioned by `subject.seq`, and `subject` is attacker-supplied, so the
+        // lookup is guarded: a seq that is not an integer positions nothing, which is honest — it
+        // names no entry — and it is never used as a key.
+        const s = isRecord(subject) ? toPlain(subject["seq"]) : null;
+        if (!isSeq(s))
+            return [null, null];
+        const entry = bySeq.get(s);
+        if (entry === undefined)
+            return [s, null];
+        return [orNull(entry["seq"]), orNull(entry["node"])];
+    }
+    function report(reason, detail) {
+        const [seq, node] = position();
+        fail.add(reason, `${reason}: ${detail}`, { seq, node });
+        return null;
+    }
+    if (!isRecord(envelope)) {
+        fail.add("envelope_unknown_version", `envelope_unknown_version: envelope #${index} is not a JSON object`);
+        return null;
+    }
+    // (1) version — a `v` or `typ` this build does not know is a DIFFERENT CONTRACT, and nothing
+    // further about it can be read safely.
+    const v = toPlain(envelope["v"]);
+    const typ = toPlain(envelope["typ"]);
+    if (v !== ENVELOPE_VERSION || typ !== ENVELOPE_TYP) {
+        return report("envelope_unknown_version", `envelope v=${pyRepr(v)} typ=${pyRepr(typ)}, this build knows v=${ENVELOPE_VERSION} ` +
+            `typ='${ENVELOPE_TYP}'`);
+    }
+    // (2) member sets — the version commits the exact signed member set of the whole envelope, so
+    // a member added ANYWHERE is a new version that did not declare itself.
+    const levels = [
+        ["envelope", envelope, ENVELOPE_MEMBERS],
+        ["observed", envelope["observed"], ENVELOPE_OBSERVED_MEMBERS],
+        ["witness", envelope["witness"], ENVELOPE_WITNESS_MEMBERS],
+    ];
+    for (const [label, value, expected] of levels) {
+        const members = isRecord(value) ? sortedStrings(Object.keys(value)) : null;
+        if (members === null || members.length !== expected.size || members.some((m) => !expected.has(m))) {
+            // "not an object" rather than the type's name: the two languages spell their type names
+            // differently and both implementations report the same failure strings for the same bundle.
+            const got = members === null ? "not an object" : reprList(members);
+            return report("envelope_unknown_member", `${label} member set is ${got}, expected ${reprList(sortedStrings(expected))}`);
+        }
+    }
+    // (3) subject — the event decides the member set; a member ADDED to it is unknown_member, one
+    // MISSING is subject_mismatch (a subject that does not say what it covers).
+    if (!isRecord(subject)) {
+        // No type name, for the same reason as the member-set message above: the two languages spell
+        // their type names differently and report the same strings for the same bundle.
+        return report("envelope_subject_mismatch", "subject is not a JSON object");
+    }
+    const event = toPlain(subject["event"]);
+    if (typeof event !== "string") {
+        // `event` selects the subject member set, so it is a lookup key as well; in Python an
+        // unhashable one raises. Found by the hostile-value suite, not by review.
+        return report("envelope_subject_mismatch", "subject event is not a string");
+    }
+    const expectedMembers = ENVELOPE_SUBJECT_MEMBERS.get(event);
+    if (expectedMembers === undefined) {
+        return report("envelope_subject_mismatch", `subject event=${pyRepr(event)}; envelope v${ENVELOPE_VERSION} defines a subject for ` +
+            `${reprList(sortedStrings(ENVELOPE_SUBJECT_MEMBERS.keys()))} and no other event`);
+    }
+    const present = sortedStrings(Object.keys(subject));
+    const added = present.filter((m) => !expectedMembers.has(m));
+    if (added.length > 0) {
+        return report("envelope_unknown_member", `subject member set is ${reprList(present)}, expected ` +
+            `${reprList(sortedStrings(expectedMembers))} for a ${event} subject`);
+    }
+    const missing = sortedStrings(expectedMembers).filter((m) => !(m in subject));
+    if (missing.length > 0) {
+        return report("envelope_subject_mismatch", `subject is missing ${reprList(missing)}, which a ${event} subject requires`);
+    }
+    // (3a) the binding member. `seq` is the lookup key, so there is nothing to compare it against;
+    // the entry it finds supplies the hash the subject is checked against. It is also the one
+    // subject member used as a KEY, so its type is checked before it is used as one.
+    const subjectSeq = toPlain(subject["seq"]);
+    if (!isSeq(subjectSeq)) {
+        return report("envelope_subject_mismatch", "subject seq is not an integer");
+    }
+    const entry = bySeq.get(subjectSeq);
+    if (entry === undefined) {
+        return report("envelope_subject_mismatch", `no entry at seq ${pyRepr(subjectSeq)} in this bundle`);
+    }
+    const seq = orNull(entry["seq"]);
+    // (3a') one entry, at most one envelope. Counted here, before anything else about this
+    // envelope is judged, so the rule cannot be sidestepped by making the second envelope
+    // defective in some other way as well.
+    const claimKey = String(seq);
+    const already = claims.get(claimKey) ?? 0;
+    claims.set(claimKey, already + 1);
+    if (already > 0) {
+        return report("envelope_duplicate_subject", `seq ${claimKey} is already covered by an earlier envelope in this bundle; two ` +
+            "observations of one event contradict each other by construction, so this entry is not " +
+            "witness-signed");
+    }
+    const computed = recomputed.get(seq) ?? null;
+    const claimed = toPlain(subject["entry_hash"]);
+    if (claimed !== computed) {
+        return report("envelope_subject_mismatch", `subject entry_hash ${pyRepr(claimed)} != the hash recomputed for seq ${String(seq)} from ` +
+            `this bundle (${pyRepr(computed)})`);
+    }
+    // (3b) the locators, checked against the SAME entry `seq` found. A matching locator attests
+    // nothing on its own; a disagreeing one is the same failure at the same position.
+    const locators = [
+        ["chain_id", orNull(entry["chain_id"])],
+        ["node", orNull(entry["node"])],
+        ["event", orNull(entry["event"])],
+    ];
+    if (event === "allow")
+        locators.push(["call_id", orNull(entry["call_id"])]);
+    for (const [member, actual] of locators) {
+        const stated = toPlain(subject[member]);
+        if (stated !== actual) {
+            return report("envelope_subject_mismatch", `subject ${member}=${pyRepr(stated)} != ${pyRepr(actual)} on the entry at seq ${String(seq)}`);
+        }
+    }
+    // (4) canonicality — an invariant SEPARATE from the signature: the received bytes must equal
+    // JCS of what they parse to. It can only be raised where the bytes as received are supplied,
+    // because formatting and escaping do not survive a parse.
+    let nonCanonical = false;
+    if (raw !== null) {
+        const received = receivedBytes(raw);
+        if (received === null) {
+            return report("envelope_non_canonical", "envelope_bytes entry is not hex or bytes");
+        }
+        let recanonicalized;
+        try {
+            recanonicalized = canonicalBytes(envelope);
+        }
+        catch (err) {
+            // A value JCS cannot represent at all — a non-finite number, an integer outside the
+            // binary64 safe range, a lone surrogate. There is no canonical form to compare the
+            // received bytes with and none to verify a signature over, so this is the end of it.
+            return report("envelope_non_canonical", `the envelope cannot be canonicalized: ${String(err)}`);
+        }
+        if (!recanonicalized.equals(received)) {
+            nonCanonical = true;
+            report("envelope_non_canonical", "the bytes as received are not JCS of what they parse to " +
+                `(${received.length} received, ${recanonicalized.length} canonical)`);
+        }
+    }
+    // (5) the witness key. A signature that verifies under some OTHER trusted key is not
+    // witness-signed: the kid names the key, and that is the key it has to verify under.
+    const witness = envelope["witness"];
+    const kid = toPlain(witness["kid"]);
+    const alg = toPlain(witness["alg"]);
+    if (typeof kid !== "string") {
+        // `kid` names a key, so it is a lookup key here too, and in Python an unhashable one raises.
+        return report("envelope_unknown_witness", "witness kid is not a string");
+    }
+    if (alg !== ENVELOPE_ALG) {
+        // v1 defines Ed25519 and nothing else. Without this, `"alg": "none"` on both sides — in the
+        // envelope and in a trust-set row — agreed with each other and read as witness-signed.
+        return report("envelope_unknown_witness", `witness alg=${pyRepr(alg)} is not '${ENVELOPE_ALG}'; envelope v${ENVELOPE_VERSION} ` +
+            "defines Ed25519 and no other algorithm");
+    }
+    const known = trusted.get(kid);
+    if (known === undefined) {
+        return report("envelope_unknown_witness", `witness kid=${pyRepr(kid)} alg=${pyRepr(alg)} is not in the trusted witness keys ` +
+            `(${reprList(sortedStrings(trusted.keys()))})`);
+    }
+    // (6) the signature, over JCS(envelope minus "sig").
+    const sigHex = toPlain(envelope["sig"]);
+    if (typeof sigHex !== "string") {
+        // A `sig` that is not a string is not a signature. In Python it reached `bytes.fromhex` and
+        // raised a TypeError the surrounding `except ValueError` does not catch.
+        return report("envelope_bad_signature", "sig is not a hex string");
+    }
+    const signature = /^[0-9a-fA-F]*$/.test(sigHex) && sigHex.length % 2 === 0
+        ? Buffer.from(sigHex, "hex")
+        : Buffer.alloc(0);
+    let signingInput;
+    try {
+        signingInput = envelopeSigningInput(envelope);
+    }
+    catch (err) {
+        // Reached only when no `envelopeBytes` were supplied, so step (4) did not run: the envelope
+        // holds a value JCS cannot represent and there is nothing to verify OVER.
+        return report("envelope_non_canonical", `the envelope cannot be canonicalized: ${String(err)}`);
+    }
+    let verified = false;
+    try {
+        verified = new Ed25519Verifier(known[1], kid).verify(signingInput, signature);
+    }
+    catch {
+        verified = false;
+    }
+    if (!verified) {
+        return report("envelope_bad_signature", `the signature does not verify under the key kid=${pyRepr(kid)} names`);
+    }
+    if (nonCanonical)
+        return null;
+    return { seq, node: orNull(entry["node"]), result: toPlain(envelope["observed"]["result"]) };
+}
+/**
+ * Score a bundle's observer envelopes on their own, without the ledger checks.
+ *
+ * Returns `{ok, ...summary, failure_details}`. `states` maps every entry's seq to
+ * `witness-signed` or `process-asserted`; `lines` is the report line for each.
+ */
+export function verifyEnvelopes(bundle, options = {}) {
+    const [summary, fail] = scoreEnvelopes(bundle.entries ?? [], bundle.envelopes ?? [], trustedWitnesses(options.witnessKeys ?? null), options.envelopeBytes ?? null);
+    return { ok: fail.length === 0, ...summary, failure_details: fail.details };
+}
+// =============================================================================================
 // Execution binding (0.9.0): offline checks over callId/allow/outcome, from the ledger alone —
 // docs/execution-binding spec section 5. schemaVersion=2 chains only; a v1 bundle's
 // executionBinding is `{status: "not applicable"}`.
@@ -960,6 +1542,7 @@ export function verifyBundle(bundle, signer = null, options = {}) {
         chain_id: false,
         root: false,
         expected_anchor: "not checked",
+        envelopes: "not present",
     };
     const log = new FailureLog();
     // (0) version: the bundle must declare a schema version this build understands, and — when
@@ -1114,9 +1697,21 @@ export function verifyBundle(bundle, signer = null, options = {}) {
         : [{ status: "not applicable" }, new FailureLog()];
     if (eb.failures !== undefined && eb.failures.length > 0)
         log.extend(ebFailures);
-    // "anchor" and "expected_anchor" are excluded here — both carry a tri-state status string
-    // ("not checked"/"verified"/"FAILED"), not a plain pass/fail boolean, and a failed check on
-    // either already lands its own entry in `failures`, which the `ok` computation still gates on.
+    // (4) observer envelopes. Never required — an absent envelope is the status quo and changes
+    // nothing — but a PRESENT one has to verify, and a broken one lands in this same list. The
+    // per-entry state is reported either way, so a reader sees which hops were covered before
+    // reading which one failed.
+    const [envelopeSummary, envelopeFailures] = scoreEnvelopes(entries, bundle.envelopes ?? [], trustedWitnesses(options.witnessKeys ?? null), options.envelopeBytes ?? null);
+    if (bundle.envelopes === undefined) {
+        envelopeSummary.status = "not present";
+    }
+    else {
+        checks.envelopes = envelopeSummary.status;
+        log.extend(envelopeFailures);
+    }
+    // "anchor", "expected_anchor" and "envelopes" are excluded here — each carries a status
+    // string, not a plain pass/fail boolean, and a failed check on any of them already lands its
+    // own entry in `failures`, which the `ok` computation still gates on.
     const ok = checks.integrity &&
         checks.monotonicity &&
         checks.containment &&
@@ -1133,6 +1728,7 @@ export function verifyBundle(bundle, signer = null, options = {}) {
         actions_checked: actions,
         chain_id: orNull(bundle.chain_id),
         execution_binding: eb,
+        envelopes: envelopeSummary,
         verified_against: expectedAnchor !== null || expectedHead !== null ? "expected_anchor" : "bundle_anchor",
     };
 }