Skip to content

docs(specs): align ceremony browser contract - #20

Merged
Wondertan merged 6 commits into
mainfrom
docs/ceremony-browser-contract
Sep 3, 2026
Merged

docs(specs): align ceremony browser contract#20
Wondertan merged 6 commits into
mainfrom
docs/ceremony-browser-contract

Conversation

@Wondertan

@Wondertan Wondertan commented Aug 22, 2026

Copy link
Copy Markdown
Member

Summary

This PR aligns the normative ceremony rules with the browser protocol. It targets main directly and keeps the existing terminology so the protocol changes can merge independently.

It supersedes #15, which GitHub marked merged into the terminology branch while the stack order was being reversed.

Changes

Ceremony boundary and lifecycle

  • Define the Ceremony as the off-ledger process that authenticates the selected identity-platform account, derives its canonical user ID and handle, and locally generates the exact OAuth Proof.
  • Retain one exact platform profile for a live ceremony and forbid profile substitution after authorization starts.
  • Keep ceremonies one-shot: remove normative mid-ceremony persistence and resume, and require a fresh GitHub ceremony when a consumed exchange response is lost.
  • Assign browsing contexts, redirect transport, interruption behavior, and application handoff to the browser architecture.

Proof construction and ledger selection

  • Rename platformVerifierVersion to platformCeremonyVersion and define it as the shared version boundary for the Authorization Digest construction, platform OAuth construction, and platform-specific proof statement.
  • Keep verifier contracts and implementations outside that boundary: different ledgers may enforce the same Platform Ceremony Version with different verifier artifacts.
  • Remove the separate pkceNonce; derive the PKCE verifier from the Authorization Digest and its existing fresh authorizationNonce.
  • Keep that nonce private until token exchange completes, then reuse the copy already carried by the OAuth Proof for verifier recomputation.
  • Remove the redundant PKCE domain and update the golden vector and conformance requirements.
  • Let application composition select a Ledger Profile for each ceremony while requiring the Verifier Dispatcher to derive the Ledger ID independently from the Execution Ledger.

Authenticated delivery

  • Permit a deployment-configured set of application origins.
  • Deliver only over a live channel authenticated to an exact configured origin.
  • Ignore caller-supplied forwarding targets and add multi-origin positive and foreign-origin negative coverage.

Platform behavior

  • Define the GitHub Token Service's semantic inputs, outputs, statelessness, fixed configuration, and isolated-prover boundary while leaving endpoint and wire formatting to browser/deployment specifications.
  • Preserve the local checks binding the returned attestation, authorization code, client, redirect, verifier, bearer opening, and disclosure.
  • State directly that Google has no server-side token exchange; X remains browser-owned.
  • Require X's first notarized token request to reach X within the 30-second authorization-code deadline; later response and proving work are outside it.

Scope

Normative documentation only:

  • specs/libid.md
  • specs/ceremony-common.md
  • specs/platform-ceremonies.md

The TypeScript ceremony architecture and package test plan remain in #13.

Validation

  • git diff --check

@Wondertan
Wondertan force-pushed the docs/ceremony-browser-contract branch 3 times, most recently from 3ef62fd to 88765ad Compare August 24, 2026 12:51
Co-authored-by: xgreenx <xgreenx9999@gmail.com>
Signed-off-by: Wondertan <hlibwondertan@gmail.com>
@Wondertan
Wondertan force-pushed the docs/ceremony-browser-contract branch from 88765ad to ab3a70b Compare August 24, 2026 18:59
Signed-off-by: Wondertan <hlibwondertan@gmail.com>
Signed-off-by: Wondertan <hlibwondertan@gmail.com>
Signed-off-by: Wondertan <hlibwondertan@gmail.com>
The Platform Ceremony Version identifies the ceremony boundary and is bound in
the digest, so it is the same on every Consumer Chain. What a Consumer Chain
routes on is a second number, the Verifier Version: local to that chain,
assigned on its own cadence, and not in the digest. Two Verifier Versions may
implement one Platform Ceremony Version, so a proof stays acceptable across a
verifier upgrade; the Consumer's nullifier, not the route, prevents replay.

Because routing no longer names what the digest binds, the Proof Verifier can
no longer recompute the digest. The Submission becomes a platform, a Verifier
Version, a value, and an opaque Submission Payload that only the selected
Platform Verifier decodes. That verifier refuses any ceremony version but its
own before a fee moves, recomputes the digest from what it decoded and its own
Chain ID, and returns the digest with its fields. REQ-COMMON-02, 46 and 06C
move accordingly.

Signed-off-by: xgreenx <xgreenx9999@gmail.com>
Assisted-by: Claude Fable 5.1
docs(specs): a Verifier Version beside the Platform Ceremony Version
@Wondertan
Wondertan merged commit 79ad76b into main Sep 3, 2026
4 checks passed
@Wondertan
Wondertan deleted the docs/ceremony-browser-contract branch September 3, 2026 09:07
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants