From 466081354d7781089bd9cb8307912908a66e5753 Mon Sep 17 00:00:00 2001 From: Lann Martin Date: Mon, 17 Aug 2026 19:53:57 -0400 Subject: [PATCH] docs: pay down the restructure's doc debt MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The rust/+js/ restructure (182f911) and later growth left the docs contradicting the tree; every claim below is corrected to what the referenced files actually do. - Five dead relative links: the js/componentize README's guest-crate, demo, and toolchain-workflow links (all still resolving inside js/), the wpt README's workflow link, and the componentize-demo README's library link. - The root README described the two componentize checks' requirements backwards: wpt::test componentizes its runner from the tree (there is no published runner component) and downloads the digest-verified toolchain, and componentize::test uses that same downloaded toolchain (nobody here builds the CLI) — per component.sh and the library's Toolchain section. - The js/componentize consumer instructions prescribed a two-interface world, which fails at componentize time against the shim's static imports; the world requirement now points at the webcrypto.js header (the authoritative registry) and the demo's complete world. - The wpt README's vendored table gains the wrapKey_unwrapKey row (landed 0c39433). - `just ci` runs the core CI jobs' checks, not "everything CI runs" / "mirrors CI exactly": the engine-leg jobs (Firefox, the macOS WebKit pair) and the conformance-aggregate job run only in CI (README, AGENTS.md). The hpke experiment's compose comment names justfile.shared.just, where _compose lives. --- AGENTS.md | 5 ++++- README.md | 14 ++++++++------ examples/componentize-demo/README.md | 2 +- experiments/hpke/justfile | 2 +- js/componentize/README.md | 17 ++++++++++------- js/componentize/wpt/README.md | 3 ++- 6 files changed, 26 insertions(+), 17 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 1d19131..280f703 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -415,7 +415,10 @@ experiment cannot gate pull requests (see timing-lab/README.md, ### Checks to run before committing Run the recipes that cover what you changed, and fix anything they report. -`just check` is the fast gate; `just ci` mirrors CI exactly. +`just check` is the fast gate; `just ci` runs the core CI jobs' checks. +(CI runs more than `just ci` can: the dedicated engine-leg jobs — the +Firefox conformance leg, the macOS WebKit conformance and parity legs — +and the cross-target conformance-aggregate job.) | Recipe | Run it when you change… | | --- | --- | diff --git a/README.md b/README.md index 4fa8077..1c67049 100644 --- a/README.md +++ b/README.md @@ -177,12 +177,12 @@ just demo::test-node # transpile and run the same guest under the jco ho just demo::test-composed # compose guest + in-guest provider + driver (wac plug) # and run the whole thing under `wasmtime run` just wpt::test # the WPT WebCryptoAPI suites against the - # webcrypto-componentize JS guest library, via its - # published runner component (no componentize-js - # toolchain needed — see js/componentize/wpt/) + # webcrypto-componentize JS guest library — the + # runner componentized from the tree, the toolchain + # downloaded and digest-verified (js/componentize/wpt/) just componentize::test # the composed pipeline with the JS demo guest - # (needs the componentize-js CLI — see - # js/componentize/README.md) + # (the same downloaded toolchain — see + # js/componentize/README.md, "Toolchain") just wpt::parity # the WPT suites against the platform's own # crypto.subtle and through the jco round trip; # holds the round trip to the platform's pass set @@ -205,7 +205,9 @@ just conformance-ct::web # serve the conformance results viewer + a live # matrix page is at conformance/driver-ct/compat/ just timing-lab::run # dudect-style timing tests of the composed in-guest # provider (statistical; not part of `just ci`) -just ci # everything CI runs +just ci # the core CI jobs' checks (CI additionally runs + # dedicated engine-leg jobs — Firefox, macOS + # WebKit — and a cross-target aggregation job) ``` All implementations run identical suite components. The conformance diff --git a/examples/componentize-demo/README.md b/examples/componentize-demo/README.md index 00a13f1..c52e05c 100644 --- a/examples/componentize-demo/README.md +++ b/examples/componentize-demo/README.md @@ -2,7 +2,7 @@ A JavaScript guest component, built with [componentize-js] (the wit-dylib–based reboot of ComponentizeJS), that exercises the -WebCrypto-subset library in [`js/componentize/`](../../webcrypto-componentize) +WebCrypto-subset library in [`js/componentize/`](../../js/componentize) end to end: HMAC-SHA-256 known answers (RFC 4231), AES-256-GCM known answers (NIST GCM test case 16), round trips including the empty plaintext, and the key-capability surface (usages, extractability, malformed-input rejection). diff --git a/experiments/hpke/justfile b/experiments/hpke/justfile index 1aa9850..70773e7 100644 --- a/experiments/hpke/justfile +++ b/experiments/hpke/justfile @@ -18,7 +18,7 @@ test: # Compose the fully in-guest smoke run: the HPKE guest's polymorph:webcrypto # imports are satisfied by the repository's in-guest provider (RustCrypto in # wasm), then a CLI driver (async wasi:cli/run) is plugged on top. Mirrors -# the root justfile's `_compose`. +# the root justfile.shared.just's `_compose`. compose: build-component cargo build --release -p hpke-driver --target wasm32-wasip2 cargo build --release -p polymorph-webcrypto-guest-provider --target wasm32-wasip2 \ diff --git a/js/componentize/README.md b/js/componentize/README.md index deea5f4..f4e48e9 100644 --- a/js/componentize/README.md +++ b/js/componentize/README.md @@ -3,7 +3,7 @@ A WebCrypto-subset library for JavaScript guests componentized with [componentize-js] (the wit-dylib–based reboot of ComponentizeJS), backed by the `polymorph:webcrypto` interfaces. This is the JS-guest counterpart of the Rust -[`polymorph-webcrypto-guest`](../polymorph-webcrypto-guest): where `polymorph-webcrypto-guest` wraps the raw bindings in +[`polymorph-webcrypto-guest`](../../rust/guest): where `polymorph-webcrypto-guest` wraps the raw bindings in ergonomic Rust newtypes, `webcrypto.js` wraps them in the API JS code already knows — `crypto.subtle`. @@ -46,11 +46,14 @@ toolchain, so neither CI nor contributors compile SpiderMonkey. ## Using it in a component -The component's world must import `polymorph:webcrypto/hmac-sha2@0.1.0` and -`polymorph:webcrypto/aes-gcm@0.1.0` (WIT elaboration pulls in their -`mac`/`aead`/`types` dependencies) — see -[`examples/componentize-demo`](../examples/componentize-demo) for a complete -world, guest, and composition. The `sha1-checked` +The component's world must import every `polymorph:webcrypto` interface the +library statically imports, plus `wasi:random/random@0.2.0` — the list at +the top of `webcrypto.js` is the authoritative registry (the generic +`mac`/`aead`/`types`-style dependencies arrive by WIT elaboration), and +[`examples/componentize-demo`](../../examples/componentize-demo) keeps a +complete, compiling world +([`wit/world.wit`](../../examples/componentize-demo/wit/world.wit)) with +guest and composition. The `sha1-checked` import is gated `@unstable` in the package (see `wit/README.md`, "Stability gates"), so that world line carries an `@unstable(feature = ...)` gate and the @@ -75,7 +78,7 @@ The componentize-js CLI turns a JS guest into a component (`just componentize::build-demo`, and the WPT check's runner); it is not needed to *run* one. Nobody here builds it: building compiles SpiderMonkey to wasm and needs WASI-SDK 30 and Clang 19+, so the -[`componentize-js-toolchain`](../.github/workflows/componentize-js-toolchain.yml) +[`componentize-js-toolchain`](../../.github/workflows/componentize-js-toolchain.yml) workflow builds one per (revision, platform) and publishes it on the rolling `toolchains` release, and `js/componentize/wpt/component.sh toolchain` downloads it into `target/toolchains/` on first use — verified against the diff --git a/js/componentize/wpt/README.md b/js/componentize/wpt/README.md index 72fb696..5a7bf55 100644 --- a/js/componentize/wpt/README.md +++ b/js/componentize/wpt/README.md @@ -23,7 +23,7 @@ artifacts involved have very different costs, and are handled accordingly: exercised. - The **toolchain** takes about twenty minutes, and depends on nothing but the revision in [`../componentize-js.rev`](../componentize-js.rev). The - [`componentize-js-toolchain`](../../.github/workflows/componentize-js-toolchain.yml) + [`componentize-js-toolchain`](../../../.github/workflows/componentize-js-toolchain.yml) workflow builds one per (revision, platform), publishes it on the rolling [`toolchains` release] with a build-provenance attestation, and `component.sh` downloads it into `target/toolchains/` on first use. @@ -213,6 +213,7 @@ relative path. | `encrypt_decrypt/aes_gcm` (256-bit iv) | `aes_gcm_256_iv.https.any.js` (reference), `aes_gcm_256_iv_fixtures.js` (the shared `aes.js` runner and `aes_gcm_vectors.js`) | | `encrypt_decrypt/aes_cbc` | `aes_cbc.https.any.js` (reference), `aes_cbc_vectors.js` (the shared `aes.js` runner) | | `encrypt_decrypt/aes_ctr` | `aes_ctr.https.any.js` (reference), `aes_ctr_vectors.js` | +| `wrapKey_unwrapKey` | `wrapKey_unwrapKey.https.any.js` (wrapped callable — see `component.sh`), `wrapKey_unwrapKey_vectors.js` | | `import_export/symmetric_importKey` | `symmetric_importKey.https.any.js` (reference), `symmetric_importKey.js` | | `generateKey` successes | `successes_HMAC.https.any.js`, `successes_X25519.https.any.js`, `successes_Ed25519.https.any.js` (references), `successes.js` | | `generateKey` failures | `failures_HMAC.https.any.js`, `failures_AES-GCM.https.any.js`, `failures_AES-CBC.https.any.js`, `failures_AES-CTR.https.any.js`, `failures_Ed25519.https.any.js`, `failures_X25519.https.any.js` (references), `failures.js` |