@sanning/proof 0.19.1 → 0.20.0

package/dist/compose.js

@@ -1,48 +1,27 @@
-// Attested-evidence-export composer (`proof export`, evidence-export.md §5,
-// phase 2). The last-mile issuer/runtime job the kernel does NOT own (§5.1
-// "Out of the kernel"): take a source `sanning.anchor.trace/v3` bundle + a set of
-// operator attestation records + an exporter Ed25519 key, and PRODUCE one signed,
-// offline-verifiable `sanning.evidence.export/v2` artifact, exactly the bytes the
-// kernel's verifyExportBody round-trip-verifies.
+// Composes a signed, offline-verifiable `sanning.evidence.export/v2` artifact
+// from a source trace bundle, operator attestation records and an exporter
+// Ed25519 key (evidence-export.md §5).
 //
-// This is the inverse of evidence.ts's verifyExportBody, and it is deliberately
-// thin: it never reimplements the verdict recompute (it calls the kernel's own
-// recomputeExportVerdict, which reuses verifyEvidenceBundle + verifyAttestation +
-// buildVerdictObject), so the cached kernel_verdict it embeds cannot drift from
-// what the verifier recomputes (§5 step 5). Pure/offline — no network in this
-// slice; a `--sidecar <url>` attestation fetch is a documented follow-up (§5.1),
-// not built here.
-//
-// Trust boundary (P-4, "anyone can export"): the WRAPPER is Ed25519-signed by the
-// exporter's key; the embedded operator attestations keep their own RSA-PSS
-// signatures untouched (the composer never re-signs them — it is not the
-// operator). The only per-record transformation is a boundary transcode of the
-// attestation `signature` to the lowercase hex §2.2 stores; that field is OUTSIDE
-// the signed attestation payload (JCS(payload)), so re-encoding it is safe and
-// does not invalidate the operator signature.
+// The exporter signs only the wrapper. Each operator attestation keeps its own
+// RSA-PSS signature; the composer re-encodes only the `signature` field to hex,
+// which sits outside the signed payload, so the operator signature still holds.
 import { EXPORT_BODY_TYPE, recomputeExportVerdict, } from "./evidence.js";
 import { base64UrlToBytes, bytesToHex, ed25519PublicKey, ed25519Sign, sha256Hex, utf8, } from "./crypto.js";
 import { isRfc3339UtcInstant, jcs } from "./verifier.js";
 const GENESIS = "GENESIS";
 const EXPORT_SCHEMA = EXPORT_BODY_TYPE;
-// Transcode an attestation `signature` to the lowercase hex §2.2 mandates. The
-// issuer emits either lowercase-hex or unpadded base64url; §2.2 stores hex, so
-// this is the composer's boundary normalization. Heuristic mirrors the repo's
-// existing hex-vs-text discriminator (cli.ts decodeLogValue): an even-length,
-// all-hex-digit string is already hex (lowercased); anything else is decoded as
-// base64url and hex-encoded. A 256-byte RSA signature is 512 hex chars vs ~342
-// base64url chars, so the two never collide in practice. Throws on a value that
-// is neither.
+// Transcodes an attestation `signature` to the lowercase hex §2.2 stores. An
+// even-length all-hex string is already hex; anything else is decoded as
+// base64url. A 256-byte RSA signature is 512 hex chars against about 342
+// base64url chars, so the two forms do not collide. Throws on neither.
 export function attestationSignatureToHex(signature) {
     if (signature.length > 0 && signature.length % 2 === 0 && /^[0-9a-fA-F]+$/.test(signature)) {
         return signature.toLowerCase();
     }
     return bytesToHex(base64UrlToBytes(signature));
 }
-// Normalize one attestation record for embedding: deep-clone (never mutate the
-// caller's input) and transcode its signature to lowercase hex. Everything else
-// — payload, public_key, signature_alg, checkpoint_ref — rides verbatim so the
-// operator's RSA-PSS signature over JCS(payload) remains valid.
+// Deep-clones the record and transcodes its signature. Every other field rides
+// verbatim so the operator's signature over JCS(payload) stays valid.
 function normalizeAttestation(rec) {
     const cloned = JSON.parse(JSON.stringify(rec));
     if (typeof cloned.signature !== "string") {
@@ -51,8 +30,8 @@ function normalizeAttestation(rec) {
     cloned.signature = attestationSignatureToHex(cloned.signature);
     return cloned;
 }
-// True when `value` holds a number that is NaN or +-Infinity. Iterative, so a
-// deeply nested input cannot overflow the stack before `jcs` bounds it.
+// Iterative, so a deeply nested input cannot overflow the stack before `jcs`
+// bounds it.
 function hasNonFiniteNumber(value) {
     const stack = [value];
     while (stack.length > 0) {
@@ -72,18 +51,9 @@ function hasNonFiniteNumber(value) {
     }
     return false;
 }
-// Compose an attested evidence export (evidence-export.md §5).
-//
-// 1. Normalize + transcode the attestation records (boundary hex, above).
-// 2. Recompute the §4 kernel_verdict over the source bundle + attestations,
-//    reusing the kernel's own verify path (recomputeExportVerdict) so the cached
-//    copy byte-agrees with the verifier's later recompute (§5 step 5).
-// 3. Assemble the export body: kernel_verdict + inline source_bundle +
-//    source_bundle_hash = SHA-256(JCS(source_bundle)) + attestations[] + schema.
-// 4. Build the sanning.evidence/v1 wrapper (body_type export, Ed25519), strip
-//    signature, JCS, Ed25519-sign with the exporter key, attach.
-//
-// Returns the signed artifact + a small compose summary.
+// Composes an attested evidence export (evidence-export.md §5). The embedded
+// kernel_verdict comes from the verifier's own recompute path, so it cannot
+// drift from what a verifier later recomputes.
 export async function composeExport(sourceBundle, attestations, exporterKey, options = {}) {
     if (sourceBundle === null || typeof sourceBundle !== "object" || Array.isArray(sourceBundle)) {
         throw new Error("composeExport: source bundle must be a JSON object");
@@ -94,9 +64,9 @@ export async function composeExport(sourceBundle, attestations, exporterKey, opt
     if (typeof exporterKey?.privateKey !== "string" || exporterKey.privateKey.length === 0) {
         throw new Error("composeExport: exporterKey.privateKey (32-byte hex seed) is required");
     }
-    // An over-long integer reads as Infinity (proof#217), which `jcs` refuses in
-    // the runtime's own words. Say it once, in the kernel's, before any
-    // verification: both kernels write this sentence, with no function-name prefix, so the CLI line is byte-identical.
+    // An over-long integer reads as Infinity. Reject it here with a fixed
+    // sentence and no function-name prefix: the CLI error line is part of the
+    // cross-implementation contract.
     if (hasNonFiniteNumber(sourceBundle)) {
         throw new Error("the source bundle carries a number that is not a finite JSON number " +
             "(an integer past the 1.8e308 range, or too long to read)");
@@ -106,20 +76,17 @@ export async function composeExport(sourceBundle, attestations, exporterKey, opt
             "(an integer past the 1.8e308 range, or too long to read)");
     }
     if (options.generatedAt !== undefined && !isRfc3339UtcInstant(options.generatedAt)) {
-        // The verifier reads this as `malformed generated_at` (evidence-bundle §2,
-        // A31), so composing one would sign an export this kernel rejects.
+        // The verifier rejects this as `malformed generated_at` (evidence-bundle section 2),
+        // so composing it would sign an export that cannot verify.
         throw new Error("composeExport: generatedAt is not an RFC 3339 UTC date-time with Z naming a real date and time");
     }
     const generatedAt = options.generatedAt ?? new Date().toISOString();
     const previousHash = options.previousHash ?? GENESIS;
     const issuerId = options.issuerId ?? "sanning-verify";
     const gateway = options.gateway ?? null;
-    // (1) boundary-transcode the attestation signatures to hex.
     const records = attestations.map(normalizeAttestation);
-    // (2) recompute the §4 verdict via the KERNEL's own verify path (no reimpl).
     const composed = await recomputeExportVerdict(sourceBundle, records, generatedAt);
-    // (3) assemble the export body. source_bundle_hash is SHA-256(JCS(source)) —
-    // the linkage commitment the wrapper signature transitively covers (§2.4).
+    // The wrapper signature covers source_bundle_hash, and through it the source (§2.4).
     const sourceBundleHash = await sha256Hex(utf8(jcs(sourceBundle)));
     const body = {
         kernel_verdict: composed.verdict,
@@ -128,9 +95,6 @@ export async function composeExport(sourceBundle, attestations, exporterKey, opt
         attestations: records,
         export_schema: EXPORT_SCHEMA,
     };
-    // (4) build + sign the sanning.evidence/v1 wrapper. The wrapper `verdict` is the
-    // coarse family rollup DERIVED from body.kernel_verdict (display context, never
-    // trusted — the verifier recomputes). body_hash = SHA-256(JCS(body)).
     const publicKey = exporterKey.publicKey ?? (await ed25519PublicKey(exporterKey.privateKey));
     const wrapperPre = {
         spec_version: "sanning.evidence/v1",
@@ -138,12 +102,6 @@ export async function composeExport(sourceBundle, attestations, exporterKey, opt
         issuer: { kind: "issuer", issuer_id: issuerId },
         generated_at: generatedAt,
         gateway,
-        verdict: {
-            status: composed.verdict.status,
-            ...(composed.verdict.summary !== undefined ? { summary: composed.verdict.summary } : {}),
-            ...(composed.verdict.counts !== undefined ? { counts: composed.verdict.counts } : {}),
-            as_of: generatedAt,
-        },
         body,
         body_hash: await sha256Hex(utf8(jcs(body))),
         previous_hash: previousHash,

package/dist/crypto.d.ts

@@ -6,19 +6,18 @@ export declare function sha256Bytes(bytes: Uint8Array): Promise<Uint8Array>;
 export declare function sha256Hex(bytes: Uint8Array): Promise<string>;
 /** The sentence a refused signature reads in an envelope result. */
 export declare const SIGNATURE_FAILED = "Ed25519 signature verification failed";
+/** The clauses of the rule, in the order they are checked. */
 export declare const ED25519_RULE_REASONS: readonly ["the public key is not the canonical encoding of a point", "the public key is a point of small order", "the public key is not in the prime-order subgroup", "R is not the canonical encoding of a point", "R is the identity", "R is a point of small order", "R is not in the prime-order subgroup", "S is not below the group order"];
 /**
- * The clause of the rule that (`publicKey`, `signature`) breaks, or `null`
- * when it breaks none and the equation is what is left to check. Lengths are
- * the caller's (32 and 64 bytes). Never throws.
+ * The clause of the rule (`publicKey`, `signature`) breaks, or `null` if none
+ * and only the equation is left. The caller checks lengths (32 and 64 bytes).
+ * Never throws.
  */
 export declare function ed25519RuleReason(signature: Uint8Array, publicKey: Uint8Array): string | null;
 /**
- * `null` iff `signatureHex` is a signature of `message` under `publicKeyHex`
- * by the rule; otherwise the sentence the refusal reads: `SIGNATURE_FAILED`,
- * with `": "` and the clause of the rule it broke when it broke one. A
- * malformed field, a wrong length and an equation that does not hold read
- * the bare sentence. Never throws. The Python twin is `ed25519_refusal`.
+ * `null` if `signatureHex` verifies `message` under `publicKeyHex` by the rule;
+ * otherwise `SIGNATURE_FAILED`, followed by `": "` and the broken clause when
+ * one was broken. Never throws.
  */
 export declare function ed25519Refusal(message: Uint8Array, signatureHex: string, publicKeyHex: string): Promise<string | null>;
 export declare function ed25519Verify(message: Uint8Array, signatureHex: string, publicKeyHex: string): Promise<boolean>;

package/dist/crypto.js

@@ -1,17 +1,9 @@
-// Low-level cryptographic primitives for the verifier. Deliberately thin: the
-// only third-party crypto dependency is @noble/ed25519 (single-file, audited,
-// zero-dependency). SHA-256 and SHA-512 come from WebCrypto — no extra hashing
-// library to trust.
+// Cryptographic primitives for the verifier. The only third-party crypto
+// dependency is @noble/ed25519; SHA-256 and SHA-512 come from WebCrypto.
 import * as ed from "@noble/ed25519";
-// @noble/ed25519 needs SHA-512 to verify. Wire it to WebCrypto rather than
-// pulling in @noble/hashes. globalThis.crypto.subtle exists in every modern
-// browser and in Node >= 19, so the same code path runs in the app and in tests.
-// noble 3 ships this provider as its default; it is set here so the kernel
-// says what it hashes with rather than inheriting it.
+// Set explicitly so the kernel states what Ed25519 hashes with.
 ed.hashes.sha512Async = async (message) => new Uint8Array(await crypto.subtle.digest("SHA-512", asBufferSource(message)));
-// WebCrypto's digest() wants a BufferSource backed by a (non-shared) ArrayBuffer.
-// Our byte arrays always are; this keeps TS 5.7's stricter Uint8Array<ArrayBufferLike>
-// typing satisfied without a runtime copy.
+// Satisfies the typing of WebCrypto's BufferSource without a runtime copy.
 function asBufferSource(bytes) {
     return bytes;
 }
@@ -22,19 +14,13 @@ export function bytesToHex(bytes) {
     return out;
 }
 export function hexToBytes(hex) {
-    // The type says `string` and a bundle is not typed: every caller here reads
-    // a field a party wrote, so `undefined` and `null` arrive at runtime. Until
-    // gate 4 on proof#140 this line threw the HOST's `Cannot read properties of
-    // undefined (reading 'length')` where the Python kernel raises
-    // `hexToBytes: not a string`, and a finding that wraps it (`inclusion verify
-    // error: ...`) then read two ways. This kernel's own words, in the other
-    // kernel's wording, so a finding may quote them.
+    // Callers pass fields a party wrote, so a non-string arrives at runtime.
+    // Throw this message rather than the host's, so a finding quotes stable words.
     if (typeof hex !== "string")
         throw new Error("hexToBytes: not a string");
     if (hex.length % 2 !== 0)
         throw new Error("hexToBytes: odd-length string");
-    // Full validation: parseInt() partially parses ("1g" -> 1), which would let
-    // malformed hex through. A strict charset check closes that.
+    // parseInt() accepts "1g" as 1, so check the charset strictly first.
     if (!/^[0-9a-fA-F]*$/.test(hex))
         throw new Error("hexToBytes: non-hex characters");
     const out = new Uint8Array(hex.length / 2);
@@ -43,21 +29,10 @@ export function hexToBytes(hex) {
     }
     return out;
 }
-// The one hex-field test, beside the one hex reader above. The Python twin is
-// `is_hex_field` in `src/sanning_proof/hex.py`, and every site in either kernel
-// that asks whether a producer's hex is the shape a spec fixes goes through one
-// of the two.
-//
-// The test runs BEFORE any decoder sees the value, so the failure a reader is
-// handed names the field's FORM rather than whatever the decoder happened to
-// say about it: `hexToBytes: non-hex characters` on a respelled key sends an
-// auditor looking for a broken tool, and `Ed25519 signature verification
-// failed` sends them looking for a forgery. Neither is what happened.
-//
-// CASE IS A PARAMETER AND NOT THE DEFAULT. proof#135 (option B, Phil
-// 2026-09-22) pinned the hex charset and left the case open, so `lower` is
-// passed only where a value is compared against a RECOMPUTED lowercase digest
-// and no other spelling of it could ever be that digest.
+// Checks a producer's hex field for its spec'd form before any decoder sees
+// it, so a failure names the field's form instead of a misleading decode or
+// signature error. Pass `lower` only where the value is compared with a
+// recomputed lowercase digest; elsewhere the spec leaves case open.
 export function isHexField(value, nibbles, lower = false) {
     if (typeof value !== "string" || value.length !== nibbles)
         return false;
@@ -72,29 +47,18 @@ export async function sha256Bytes(bytes) {
 export async function sha256Hex(bytes) {
     return bytesToHex(await sha256Bytes(bytes));
 }
-// ---------------------------------------------------------------------------
-// The Ed25519 rule (envelope-spec §7, A44, proof#230)
-//
-// Strict RFC 8032 (`zip215: false`, a frozen invariant), and more: the public
-// key A and the signature's R must each be the canonical encoding of a point
-// in the prime-order subgroup other than the identity, and S below the group
-// order L. Only then is the equation checked.
+// The Ed25519 rule (envelope-spec §7): strict RFC 8032 (`zip215: false`), plus
+// the public key A and signature R must each canonically encode a point in the
+// prime-order subgroup other than the identity, and S must be below L.
 //
-// Why more than `zip215: false`: noble checks the equation with the cofactor,
-// 8·S·B = 8·R + 8·k·A, and Go's crypto/ed25519 and libsodium without it, so on
-// their own they disagree when A or R has a small-order component. noble 2.3
-// also could not encode an identity R and hashed nothing for k, so it accepted
-// one signature from a key holder over every message. With A and R in the
-// prime-order subgroup the two equations are the same equation, and every
-// kernel accepts exactly the same signatures.
-//
-// Each clause is checked here, in this order, and named in these words: the
-// Python twin is `ed25519_rule_reason` in `src/sanning_proof/ed25519_rule.py`
-// and the Go kernel's `verifyEd25519Strict` in sanning-io/agent `pkg/proof`.
-// Several clauses are ones noble 3 refuses on its own; they are checked here
-// anyway so the refusal names the clause, which a library's `false` cannot.
+// Why more than `zip215: false`: cofactored and cofactorless verification
+// disagree when A or R has a small-order component. With A and R in the
+// prime-order subgroup the two equations coincide, so every implementation
+// accepts exactly the same signatures. Clauses noble already refuses are still
+// checked here so the refusal names the clause.
 /** The sentence a refused signature reads in an envelope result. */
 export const SIGNATURE_FAILED = "Ed25519 signature verification failed";
+/** The clauses of the rule, in the order they are checked. */
 export const ED25519_RULE_REASONS = [
     "the public key is not the canonical encoding of a point",
     "the public key is a point of small order",
@@ -113,9 +77,8 @@ function bytesToNumberLE(bytes) {
         v = (v << 8n) | BigInt(bytes[i]);
     return v;
 }
-// `Point.fromBytes(..., false)` is RFC 8032 decoding with its two strict
-// branches: it throws on y at or above p and on x zero with the sign bit set,
-// the two non-canonical encodings of a point, and on bytes that are no point.
+// RFC 8032 strict decoding: rejects y >= p, x = 0 with the sign bit set, and
+// bytes that are no point.
 function decodeStrict(bytes) {
     try {
         return ed.Point.fromBytes(bytes, false);
@@ -125,9 +88,9 @@ function decodeStrict(bytes) {
     }
 }
 /**
- * The clause of the rule that (`publicKey`, `signature`) breaks, or `null`
- * when it breaks none and the equation is what is left to check. Lengths are
- * the caller's (32 and 64 bytes). Never throws.
+ * The clause of the rule (`publicKey`, `signature`) breaks, or `null` if none
+ * and only the equation is left. The caller checks lengths (32 and 64 bytes).
+ * Never throws.
  */
 export function ed25519RuleReason(signature, publicKey) {
     const A = decodeStrict(publicKey);
@@ -151,11 +114,9 @@ export function ed25519RuleReason(signature, publicKey) {
     return null;
 }
 /**
- * `null` iff `signatureHex` is a signature of `message` under `publicKeyHex`
- * by the rule; otherwise the sentence the refusal reads: `SIGNATURE_FAILED`,
- * with `": "` and the clause of the rule it broke when it broke one. A
- * malformed field, a wrong length and an equation that does not hold read
- * the bare sentence. Never throws. The Python twin is `ed25519_refusal`.
+ * `null` if `signatureHex` verifies `message` under `publicKeyHex` by the rule;
+ * otherwise `SIGNATURE_FAILED`, followed by `": "` and the broken clause when
+ * one was broken. Never throws.
  */
 export async function ed25519Refusal(message, signatureHex, publicKeyHex) {
     let signature;
@@ -179,67 +140,38 @@ export async function ed25519Refusal(message, signatureHex, publicKeyHex) {
         return SIGNATURE_FAILED;
     }
 }
-// Verify an Ed25519 signature by the rule above. Inputs are hex (signature,
-// public key) as they appear in the envelope; message is raw bytes. Never
-// throws — a malformed signature or key is "not verified," not an exception,
-// so a hostile envelope can't crash the checker.
-// Arguments in the Python twin's order, `ed25519_verify(message,
-// signature_hex, public_key_hex)` (P-03, 0.13.0). The message came second
-// until 0.13.0; a caller that still passes the signature first gets a compile
-// error, because a string is not a Uint8Array.
+// Verifies an Ed25519 signature by the rule above. Never throws: a malformed
+// signature or key is "not verified", so a hostile envelope cannot crash the
+// checker.
 export async function ed25519Verify(message, signatureHex, publicKeyHex) {
     return (await ed25519Refusal(message, signatureHex, publicKeyHex)) === null;
 }
-// Ed25519 SIGN the raw `message` bytes with a 32-byte private-key seed (lowercase
-// hex). Returns the signature as lowercase hex. The signing counterpart to
-// ed25519Verify — the ONE signing primitive the composer (`proof export`,
-// evidence-export.md §5) needs to Ed25519-sign the export wrapper with the
-// exporter's key ("anyone can export", P-4). The @noble sha512Async provider wired at
-// module load serves signing and verification alike, so this stays WebCrypto-only.
+// Signs `message` with a 32-byte seed (hex) and returns the signature as hex.
+// Used to sign the export wrapper (evidence-export.md §5).
 export async function ed25519Sign(message, privateKeyHex) {
     return bytesToHex(await ed.signAsync(message, hexToBytes(privateKeyHex)));
 }
-// Derive the Ed25519 public key (lowercase hex) from a 32-byte private-key seed
-// (lowercase hex) — the wrapper's embedded `public_key` when composing an export.
+// The Ed25519 public key (hex) for a 32-byte seed (hex).
 export async function ed25519PublicKey(privateKeyHex) {
     return bytesToHex(await ed.getPublicKeyAsync(hexToBytes(privateKeyHex)));
 }
-// ---------------------------------------------------------------------------
-// RSA-PSS operator-attestation crypto (sanning.evidence.export/v2)
-//
-// The attested-evidence-export body embeds operator attestations signed with
-// RSA-PSS-SHA-256 over the JCS-canonical attestation payload; the operator key
-// is the operator's Arweave RSA wallet. These two pure functions are the only
-// new primitive that body needs and the only RSA in the kernel: verify one
-// attestation signature, and derive the operator's Arweave address from the
-// embedded modulus (the self-describing key→wallet binding).
+// RSA-PSS verification for operator attestations (sanning.evidence.export/v2),
+// signed over JCS(payload) with the operator's Arweave RSA wallet.
 //
-// RSA-PSS parameters are PINNED for cross-kernel byte-agreement between the
-// issuer, the TS kernel, and the Python kernel: hash = SHA-256; MGF1 with
-// SHA-256; salt length = 32 (the SHA-256 digest length, i.e. OpenSSL's
-// RSA_PSS_SALTLEN_DIGEST); padding = PSS. saltLength=32 is load-bearing — the
-// shipped issuer's former RSA_PSS_SALTLEN_AUTO (which resolves to the maximum,
-// key-size-dependent salt on signing) is NOT verifiable by WebCrypto, which
-// does not auto-detect salt on verify. The pin is what makes these round-trip.
+// Parameters are pinned: SHA-256, MGF1-SHA-256, salt length 32 (the digest
+// length). WebCrypto does not auto-detect salt on verify, so a signature made
+// with a maximum-length salt would not verify.
 const RSA_PSS_SALT_LENGTH = 32;
-// The ONLY RSA public exponent a legitimate operator (Arweave wallet) key uses.
-// The operator-address binding SHA-256(n) commits to the modulus ALONE and
-// assumes this exponent; a verifier MUST reject any other. Without it, e=1 makes
-// RSA verification the identity (s^1 mod n = s), letting an attacker forge a
-// valid-looking attestation from a victim operator's PUBLIC modulus with NO
-// private key. See the exponent guard in verifyRsaPssSha256.
+// The only exponent an Arweave wallet key uses. The operator address commits to
+// the modulus alone, so any other exponent must be rejected: with e=1, RSA
+// verification is the identity and anyone could forge an attestation from a
+// victim's public modulus.
 const RSA_PUBLIC_EXPONENT = 65537n;
-// Verify an RSA-PSS-SHA-256 signature over `payloadBytes` (the raw JCS bytes of
-// the attestation payload) with the JWK RSA public key `{kty:"RSA", n, e}`
-// (`n`/`e` base64url) and a lowercase-hex `signatureHex`.
+// Verifies an RSA-PSS-SHA-256 signature over `payloadBytes` with a JWK RSA key
+// (`n`, `e` base64url) and a hex signature.
 //
-// Malformed-vs-failed follows the kernel's split: a malformed key (JWK that
-// won't import) or malformed signature hex is a caller/input error and THROWS a
-// prefixed Error — the same "malformed" signal hexToBytes raises and the CLI
-// buckets as exit-2. A well-formed key + signature that simply does not verify
-// (wrong signer, tampered payload, wrong salt length) returns `false` and never
-// throws, so a hostile attestation can't crash the checker (same contract as
-// ed25519Verify above).
+// A malformed key or signature hex throws (exit 2 at the CLI). A well-formed
+// signature that does not verify returns `false` and never throws.
 export async function verifyRsaPssSha256(payloadBytes, signatureHex, publicKey) {
     let signature;
     try {
@@ -248,14 +180,9 @@ export async function verifyRsaPssSha256(payloadBytes, signatureHex, publicKey)
     catch (e) {
         throw new Error(`verifyRsaPssSha256: malformed signature hex: ${stringifyErr(e)}`);
     }
-    // Enforce the RSA public exponent (see RSA_PUBLIC_EXPONENT). A structurally
-    // valid key with a non-65537 exponent is not a legitimate operator key, so
-    // its signature does not validly verify — return false (a FAILED attestation,
-    // exit 1), never accept it. A malformed `e` falls through to importKey below,
-    // which throws the malformed-key error (exit 2). This is the guard that closes
-    // the e=1 identity-forgery: e=1 imports fine in WebCrypto and would otherwise
-    // "verify" an attacker-built PSS encoded message with no private key.
-    // Decode `e`. A non-base64url `e` is malformed — importKey raises it below.
+    // A non-65537 exponent is not an operator key, so it fails (exit 1). This
+    // closes the e=1 forgery, which WebCrypto would otherwise import and
+    // "verify". A non-base64url `e` falls through to importKey, which throws.
     let eBytes = null;
     try {
         eBytes = base64UrlToBytes(publicKey.e);
@@ -263,9 +190,8 @@ export async function verifyRsaPssSha256(payloadBytes, signatureHex, publicKey)
     catch {
         eBytes = null;
     }
-    // An empty `e` is malformed too: WebCrypto imports it as e=0 (which would
-    // return false), while the Python kernel's key import raises. Throw here so
-    // an empty exponent is malformed/exit-2 in BOTH kernels, not a divergence.
+    // WebCrypto imports an empty `e` as 0 and returns false; treat it as a
+    // malformed key instead, so the exit code is the same in every implementation.
     if (eBytes !== null && eBytes.length === 0) {
         throw new Error("verifyRsaPssSha256: malformed RSA public key: empty exponent");
     }
@@ -284,32 +210,21 @@ export async function verifyRsaPssSha256(payloadBytes, signatureHex, publicKey)
         return await crypto.subtle.verify({ name: "RSA-PSS", saltLength: RSA_PSS_SALT_LENGTH }, key, asBufferSource(signature), asBufferSource(payloadBytes));
     }
     catch {
-        // Some engines throw (rather than return false) on a wrong-length RSA
-        // signature. That is still just "not verified," not a malformed-input
-        // condition — the signature parsed as hex fine; it's the wrong signature.
+        // Some engines throw on a wrong-length signature. The hex parsed, so this
+        // is a failed signature, not malformed input.
         return false;
     }
 }
-// Derive an operator's Arweave wallet address from the base64url JWK modulus
-// `n`: address = base64url(SHA-256(rawModulusBytes)), where rawModulusBytes is
-// the decoded base64url `n`. This is the same owner→address derivation
-// arweave-js uses (SHA-256 over the modulus octets, base64url without padding),
-// so it binds an embedded RSA key to a specific wallet with no roster lookup.
-//
-// Async because the kernel takes SHA-256 from WebCrypto (crypto.subtle.digest),
-// which is Promise-based — the module is deliberately WebCrypto-only with no
-// second hashing library and no node:crypto, so it stays browser-portable.
-// Throws a prefixed Error on a malformed (non-base64url) `n`.
+// The operator's Arweave address from the JWK modulus `n`:
+// base64url(SHA-256(n bytes)), as arweave-js derives it. Binds an embedded RSA
+// key to a wallet with no roster lookup. Throws on a non-base64url `n`.
 export async function deriveOperatorAddress(nBase64url) {
     const modulus = base64UrlToBytes(nBase64url);
     const digest = await sha256Bytes(modulus);
     return bytesToBase64Url(digest);
 }
-// base64url (RFC 4648 §5, unpadded) codecs. Kept WebCrypto/browser-portable —
-// atob/btoa exist in browsers and in Node >= 16 — so the kernel stays free of
-// node:Buffer. Arweave and JWK both use unpadded base64url. Exported because the
-// composer transcodes an issuer-emitted base64url attestation signature to the
-// lowercase hex §2.2 stores (evidence-export.md §2.2 — the composer's boundary job).
+// Unpadded base64url (RFC 4648 §5) via atob/btoa, so the kernel needs no
+// node:Buffer.
 export function base64UrlToBytes(b64url) {
     if (!/^[A-Za-z0-9_-]*$/.test(b64url)) {
         throw new Error("base64url: non-base64url characters");
@@ -334,9 +249,7 @@ export function bytesToBase64Url(bytes) {
         bin += String.fromCharCode(b);
     return btoa(bin).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
 }
-// Big-endian unsigned integer from bytes — used only for the RSA public-exponent
-// guard, so alternate encodings of 65537 (e.g. with leading zero octets) still
-// compare equal.
+// Big-endian, so leading zero octets in `e` still compare equal to 65537.
 function bytesToBigInt(bytes) {
     let v = 0n;
     for (const b of bytes)