@sanning/proof 0.19.1 → 0.20.0

package/src/compose.ts

@@ -1,25 +1,10 @@
-// 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,
@@ -41,50 +26,42 @@ import {
 } from "./crypto.js";
 import { isRfc3339UtcInstant, jcs } from "./verifier.js";
 
-// The exporter's Ed25519 wrapper-signing key. `privateKey` is a 32-byte seed as
-// lowercase hex (the @noble/ed25519 / stack convention, e.g. the fixtures'
-// SEED_HEX). `publicKey` is derived from it when omitted.
+// The exporter's wrapper-signing key: `privateKey` is a 32-byte Ed25519 seed as
+// lowercase hex. `publicKey` is derived when omitted.
 export interface ExporterKey {
   privateKey: string;
   publicKey?: string;
 }
 
 export interface ComposeExportOptions {
-  // The composing issuer's instance id → wrapper issuer.issuer_id (§2.1).
-  // Identity CONTEXT only; the load-bearing key is the wrapper public_key.
+  // Wrapper issuer.issuer_id (§2.1). Identity context only; the wrapper
+  // public_key is what binds.
   issuerId?: string;
-  // Named delivery surface for the wrapper (§2.1). Not trusted. Default null.
+  // Delivery surface for the wrapper (§2.1). Not trusted.
   gateway?: string | null;
-  // Wrapper custody pointer (§2.3): GENESIS for a one-off export (default), or
-  // SHA-256(JCS(prior wrapper without signature)) for a re-issued chain link.
+  // Wrapper previous_hash (§2.3): GENESIS for a one-off export, or
+  // SHA-256(JCS(prior wrapper without signature)) for a chain link.
   previousHash?: string;
-  // RFC 3339 compose time → wrapper generated_at + verdict as_of (§2.1). Default
-  // new Date().toISOString().
+  // RFC 3339 compose time, used for generated_at and verdict as_of.
   generatedAt?: string;
 }
 
 export interface ComposeExportResult {
-  // The signed, offline-verifiable sanning.evidence.export/v2 artifact.
   bundle: EvidenceBundle;
-  // The export rollup the embedded kernel_verdict carries (verified|partial|failed).
   status: EvidenceStatus;
-  // SHA-256(JCS(source_bundle)) linkage commitment (§2.2), for logging.
+  // SHA-256(JCS(source_bundle)) (§2.2).
   sourceBundleHash: string;
-  // Count of embedded attestations that fully bound (sig + operator + data_hash).
+  // Embedded attestations that fully bound (signature, operator and data_hash).
   boundAttestations: number;
 }
 
 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: string): string {
   if (signature.length > 0 && signature.length % 2 === 0 && /^[0-9a-fA-F]+$/.test(signature)) {
     return signature.toLowerCase();
@@ -92,10 +69,8 @@ export function attestationSignatureToHex(signature: string): string {
   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: AttestationRecord): AttestationRecord {
   const cloned = JSON.parse(JSON.stringify(rec)) as AttestationRecord;
   if (typeof cloned.signature !== "string") {
@@ -105,8 +80,8 @@ function normalizeAttestation(rec: AttestationRecord): AttestationRecord {
   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: unknown): boolean {
   const stack: unknown[] = [value];
   while (stack.length > 0) {
@@ -122,18 +97,9 @@ function hasNonFiniteNumber(value: unknown): boolean {
   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: EvidenceBundle,
   attestations: AttestationRecord[],
@@ -150,9 +116,9 @@ export async function composeExport(
     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 " +
@@ -167,8 +133,8 @@ export async function composeExport(
   }
 
   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",
     );
@@ -178,14 +144,11 @@ export async function composeExport(
   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: ExportBody = {
     kernel_verdict: composed.verdict,
@@ -195,9 +158,6 @@ export async function composeExport(
     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",
@@ -205,12 +165,6 @@ export async function composeExport(
     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/src/crypto.ts

@@ -1,21 +1,13 @@
-// 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: Uint8Array): BufferSource {
   return bytes as unknown as BufferSource;
 }
@@ -27,17 +19,11 @@ export function bytesToHex(bytes: Uint8Array): string {
 }
 
 export function hexToBytes(hex: string): Uint8Array {
-  // 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);
   for (let i = 0; i < out.length; i++) {
@@ -46,21 +32,10 @@ export function hexToBytes(hex: string): Uint8Array {
   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: unknown, nibbles: number, lower = false): value is string {
   if (typeof value !== "string" || value.length !== nibbles) return false;
   return (lower ? /^[0-9a-f]*$/ : /^[0-9a-fA-F]*$/).test(value);
@@ -78,31 +53,20 @@ export async function sha256Hex(bytes: Uint8Array): Promise<string> {
   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",
@@ -133,9 +97,8 @@ function bytesToNumberLE(bytes: Uint8Array): bigint {
   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: Uint8Array): ed.Point | null {
   try {
     return ed.Point.fromBytes(bytes, false);
@@ -145,9 +108,9 @@ function decodeStrict(bytes: Uint8Array): ed.Point | null {
 }
 
 /**
- * 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: Uint8Array, publicKey: Uint8Array): string | null {
   const A = decodeStrict(publicKey);
@@ -164,11 +127,9 @@ export function ed25519RuleReason(signature: Uint8Array, publicKey: Uint8Array):
 }
 
 /**
- * `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: Uint8Array,
@@ -193,14 +154,9 @@ export async function ed25519Refusal(
   }
 }
 
-// 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: Uint8Array,
   signatureHex: string,
@@ -209,60 +165,36 @@ export async function ed25519Verify(
   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: Uint8Array, privateKeyHex: string): Promise<string> {
   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: string): Promise<string> {
   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: Uint8Array,
   signatureHex: string,
@@ -275,23 +207,17 @@ export async function verifyRsaPssSha256(
     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: Uint8Array | null = null;
   try {
     eBytes = base64UrlToBytes(publicKey.e);
   } 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");
   }
@@ -321,34 +247,23 @@ export async function verifyRsaPssSha256(
       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: string): Promise<string> {
   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: string): Uint8Array {
   if (!/^[A-Za-z0-9_-]*$/.test(b64url)) {
     throw new Error("base64url: non-base64url characters");
@@ -370,9 +285,7 @@ export function bytesToBase64Url(bytes: Uint8Array): string {
   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: Uint8Array): bigint {
   let v = 0n;
   for (const b of bytes) v = (v << 8n) | BigInt(b);