- HTML 30%
- Rust 24%
- JavaScript 20%
- Shell 10%
- CSS 9%
- 1 more language 7%
recovery-key #
A small, auditable Rust crate that generates a did:plc rotation key (a "recovery key") entirely in the browser, and the single-file web page that wraps it, published at https://pyroclastic.cloud/recovery-key.
Source: https://tangled.org/ngerakines.me/recovery-key-guide
The page makes no network requests, loads no external scripts, and works with networking disabled. The key leaves the page only through the clipboard.
Layout #
| Path | What it holds |
|---|---|
crates/recovery-key-core |
Pure Rust, #![no_std] + alloc: key generation and multibase / did:key encoding for P-256 and K-256. No I/O, no wasm dependencies; cargo test runs natively. |
crates/recovery-key-wasm |
cdylib with two wasm-bindgen exports, generate_recovery_key and public_key_for_private, over the core crate. |
web/ |
index.template.html, app.js (all DOM behaviour), style.css, and the self-hosted fonts with their OFL licences. |
design/design-preview.html |
The design export the page was built from, kept unedited for reference. Its {{…}} bindings, "ghost" markers and trailing script belong to the design tool, not to the page. |
scripts/ |
build.sh (the page), ci.sh (every check), tools.sh (pinned tools into .tools/), test-wasm.sh (browser tests), smoke.mjs (offline end-to-end check), inline.py (the single-file assembly). |
site/ |
stage.py, which stages the built page into the pyroclastic.cloud site record; the publishing steps; and an entry card for the main site. |
For a reviewer: where the key can go #
Read these three files; together they are under 600 lines.
crates/recovery-key-core/src/lib.rs. Entropy is onegetrandom::fillcall, which in the browser iscrypto.getRandomValues. The scalar lives in aZeroizing<[u8; 32]>and is wiped on drop; the encoding buffers areZeroizingtoo. The crate isno_std, so it cannot open a file or a socket.crates/recovery-key-wasm/src/lib.rs. Two functions and one class.GeneratedKeyholds the key itself, and the page callsfree()on it as soon as it has read the strings.web/app.js. The secret is held in one module-scoped object,current, which Done sets tonullbefore reloading. It goes tonavigator.clipboard.writeTextand to the DOM (masked unless revealed), and nowhere else.
What the browser enforces regardless of the code, from the page's meta CSP: default-src 'none', connect-src 'none', img-src data:, font-src data:, form-action 'none', base-uri 'none', and script and style allowed only by the SHA-256 of the one inline <script> and the one inline <style> (plus 'wasm-unsafe-eval' so the module can compile). So the page cannot fetch, post, beacon, or load an image or font from anywhere. A meta CSP cannot set frame-ancestors, so the script refuses to run inside a frame before it does anything else.
When the page is served at pyroclastic.cloud, its host, Highport, sends a Content-Security-Policy header of its own (default-src 'self'; script-src 'self' 'unsafe-inline' 'wasm-unsafe-eval' blob:; …). A browser enforces both policies, so the stricter meta policy still decides, and nothing the page needs is outside the header's allowances.
Limits worth knowing: JavaScript strings cannot be wiped, so the secret string stays in the JS heap until it is garbage collected; bs58's internal working buffers are not zeroized; and the clipboard is the clipboard. The page tries to clear the clipboard 60 seconds after the secret is copied: it reads the clipboard only where clipboard-read permission is already granted (reading otherwise makes browsers show a permission prompt out of nowhere), and elsewhere overwrites only if focus never left the page since the copy.
Dependencies #
p256, k256 (both 0.14, arithmetic only), bs58, zeroize, getrandom 0.4.3 (wasm_js in the wasm crate only), wasm-bindgen (pinned to =0.2.129). To check:
cargo tree -p recovery-key-wasm --target wasm32-unknown-unknown -e normal
This shows exactly one getrandom and no reqwest, tokio, serde_json, chrono, ed25519-dalek, or p384. Leave out -e normal and tokio and serde_json appear, through wasm-bindgen-test, which is a dev-dependency used only by the browser tests and never reaches the built wasm. scripts/ci.sh checks this rule.
Formats #
| Encoding | Starts with | |
|---|---|---|
| P-256 secret | z + base58btc(86 26 + 32-byte scalar) |
z42t, or z42u for the top ~0.66% of scalars |
| K-256 secret | z + base58btc(81 26 + 32-byte scalar) |
z3vL |
| P-256 public | did:key:z + base58btc(80 24 + 33-byte compressed point) |
did:key:zDnae |
| K-256 public | did:key:z + base58btc(e7 01 + 33-byte compressed point) |
did:key:zQ3sh |
The secret is the form goat key generate prints and goat plc sign --plc-signing-key reads. 50 keys generated by goat 0.2.7 (25 per curve) were decoded by this crate during development, and each re-derived the public key goat printed and re-encoded to the same secret. The tests check the atproto cryptography spec examples, the W3C did:key private-to-public vectors that bluesky-social/atproto's crypto tests carry, and scalar 1 against each curve's generator point.
goat_golden_vectors in crates/recovery-key-core/src/tests.rs pins four throwaway keys made by goat 0.2.7 (two per curve): each goat secret must decode to the curve goat named, derive the public key goat printed, and re-encode to the same string. That ties the private-key prefixes 86 26 and 81 26 to what goat writes and reads.
Building #
scripts/tools.sh # once: wasm-bindgen-cli, binaryen, twiggy into .tools/
scripts/build.sh # dist/index.html and dist/index.html.sha256
scripts/ci.sh # every check; size report in target/ci-report.md
scripts/build.sh runs cargo build --release --target wasm32-unknown-unknown -p recovery-key-wasm, wasm-bindgen --target web, wasm-opt -Oz, then scripts/inline.py, which writes the template with the stylesheet, the fonts (as data URIs), the wasm-bindgen glue, app.js and the base64 wasm inlined, and computes the two CSP hashes. It refuses any absolute URL other than the documented ones: the three links in the page (pyroclastic.cloud/, github.com/bluesky-social/goat, atproto.com/guides/account-recovery) and the two the link-preview tags name (the canonical pyroclastic.cloud/recovery-key and its Open Graph image, pyroclastic.cloud/recovery-key/og.png). Meta tags and the canonical link are not fetched by the page, so none of these is a request. Source paths are remapped out of the wasm, so the build carries no local paths.
scripts/ci.sh needs Chrome for the browser tests and the smoke test, and Node 22 or later for the smoke test. There is no hosted CI; run it before tagging.
Toolchain and sizes #
Built on 2026-10-27 with:
| Tool | Version |
|---|---|
| Rust | 1.99.0 (rust-toolchain.toml) |
| wasm-bindgen | 0.2.129 (crate and CLI) |
binaryen (wasm-opt) |
version_133 |
| twiggy | 0.8.0 |
| Profile | .wasm before wasm-opt |
.wasm after wasm-opt -Oz |
index.html |
index.html gzipped |
|---|---|---|---|---|
release (opt-level = "z", the default) |
115,574 | 102,895 | 291,433 | 153,253 |
release-s (opt-level = "s") |
110,385 | 99,138 | 286,421 | 150,987 |
All sizes are in bytes. opt-level = "s" comes out 3.7 KB smaller after wasm-opt (about 2 KB gzipped), which is common for RustCrypto code. The release stays on "z", which is what is published; release-s is kept so scripts/ci.sh can keep reporting the comparison. The fonts are about 110 KB of the page once base64-encoded.
Reproducible builds #
With the same rust-toolchain.toml, Cargo.lock and the tool versions above, the build is byte-for-byte reproducible, wherever the checkout lives: scripts/build.sh remaps local paths out of the wasm, and a fresh clone at another path builds the same index.html. The page published at https://pyroclastic.cloud/recovery-key is exactly what this repository builds; its SHA-256 is at https://pyroclastic.cloud/recovery-key/index.html.sha256.
Comments count. style.css and app.js are inlined verbatim, so editing a comment in either changes the page, and adding or removing a line in recovery-key-core/src/lib.rs moves the line numbers in the wasm's panic messages.
Verifying a saved copy #
Anyone who saved index.html can check it against the published hash:
sha256sum index.html # Linux
shasum -a 256 index.html # macOS
The output must match https://pyroclastic.cloud/recovery-key/index.html.sha256.
Releasing #
Tag the commit, run scripts/ci.sh, run site/stage.py to stage dist/ into the pyroclastic.cloud site record, and publish that record (see site/README.md). Update the sizes above when they change.
Things to re-check #
- goat's
--first. Confirmed in goat 0.2.7 (Homebrew) and in goat's source at1101b5b(2026-10-26):account plc add-rotation-key --firstinserts the key at index 0 (slices.Insert(plcData.RotationKeys, 0, newKeyStr)).account login -u/-p,account plc request-token,account plc current,account logout, andplc sign --plc-signing-key(multibase secret) exist as the page uses them. Re-check when goat changes. - Five rotation keys at most. goat only warns when an account already has five rotation keys and submits anyway; the PLC directory then refuses the operation. Most accounts have one or two. The page does not mention this.
Licence #
The code is MIT licensed; see LICENSE. The fonts in web/fonts/ (and inlined into the built page) are Space Grotesk, IBM Plex Sans and IBM Plex Mono, each under the SIL Open Font License 1.1, whose texts are beside them.