Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 38 additions & 1 deletion docs/design-history.md
Original file line number Diff line number Diff line change
Expand Up @@ -2144,7 +2144,10 @@ The rule is now normative and stated where an implementer will find it: the
It was not always — for most of this work it lived only in one client's code,
inherited from a port rather than decided, which is why an Exchange advertising a
separate domain could be conformant and then stop being so. Enforcement sits in
the shared endpoint resolver, so every consumer of that resolver inherits it.
the shared endpoint resolver, so every consumer of that resolver inherits it. The
revocation URL's half of the rule was written down later, on the
`WBAFile.revocation_url` comment and the authentication page; the section on where a
revocation list sits says why.

The anchor is the host that SERVED the manifest, not the `domain` member inside
it. That member is self-asserted, so anchoring to it would let a hostile manifest
Expand Down Expand Up @@ -2565,6 +2568,40 @@ directory, so a predicate built on a resolver that has never fetched an Exchange
directory screens nothing for that Exchange. The cache polling each Exchange's own list
itself would close that gap; this change leaves it as it was and only scopes the answer.

## A revocation list sits on its directory's host, at a path the protocol does not name

A key directory names its revocation list by URL, in `revocation_url`. The protocol has
never fixed a path for it: the list was a pointer before the Web Bot Auth split, as the
manifest's `invalidation_url`, and it stayed one after. The SDKs read only the pointer.

They also poll it only when it sits on the host and port that served the directory, or on
a subdomain of that host on that port. A directory is fetched from whichever host a
signature names, before the signature is checked, so a pointer allowed anywhere would let
any party aim every verifier's poller at a host of its choosing. All three SDKs enforce
that, but the protocol never said so, although it stated the same binding for an
Exchange's endpoint. A producer that read only the specification could therefore put its
list anywhere, and one did: a service that publishes a directory for each agent on the
agent's own subdomain advertised one revocation URL for all of them. That URL could
anchor to one host at most, so the other agents' lists were never polled, and a key
revoked there kept verifying until it expired. Nothing failed. The rule is now normative,
on the field and on the authentication page, in the words the endpoint rule uses.

The path is left to the publisher, and the SDK deliberately exports no constant for it.
One was proposed, so that the service publishing a list and the verifier reading it would
hold the same value. But the verifier holds no value: it reads the pointer. A constant
next to `WBADirectoryPath` would read as a second protocol path, which is the shape that
invites a verifier to build the URL itself, and it would fail the first condition of the
SDK's inclusion test (ADR-020 §3): that the thing be defined by the protocol. What the two
sides do share is the anchoring, and that already has one definition, `HostAnchored`, held
to the same verdicts in all three languages by the host-rule corpus. The path a deployment
serves its list at is that deployment's own constant. The SDK's test origins pick one path
for their fixtures and other fixtures use other paths; that is deliberate, since no
verifier may depend on any of them.

Two questions about the poll's fetch are left open: whether each redirect hop must stay
anchored, and whether a `revocation_url` may carry userinfo, which the endpoint rule
forbids.

## The TypeScript document reader carries its own bounds

Go and Python bound a document read in the reader: Go reads the body through a limit and
Expand Down
Binary file modified gen/descriptor.binpb
Binary file not shown.
12 changes: 12 additions & 0 deletions gen/go/fora/v1/fora.pb.go

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

3 changes: 2 additions & 1 deletion gen/jsonschema/fora.v1.WBAFile.schema.json
Original file line number Diff line number Diff line change
Expand Up @@ -55,7 +55,8 @@
"type": "array"
},
"revocation_url": {
"description": "Directory-level emergency revocation channel. One per directory; the list\n it points to enumerates revoked key thumbprints. Consumers poll on a 300s\n cadence (±10% jitter) and replace their local revoked set with the response.\n The list revokes keys of this directory only: a consumer checks a\n signature against the list of the directory that published its key, and\n never applies this list to another party's key. A fetch of the list MAY\n follow up to five redirects (see \"Redirects\" under Well-Known Discovery).",
"description": "The URL MUST be absolute and on the same host AND PORT that serve this\n directory, or on a subdomain of that host on that port. A consumer MUST NOT\n poll a revocation_url anywhere else: a directory is fetched from whichever\n host a signature names, before that signature is checked, so a list on an\n unrelated host would let any party aim every verifier's poller at a host of\n its choosing. A list named anywhere else therefore revokes nothing, and a\n party that serves one directory per host advertises a separate\n revocation_url in each. The host match is on a full dot-delimited label\n boundary, and a port equal to the scheme's default and an omitted port are\n the SAME port. The protocol names no path for the list: the publishing party\n chooses it, and a consumer reads it from this field and never derives it.",
"title": "Directory-level emergency revocation channel. One per directory; the list\n it points to enumerates revoked key thumbprints. Consumers poll on a 300s\n cadence (±10% jitter) and replace their local revoked set with the response.\n The list revokes keys of this directory only: a consumer checks a\n signature against the list of the directory that published its key, and\n never applies this list to another party's key. A fetch of the list MAY\n follow up to five redirects (see \"Redirects\" under Well-Known Discovery).",
"type": "string"
}
},
Expand Down
3 changes: 2 additions & 1 deletion gen/jsonschema/fora.v1.WBAFile.schema.strict.json
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,8 @@
"type": "array"
},
"revocation_url": {
"description": "Directory-level emergency revocation channel. One per directory; the list\n it points to enumerates revoked key thumbprints. Consumers poll on a 300s\n cadence (±10% jitter) and replace their local revoked set with the response.\n The list revokes keys of this directory only: a consumer checks a\n signature against the list of the directory that published its key, and\n never applies this list to another party's key. A fetch of the list MAY\n follow up to five redirects (see \"Redirects\" under Well-Known Discovery).",
"description": "The URL MUST be absolute and on the same host AND PORT that serve this\n directory, or on a subdomain of that host on that port. A consumer MUST NOT\n poll a revocation_url anywhere else: a directory is fetched from whichever\n host a signature names, before that signature is checked, so a list on an\n unrelated host would let any party aim every verifier's poller at a host of\n its choosing. A list named anywhere else therefore revokes nothing, and a\n party that serves one directory per host advertises a separate\n revocation_url in each. The host match is on a full dot-delimited label\n boundary, and a port equal to the scheme's default and an omitted port are\n the SAME port. The protocol names no path for the list: the publishing party\n chooses it, and a consumer reads it from this field and never derives it.",
"title": "Directory-level emergency revocation channel. One per directory; the list\n it points to enumerates revoked key thumbprints. Consumers poll on a 300s\n cadence (±10% jitter) and replace their local revoked set with the response.\n The list revokes keys of this directory only: a consumer checks a\n signature against the list of the directory that published its key, and\n never applies this list to another party's key. A fetch of the list MAY\n follow up to five redirects (see \"Redirects\" under Well-Known Discovery).",
"type": "string"
}
},
Expand Down
2 changes: 1 addition & 1 deletion gen/python/wire/models.py
Original file line number Diff line number Diff line change
Expand Up @@ -1160,7 +1160,7 @@ class WBAFile(WireModel):
)
revocation_url: str | None = Field(
None,
description='Directory-level emergency revocation channel. One per directory; the list\n it points to enumerates revoked key thumbprints. Consumers poll on a 300s\n cadence (±10% jitter) and replace their local revoked set with the response.\n The list revokes keys of this directory only: a consumer checks a\n signature against the list of the directory that published its key, and\n never applies this list to another party\'s key. A fetch of the list MAY\n follow up to five redirects (see "Redirects" under Well-Known Discovery).',
description='Directory-level emergency revocation channel. One per directory; the list\n it points to enumerates revoked key thumbprints. Consumers poll on a 300s\n cadence (±10% jitter) and replace their local revoked set with the response.\n The list revokes keys of this directory only: a consumer checks a\n signature against the list of the directory that published its key, and\n never applies this list to another party\'s key. A fetch of the list MAY\n follow up to five redirects (see "Redirects" under Well-Known Discovery).\n\nThe URL MUST be absolute and on the same host AND PORT that serve this\n directory, or on a subdomain of that host on that port. A consumer MUST NOT\n poll a revocation_url anywhere else: a directory is fetched from whichever\n host a signature names, before that signature is checked, so a list on an\n unrelated host would let any party aim every verifier\'s poller at a host of\n its choosing. A list named anywhere else therefore revokes nothing, and a\n party that serves one directory per host advertises a separate\n revocation_url in each. The host match is on a full dot-delimited label\n boundary, and a port equal to the scheme\'s default and an omitted port are\n the SAME port. The protocol names no path for the list: the publishing party\n chooses it, and a consumer reads it from this field and never derives it.',
)


Expand Down
Loading
Loading