Build prod WASM-module distribution over the signed config/fronting channel
Nobody has claimed this yet.
- Dominant language
- Rust
- Stars
- 1
- Forks
- 0
- Avg merge
- 11h 35m
- Merged PRs (30d)
- 4
Description
Summary
Everything for prod WASM-module signing is now in place except the part that actually gets a signed module to clients. This issue tracks building module distribution over the signed config/fronting channel — the "north star" from dynamic-transport-framework-design.md: ship a new/updated transport as a signed artifact, not an app-store release.
What already exists
- Prod module-signing keypair minted; private half in Vault (
secret/lantern_cloud/spark→SPARK_MODULE_SIGNING_KEY, base64 DER PKCS#8). - Public half pinned in CI —
SPARK_MODULE_PUBKEY_HEXrepo variable (1f090afa…85ce), verified to match the Vault key;release.ymlbuilds--features bip324when set. - Offline signing runbook: #113 (
docs/prod-module-signing-runbook.md). - Client-side verify path:
ModuleVerifier::pinned()accepts modules signed by the pinned key; the dial path runsWasmConfig/WasmTransport.
The gap
- The committed
.spkw(bip324,obfs-xor) are dev-key-signed test fixtures — nothing prod-signed exists. - There is no mechanism to deliver a prod-signed
.spkw+ itsTransportConfigto shipped clients. §7 step 4 says "distribute over the existing signed config/fronting channel" but that path isn't built for modules.
Goal
An already-shipped client (pinned to SPARK_MODULE_PUBKEY_HEX) can receive a prod-signed WASM transport module + config over the config channel, verify it, and dial through it — with no client release — and we can roll it out and back safely.
Design questions to resolve first
- Payload shape — inline the
.spkwbytes in the signed config, or reference a fetch URL from the config? (obfs-xor.spkw≈ 722 B is trivially inlineable;bip324.spkw≈ 23 KB may bloat every config fetch — a referenced+hashed URL may be better for the large ones.) - Where distribution lives — how modules get added to the lantern-cloud config/fronting distribution (which service, what schema change to the config payload).
- Rollout granularity — per-region? per bandit track? staged %? (reuse existing config-targeting.)
- Rollback — how to pull a bad module fast (config revert / kill-switch).
- Integrity — the Ed25519 signature + pinned pubkey are the trust anchor; confirm no additional transport-level integrity is needed for the referenced-URL case (hash in the signed config).
Deliverables
- ADR / design note: inline-vs-referenced module delivery over the config channel (fold into
dynamic-transport-framework-design.md). -
build-module.shoutput-dir override — prod signing writes to a dist dir, not the committedcore/tests/fixtures/wasm/*.spkwdev fixtures (today it clobbers them). -
sign-module verify <spkw> --pubkey-hex <hex>helper — lets the runbook's "verify before ship" step check an artifact against the pinned pubkey without a bespoke cargo test. - Producer path — offline: sign prod modules (per runbook) → publish
.spkw+TransportConfigto the distribution channel. - Consumer path — confirm/extend the client to fetch + load a module delivered via config through
ModuleVerifier::pinned()(schema for the module inWasmConfig). - Rollout + rollback controls (per-region / track targeting).
- E2E test — a prod-signed
obfs-xor(orbip324) delivered via config, loaded by a client pinned to the prod pubkey, dialing end-to-end.
Hard invariant (do not violate)
Signing stays offline; the private key never enters CI or the repo (§7). This issue is about distribution of already-signed artifacts + the client consume path — not about automating signing. The distribution channel only ever carries signed .spkw; trust is the Ed25519 signature verified against the compiled-in pubkey.
References
- Runbook: #113 · Design:
docs/dynamic-transport-framework-design.md§7 ·release.yml(pubkey pin) ·scripts/build-module.sh·core/src/bin/sign-module.rs·core/src/transport/wasm/signing.rs(ModuleVerifier).
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with docs/dynamic-transport-framework-design.md §7 and the prod-module-signing runbook in #113, then trace scripts/build-module.sh, core/src/bin/sign-module.rs, core/src/transport/wasm/signing.rs, and release.yml. Resolve the delivery, rollout, rollback, and integrity design before implementing the producer and consumer paths. Done means a prod-signed module can travel through config, be verified and loaded by a shipped client, and pass the end-to-end test without moving the private key into CI or the repository.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust, wasm
- Domain
- distributed-systems, infrastructure, release, security
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100