diff --git a/docs/design-history.md b/docs/design-history.md index 99ad40d7..ef59c98c 100644 --- a/docs/design-history.md +++ b/docs/design-history.md @@ -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 @@ -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 diff --git a/gen/descriptor.binpb b/gen/descriptor.binpb index e48595ac..663f691d 100644 Binary files a/gen/descriptor.binpb and b/gen/descriptor.binpb differ diff --git a/gen/go/fora/v1/fora.pb.go b/gen/go/fora/v1/fora.pb.go index 82cec52f..426662fc 100644 --- a/gen/go/fora/v1/fora.pb.go +++ b/gen/go/fora/v1/fora.pb.go @@ -8475,6 +8475,18 @@ type WBAFile struct { // signature against the list of the directory that published its key, and // never applies this list to another party's key. A fetch of the list MAY // follow up to five redirects (see "Redirects" under Well-Known Discovery). + // + // The URL MUST be absolute and on the same host AND PORT that serve this + // directory, or on a subdomain of that host on that port. A consumer MUST NOT + // poll a revocation_url anywhere else: a directory is fetched from whichever + // host a signature names, before that signature is checked, so a list on an + // unrelated host would let any party aim every verifier's poller at a host of + // its choosing. A list named anywhere else therefore revokes nothing, and a + // party that serves one directory per host advertises a separate + // revocation_url in each. The host match is on a full dot-delimited label + // boundary, and a port equal to the scheme's default and an omitted port are + // the SAME port. The protocol names no path for the list: the publishing party + // chooses it, and a consumer reads it from this field and never derives it. RevocationUrl *string `protobuf:"bytes,2,opt,name=revocation_url,json=revocationUrl,proto3,oneof" json:"revocation_url,omitempty"` unknownFields protoimpl.UnknownFields sizeCache protoimpl.SizeCache diff --git a/gen/jsonschema/fora.v1.WBAFile.schema.json b/gen/jsonschema/fora.v1.WBAFile.schema.json index 014c2792..7521984f 100644 --- a/gen/jsonschema/fora.v1.WBAFile.schema.json +++ b/gen/jsonschema/fora.v1.WBAFile.schema.json @@ -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" } }, diff --git a/gen/jsonschema/fora.v1.WBAFile.schema.strict.json b/gen/jsonschema/fora.v1.WBAFile.schema.strict.json index db16c1f6..8af942d5 100644 --- a/gen/jsonschema/fora.v1.WBAFile.schema.strict.json +++ b/gen/jsonschema/fora.v1.WBAFile.schema.strict.json @@ -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" } }, diff --git a/gen/python/wire/models.py b/gen/python/wire/models.py index 153943a8..e16185a6 100644 --- a/gen/python/wire/models.py +++ b/gen/python/wire/models.py @@ -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.', ) diff --git a/gen/ts/wire/schemas.ts b/gen/ts/wire/schemas.ts index 7d72c01a..b02f0b26 100644 --- a/gen/ts/wire/schemas.ts +++ b/gen/ts/wire/schemas.ts @@ -222,7 +222,7 @@ export const UsageReportRejectionReasonSchema = /* @__PURE__ */ (() => wire(z.en export const UsageReportResponseSchema = /* @__PURE__ */ (() => wire(z.object({ "ext": z.record(z.string(), z.any()).describe("Extension point").optional(), "ext_critical": z.array(z.string()).describe("Critical extension keys (COSE crit pattern, RFC 9052).\n Lists keys within ext that the consumer MUST understand.\n Unknown keys in this list → reject with UNKNOWN_CRITICAL_EXTENSION.\n Empty (default) → all ext keys are safe to ignore.").optional(), "report_id": z.string().describe("Exchange-assigned report identifier. Required for the dispute chain —\n the agent must reference this report_id in DisputeRequest to prove that\n a usage report was filed before disputing. The complete evidence chain:\n Offer → Transaction (transaction_id, billing_id)\n → UsageReport → UsageReportResponse (report_id)\n → DisputeRequest (transaction_id + report_id)").default(""), "ver": z.string().describe("FORA protocol version — \"1.0\". Stamped by the sender from a single\n constant; advisory on receive. See \"Protocol version\" in the file header.").default("") }).describe("UsageReportResponse — Acknowledgment of a usage report.")))(); -export const WBAFileSchema = /* @__PURE__ */ (() => wire(z.object({ "keys": z.array(z.object({ "alg": z.string().describe("Signing algorithm. FORA v1.0: MUST be \"EdDSA\".").default(""), "crv": z.string().describe("Curve. FORA v1.0: MUST be \"Ed25519\".").default(""), "kty": z.string().describe("Key type. FORA v1.0: MUST be \"OKP\".").default(""), "not_after": z.string().describe("REQUIRED. RFC3339 timestamp. Key is invalid at and after this instant\n (strict upper bound), and a key without it is never valid.").default(""), "not_before": z.string().describe("REQUIRED. RFC3339 timestamp. Key is invalid before this instant, and a key\n without it is never valid.").default(""), "use": z.string().describe("Intended key use. FORA v1.0: MUST be \"sig\".").default(""), "x": z.string().describe("base64url-encoded 32-byte Ed25519 public key.").default("") }).describe("JsonWebKey — Inline RFC 7517 JWK object.\n\nFORA v1.0 supports Ed25519 only: kty=\"OKP\", crv=\"Ed25519\", alg=\"EdDSA\".\n Additional curves are a later concern. `alg` is the JOSE name RFC 7517 §4.4\n defines; WG-00 §5.5.1 restricts the member to HTTP Message Signatures names\n (`ed25519`), a known and deliberate deviation. The RFC 9421 signature\n parameter `alg` in Signature-Input is a different field: a FORA signer sets\n it to \"ed25519\", and a verifier also accepts a signature without it, the\n Ed25519 key deciding the algorithm.\n\n Time bounds are RFC3339 strings (sortable, ops-debuggable, avoids the\n JWT nbf/exp collision). At least one key in the served key set (WBAFile.keys)\n MUST have `not_before <= now < not_after`. Verification MUST reject\n signatures whose key falls outside its window. A key that lacks either bound,\n or whose bound is not an RFC3339 timestamp, is never valid. WG-00 defines no\n such members, so this is a deliberate departure: a directory written to WG-00\n alone must add them before a FORA verifier uses its keys.\n\n Keys carry no `kid`: the RFC 9421 keyid is the RFC 7638 JWK Thumbprint,\n computed locally by the verifier. Carrying a kid alongside the thumbprint\n created a drift surface and is removed.")).describe("RFC 7517 JWK Set \"keys\" member. FORA v1: Ed25519 (OKP) keys, each with\n not_before/not_after FORA extension members, which a FORA verifier\n requires (see JsonWebKey). A verifier uses only the keys whose response\n signature verifies; WG-00 Appendix B.1 only RECOMMENDS signing the\n response, and FORA requires it.").optional(), "revocation_url": z.string().describe("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).").optional() }).describe("WBAFile — Pure Web Bot Auth directory served at the WBA-canonical well-known\n path (/.well-known/http-message-signatures-directory), over https, with\n status 200 and no redirect, as application/http-message-signatures-directory+json.\n The response is signed once per listed key under\n tag=\"http-message-signatures-directory\", covering \"@authority\";req and\n content-digest. A JOSE JWK Set per RFC 7517 §5 plus a directory-level\n revocation pointer. JWKs carry no kid; the\n RFC 9421 keyid is the RFC 7638 JWK Thumbprint. Off-the-shelf WBA verifiers\n read the `keys` array and ignore FORA's extra members (per-key\n not_before/not_after, and revocation_url) per RFC 7517 §5. A FORA verifier\n does not: it requires each key's bounds and uses only the keys whose\n response signature verifies (see `keys`).")))(); +export const WBAFileSchema = /* @__PURE__ */ (() => wire(z.object({ "keys": z.array(z.object({ "alg": z.string().describe("Signing algorithm. FORA v1.0: MUST be \"EdDSA\".").default(""), "crv": z.string().describe("Curve. FORA v1.0: MUST be \"Ed25519\".").default(""), "kty": z.string().describe("Key type. FORA v1.0: MUST be \"OKP\".").default(""), "not_after": z.string().describe("REQUIRED. RFC3339 timestamp. Key is invalid at and after this instant\n (strict upper bound), and a key without it is never valid.").default(""), "not_before": z.string().describe("REQUIRED. RFC3339 timestamp. Key is invalid before this instant, and a key\n without it is never valid.").default(""), "use": z.string().describe("Intended key use. FORA v1.0: MUST be \"sig\".").default(""), "x": z.string().describe("base64url-encoded 32-byte Ed25519 public key.").default("") }).describe("JsonWebKey — Inline RFC 7517 JWK object.\n\nFORA v1.0 supports Ed25519 only: kty=\"OKP\", crv=\"Ed25519\", alg=\"EdDSA\".\n Additional curves are a later concern. `alg` is the JOSE name RFC 7517 §4.4\n defines; WG-00 §5.5.1 restricts the member to HTTP Message Signatures names\n (`ed25519`), a known and deliberate deviation. The RFC 9421 signature\n parameter `alg` in Signature-Input is a different field: a FORA signer sets\n it to \"ed25519\", and a verifier also accepts a signature without it, the\n Ed25519 key deciding the algorithm.\n\n Time bounds are RFC3339 strings (sortable, ops-debuggable, avoids the\n JWT nbf/exp collision). At least one key in the served key set (WBAFile.keys)\n MUST have `not_before <= now < not_after`. Verification MUST reject\n signatures whose key falls outside its window. A key that lacks either bound,\n or whose bound is not an RFC3339 timestamp, is never valid. WG-00 defines no\n such members, so this is a deliberate departure: a directory written to WG-00\n alone must add them before a FORA verifier uses its keys.\n\n Keys carry no `kid`: the RFC 9421 keyid is the RFC 7638 JWK Thumbprint,\n computed locally by the verifier. Carrying a kid alongside the thumbprint\n created a drift surface and is removed.")).describe("RFC 7517 JWK Set \"keys\" member. FORA v1: Ed25519 (OKP) keys, each with\n not_before/not_after FORA extension members, which a FORA verifier\n requires (see JsonWebKey). A verifier uses only the keys whose response\n signature verifies; WG-00 Appendix B.1 only RECOMMENDS signing the\n response, and FORA requires it.").optional(), "revocation_url": z.string().describe("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.").optional() }).describe("WBAFile — Pure Web Bot Auth directory served at the WBA-canonical well-known\n path (/.well-known/http-message-signatures-directory), over https, with\n status 200 and no redirect, as application/http-message-signatures-directory+json.\n The response is signed once per listed key under\n tag=\"http-message-signatures-directory\", covering \"@authority\";req and\n content-digest. A JOSE JWK Set per RFC 7517 §5 plus a directory-level\n revocation pointer. JWKs carry no kid; the\n RFC 9421 keyid is the RFC 7638 JWK Thumbprint. Off-the-shelf WBA verifiers\n read the `keys` array and ignore FORA's extra members (per-key\n not_before/not_after, and revocation_url) per RFC 7517 §5. A FORA verifier\n does not: it requires each key's bounds and uses only the keys whose\n response signature verifies (see `keys`).")))(); export const WellKnownManifestSchema = /* @__PURE__ */ (() => wire(z.object({ "accepted_verifiers": z.array(z.string()).describe("Exchange-only. Trusted attestation verification vendors (domains).").optional(), "account_registration": z.object({ "data_schema": z.record(z.string(), z.any()).describe("JSON Schema (draft 2020-12) describing the RegisterRequest.registration_data\n object this Exchange expects. This field is the single home of the\n enforce/pass-through contract, and publishing it IS the enforcement switch.\n Present: this Exchange validates registration_data against the schema and\n refuses a non-conforming payload with\n REGISTRATION_FAILURE_REASON_INVALID_REGISTRATION_DATA, naming the offending\n members in RegistrationFailure.field_errors. Absent: registration_data is\n passed through to the system of record uninspected, so an Exchange that\n publishes no schema needs no change to stay conformant.\n\nThe gate above runs on ACCOUNT CREATION ONLY. A repeat registration, for an\n agent that already holds an account, is answered from the stored record and\n runs no schema check at all — it discards registration_data rather than\n validating it. That exception is stated here rather than left to the section\n above, because this field calls itself the single home of the contract and a\n reader who comes here for the whole rule would otherwise leave with the wrong\n one. See \"Repeat registration\" in the Agent Account Registration section for\n why, and for the other gates it applies to.\n\n Absent means the field carries no bytes, or only JSON whitespace — space, tab,\n carriage return and line feed, RFC 8259's four and no others. Nothing else\n counts, and the distinction is load-bearing rather than pedantic: this is the\n enforcement switch, so a byte sequence read as absent is one that turns\n validation OFF. A consumer that asked its own language what \"blank\" means got\n three different answers to the same document — U+00A0 and U+3000 are whitespace\n to some runtimes and not others, and a decoder that strips a byte order mark\n makes a mark followed by a space look like nothing at all. A document that is\n not empty and not JSON is malformed, which is a refusal; it is never silence.\n\n Safety rules, because a consumer reads this schema out of a THIRD PARTY's\n manifest and validates against it before any signature has been checked. A\n publisher MUST satisfy every rule below and a consumer MUST refuse a schema\n that does not. The bounds are stated here as numbers rather than left to each\n implementation on purpose: a schema is validated at both ends of the same\n registration, and a limit chosen privately by one side refuses payloads the\n other accepts.\n\n Self-contained. Every $ref, $dynamicRef and $recursiveRef MUST be a\n same-document reference — it begins with \"#\". A consumer MUST NOT resolve a\n reference that leaves the document: doing so turns every reader into an\n SSRF vector aimed at a URL the schema's author chose.\n\n One dialect. $schema, wherever it appears in the document, MUST name\n https://json-schema.org/draft/2020-12/schema (an empty fragment on the end\n is the same value). A document declaring none is read as that dialect. An\n older draft is refused rather than validated under semantics its author did\n not intend.\n\n Data is not schema. `const`, `enum`, `default` and `examples` hold arbitrary\n JSON VALUES, and their contents are never read as keywords: a `const` whose\n value happens to carry a \"$ref\" or \"$schema\" member states a value a payload\n may equal, not a reference to resolve or a dialect to honour. Both rules\n above therefore stop at those four keywords, and so does the pattern\n alphabet. Their nesting still counts against the depth cap. Likewise the\n child keys of `properties`, `patternProperties`, `$defs`, `definitions` and\n `dependentSchemas` are NAMES rather than keywords, so a property called\n \"$ref\" is a property.\n\n Bounded size: 16KB, measured as the UTF-8 bytes of this member AS SERVED in\n fora.json.\n\n One encoding. The bytes MUST be well-formed UTF-8 (RFC 8259 requires it for\n interchange) and MUST NOT begin with a byte order mark. RFC 8259 forbids\n ADDING a mark and lets a parser ignore one, so both policies conform and the\n choice is made here rather than left to each implementation: parsers differ,\n and one that strips a mark validates a different document — and counts three\n bytes against the size cap that the schema does not contain. A consumer MUST\n NOT repair ill-formed bytes either; substituting U+FFFD silently enforces a\n schema nobody published. A mark is in any case only valid at the start of a\n JSON text, and this is a member inside one.\n\n Bounded depth: 32 nested JSON containers, counting the schema itself as the\n first.\n\n Bounded WORK: 10000 evaluations, counted statically over the SCHEMA — each\n anyOf/oneOf/allOf branch and prefixItems entry costs its own subschema, and a\n $ref costs its target. It is the cost of applying the schema at ONE location\n in a payload, not of a whole payload: a subschema under `items` is counted\n once here and evaluated once per element at runtime. The size and depth caps\n do not bound it and are not a substitute for it: branches multiply along a\n reference chain, so a 1.6KB schema five containers deep can cost tens of\n millions of evaluations and tens of seconds against a two-member payload. A\n definition nobody references costs nothing, so a document may carry a library\n of them.\n\n Bounded reference chains: 100 hops, counted as the longest path of $ref hops\n rather than as the number of references the document contains. This is a\n THIRD axis, and a flat chain of definitions shows why it has to be: each one\n referring to the next is three JSON containers deep however long it is, so\n the depth cap never sees it, and it costs one evaluation per link, so the\n work cap does not either. What it does reach is the recursion a validator\n performs while resolving the chain — a chain of a few hundred exhausted one\n implementation's stack outright, on a document every other rule had passed.\n A schema describing a business entity chains one or two references.\n\n No reference cycles. A $ref chain MUST NOT return to a schema already on it.\n The construct is legal JSON Schema and is how a recursive structure is\n written, but its evaluation cost has no static bound and it is what makes a\n validator recurse until it aborts. Registration data describes a business\n entity, which is not a recursive shape.\n\n A portable `pattern` alphabet, stated as what a pattern MAY contain rather\n than as what it may not. A group MUST open with \"(\" or \"(?:\" and nothing\n else; only the escapes \\$, \\(, \\), \\*, \\+, \\., \\/, \\?, \\D, \\W, \\[, \\\\, \\],\n \\^, \\d, \\f, \\n, \\r, \\t, \\v, \\w, \\{, \\| and \\} MAY appear, together with \\xHH\n carrying exactly two hexadecimal digits (spelled out rather than ranged, so a\n conformance guard can check the set character by character); a counted repeat\n MUST NOT exceed 1000 and MUST state its first bound, so \"a{2,}\" is admitted\n and \"a{,5}\" is not; a \"}\" outside a bracket expression MUST close a counted\n repeat, so a literal brace is written \"\\}\"; \"[:\" MUST NOT appear inside a\n bracket expression; a bracket expression MUST close and MUST NOT open with\n \"]\"; and a range endpoint MUST NOT be one of the shorthand classes (\"[\\w-x]\").\n\n The two brace rules are there for the same reason as the bracket ones, and\n were found the same way. \"a{,5}\" is five literal characters to RE2 and a\n repeat of zero to five to Python, so both engines compile it and then\n disagree about which payloads match — the silent kind. An unmatched \"}\" is a\n literal to RE2 and to Python and a syntax error to ECMA-262 under the `u`\n flag, which is the loud kind, and exactly what the unmatched \"]\" rule above\n already refuses.\n\n The direction of that rule is the rule. Draft 2020-12 patterns are ECMA-262,\n but the engines implementations run do not agree on it, and the set they\n disagree about has no end: it grows with every dialect and every library\n version, so a list of forbidden escapes needs a new entry each time somebody\n finds one, and until then the gap is open. The portable set is small and\n closed, and an author who wants a construct outside it writes the characters\n out instead.\n\n Some of the disagreement is loud — RE2 refuses the lookaround, atomic groups\n and backreferences ECMA allows, so a schema using them compiles for one\n implementation and fails for another. The rest is SILENT, and is why this is\n a MUST rather than a SHOULD: inline flags, Unicode property classes, text\n anchors and POSIX bracket names are accepted by one engine and either refused\n or read DIFFERENTLY by the next, so two conformant validators both compile\n the pattern and then disagree about which payloads match it, with nothing\n logged. `\\s` and `\\B` are the plainest examples — RE2 reads `\\s` as\n [\\t\\n\\f\\r ], Python adds the vertical tab, and ECMA-262 adds that plus every\n Unicode space separator; `\\B` finds no word boundary in the empty string for\n RE2 and ECMA-262 and finds one for Python. An explicit character class says\n what was meant and means it everywhere.\n\n Where a pattern may appear. `pattern` states its regex as a value and\n `patternProperties` states its regexes as KEYS; both are patterns and both\n are held to the alphabet above. They are the only two keywords in the dialect\n that carry one — `propertyNames` reaches the rule through the subschema it\n applies.\n\n No nested quantifiers. A quantified group MUST NOT have a body that can\n itself repeat or branch: `(a+)+`, `(a|a)*` and `([a-z]+)*` are refused, while\n `(?:ab)+` is admitted. This is the denial-of-service half of the pattern\n rule, and it is deliberately SEPARATE from the alphabet above, because\n excluding lookaround and backreferences does not cover it — catastrophic\n backtracking needs neither. It has to be a publishing rule rather than a\n runtime bound: a regex spin holds its interpreter, so a consumer cannot\n reliably interrupt one it has already started.\n\n Annotations stay annotations. A consumer MUST NOT assert format,\n contentEncoding or contentMediaType. Libraries default differently on each,\n and a schema whose verdict depends on which library read it has no single\n answer.\n\n The value MUST be a JSON object. Draft 2020-12 also admits a bare boolean as a\n schema, but this field is a Struct and cannot carry one.\n\n A consumer that finds a schema breaking any of these MUST refuse it, and MUST\n then SKIP its local pre-check rather than repair or truncate the schema —\n leaving the Exchange's own enforcement the deciding check, exactly as when no\n schema is published. Refusing locally and declining to send would turn a rule\n about reading a third party's document into a denial of service against the\n consumer's own user. That is the CLIENT side. An Exchange that cannot compile\n its OWN configured schema is looking at a misconfiguration of its deployment,\n and MUST NOT advertise a schema it is not itself enforcing.").optional() }).describe("Exchange-only. How to open an account here — see AccountRegistration, which\n owns the contract. Absent: registration_data is accepted uninspected,\n exactly as before this field existed.").optional(), "base_currency": z.string().describe("Exchange-only. Base currency for pricing (ISO 4217). All unit_cost\n values from this Exchange are denominated in this currency.").optional(), "catalog_contributors": z.array(z.object({ "domain": z.string().describe("Canonical domain of the authorized contributor (e.g., \"doubleverify.com\").").default(""), "relationship": z.string().describe("Relationship of this contributor to the provider.\n Examples: \"verifier\" (resource intelligence vendor that attests to resource\n properties), \"exchange\" (an Exchange that enriches catalog entries).").default("") }).describe("CatalogContributor — A third party authorized to push catalog metadata\n (including attestations) on behalf of a provider.")).describe("Publisher-only. Authorized third-party catalog contributors.\n MUST be empty for non-publisher roles.").optional(), "catalog_endpoint": z.string().describe("Exchange-only. CatalogService endpoint URL (if exposed). It carries the\n same binding as endpoint: it MUST be on the same host AND PORT that serve\n this manifest, or on a subdomain of that host on that port, and MUST NOT\n carry userinfo. A consumer refuses a catalog endpoint anywhere else — a\n publisher's push is a signed call, and a manifest naming an unrelated host\n would redirect it to a party the signature never covered. The host match is\n on a full dot-delimited label boundary, and a port equal to the scheme's\n default and an omitted port are the SAME port. Absent means this Exchange\n does not expose CatalogService; a consumer does not fall back to endpoint.").optional(), "contact": z.string().describe("Contact email (licensing, integration, security).").optional(), "delivery_methods_supported": z.array(z.enum(["DELIVERY_METHOD_DIRECT","DELIVERY_METHOD_INSTRUCTIONS","DELIVERY_METHOD_STREAMING"])).describe("Exchange-only. Supported delivery methods.").optional(), "domain": z.string().describe("Canonical domain serving this manifest.").default(""), "endpoint": z.string().describe("Exchange-only. ExchangeService endpoint URL. MUST be on the same host AND\n PORT that serve this manifest, or on a subdomain of that host on that port,\n and MUST NOT carry userinfo. A consumer refuses an endpoint anywhere else:\n this document is only as trustworthy as the host that served it, so an\n endpoint naming an unrelated host would let whoever answers for the manifest\n redirect a signed call to a party the signature never covered, and another\n port is another service the publisher of the manifest need not control. The\n host match is on a full dot-delimited label boundary, so evil-a.com is not a\n subdomain of a.com. A port equal to the scheme's default and an omitted port\n are the SAME port, so https://x, https://x:443 and x all match. An Exchange\n reachable on a non-default port names that port on both sides.").optional(), "exchanges": z.array(z.object({ "domain": z.string().regex(new RegExp("^[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?(\\.[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?)*(:(6553[0-5]|655[0-2][0-9]|65[0-4][0-9]{2}|6[0-4][0-9]{3}|[1-5][0-9]{4}|[1-9][0-9]{0,3}))?$")).max(260).describe("Canonical domain of the Exchange, in the shape \"Request recipient\" defines\n in the file header."), "endpoint": z.string().describe("FORA ExchangeService endpoint URL.").default(""), "ext": z.record(z.string(), z.any()).describe("Extension point").optional(), "ext_critical": z.array(z.string()).describe("Critical extension keys (COSE crit pattern, RFC 9052).\n Lists keys within ext that the consumer MUST understand.\n Unknown keys in this list → reject with UNKNOWN_CRITICAL_EXTENSION.\n Empty (default) → all ext keys are safe to ignore.").optional(), "relationship": z.enum(["PROVIDER_RELATIONSHIP_DIRECT","PROVIDER_RELATIONSHIP_RESELLER"]).describe("Relationship type (mirrors ads.txt DIRECT/RESELLER).") }).describe("AuthorizedExchange — A Exchange authorized to sell this provider's resources.")).describe("Publisher-only. Authorized exchanges for this publisher's resources.\n Like ads.txt — declares who may sell. MUST be empty for non-publisher\n roles.").optional(), "ext": z.record(z.string(), z.any()).describe("Extension point").optional(), "ext_critical": z.array(z.string()).describe("Critical extension keys (COSE crit pattern, RFC 9052). Lists keys\n within ext that the consumer MUST understand. Unknown values reject\n with UNKNOWN_CRITICAL_EXTENSION. Empty (default) → ignore-unknown.").optional(), "gnap_grant_endpoint": z.string().describe("Exchange-only. GNAP grant endpoint when GNAP is supported.").optional(), "hash_methods_supported": z.array(z.string()).describe("Exchange-only. Accepted resource hash methods for attestation\n verification.").optional(), "health_endpoint": z.string().describe("Exchange-only. The URL a consumer, such as a Broker deciding whether to route\n to this Exchange, probes to judge whether it is serving: an absolute URL, or\n a path resolved against this manifest's own URL (RFC 3986). A 200 answer\n means serving. When absent, a consumer judges reachability by fetching this\n manifest itself; it never assumes a path the protocol does not name.").optional(), "max_intermediary_hops": z.coerce.number().int().gte(-2147483648).lte(2147483647).describe("Exchange-only. Maximum number of RFC 9421 HTTP Message Signatures this\n Exchange accepts on an inbound request. Every signature counts, whether or\n not it covers another. A request signed only by the party that sent it — an\n agent, or a Broker for a request it authored — carries one, so the cap\n bounds a request that a party forwarded unchanged and signed again. An\n Exchange refuses a request carrying more before it verifies any signature,\n with the Connect code resource_exhausted (HTTP 429) and no typed reason.\n Lets Exchanges publish their tolerance so a sender stays within it.\n Absent = no published limit (Exchange applies its own default policy).").optional(), "name": z.string().describe("Exchange-only. Human-readable Exchange name.").optional(), "oidc_issuer": z.string().describe("Exchange-only. OIDC Discovery URL when OAuth methods are supported.").optional(), "operator": z.string().describe("Exchange-only. Organization operating this Exchange.").optional(), "operator_domain": z.string().describe("Exchange-only. Operator's corporate domain (may differ from domain).").optional(), "pricing_models_supported": z.array(z.enum(["PRICING_MODEL_FREE","PRICING_MODEL_PER_UNIT","PRICING_MODEL_FLAT"])).describe("Exchange-only. Supported pricing models.").optional(), "privacy_uri": z.string().describe("Exchange-only. Privacy policy URL.").optional(), "protocol_versions_supported": z.array(z.string()).describe("Exchange-only. Supported FORA protocol versions (e.g. [\"1.0\"]).").optional(), "role": z.enum(["ROLE_AGENT","ROLE_EXCHANGE","ROLE_BROKER","ROLE_PUBLISHER"]).describe("Role this manifest describes."), "supported_auth_methods": z.array(z.enum(["AUTH_METHOD_GNAP","AUTH_METHOD_OAUTH_DPOP","AUTH_METHOD_OAUTH_BEARER","AUTH_METHOD_OAUTH_MTLS"])).describe("Exchange-only. Authorization methods this Exchange supports\n (ordered by preference).").optional(), "supported_profiles": z.array(z.string()).describe("Exchange-only. Domain extension profiles this Exchange conforms to.\n See standards-layering docs.").optional(), "terms_digest": z.string().regex(new RegExp("^(sha256:[0-9a-f]{64}|sha384:[0-9a-f]{96}|sha512:[0-9a-f]{128})?$")).describe("Exchange-only. Digest of the document served at `terms_uri`, in\n \"method:hexdigest\" form (e.g. \"sha256:9f86d081...\"), pinning WHICH terms\n document this manifest is currently offering. `terms_uri` alone cannot\n answer that: it is a URL, and its content changes, so after the first\n revision every earlier registration points at a document that no longer says\n what was agreed. RegisterRequest.terms_digest echoes this value, the request\n signature covers that echo, and the Exchange records the accepted digest\n with the account — which is what makes \"which terms did this operator\n accept\" answerable later, through GetAccountStatusResponse.terms_digest, which\n is where the accepted value is read back. Because a digest identifies a\n document only while\n a copy of it still exists, keeping the historical terms documents\n retrievable is the Exchange's obligation. It sits at the top level rather\n than inside account_registration on purpose: an Exchange with pass-through\n registration publishes no block yet still needs to pin its terms version,\n and coupling \"I enforce a schema\" to \"I version my terms\" would tie together\n two independent decisions. Operator note: publishing this field for the\n first time refuses every client that does not yet echo it, so it is a\n coordinated change rather than a safe addition.").optional(), "terms_uri": z.string().describe("Exchange-only. Terms of service URL.").optional(), "ver": z.string().describe("Version of THIS MANIFEST DOCUMENT's layout — \"1.0\", stamped by the party\n that serves the document from the SDK's WellKnownManifestVersion, never from\n ProtocolVersion. A namespace separate from the RPC envelope `ver`: a change\n to this document's layout bumps both numbers, a protocol change that leaves\n the document untouched bumps only the envelope's, so a reader that parses\n only manifests upgrades when the manifest changes and at no other time.\n\nConsumers read `ver` before any other member. They ACCEPT a recognised\n MAJOR version whatever the MINOR — a minor revision of the manifest is\n additive, and a reader ignores members it does not know. They REJECT an\n unrecognised MAJOR, a value that is not MAJOR.MINOR, and an ABSENT `ver`:\n the document sits at a fixed, unversioned path and is read before any\n signature is checked, so a layout the reader cannot classify must not\n supply anything a signed call then carries — the endpoint that call is sent\n to, or the terms_digest it echoes and its signature covers.\n\n It binds every consumer of this document rather than one use of it. In the\n SDK that is both manifest-reading faces, in all three languages — the\n endpoint resolver and the registration-requirements reader — each applying\n it at its own call site, pinned to one corpus. The key face is exempt\n because it reads a plain JWK Set, which carries no version of this document\n and never will.").default("") }).describe("WellKnownManifest — FORA commercial overlay, served at /.well-known/fora.json\n by every FORA participant (agent, exchange, broker, publisher).\n\nCommercial graph only: role, authorized exchanges/contributors, and exchange\n capability fields. Identity keys are NOT here — they live in the WBA directory\n (WBAFile) served at /.well-known/http-message-signatures-directory and are\n referenced by RFC 7638 thumbprint, never republished here.\n Per-role fields are populated only when that role applies; consumers\n MUST ignore non-applicable fields based on `role`.")))(); diff --git a/proto/CHANGELOG.md b/proto/CHANGELOG.md index 745ccc84..2e563b81 100644 --- a/proto/CHANGELOG.md +++ b/proto/CHANGELOG.md @@ -2,6 +2,18 @@ ## Unreleased +**A key directory's `revocation_url` must sit on the directory's own host (comments and docs +only; no wire change).** The `WBAFile.revocation_url` comment and the Emergency Revocation +section of the authentication page state the rule all three SDKs already enforce: 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, with a port equal to the scheme's default the same as an omitted one, +and a consumer polls no other value. A party that serves one directory per host, such as a +registry that gives each agent its own subdomain, advertises a separate `revocation_url` in +each. The protocol names no path for the list, and the SDK exports none: a consumer reads the +location from `revocation_url` and never derives it. The proto reference, the verification +steps for Exchange operators and the Identity Service page link to the rule, and the design +history records why the SDK names no path. + **A Broker orders offers by relevance, and the agent decides (docs and comments only; no wire change).** The docs no longer describe the Broker as choosing the cheapest offer or the best deal. A Broker returns every Exchange's signed offers in its order of relevance to the agent's request, diff --git a/proto/fora/v1/fora.proto b/proto/fora/v1/fora.proto index d182af38..c03135f5 100644 --- a/proto/fora/v1/fora.proto +++ b/proto/fora/v1/fora.proto @@ -4394,6 +4394,18 @@ message WBAFile { // signature against the list of the directory that published its key, and // never applies this list to another party's key. A fetch of the list MAY // follow up to five redirects (see "Redirects" under Well-Known Discovery). + // + // The URL MUST be absolute and on the same host AND PORT that serve this + // directory, or on a subdomain of that host on that port. A consumer MUST NOT + // poll a revocation_url anywhere else: a directory is fetched from whichever + // host a signature names, before that signature is checked, so a list on an + // unrelated host would let any party aim every verifier's poller at a host of + // its choosing. A list named anywhere else therefore revokes nothing, and a + // party that serves one directory per host advertises a separate + // revocation_url in each. The host match is on a full dot-delimited label + // boundary, and a port equal to the scheme's default and an omitted port are + // the SAME port. The protocol names no path for the list: the publishing party + // chooses it, and a consumer reads it from this field and never derives it. optional string revocation_url = 2; } diff --git a/website/src/content/docs/components/identity/overview.mdx b/website/src/content/docs/components/identity/overview.mdx index 46416f54..79a61e32 100644 --- a/website/src/content/docs/components/identity/overview.mdx +++ b/website/src/content/docs/components/identity/overview.mdx @@ -55,6 +55,8 @@ The account row is the authoritative record of registration, and sign-up reserve The directory follows the [Key Directory](/protocol/authentication/#key-directory) rules: https, a direct `200`, the media type above, and a response signed by each key it lists. The service release that predates the Web Bot Auth profile serves it as `application/jwk-set+json` and unsigned. +Each agent's directory names its revocation list on the agent's own subdomain, at the path above. A verifier polls a revocation list only on the host that served the directory (see [Emergency Revocation](/protocol/authentication/#emergency-revocation)), so one URL shared by every agent would leave all but one agent's revocations unread. The path itself is this service's choice; the protocol names none. + Two properties of the directory are load-bearing. It is assembled as a real JWK Set with a JOSE library rather than marshalled from FORA's protobuf. The audience is any Web Bot Auth verifier on the open internet, and those implement RFC 7517, not `fora.v1`. And keys come out **newest-first**, which matters for the signing tie-break described below. Keys carry no `kid`. Identity is the RFC 7638 thumbprint, so entries are deduplicated on the JWK `x` member actually emitted into the document. The FORA-specific `not_before` / `not_after` validity window is spliced onto each key as an extension member, which a generic verifier ignores. Each key also carries `alg` `EdDSA`, the JOSE name RFC 7517 defines, which is a known, deliberate deviation from WG-00 §5.5.1 (see [Key Directory](/protocol/authentication/#key-directory)). diff --git a/website/src/content/docs/getting-started/for-exchange-operators.mdx b/website/src/content/docs/getting-started/for-exchange-operators.mdx index 846f7bb8..f49f0a69 100644 --- a/website/src/content/docs/getting-started/for-exchange-operators.mdx +++ b/website/src/content/docs/getting-started/for-exchange-operators.mdx @@ -86,7 +86,7 @@ The `Requester` message carries no signature: it states who is asking, and the R 1. **Count the signatures first.** Before you verify any, refuse a request carrying more signatures than your `WellKnownManifest.max_intermediary_hops` with `resource_exhausted` (HTTP 429) and no typed reason. Every signature counts, whether or not it covers another. See [Verification at the Exchange](/protocol/authentication/#verification-at-the-exchange). 2. **Verify each signature under the Web Bot Auth profile.** Resolve its `keyid`, the key's RFC 7638 thumbprint, in the key directory its own covered `Signature-Agent` member names (`{origin}/.well-known/http-message-signatures-directory`), never from `Requester.domain`. Check the profile parameters, the four components a FORA RPC covers (`@method`, `@target-uri`, `content-digest`, `authorization`) and the `Content-Digest` of the body. Refuse a failure as `unauthenticated` with `request_auth_failure`: `SIGNATURE_MISSING` when no signature parses, `SIGNATURE_INVALID` when one does not verify, `SIGNATURE_STALE` outside its `created`/`expires` window. When a required component is missing, also answer with an `Accept-Signature` field listing the components you require, so the client can fix its request. See [Signature Verification](/protocol/authentication/#signature-verification) and [The Web Bot Auth Profile](/protocol/authentication/#the-web-bot-auth-profile). 3. **Refuse a replay.** A signature you have already accepted is refused as `SIGNATURE_STALE`. See [Replay protection](/protocol/authentication/#replay-protection). -4. **Check revocation against the signer's own directory only.** A key is revoked when the revocation list its own directory names lists it. No other party's list can revoke it, even one that names its thumbprint. See [Whose list revokes whose key](/protocol/authentication/#whose-list-revokes-whose-key). +4. **Check revocation against the signer's own directory only.** A key is revoked when the revocation list its own directory names lists it. No other party's list can revoke it, even one that names its thumbprint. See [Whose list revokes whose key](/protocol/authentication/#whose-list-revokes-whose-key). Poll that list only when the directory's `revocation_url` sits on the directory's own host and port, or a subdomain of it; see [Emergency Revocation](/protocol/authentication/#emergency-revocation). 5. **Tell a direct request from a relayed one.** On `ResourceQuery` and `TransactionRequest`, compare `Requester.domain` with the host of the directory the covered `Signature-Agent` member names, by the request-recipient identity rule. Equal is a direct request from the requester itself. Different is a request a Broker authored for that requester, and you act on it only when you admit the signer as a Broker, by your own policy (for example, the Brokers registered with you); otherwise refuse it as `unauthenticated` with `request_auth_failure` `SIGNATURE_INVALID`. A Broker never forwards an agent's request unchanged: it signs the requests it authors alone. See [Direct and relayed requests](/protocol/authentication/#direct-and-relayed-requests). 6. **On a purchase, verify the agent's acceptances.** Verify each item's `AgentAcceptance`, and the request's `AgentRequestAcceptance`, against the Ed25519 keys currently valid in the directory `Requester.domain` names, never against a Broker's key. On a relayed purchase these are the agent's identity and consent, the acceptance key is what the delivery URL is bound to, and a delegation's `cnf.jkt` is checked against it. A sub-request that is not the exact in-order projection of the set the agent signed is denied in the body, every item with `DENIAL_REASON_SIGNATURE_INVALID`. See [Projected execute requests](/protocol/authentication/#projected-execute-requests). 7. **On Broker-led discovery, `Requester.domain` is the Broker's statement.** A `ResourceQuery` a Broker originated carries no agent signature, so nothing authenticates the field there: it says whom the Broker queries for, under the Broker's own signature. diff --git a/website/src/content/docs/protocol/authentication.mdx b/website/src/content/docs/protocol/authentication.mdx index 4a0d7637..3cd9f542 100644 --- a/website/src/content/docs/protocol/authentication.mdx +++ b/website/src/content/docs/protocol/authentication.mdx @@ -947,6 +947,10 @@ Enforcement is operational, not protocol-guaranteed: a consumer that grants acce When a WBA directory sets `revocation_url`, consumers poll it on a 300s cadence (±10% jitter) and replace their local revoked set with the response — a `KeyRevocationList` (thumbprint-only snapshot: `as_of` + `revoked[]`). A revoked thumbprint stays revoked; reject any signature whose key thumbprint is in the set. When `revocation_url` is unset, consumers rely on routine rotation and `not_after` expiry. +`revocation_url` **MUST** be an absolute URL on the same host **and port** that serve the key directory, or on a subdomain of that host on that port. A consumer **MUST NOT** poll a `revocation_url` anywhere else: a directory is fetched from whichever origin a signature's covered `Signature-Agent` member names, before that signature is checked, so a list on an unrelated host would let any party aim every verifier's poller wherever it liked. A list named anywhere else therefore revokes nothing. Host and port match as for an Exchange's [endpoint](/protocol/exchange-manifest/#endpoint-host-binding): on a full dot-delimited label boundary, with a port equal to the scheme's default the same as an omitted port. + +A party that serves one directory per host, such as a registry that gives each agent its own subdomain, advertises a separate `revocation_url` in each; one shared URL anchors to at most one of them, and every other agent's revocations go unread. The protocol names no path for the list: the publishing party chooses it, and a consumer reads it from `revocation_url` and never derives it. + ### Whose list revokes whose key Revocation is scoped to the signer. Each signature is verified against its own signer's key directory and the revocation list that directory names, and against no other party's: diff --git a/website/src/content/docs/reference/changelog.mdx b/website/src/content/docs/reference/changelog.mdx index 9f452ebe..ff027be4 100644 --- a/website/src/content/docs/reference/changelog.mdx +++ b/website/src/content/docs/reference/changelog.mdx @@ -8,6 +8,18 @@ and protocol history, see [`proto/CHANGELOG.md`](https://github.com/FORA-Protoco ## Unreleased +**A key directory's `revocation_url` must sit on the directory's own host (comments and docs +only; no wire change).** The `WBAFile.revocation_url` comment and the Emergency Revocation +section of the authentication page state the rule all three SDKs already enforce: 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, with a port equal to the scheme's default the same as an omitted one, +and a consumer polls no other value. A party that serves one directory per host, such as a +registry that gives each agent its own subdomain, advertises a separate `revocation_url` in +each. The protocol names no path for the list, and the SDK exports none: a consumer reads the +location from `revocation_url` and never derives it. The proto reference, the verification +steps for Exchange operators and the Identity Service page link to the rule, and the design +history records why the SDK names no path. + **A Broker orders offers by relevance, and the agent decides (docs and comments only; no wire change).** The docs no longer describe the Broker as choosing the cheapest offer or the best deal. A Broker returns every Exchange's signed offers in its order of relevance to the agent's request, diff --git a/website/src/content/docs/reference/proto-fora.mdx b/website/src/content/docs/reference/proto-fora.mdx index 8d9ad251..fa5a1304 100644 --- a/website/src/content/docs/reference/proto-fora.mdx +++ b/website/src/content/docs/reference/proto-fora.mdx @@ -363,7 +363,7 @@ The pure WBA directory, served at `/.well-known/http-message-signatures-director | Field | Type | Number | Description | |---|---|---|---| | `keys` | repeated JsonWebKey | 1 | Signature-verification keys; ≥1 valid at serve time | -| `revocation_url` | optional string | 2 | Emergency key-revocation list URL (`KeyRevocationList`) | +| `revocation_url` | optional string | 2 | Emergency key-revocation list URL (`KeyRevocationList`), on the directory's own host and port or a subdomain of it; see [Emergency Revocation](/protocol/authentication/#emergency-revocation) | ### JsonWebKey