@sanning/proof 0.4.0

package/src/compose.ts

@@ -0,0 +1,189 @@
+// 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/v1` bundle + a set of
+// operator attestation records + an exporter Ed25519 key, and PRODUCE one signed,
+// offline-verifiable `sanning.evidence.export/v1` artifact — exactly the bytes the
+// kernel's verifyExportBody round-trip-verifies.
+//
+// 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.
+
+import {
+  EXPORT_BODY_TYPE,
+  recomputeExportVerdict,
+} from "./evidence.js";
+import type {
+  AttestationRecord,
+  EvidenceBundle,
+  EvidenceStatus,
+  ExportBody,
+} from "./evidence.js";
+import {
+  base64UrlToBytes,
+  bytesToHex,
+  ed25519PublicKey,
+  ed25519Sign,
+  sha256Hex,
+  utf8,
+} from "./crypto.js";
+import { 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.
+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.
+  issuerId?: string;
+  // Named delivery surface for the wrapper (§2.1). Not trusted. Default null.
+  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.
+  previousHash?: string;
+  // RFC 3339 compose time → wrapper generated_at + verdict as_of (§2.1). Default
+  // new Date().toISOString().
+  generatedAt?: string;
+}
+
+export interface ComposeExportResult {
+  // The signed, offline-verifiable sanning.evidence.export/v1 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.
+  sourceBundleHash: string;
+  // Count of embedded attestations that fully bound (sig + operator + data_hash).
+  boundAttestations: number;
+}
+
+const GENESIS = "GENESIS";
+const EXPORT_SCHEMA = "sanning.evidence.export/v1";
+
+// 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.
+export function attestationSignatureToHex(signature: string): string {
+  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_tx_id — rides verbatim so the
+// operator's RSA-PSS signature over JCS(payload) remains valid.
+function normalizeAttestation(rec: AttestationRecord): AttestationRecord {
+  const cloned = JSON.parse(JSON.stringify(rec)) as AttestationRecord;
+  if (typeof cloned.signature !== "string") {
+    throw new Error("attestation record missing a string `signature`");
+  }
+  cloned.signature = attestationSignatureToHex(cloned.signature);
+  return cloned;
+}
+
+// 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.
+export async function composeExport(
+  sourceBundle: EvidenceBundle,
+  attestations: AttestationRecord[],
+  exporterKey: ExporterKey,
+  options: ComposeExportOptions = {},
+): Promise<ComposeExportResult> {
+  if (sourceBundle === null || typeof sourceBundle !== "object" || Array.isArray(sourceBundle)) {
+    throw new Error("composeExport: source bundle must be a JSON object");
+  }
+  if (!Array.isArray(attestations)) {
+    throw new Error("composeExport: attestations must be an array");
+  }
+  if (typeof exporterKey?.privateKey !== "string" || exporterKey.privateKey.length === 0) {
+    throw new Error("composeExport: exporterKey.privateKey (32-byte hex seed) is required");
+  }
+
+  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).
+  const sourceBundleHash = await sha256Hex(utf8(jcs(sourceBundle)));
+  const body: ExportBody = {
+    kernel_verdict: composed.verdict,
+    source_bundle: sourceBundle,
+    source_bundle_hash: sourceBundleHash,
+    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",
+    body_type: EXPORT_BODY_TYPE,
+    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,
+    signature_alg: "ed25519",
+    public_key: publicKey,
+  };
+  const signature = await ed25519Sign(utf8(jcs(wrapperPre)), exporterKey.privateKey);
+  const bundle: EvidenceBundle = { ...wrapperPre, signature };
+
+  return {
+    bundle,
+    status: composed.status,
+    sourceBundleHash,
+    boundAttestations: composed.attestations.filter((a) => a.ok).length,
+  };
+}

package/src/crypto.ts

@@ -0,0 +1,243 @@
+// 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.
+
+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.
+ed.etc.sha512Async = async (...msgs: Uint8Array[]): Promise<Uint8Array> =>
+  new Uint8Array(await crypto.subtle.digest("SHA-512", asBufferSource(ed.etc.concatBytes(...msgs))));
+
+// 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.
+function asBufferSource(bytes: Uint8Array): BufferSource {
+  return bytes as unknown as BufferSource;
+}
+
+export function bytesToHex(bytes: Uint8Array): string {
+  let out = "";
+  for (const b of bytes) out += b.toString(16).padStart(2, "0");
+  return out;
+}
+
+export function hexToBytes(hex: string): Uint8Array {
+  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.
+  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++) {
+    out[i] = Number.parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+  }
+  return out;
+}
+
+export function utf8(s: string): Uint8Array {
+  return new TextEncoder().encode(s);
+}
+
+export async function sha256Bytes(bytes: Uint8Array): Promise<Uint8Array> {
+  return new Uint8Array(await crypto.subtle.digest("SHA-256", asBufferSource(bytes)));
+}
+
+export async function sha256Hex(bytes: Uint8Array): Promise<string> {
+  return bytesToHex(await sha256Bytes(bytes));
+}
+
+// Verify an Ed25519 signature. 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.
+export async function ed25519Verify(
+  signatureHex: string,
+  message: Uint8Array,
+  publicKeyHex: string,
+): Promise<boolean> {
+  try {
+    // zip215:false → strict RFC-8032 verification, matching the Go agent's
+    // crypto/ed25519 exactly (noble defaults to the more lenient zip215:true).
+    return await ed.verifyAsync(hexToBytes(signatureHex), message, hexToBytes(publicKeyHex), {
+      zip215: false,
+    });
+  } catch {
+    return false;
+  }
+}
+
+// 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 hook wired at
+// module load serves signing and verification alike, so this stays WebCrypto-only.
+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.
+export async function ed25519PublicKey(privateKeyHex: string): Promise<string> {
+  return bytesToHex(await ed.getPublicKeyAsync(hexToBytes(privateKeyHex)));
+}
+
+// ---------------------------------------------------------------------------
+// RSA-PSS operator-attestation crypto (sanning.evidence.export/v1)
+//
+// 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 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.
+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.
+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`.
+//
+// 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).
+export async function verifyRsaPssSha256(
+  payloadBytes: Uint8Array,
+  signatureHex: string,
+  publicKey: { kty: "RSA"; n: string; e: string },
+): Promise<boolean> {
+  let signature: Uint8Array;
+  try {
+    signature = hexToBytes(signatureHex);
+  } 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.
+  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.
+  if (eBytes !== null && eBytes.length === 0) {
+    throw new Error("verifyRsaPssSha256: malformed RSA public key: empty exponent");
+  }
+  const exponent = eBytes === null ? null : bytesToBigInt(eBytes);
+  if (exponent !== null && exponent !== RSA_PUBLIC_EXPONENT) {
+    return false;
+  }
+
+  let key: CryptoKey;
+  try {
+    key = await crypto.subtle.importKey(
+      "jwk",
+      { kty: publicKey.kty, n: publicKey.n, e: publicKey.e, ext: true },
+      { name: "RSA-PSS", hash: "SHA-256" },
+      false,
+      ["verify"],
+    );
+  } catch (e) {
+    throw new Error(`verifyRsaPssSha256: malformed RSA public key: ${stringifyErr(e)}`);
+  }
+
+  try {
+    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.
+    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`.
+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).
+export function base64UrlToBytes(b64url: string): Uint8Array {
+  if (!/^[A-Za-z0-9_-]*$/.test(b64url)) {
+    throw new Error("base64url: non-base64url characters");
+  }
+  let b64 = b64url.replace(/-/g, "+").replace(/_/g, "/");
+  const rem = b64.length % 4;
+  if (rem === 1) throw new Error("base64url: invalid length");
+  if (rem === 2) b64 += "==";
+  else if (rem === 3) b64 += "=";
+  const bin = atob(b64);
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+}
+
+export function bytesToBase64Url(bytes: Uint8Array): string {
+  let bin = "";
+  for (const b of 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.
+function bytesToBigInt(bytes: Uint8Array): bigint {
+  let v = 0n;
+  for (const b of bytes) v = (v << 8n) | BigInt(b);
+  return v;
+}
+
+function stringifyErr(e: unknown): string {
+  return e instanceof Error ? e.message : String(e);
+}