@agentcontextdistributionprotocol/acdp-wasm 0.7.0

package/README.md

@@ -0,0 +1,161 @@
+# acdp-wasm — ACDP WebAssembly verification core
+
+The **browser / edge / WASI** member of the ACDP binding family
+(`bindings/acdp-py`, `bindings/acdp-node`). A pure, **offline**
+cryptographic verifier: it lets a consumer render an ACDP context and
+independently reach a real verification **verdict** — the producer
+signature, the `content_hash`, a registry receipt (RFC-ACDP-0010), a
+lineage-head receipt (RFC-ACDP-0011), a transparency-log checkpoint /
+inclusion / consistency proof (RFC-ACDP-0012), a lifecycle event
+(RFC-ACDP-0013), a key revocation (RFC-ACDP-0014), and witness
+cosignatures + quorum (RFC-ACDP-0015) — **without trusting any server to
+have done it**. This is the client-side verification core the console's
+verdicts consume.
+
+It is a standalone Cargo package (its own `[workspace]`) that depends on
+the umbrella `acdp` crate with `default-features = false`, so
+`reqwest` / `tokio` / `rustls` never enter the `.wasm` binary. See
+`docs/research/wasm-target.md` for the design rationale.
+
+## Design (same rules as the Python / Node bindings)
+
+- **JSON across the boundary.** Every export takes JSON strings and
+  returns a JSON string — a **verdict object** (`{"valid": true, ...}` /
+  `{"valid": false, "code"?, "error"}`) for verification outcomes, or a
+  result string for constructors/resolvers. Malformed *host* input
+  throws a `JsError`; a failed *verification* is `{"valid": false}`,
+  never a throw.
+- **Crypto in Rust, HTTP in the host.** No network calls. `did:web`
+  resolution and all transport stay in JS (`fetch` the DID document /
+  receipt / body, pass the JSON in). `did:key` verification is fully
+  offline and needs no host help — the highest-value browser path.
+- **No crypto reimplemented.** Every check delegates to the same `acdp`
+  core the native library, Python, and Node bindings use. The 0.3/0.4
+  verdict logic (`src/v030.rs`, `src/v040.rs`) is lifted **verbatim,
+  byte-identical** from the other bindings.
+
+## Exported surface
+
+wasm-bindgen exports (camelCase in JS/TypeScript):
+
+| Export | RFC | Purpose |
+|---|---|---|
+| `verifyContentHash` | 0001 §5.7 | recompute `sha256(JCS(producer_content))` |
+| `verifySignatureEd25519` / `verifySignatureP256` | 0001 §5.8 | signature over the ASCII `"sha256:<hex>"` string |
+| `verifyBodyOffline` / `verifyPublishRequestOffline` | 0002 | full `did:key` context verify (no resolution) |
+| `fingerprintEd25519` / `verifyReceipt` | 0010 | registry-receipt verification |
+| `verifyLineageHeadReceipt` | 0011 | lineage-head receipt |
+| `verifyLogCheckpoint` / `verifyLogInclusion` / `verifyLogConsistency` / `buildLogLeaf` / `merkleLeafHash` / `merkleNodeHash` / `merkleRootHash` | 0012 | transparency log |
+| `verifyLifecycleEvent` | 0013 | lifecycle event |
+| `parseKeyRevocation` / `classifyUnderRevocation` | 0014 | key revocation |
+| `buildWitnessCosignature` / `verifyWitnessCosignature` / `evaluateWitnessQuorum` | 0015 | witness cosignatures + quorum |
+| `resolveDidKey` | — | offline `did:key` → public key |
+| `canonicalPreimage` / `explainHashMismatch` | — | hash-divergence diagnostics |
+
+## Install
+
+Published to npm as **`@agentcontextdistributionprotocol/acdp-wasm`** (a
+public scoped package, provenance-signed on GitHub Actions), so the console
+and other consumers depend on it without a sibling checkout:
+
+```bash
+npm install @agentcontextdistributionprotocol/acdp-wasm
+```
+
+```js
+import init, { verifyContentHash, verifySignatureEd25519 }
+  from "@agentcontextdistributionprotocol/acdp-wasm";
+await init();
+const verdict = JSON.parse(verifyContentHash(bodyJson, body.content_hash));
+if (verdict.valid) { /* the hash the consumer recomputed itself checks out */ }
+```
+
+The package is built with `wasm-pack --target web`: an ESM module you
+initialize once with `await init()`. This is the target the crate is
+designed and CI-tested around, and it loads cleanly in browsers and in
+Next.js client components (webpack 5 resolves the `new URL(..., import.meta.url)`
+wasm asset the `web` target emits — no `experiments.asyncWebAssembly`
+webpack override, which the `bundler` target would require).
+
+## Build
+
+```bash
+rustup target add wasm32-unknown-unknown
+
+# Raw wasm (regression build-check):
+cargo build --target wasm32-unknown-unknown            # verify-only default
+
+# Browser package (.js / .wasm / .d.ts) with wasm-pack. `--scope` makes
+# wasm-pack emit the package name `@agentcontextdistributionprotocol/acdp-wasm`
+# (the same rename the release workflow performs):
+wasm-pack build --target web --out-dir pkg --scope agentcontextdistributionprotocol
+```
+
+Import from a browser (local, unpublished build):
+
+```js
+import init, { verifyContentHash, verifySignatureEd25519 } from "./pkg/acdp_wasm.js";
+await init();
+const verdict = JSON.parse(verifyContentHash(bodyJson, body.content_hash));
+if (verdict.valid) { /* the hash the consumer recomputed itself checks out */ }
+```
+
+## Golden-vector parity
+
+`tests/golden.rs` is a **native** `cargo test` that runs the canonical
+`sig-001` (content hash + Ed25519 signature) and `wit-001` (witness
+cosignature mint + verify) spec fixtures through the same pure `core`
+functions the wasm exports wrap, asserting byte-for-byte reproduction of
+the pinned golden values — the same constants the `acdp-py` / `acdp-node`
+suites pin. It locates fixtures via `ACDP_SPEC_DIR` and skips gracefully
+when absent:
+
+```bash
+ACDP_SPEC_DIR=../../../agentcontextdistributionprotocol cargo test
+```
+
+`tests/wasm.rs` is a `wasm-bindgen-test` real-engine smoke test of the
+exported wrappers (inline sig-001 constants, no fixtures needed):
+
+```bash
+wasm-pack test --node
+```
+
+## Randomness — a correction to the research memo
+
+`docs/research/wasm-target.md` §4 predicted a **verify-only** build would
+need **no `getrandom` backend** on any wasm target. That holds at
+*runtime* — no exported verification (nor the deterministic Ed25519
+witness mint) draws randomness. It does **not** hold at *compile time*
+for `wasm32-unknown-unknown`: the core crates pull two randomness sources
+**unconditionally**, and each emits a hard `compile_error!` on that
+target unless a backend is wired:
+
+1. **`getrandom 0.2`** via `rand_core 0.6` / `OsRng` (a non-optional
+   dependency of `acdp-crypto`) → enabled with the getrandom **`js`
+   feature**.
+2. **`getrandom 0.4`** via **`uuid` v4** (a non-optional dependency of
+   `acdp-primitives`) → enabled with the getrandom **`wasm_js` feature**
+   *plus* `--cfg getrandom_backend="wasm_js"` (set in
+   `.cargo/config.toml`). `uuid` additionally needs its own **`js`
+   feature** for its v4 RNG shim.
+
+All three are wired here, **target-gated to `wasm32` only** (see
+`Cargo.toml` and `.cargo/config.toml`), so a native `cargo test` is
+untouched. `crypto.getRandomValues` (the `js` backend) is the CSPRNG
+RFC-ACDP-0001 §5.10 names for the browser, so the choice is spec-blessed
+— but it is never invoked on the verify path; it is present only to link.
+
+A future `producer` feature (reserved, not yet wired) would expose fresh
+key generation (`SigningKey::generate`, the only `OsRng` caller) and is
+where a runtime randomness draw would actually occur.
+
+## Security notes
+
+- This artifact is a **verifier, not a fetcher**. `RegistryClient`,
+  `CrossRegistryResolver`, and `did:web` resolution do NOT move to wasm;
+  the host owns HTTP and the RFC-ACDP-0006 §7 / RFC-ACDP-0008 SSRF
+  defenses. Pass fetched documents in as JSON.
+- A browser tab is not an HSM. Verification holds no secrets, but a
+  future `producer`/keygen surface would place the signing seed in wasm
+  linear memory during a call (RFC-ACDP-0001 §5.10).

package/acdp_wasm.d.ts

@@ -0,0 +1,191 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/**
+ * Build the canonical §4 log leaf from a VERIFIED receipt (§9.1 step 1).
+ */
+export function buildLogLeaf(receipt_json: string): string;
+
+/**
+ * Mint a signed witness cosignature (RFC-ACDP-0015 §5). Deterministic.
+ */
+export function buildWitnessCosignature(witnessed_checkpoint_json: string, witness_did: string, witness_seed_hex: string, witnessed_at_rfc3339: string): string;
+
+/**
+ * The exact JCS canonical preimage hashed for `content_hash`.
+ */
+export function canonicalPreimage(body_json: string): string;
+
+/**
+ * Apply the RFC-ACDP-0014 §7 compromise-boundary rule (fail-closed).
+ */
+export function classifyUnderRevocation(revocations_json: string, signer_fingerprint: string, receipt_created_at_rfc3339?: string | null): string;
+
+/**
+ * Compute the RFC-ACDP-0015 §8 N-witnessed quorum report. Returns a
+ * report JSON.
+ */
+export function evaluateWitnessQuorum(cosignatures_json: string, expected_checkpoint_json: string, trusted_witness_dids_json: string, witness_did_docs_json: string, policy_json: string, now_rfc3339?: string | null): string;
+
+/**
+ * Diagnose a `content_hash` mismatch (human-readable, never a verdict).
+ */
+export function explainHashMismatch(body_json: string, expected_hash: string): string;
+
+/**
+ * `"sha256:" + hex(SHA-256(raw 32-byte key))`.
+ */
+export function fingerprintEd25519(public_key_b64: string): string;
+
+/**
+ * §5.1 leaf hash `SHA-256(0x00 ‖ JCS(leaf))`.
+ */
+export function merkleLeafHash(leaf_json: string): string;
+
+/**
+ * §5.1 interior-node hash `SHA-256(0x01 ‖ left ‖ right)`.
+ */
+export function merkleNodeHash(left_hash: string, right_hash: string): string;
+
+/**
+ * §5.2 RFC 6962 Merkle tree hash over an ordered array of leaf hashes.
+ */
+export function merkleRootHash(leaf_hashes_json: string): string;
+
+/**
+ * Parse + shape-validate a `key-revocation` body (RFC-ACDP-0014 §4).
+ */
+export function parseKeyRevocation(body_json: string, signer_fingerprint?: string | null): string;
+
+/**
+ * Resolve a `did:key:z…` DID to its public key material — offline.
+ */
+export function resolveDidKey(did: string): string;
+
+/**
+ * Fully verify a `did:key` body offline (ACDP 0.2). Returns a verdict.
+ */
+export function verifyBodyOffline(body_json: string): string;
+
+/**
+ * Recompute `content_hash` over the body and compare to `expectedHash`.
+ * Returns a verdict JSON string. Throws on malformed input.
+ */
+export function verifyContentHash(body_json: string, expected_hash: string): string;
+
+/**
+ * Verify one lifecycle event offline (RFC-ACDP-0013 §5).
+ * `actorDidDocJson` is `null`/`undefined` for a `did:key` actor.
+ */
+export function verifyLifecycleEvent(event_json: string, actor_did_doc_json: string | null | undefined, expected_ctx_id: string): string;
+
+/**
+ * Verify a lineage-head receipt offline (RFC-ACDP-0011 §7). Returns a
+ * verdict.
+ */
+export function verifyLineageHeadReceipt(receipt_json: string, expected_json: string, registry_did_doc_json: string, now_rfc3339?: string | null, max_skew_secs?: bigint | null, max_age_secs?: bigint | null): string;
+
+/**
+ * Verify a transparency-log checkpoint offline (RFC-ACDP-0012 §9.3).
+ */
+export function verifyLogCheckpoint(checkpoint_json: string, registry_did_doc_json: string, expected_log_id?: string | null, now_rfc3339?: string | null, max_skew_secs?: bigint | null): string;
+
+/**
+ * Verify a transparency-log consistency proof offline (RFC-ACDP-0012
+ * §9.2).
+ */
+export function verifyLogConsistency(consistency_json: string, checkpoint_json: string, first_root_hash: string): string;
+
+/**
+ * Verify a transparency-log inclusion proof offline (RFC-ACDP-0012
+ * §9.1).
+ */
+export function verifyLogInclusion(inclusion_json: string, checkpoint_json: string, reconstructed_leaf_json: string): string;
+
+/**
+ * Fully verify a `did:key` PublishRequest offline (ACDP 0.2). Returns a
+ * verdict.
+ */
+export function verifyPublishRequestOffline(request_json: string): string;
+
+/**
+ * Verify a registry receipt (RFC-ACDP-0010) against the consumer's own
+ * recomputed body hash / expected ctx_id / producer key fingerprint.
+ * Returns a verdict.
+ */
+export function verifyReceipt(receipt_json: string, registry_public_key_b64: string, expected_ctx_id: string, recomputed_body_hash: string, producer_key_fingerprint: string): string;
+
+/**
+ * Verify an Ed25519 signature over the ASCII `"sha256:<hex>"` string.
+ * `pubKeyB64` is the raw 32-byte key, base64. Returns a verdict.
+ */
+export function verifySignatureEd25519(pub_key_b64: string, sig_b64: string, content_hash: string): string;
+
+/**
+ * Verify an ECDSA-P256 signature (IEEE-1363 `r‖s`, base64) over the
+ * ASCII `"sha256:<hex>"` string. `pubKeySec1B64` is the 65-byte
+ * SEC1-uncompressed key, base64. Returns a verdict.
+ */
+export function verifySignatureP256(pub_key_sec1_b64: string, sig_b64: string, content_hash: string): string;
+
+/**
+ * Verify one witness cosignature offline (RFC-ACDP-0015 §8). Returns a
+ * verdict.
+ */
+export function verifyWitnessCosignature(cosig_json: string, witness_did_doc_json: string, expected_checkpoint_json: string, now_rfc3339?: string | null, max_clock_skew_secs?: bigint | null): string;
+
+export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
+
+export interface InitOutput {
+    readonly memory: WebAssembly.Memory;
+    readonly buildLogLeaf: (a: number, b: number, c: number) => void;
+    readonly buildWitnessCosignature: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number) => void;
+    readonly canonicalPreimage: (a: number, b: number, c: number) => void;
+    readonly classifyUnderRevocation: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => void;
+    readonly evaluateWitnessQuorum: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: number, k: number, l: number, m: number) => void;
+    readonly explainHashMismatch: (a: number, b: number, c: number, d: number, e: number) => void;
+    readonly fingerprintEd25519: (a: number, b: number, c: number) => void;
+    readonly merkleLeafHash: (a: number, b: number, c: number) => void;
+    readonly merkleNodeHash: (a: number, b: number, c: number, d: number, e: number) => void;
+    readonly merkleRootHash: (a: number, b: number, c: number) => void;
+    readonly parseKeyRevocation: (a: number, b: number, c: number, d: number, e: number) => void;
+    readonly resolveDidKey: (a: number, b: number, c: number) => void;
+    readonly verifyBodyOffline: (a: number, b: number, c: number) => void;
+    readonly verifyContentHash: (a: number, b: number, c: number, d: number, e: number) => void;
+    readonly verifyLifecycleEvent: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => void;
+    readonly verifyLineageHeadReceipt: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: number, k: bigint, l: number, m: bigint) => void;
+    readonly verifyLogCheckpoint: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: number, k: bigint) => void;
+    readonly verifyLogConsistency: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => void;
+    readonly verifyLogInclusion: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => void;
+    readonly verifyPublishRequestOffline: (a: number, b: number, c: number) => void;
+    readonly verifyReceipt: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: number, k: number) => void;
+    readonly verifySignatureEd25519: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => void;
+    readonly verifySignatureP256: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => void;
+    readonly verifyWitnessCosignature: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: number, k: bigint) => void;
+    readonly __wbindgen_add_to_stack_pointer: (a: number) => number;
+    readonly __wbindgen_export: (a: number, b: number) => number;
+    readonly __wbindgen_export2: (a: number, b: number, c: number, d: number) => number;
+    readonly __wbindgen_export3: (a: number, b: number, c: number) => void;
+}
+
+export type SyncInitInput = BufferSource | WebAssembly.Module;
+
+/**
+ * Instantiates the given `module`, which can either be bytes or
+ * a precompiled `WebAssembly.Module`.
+ *
+ * @param {{ module: SyncInitInput }} module - Passing `SyncInitInput` directly is deprecated.
+ *
+ * @returns {InitOutput}
+ */
+export function initSync(module: { module: SyncInitInput } | SyncInitInput): InitOutput;
+
+/**
+ * If `module_or_path` is {RequestInfo} or {URL}, makes a request and
+ * for everything else, calls `WebAssembly.instantiate` directly.
+ *
+ * @param {{ module_or_path: InitInput | Promise<InitInput> }} module_or_path - Passing `InitInput` directly is deprecated.
+ *
+ * @returns {Promise<InitOutput>}
+ */
+export default function __wbg_init (module_or_path?: { module_or_path: InitInput | Promise<InitInput> } | InitInput | Promise<InitInput>): Promise<InitOutput>;