Skip to content

docs(specs): define CCDP and ceremony service contracts - #13

Open
Wondertan wants to merge 28 commits into
docs/popup-connection-architecturefrom
docs/ceremony-browser-architecture
Open

Wondertan wants to merge 28 commits into
docs/popup-connection-architecturefrom
docs/ceremony-browser-architecture

Conversation

@Wondertan

@Wondertan Wondertan commented Aug 20, 2026

Copy link
Copy Markdown
Member

Normative browser and service contracts

CCDP relies on the popup transport specification in #22; this PR is based on that branch. It also includes #31's framing prerequisite without reverting its canonical changes.

The existing readable document structure is retained, with stable requirement/test anchors and explicit security boundaries. Browser validation ownership is reconciled separately: Prover parses and correlates evidence, Application validates delivered structure, and ledger verification remains authoritative. Neither endpoint adds local notary-signature verification or a separate Google nonce-versus-expected-digest comparison.

Implementation APIs, module layout, proving/notary integration, asset build tooling, UI, metrics, and qualification now live in implementation PR #28, with rendered package docs. No implementation code is changed here.

GitHub simplification is split with profile PR #35, based on #31: this PR owns configuration and ProveIdentity credential delivery, removal of the Bridge token endpoint, and event/CSP cleanup. #35 owns browser notarization, the fully revealed and canonically validated token request, security assumptions, and platform conformance tests. The existing profile chapters in this branch retain the pre-change semantics until that companion is integrated; #28 follows these documentation changes separately. Draft versions remain unchanged.

The fixed-callback migration and Callback-to-Prover authenticated-origin handoff remain explicitly tracked implementation work in #28. The previous architecture snapshot is preserved; this PR's package placeholders and implementation documents are removed from its scope.

@Wondertan
Wondertan force-pushed the docs/ceremony-browser-architecture branch 2 times, most recently from 1795a93 to 42298b3 Compare August 20, 2026 02:10
@Wondertan Wondertan changed the title docs(ceremony): add package architecture docs(ceremony): add package architecture and test plan Aug 20, 2026
@Wondertan
Wondertan force-pushed the docs/ceremony-browser-architecture branch 10 times, most recently from cebe2ed to f055711 Compare August 20, 2026 09:40
@Wondertan
Wondertan force-pushed the docs/libid-ceremony-specs branch 3 times, most recently from b98ba12 to da4f501 Compare August 20, 2026 10:05
@Wondertan
Wondertan force-pushed the docs/ceremony-browser-architecture branch from 52db663 to 4deb2a5 Compare August 20, 2026 16:49
@Wondertan Wondertan changed the title docs(ceremony): add package architecture and test plan docs(ceremony): define browser architecture Aug 20, 2026
@Wondertan
Wondertan changed the base branch from docs/libid-ceremony-specs to main August 20, 2026 16:49
@Wondertan
Wondertan force-pushed the docs/ceremony-browser-architecture branch 5 times, most recently from fe6cf6c to 1add82b Compare August 20, 2026 17:49
@Wondertan
Wondertan force-pushed the docs/ceremony-browser-architecture branch 2 times, most recently from 9074ebb to 04bb956 Compare August 24, 2026 12:51
Keep the readable routes, messages, events and phases. Delegate transport to the popup specification and move implementation APIs, build tooling and qualification to the implementation PR.

Assisted-by: GPT-5
Signed-off-by: Wondertan <hlibwondertan@gmail.com>
Report valid OAuth denial with one-way Denied. Application cancellation retires the local run; popup navigation and closure stay composition-owned.

Assisted-by: GPT-5
Signed-off-by: Wondertan <hlibwondertan@gmail.com>
Define Event as an interface like the other messages. Nest operationId and attributes under optional instrumentation and preserve their validation and protocol boundaries.

Assisted-by: GPT-5
Signed-off-by: Wondertan <hlibwondertan@gmail.com>
Wondertan added a commit that referenced this pull request Sep 13, 2026
Align Callback artifact, embedded deployment data, URL clearing, version selection and browser qualification with architecture PR #13 at d42c0c4.

Assisted-by: GPT-6
Signed-off-by: Wondertan <hlibwondertan@gmail.com>
@Wondertan
Wondertan force-pushed the docs/ceremony-browser-architecture branch from 2ff7040 to 01d5fb0 Compare September 13, 2026 14:00
Wondertan added a commit that referenced this pull request Sep 13, 2026
Match architecture PR #13 at 8d5f46b: remove default/override fallback and fail locally when the selected version has no valid deployment tuple.

Assisted-by: GPT-6
Signed-off-by: Wondertan <hlibwondertan@gmail.com>
Rename Denied to UserDenied and Abort to CeremonyFailed, including wire discriminators, message links, conformance cases, and sequence labels. Preserve outcome semantics and local cancellation.

Assisted-by: GPT-5
Signed-off-by: Wondertan <hlibwondertan@gmail.com>
Accept a resolved notary address for any platform without requiring notarization. Keep nullable wire input and let the selected profile require an address only when needed.

Assisted-by: GPT-5
Signed-off-by: Wondertan <hlibwondertan@gmail.com>
Align browser identity ownership, GitHub routing and admission, and transport failure and closure semantics. Distinguish ledger-local verifier versions from ceremony versions without changing the browser flow or ledger verification.

Assisted-by: GPT-5
Signed-off-by: Wondertan <hlibwondertan@gmail.com>
Wondertan added a commit that referenced this pull request Sep 13, 2026
Align Callback artifact, embedded deployment data, URL clearing, version selection and browser qualification with architecture PR #13 at d42c0c4.

Assisted-by: GPT-6
Signed-off-by: Wondertan <hlibwondertan@gmail.com>
Wondertan added a commit that referenced this pull request Sep 13, 2026
Match architecture PR #13 at 8d5f46b: remove default/override fallback and fail locally when the selected version has no valid deployment tuple.

Assisted-by: GPT-6
Signed-off-by: Wondertan <hlibwondertan@gmail.com>
Incorporate PR #31 commit 5afdf08: maximal JSON whitespace runs, single-range extraction with cross-range delimiter counting, header conformance vectors, and matching rationale.

Preserve the reconciled browser validation, request-selected notary, and origin admission contracts. Correct the stale code_verifier circuit attribution and GitHub token-layout reference.

Assisted-by: GPT-5
Signed-off-by: Wondertan <hlibwondertan@gmail.com>
@Wondertan
Wondertan force-pushed the docs/ceremony-browser-architecture branch from 4fa2a8d to 9f363b1 Compare September 14, 2026 10:49
Allow same-origin trailing-slash redirects for directory paths that serve
no resource, ending in an inert failure. Keep actual protocol and asset
resources redirect-free and update the existing conformance case.

Assisted-by: GPT-6
Signed-off-by: Wondertan <hlibwondertan@gmail.com>
Publish and forward the public token-exchange credential, reduce the Bridge to configuration and Callback hosting, and remove the GitHub event and network-policy exceptions. Transcript and proving semantics are reviewed in a separate profile PR.

Assisted-by: GPT-5
Signed-off-by: Wondertan <hlibwondertan@gmail.com>
Keep browser exchange as the current profile choice without prohibiting Bridge-assisted OAuth for another platform or later ceremony version. Scope route exclusions and tests accordingly, and remove stale confidential-endpoint prose from the Distribution boundary.

Assisted-by: GPT-5
Signed-off-by: Wondertan <hlibwondertan@gmail.com>
Rename the public PlatformConfig and ProveIdentity field and its prose references. Keep the OAuth client_secret parameter and all validation semantics unchanged.

Assisted-by: GPT-5
Signed-off-by: Wondertan <hlibwondertan@gmail.com>
Admit Origin-less configuration GET requests using browser same-origin Fetch Metadata without checking the Bridge origin against the allowlist. Keep explicit Origin admission and Callback authentication unchanged; leave redirect construction with the Application and registration with the operator. Update conformance cases.

Assisted-by: GPT-5
Signed-off-by: Wondertan <hlibwondertan@gmail.com>
Wondertan added a commit that referenced this pull request Sep 15, 2026
Align Callback artifact, embedded deployment data, URL clearing, version selection and browser qualification with architecture PR #13 at d42c0c4.

Assisted-by: GPT-6
Signed-off-by: Wondertan <hlibwondertan@gmail.com>
Wondertan added a commit that referenced this pull request Sep 15, 2026
Match architecture PR #13 at 8d5f46b: remove default/override fallback and fail locally when the selected version has no valid deployment tuple.

Assisted-by: GPT-6
Signed-off-by: Wondertan <hlibwondertan@gmail.com>
Wondertan added a commit that referenced this pull request Sep 15, 2026
Align Callback artifact, embedded deployment data, URL clearing, version selection and browser qualification with architecture PR #13 at d42c0c4.

Assisted-by: GPT-6
Signed-off-by: Wondertan <hlibwondertan@gmail.com>
Wondertan added a commit that referenced this pull request Sep 15, 2026
Match architecture PR #13 at 8d5f46b: remove default/override fallback and fail locally when the selected version has no valid deployment tuple.

Assisted-by: GPT-6
Signed-off-by: Wondertan <hlibwondertan@gmail.com>
Wondertan added a commit that referenced this pull request Sep 15, 2026
Align Callback artifact, embedded deployment data, URL clearing, version selection and browser qualification with architecture PR #13 at d42c0c4.

Assisted-by: GPT-6
Signed-off-by: Wondertan <hlibwondertan@gmail.com>
Wondertan added a commit that referenced this pull request Sep 15, 2026
Match architecture PR #13 at 8d5f46b: remove default/override fallback and fail locally when the selected version has no valid deployment tuple.

Assisted-by: GPT-6
Signed-off-by: Wondertan <hlibwondertan@gmail.com>
* docs(specs): admit origin patterns in application allowlists

An operator serving one application per subdomain cannot enumerate them, so
an allowlist member may now be a pattern; the popup transport owns its
grammar and match, and no layer restates them.

The union stays literal, so a pattern never absorbs the CCDP origin, and the
peer is still bound to the exact observed origin. What widens is the type of
an existing Callback input: an older Callback accepts a pattern and matches
no peer, so a deployment waits for a Callback that understands one.

Assisted-by: Claude Opus 5
Signed-off-by: Green Baneling <XgreenX9999@gmail.com>

* docs(specs): refuse star members and member spellings as origins

A URL parser reports a suffix with a port, a trailing dot or an empty label
canonical, so well-formedness needs byte checks the parser does not do, and
the spec now names them rather than leaving each layer to infer them.

A star that is not a well-formed pattern is a typo, not an exact origin, and
admitting it only postpones the failure to a ceremony that never becomes ready.

Canonicality is tested ahead of membership of either kind, because the literal
branch otherwise lets a peer claim a member's own spelling and bind it.

Assisted-by: Claude Opus 5
Signed-off-by: Green Baneling <XgreenX9999@gmail.com>

* docs(bridge): refuse IP-literal suffixes and a pattern CCDP origin

A URL parser reports 127.0.0.1 canonical and every byte check passes it, so
the grammar admitted https://*.127.0.0.1 although an address has no labels to
delegate and the loopback exception covers exact hosts only.

The CCDP origin reaches the Callback's frame-src, so a pattern in that input
would reach a Content-Security-Policy, and the conformance list now says so.

Rejecting an Origin that spells a pattern is the rule that a member spelling is
never an observed origin, not an exception to literal membership.

Assisted-by: Claude Opus 5
Signed-off-by: Green Baneling <XgreenX9999@gmail.com>

* docs(specs): match the merged client's origin pattern grammar

The merged popup package spells a member `*.handles.link`, admits every depth
below the suffix, and accepts a one-label suffix, so the grammar described here
named a list the client rejects outright.

The bridge refuses `*` and a one-label suffix at startup: refusal narrows
admission, so the two sides cannot disagree, and an operator reads an error
rather than a ceremony that never becomes ready. Member validation now happens
in the popup endpoint, not the Callback.

Assisted-by: Claude Opus 5
Signed-off-by: Green Baneling <XgreenX9999@gmail.com>

* docs(bridge): the bridge admits a subset, not exactly the same set

A bridge refuses an origin carrying a byte its own policy composition
cannot name, so it admits fewer origins than the browser side under the
same member. Only the reverse would let the two disagree.

Assisted-by: Claude Opus 5
Signed-off-by: Green Baneling <XgreenX9999@gmail.com>

* docs(specs): state the origin pattern rules, argue them less

The pattern prose restated the transport's grammar and matching rule, then
explained each rule it stated. A restated normative statement can drift from
the one that owns it, and an explanation is not a requirement.

The rules are unchanged: the member kinds, the two startup refusals, the
subset relation and its direction, the literal union, the exact echoed origin,
the deployment ordering, and where member validation happens. The cut examples
and the rejected spellings live in the TEST entries.

Assisted-by: Claude Opus 5
Signed-off-by: Green Baneling <XgreenX9999@gmail.com>

* docs(specs): the bridge narrows no allowlist the transport admits

An allowlist as wide as `*` is the responsibility of whoever configures it, so
the bridge-only startup refusals come out.

The two versioning rules disagreed; the artifact contract now owns one
coordinated-upgrade exception and the bridge cites it.

TEST-CCDP-04 rejected any member's own spelling, which also rejects an exact
member's ordinary case; it is a pattern member's spelling.

Restored: the bound on the MAY, canonicality ahead of membership of any kind,
and Callback's exact-authentication.

Assisted-by: Claude Opus 5
Signed-off-by: Green Baneling <XgreenX9999@gmail.com>

* docs(bridge): the bridge narrows no member on width

The byte filter it applies to every origin it reads is a member refusal,
so a blanket claim that it adds none contradicts the paragraph below.

Assisted-by: Claude Opus 5
Signed-off-by: Green Baneling <XgreenX9999@gmail.com>

* docs(bridge): the bridge and the browser admit the same origins

The subset language covered a byte filter the bridge no longer applies
to application origins. Only the CCDP origin becomes a policy source.

Assisted-by: Claude Opus 5
Signed-off-by: Green Baneling <XgreenX9999@gmail.com>

---------

Signed-off-by: Green Baneling <XgreenX9999@gmail.com>
@cloudflare-workers-and-pages

Copy link
Copy Markdown

🚀 Deploying Preview to Cloudflare 🚀

Preview Deployments by commit

Status Deployment URL Commit Updated (UTC) See this deployment's details
  • Build: Failed ❌

View logs ↗
2b9afbf 2026-09-23T17:08:02.054Z View logs ↗

This branch has not been deployed

No deployments
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.

3 participants