Repository navigation
State where a key directory's revocation list may be served - #64
Merged
Merged
Conversation
All three SDKs poll a revocation_url only when it is on the host and port that served the key directory, or on a subdomain of that host on that port, and skip any other value. The protocol never said so, although it states the same binding for WellKnownManifest.endpoint, so a party that read only the specification could publish its list anywhere and have every verifier ignore its revocations. The WBAFile.revocation_url comment now states the rule: the URL is absolute and anchored to the directory's host and port, a consumer polls no other value, a party that serves one directory per host advertises a separate URL in each, and the host and port are matched as for the endpoint. It also says that the protocol names no path for the list: the publishing party chooses it, and a consumer reads it from the field. The redirect sentence the comment already carried is unchanged. gen/ is regenerated; only the field's comment and descriptions change. Comments only; no wire change.
…ce pages The Emergency Revocation section gains the rule the WBAFile.revocation_url comment now states, in the words the endpoint host binding uses: the URL is absolute and on the same host and port that serve the key directory, or on a subdomain of that host on that port, and a consumer polls no other value, because a directory is fetched from whichever origin a signature names before the signature is checked. A party that serves one directory per host, such as a registry giving each agent a subdomain, advertises a separate URL in each, and the protocol names no path for the list. The other pages link to that section rather than repeat it: the proto reference's revocation_url row, the fourth verification step for Exchange operators, and the Identity Service page, which says each agent's directory names its list on the agent's own subdomain and that the path it uses is its own choice. Docs only; no wire change.
A new section says that a key directory has always named its revocation list by URL and never at a fixed path, that the SDKs poll that URL only on the host and port that served the directory or a subdomain of it, and that the protocol only now says so: a service that publishes one directory per agent subdomain advertised a single URL for all of them, every other agent's list went unpolled, and revoked keys kept verifying until they expired. It also records why the SDK exports no constant for the path. A verifier reads the pointer and holds no path, a constant beside WBADirectoryPath would read as a second protocol path and invite verifiers to build the URL, and it would fail the SDK's inclusion test. What both sides share is the anchoring, already defined once as HostAnchored and pinned by the host-rule corpus. Redirect-hop anchoring and userinfo in a revocation_url are left open. The host-anchoring section now points to where the revocation URL's half of the rule is written down. Docs only; no wire change.
One Unreleased paragraph, the same in both changelogs: the rule the WBAFile.revocation_url comment and the Emergency Revocation section now state, that a party serving one directory per host advertises a separate URL in each, that the protocol names no path for the list and the SDK exports none, and which pages link to the rule. Docs only; no wire change.
main gained fourteen pull requests since this branch was cut, among them
the Broker relevance docs, the edge function's AI-crawler defaults, the
SSRF-guard proto comments, the music filter-key schema and the reporting
obligation. None of them touches a key directory's revocation_url, the
SDK's revocation checks or the Emergency Revocation section, so what this
branch states stays true on top of main. No release was cut in between, so
both sides' changelog entries stay under Unreleased.
Resolution ledger:
- textual conflicts:
- proto/CHANGELOG.md and its website mirror -> union: this branch's
revocation_url entry first, then main's nine new entries, all under
Unreleased. The two Unreleased sections stay text-identical, and the
diff of each file against main is one pure-addition hunk.
- gen/descriptor.binpb -> regenerated with buf build from the merged
proto, never content-merged.
- semantic, auto-merged, reviewed: proto/fora/v1/fora.proto,
docs/design-history.md and the authentication, Identity Service,
Exchange operator and proto reference pages -> each differs from main by
exactly this branch's hunks.
- generated, auto-merged then regenerated: gen/go, gen/python/wire,
gen/ts/wire and gen/jsonschema -> buf generate and gen-sdk-types.sh
reproduce the auto-merged bytes.
- everything else: main's, unchanged.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
A key directory names its revocation list in
revocation_url, and all three SDKs poll that URL only when it sits on the host and port that served the directory, or on a subdomain of that host on that port. The protocol never said so, although it states the same binding forWellKnownManifest.endpoint. A party reading only the specification could put its list anywhere and have every verifier ignore its revocations. That has happened: a reference-implementation service that publishes one directory per agent subdomain advertised a single revocation URL for all of them, every other agent's list went unpolled, and a revoked key kept verifying until it expired.The change also settles a question raised while aligning that service with the SDK: whether the SDK should export a constant for the revocation list's path. It should not. The protocol names no path, a verifier reads the pointer and never derives it, and the SDK's inclusion test admits only what the protocol defines. What the two sides share is the host binding, and that already has one definition,
HostAnchored, pinned in all three languages by the host-rule corpus.What changes
fora.proto: comments only.WBAFile.revocation_urlgains the rule: the URL is absolute and on the same host and port that serve the directory, or on a subdomain of that host on that port; a consumer polls no other value; a party that serves one directory per host advertises a separate URL in each; the protocol names no path for the list. The sentences the comment already carried are unchanged.gen/is regenerated, and only the field's comment and schema descriptions change.docs/design-history.md: a new section records why the SDK names no revocation-list path, and the host-anchoring section points to where the revocation URL's half of the rule is written down.Docs and comments only: no wire change, no SDK API or behaviour change, and the SDK corpora are unchanged.
Left open
Whether each redirect hop of the revocation poll must stay anchored, and whether a
revocation_urlmay carry userinfo, which the endpoint rule forbids. Neither is decided here.Checks
./scripts/ci-local.shpasses: no generated drift, Go build, vet and tests, doc conformance, parity matrix, site build with link validation, SDK types parity,buf breaking.The reference implementation needs no re-pin for this change.