Skip to content

State where a key directory's revocation list may be served - #64

Merged
legendko merged 5 commits into
mainfrom
docs/fora-192-revocation-url-host
Nov 17, 2026
Merged

legendko merged 5 commits into
mainfrom
docs/fora-192-revocation-url-host

Conversation

@legendko

@legendko legendko commented Nov 9, 2026

Copy link
Copy Markdown
Contributor

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 for WellKnownManifest.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_url gains 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.
  • Authentication page: the Emergency Revocation section states the rule in the words the endpoint host binding uses.
  • Proto reference, Exchange-operator verification steps, Identity Service page: each links to that section rather than restating it.
  • 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.
  • Changelogs: the same Unreleased paragraph in both.

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_url may carry userinfo, which the endpoint rule forbids. Neither is decided here.

Checks

  • ./scripts/ci-local.sh passes: no generated drift, Go build, vet and tests, doc conformance, parity matrix, site build with link validation, SDK types parity, buf breaking.
  • Python SDK: 2933 passed. TypeScript SDK: 3880 passed, 4 skipped.
  • All 259 quotes the reference implementation's e2e obligation registry takes from this repo still match.

The reference implementation needs no re-pin for this change.

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.
@legendko
legendko merged commit bc08bf2 into main Nov 17, 2026
4 checks passed
@legendko
legendko deleted the docs/fora-192-revocation-url-host branch November 17, 2026 15:12
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.

1 participant