getlantern / getlantern/spark

Build prod WASM-module distribution over the signed config/fronting channel

Open
#114 5 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement
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/sparkSPARK_MODULE_SIGNING_KEY, base64 DER PKCS#8).
  • Public half pinned in CISPARK_MODULE_PUBKEY_HEX repo variable (1f090afa…85ce), verified to match the Vault key; release.yml builds --features bip324 when 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 runs WasmConfig/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 + its TransportConfig to 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

  1. Payload shape — inline the .spkw bytes 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.)
  2. Where distribution lives — how modules get added to the lantern-cloud config/fronting distribution (which service, what schema change to the config payload).
  3. Rollout granularity — per-region? per bandit track? staged %? (reuse existing config-targeting.)
  4. Rollback — how to pull a bad module fast (config revert / kill-switch).
  5. 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.sh output-dir override — prod signing writes to a dist dir, not the committed core/tests/fixtures/wasm/*.spkw dev 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 + TransportConfig to the distribution channel.
  • Consumer path — confirm/extend the client to fetch + load a module delivered via config through ModuleVerifier::pinned() (schema for the module in WasmConfig).
  • Rollout + rollback controls (per-region / track targeting).
  • E2E test — a prod-signed obfs-xor (or bip324) 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

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.