feat(ceremony): rebuild browser package around supplied popup connections

[Wondertan]

Rebuild @libid/ceremony around an externally supplied PopupConnection and the current CCDP contracts. Callback clears captured OAuth returns, selects its bundled CCDP version and privately forwards them to one logical Prover. Popup owns window creation, navigation, isolation fallback and continuity; the application owns wallet operations and submission.

Client resolves the Bridge’s callbackPath against its supplied Bridge origin once and sends the same frozen redirectUri with GitHub token requests. Client snapshots the ledger hash and, for X/GitHub, its notary address before OAuth. Prover receives those values without a ledger decoder; the ledger package contains an interface and explicit synthetic fixtures. Results contain identity and oauthProof. Browser code does not cryptographically verify proofs or attestations. Safe failure codes cross the connection; raw OAuth returns and original exceptions stay private.

Asset owners declare archives, wildcard members and external URLs once. The build derives prefetch from the declarations and emitted graph; bb.js CRS requests retain their native hosts and ranges. WASM bodies are normalized at build time, with gzip/Brotli sidecars served by native SWS negotiation. Existing immutable URLs retain their bytes. Validated cached responses are delivered directly; misses can reuse the browser HTTP cache. Cache Storage writes run after response delivery while single-flight entries and Service Worker events remain alive through persistence.

Released verification keys are prefetched and supplied to bb.js. Dependency initialization, witness execution and notary socket setup overlap where their inputs permit it. GitHub identity setup starts alongside token exchange, with final delivery waiting for all required outputs and correlations. OAuth readers tolerate additional bounded provider metadata while validating required fields. X/GitHub JSON readers accept whitespace without rewriting transcript bytes. Token admission allows additional headers while requiring unique Host, Content-Type and canonical Content-Length values. Token and identity requests reject their forbidden header names while preserving the required layouts and bearer holes.

The Bridge’s new configuration uses TOML [[platforms]] tables in ts/apps/dev/bridge-config.toml, mounted by Compose; obsolete BASE_URL, NOTARY_URL and CEREMONY_PLATFORMS settings are removed. ts/apps/dev provides per-platform buttons, run history, stage timings and post-consent duration. Successful ceremonies close their popup; failures remain open for inspection. pnpm dev starts the app, Bridge, notary and SWS on separate localhost HTTP origins. pnpm dev:ccdp refreshes the static distribution without rebuilding service images. Explicit HTTP/WS exceptions cover only localhost and 127.0.0.1; production remains HTTPS/WSS.

The internal layout uses standalone barretenberg/, notary/ and assets/ modules, separate from ccdp/documents/. Barretenberg owns the engine and oidc_google/bearer_link circuit adapters; notary owns HTTP/transcript parsing. Platform orchestration owns ProverContext; JSON duplicate-key detection and progress accounting remain shared. Resource declarations use owner-specific *.assets.ts names. The platform catalog composes URL builders and proof validators directly; url.ts contains no proof re-exports. Notary owns the delivered attestation type and projection validator, shared URL/scalar guards live in primitives.ts, and document UI lives beside its three consumers.

The package exports only its root discovery/result API and @libid/ceremony/ccdp/client. CCDP codecs and document startup functions are private build inputs; configuration validators and proof-type mappings are internal. CCDPClient.enabledPlatforms discovers compatible configured platforms, and enabledVersions(platform) lists their compatible versions. The optional trailing new(..., ceremonyVersion) chooses an enabled version explicitly; omission retains the highest-compatible default. The selected version is validated before ledger reads and retained in prefetch, authorization, Prover inputs and the result. Versions may differ in disclosure behavior, so apps offering a specific mode can pin that choice. These changes leave wire messages and document routes unchanged. Existing Biome formatting and import organization are enforced, and adjacent API comments document lifecycle, ownership and trust constraints while package docs retain cross-component requirements.

Canonical test fixtures live beside their owning circuit/decoder tests; browser qualification reuses the same Google fixture. Fixture files are excluded from package contents.

Rebuilding removes obsolete gzip/Brotli sidecars when a replacement body no longer benefits from compression. This prevents content negotiation from serving stale HTML that points at workers from an earlier build.

Stack and pinned prerequisites

• Base: popup PR feat(popup): implement @libid/popup without WebRTC #25, feat/popup-package at 1c5b78c6f9d783f7b5c536f6018d724b3ced9132. No merges. This branch also adds the explicit localhost HTTP exception to popup URL validation.
• Architecture: PR docs(ceremony): define browser architecture #13; the Bridge integration note records its wire differences against 83a7fbcd071abeb62aa2cfd6f9cc91933175a328. Shared transcript requirements are maintained in PR docs(specs): the token request reveals its headers, and the verifier checks them #31 at 860075a4bf288dc7fee20866ed3536dc260f4574. This branch leaves the root specification files unchanged.
• Development Bridge: libid-server-rs #10, stacked on docs(ceremony): parameterize proof validity #9, rebased onto PR docs(ceremony): parameterize proof validity #9 at 991d5c604acdb1a67099f28cbf37ad58b6c317a5, pinned at cdc16551114070ea3458ef0d5ceb19ca4228833e. It now dials the request-selected notary host on its wire port; the RC3 pins and server-specific whitespace error classification remain above the new base. Shared parsing comes from released libid-rs v0.4.0; redundant server docs(specs): on-chain verification path, two-attestation circuits, notary fee #11 is superseded by docs(specs): trim Google circuit to the verification relation; unify X public inputs #10.
• Matching whitespace changes: merged libid-rs #21, included in v0.4.0 (82bc4e286d762531ba3ac86996db4afc6ea38f56), and merged contracts #37, replacing closed docs(specs): align ceremony browser contract #20 and #36. This dependency update does not claim full qualification against the updated contract.
• Notary/browser bundle: v0.3.0-rc.3, matching TLSN 94aaaf33 and MPZ 1dd2349d; immutable bundle mount tlsn/v0.3.0-rc.3-csp1.
• Proving: circuits v0.3.0, Noir 1.0.0-beta.25, bb.js 5.2.0, verifierTarget: 'evm'. Qualification verifies against released keys outside ceremony, without a chain/RPC dependency.
• Serving: SWS 3.0.0-beta.1, pinned multiarchitecture image. Deploy compatible Client, CCDP and Bridge wire versions.

Validation

• 407 ceremony unit tests, package/build/browser TypeScript checks, package and dev-app builds, workspace formatting and lint pass.
• 36 browser checks pass across Chromium, Firefox and WebKit over HTTP and HTTPS: actual popup flows, native-anchor fallback, root-worker migration, pending-prefetch joins, persistent HTTP-cache reuse, real Google fixture proofs and concurrent TLSNotary initialization. The six Google proofs are independently verified against the released key with mutated public inputs rejected. Real bearer-link proofs also verify against the released key in all three engines.
• The latest ownership refinement also passes 30 actual-popup, document-UI, Google fixture proof and concurrent TLSNotary initialization checks across all three engines over HTTP and HTTPS. The moved validation and UI bodies match their previous implementation.
• The final public API passes all 75 dev-app browser tests, including Android/iOS emulation, plus 18 actual-popup and real Google fixture proof checks across Chromium, Firefox and WebKit over HTTP and HTTPS. This is not physical-device qualification. Consumer type checks preserve platform proof inference and reject removed imports; runtime package resolution rejects all four private subpaths, and the packed archive excludes fixtures.
• All 17 distribution, installed-dependency-loader and native-SWS checks pass without skips. They cover blocked external asset hosts, normalized bodies, headers, sidecars, negotiation, validators and ranges. The stale-sidecar regression fails before the fix and passes after it; WebKit's real bearer proof passes after rebuilding.
• Security/correctness, API ergonomics and simplicity reviews are clear for the structure, style, sidecar, ownership and public-API changes. The stale catalog example was replaced with the public API contract and a link to its implementation.
• Previous Bridge integration validation: 124 Rust tests, Clippy and the actual Docker build passed; the running stack served configuration and Callback, rejected malformed redirects/private egress and reached GitHub through matched RC3 notarization with an intentionally invalid code. Shared parsing uses libid-rs v0.4.0. No fresh consent or updated-contract qualification is claimed by that dependency update.
• Previous matched-notary qualification completed two concurrent real sessions alongside bb initialization in all three engines. These used unauthenticated responses and do not establish authenticated identity or attestation-signature qualification.

Manual Google, X and GitHub successes were reported during development. This update does not claim fresh live-OAuth, physical-mobile or complete release qualification. Earlier broader browser coverage and the intermittent WebKit two-popup result remain documented; remaining gates and all 153 stable requirement IDs are retained in the package docs.

See the package guide, qualification, traceability, and development setup.

[SupremaLex]

Ran this branch (0469056) end to end with a real GitHub OAuth app, a local
Notary and a local Bridge. Two problems in the browser package.

1. GitHub sends iss and the parser rejects the whole return

Created a fresh GitHub OAuth app for the test. The callback came back with an
iss parameter. The parser has no case for it, so auth failed straight away —
before any token exchange.

src/platforms/codeReturn.ts:20

if (key !== 'state' && key !== 'code' && key !== 'error') return null

What GitHub sent (keys only): code, iss, state

Any unknown key makes parseCodeOAuthReturn return null, and
platforms/github/1/prover.ts:37 then throws Invalid GitHub return. The
cancel path breaks the same way — error, iss, state is rejected too.

iss is the issuer identifier from RFC 9207. Rather than just adding it to the
allowlist, it may be worth checking its value against the expected issuer —
that is what it is for.

2. Errors are thrown away, so this was hard to find

fail takes no argument:

const fail = () => {          // src/ccdp/documents/prover.ts:36

so .catch(fail) at line 116 gets the error and drops it. There are six empty
catch blocks in the two CCDP documents — prover.ts:42,72,96,133 and
prefetch.ts:25,29. Each ends in a fixed message:

Unable to complete proof. Return to your application.
Unable to prepare. Return to your application.

The user sees that, the browser console is empty, and no server logs anything,
because it fails before any request goes out. A broken OAuth parser and a broken
service worker look identical from outside.

Smallest fix: catch (e) and log it. Better: pass a reason into fail and put
it in the abort-ceremony message, which already has a reason field that is
always a constant today.

With iss accepted locally, the ceremony gets through consent, the callback,
the Bridge token exchange and a real MPC-TLS session with github.com. It then
fails in the Notary's attestation step — reported on libid-org/notary#6.