libID protocol specification

Status: proposed normative libID protocol specification.

This is the required entrypoint for the libID protocol specification. The linked documents form one normative specification and are not independent specifications.

Identity ceremonies

Common ceremony rules define the constructions and invariants shared by every identity platform.
Identity-platform ceremonies define the launch profiles for Google, X, and GitHub.
Chain profiles define what those constructions commit on one destination chain.

Browser transport

Popup transport defines the logical connection between an application document and its popup: origin allowlists, the message model, delivery guarantees, navigation and closure, continuity across popup-document replacement, and failure semantics. Browser protocols cite it instead of restating opener, isolation, and continuity mechanics.

Browser ceremony and services

Ceremony Cross-Document Protocol defines its documents, routes, private navigation inputs, messages, events, and phases over popup transport.
OAuth Bridge defines public platform configuration and callback ingress.
CCDP Distribution defines static resource responses, Callback configuration insertion, isolation policies, and compatible publication.

These chapters are normative browser/service boundaries. TypeScript APIs, build tooling, UI projections, dependency pins, and qualification evidence belong to the implementation documentation, not this specification.

System model and specification ownership

libID turns an identity-platform authorization into a proof that a Consumer applies to one proof-bound transaction:

User -> Identity Platform -> Canonical Runtime -> Proving Circuit -> Consumer
                                                                       |
                                                                       v
                                                               Proof Verifier
                                                                       |
                                                               Platform Verifier
                                                                       |
                                                               Notary Service
                                                               (X and GitHub,
                                                                once per
                                                                attestation)

The Consumer never verifies evidence itself. It calls the Proof Verifier, which selects the Platform Verifier registered for the named identity platform and ledger-local Verifier Version. Several Verifier Versions may implement the same Platform Ceremony Version. The selected Platform Verifier obtains attestation authenticity from the Notary Service once for each attestation that profile carries. Google carries none, so its path reaches no Notary Service and pays no fee; X and GitHub carry two each. The result travels back as an accept-or-reject decision plus the authenticated operation domain, Authorized Transaction Data, and client identifier, and the Consumer decides what that transaction means. Common §5.1 owns this path.

The Application, OAuth Bridge, and CCDP Distribution may have different operators. The Application controls its frontend and selects its ceremony configuration; the Bridge owns OAuth registrations, public client configuration, and callback ingress; the Distribution supplies CCDP browser code and proving assets. Those deployments are trusted for the local browser ceremony, but not to choose authoritative identity fields, change the proof-bound operation, or widen proof validity. GitHub token exchange and identity notarization run in the browser; there is no confidential exchange service. The identity platform controls the authenticated account response. The notary authenticates X/GitHub transcripts and their creation times. Verifier governance selects the Supported Version Set, accepted verifier artifacts, and trust roots. Each Platform Profile fixes its protocol parameters. The Consumer Chain authenticates the Transaction Author and supplies its Chain ID and Block Time.

Principal	Knows and can	Trusted for	Not trusted for
User	chooses an account and authorizes an operation	human intent	parsing or cryptographic verification
Application operator	selects a Bridge and operation; starts or withholds work	frontend availability and declared ceremony inputs	identity fields, proof target, or proof validity
OAuth Bridge operator	holds OAuth registrations and public application credentials; configures and serves Callback	correct public configuration, Callback delivery, and availability	ledger identity, digest, notary-key, or validity decisions
CCDP Distribution publisher	supplies browser code, proving assets, and response policies to multiple Bridges	correct code and asset supply under ASM-CCDP-01	authority to change ledger verification rules
Identity-platform operator	authenticates accounts and issues signed or TLS-authenticated responses	the `ASM-PROV-*` behavior the selected profile cites	the proof-bound transaction or Transaction Author
Notary operator	operates the X/GitHub attestation key and observes sessions	`ASM-NOTARY-01`	user intent or transaction authorization
Verifier governance administrator	activates verifier artifacts, trust roots, and the Supported Version Set	correct authority lifecycle	user consent

The principal trust roots are Google’s active signing moduli, the active X/GitHub notary keys, the selected proof-verifier artifacts, the Proof Verifier that dispatches to them, the Platform Verifiers it selects, Verifier governance, and Consumer Chain consensus. The Proof Verifier is the most concentrated of these: every Consumer takes its accept-or-reject decision, operation domain, and Authorized Transaction Data from that one component, so its compromise authorizes arbitrary transactions at every Consumer at once. A compromised Platform Verifier does the same for one platform and version, because it is the role that verifies the proof and binds the digest. Replacing or retiring a root stops future acceptance after the change takes effect; it does not undo bindings or sessions already committed. Loss of an application deployment is a liveness failure. Compromise of the Canonical Runtime build or its supply chain defeats local client and operation construction. Compromise of a platform signing root, notary key, or selected Platform Verifier can mint future evidence for the affected profiles. Compromise of Verifier governance can change every accepted root and verifier.

Subject	Single normative owner
Authorization Digest, PKCE, extraction, client binding, evidence time	Common ceremony rules
Chain ID, Transaction Author, Block Time, and transaction-data encoding	Chain profiles, with the Consumer’s protocol fixing each transaction kind’s arguments
Platform endpoints, fields, trust roots, and proof projections	Identity-platform ceremonies
Popup origin allowlists, message model, delivery, navigation, closure, and continuity guarantees	Popup transport
Ceremony documents, routes, private fragments, messages, events, and phase transitions	CCDP
Public ceremony configuration and callback ingress	OAuth Bridge
Static response policies, aggregate Callback artifact, immutable asset publication	CCDP Distribution
Package APIs, UI projections, build tooling, and qualification evidence	implementation documentation (non-normative)
Transaction dispatch and author authentication	Consumer protocol
Verification dispatch, replay recording, trust roots, and version governance	Common ceremony rules

The linked ceremony chapters specify the ceremony layer. The browser and consumer protocol specifications do not redefine its proof fields or security assumptions. A profile is implementable only when its exact proving artifacts are published. It is usable on a destination chain only while that chain’s Verifier Governance Process selects a conforming verifier artifact and, where required, a compatible Notary Service.

Enforceable guarantees and accepted boundaries

The Platform Verifier enforces the proof-bound operation — comparing the Authorization Digest public input on Google, recomputing the revealed code_verifier on X and GitHub (REQ-COMMON-02A, REQ-COMMON-15A) — verifies the proof under the artifact selected for the submitted platform and version (REQ-COMMON-45), and enforces authenticated freshness. Proof-field provenance is the signed ID Token on Google and the revealed attestation bytes on X and GitHub; the Proving Circuit proves only what cannot be read from that evidence, which is Google’s signature relation and, on X and GitHub, that one hidden bearer opens both sessions’ commitments. The Consumer enforces replay rejection by recording every Authorization Digest it accepts before applying an effect (REQ-COMMON-03, REQ-COMMON-03A). The Canonical Runtime locally enforces the selected OAuth client and redirect profile. The protocol assumes the named identity-platform parser, PKCE, delivery, notary, browser, verifier-soundness, and chain behaviors. It does not enforce human understanding of a platform consent screen, prevent cross-deployment presentation of the same proof, or make mutable display metadata authoritative.

Collusion sanity check — non-exhaustive: application plus a malicious identity-platform operator defeats identity authenticity for that platform but not Authorization Digest binding; any pair containing compromised Verifier governance, a selected verifier, or the applicable platform/notary trust root inherits that single-root compromise. This does not model adaptive or three-party compromise, shared key custody, browser supply-chain compromise, or Consumer Chain failure.

Conventions

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” throughout this specification are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

Protocol parameters

Protocol parameters are unsigned 64-bit values expressed in seconds. The Platform Profile fixes the value of every parameter it names, as it fixes its request lines, so one (identityPlatform, platformCeremonyVersion) pair selects one value on every Consumer Chain and at every Verifier Version implementing that profile.

Platform Profile	`proofLifetime`	`maxFutureAttestationSkew`
`("google", 1)`	not named	not named
`("x", 1)`	3600	300
`("github", 1)`	3600	300

proofLifetime is the maximum age of the attestation that supplies evidence time: the X token attestation and the GitHub token-exchange attestation. maxFutureAttestationSkew is the maximum lead of an X/GitHub attestation timestamp over Block Time. Google’s signed exp bounds its validity, so ("google", 1) names neither. Verifier governance controls the Supported Version Set and the trust roots, so a proof is accepted only while a Verifier Version implementing its profile is supported and the trust roots it relies on are active.

REQ-PARAM-01: The Platform Profile MUST fix each protocol parameter it names as one unsigned 64-bit number of seconds. The Platform Verifier MUST NOT expose an operation that changes a value its profile fixes. The Verifier Governance Process MUST NOT change that value, including by upgrading a Platform Verifier registered for the profile. A different value changes the ceremony boundary of REQ-COMMON-01B, so it takes a new Platform Ceremony Version, verified by a new Platform Verifier registered under its own Verifier Version. Necessity: the Canonical Runtime derives a proof’s expiry from the profile it ran, so one Platform Ceremony Version must mean one value on every Consumer Chain and through every verifier upgrade.
REQ-PARAM-02: The Platform Verifier MUST use the value its profile fixes, with checked arithmetic, whenever a ceremony rule names one of these parameters. The Platform Verifier MUST NOT accept a caller-supplied substitute. Necessity: callers must not widen proof freshness.
TEST-PARAM-01 (exercises REQ-PARAM-01, REQ-PARAM-02): The values above reproduce the platform validity vectors; a caller override and an overflowing calculation fail; a Platform Verifier exposes no operation that changes a value its profile fixes; and two Platform Verifiers implementing one profile, on different Consumer Chains, under different Verifier Versions, or before and after an upgrade, apply the same values to the same evidence time.

Security Considerations

Each X and GitHub Platform Profile fixes its acceptance window, which is therefore the same on every Consumer Chain and at every Verifier Version implementing that profile. Verifier governance can end a proof’s acceptance before the window closes by retiring a trust root it relies on or every Verifier Version implementing its profile. Google remains bounded by its signed expiry. The linked chapters define the remaining assumptions, security properties, requirements, and platform-specific security considerations.

References

Normative: [RFC2119], [RFC8174].