Authority Binding in UCP – Definition and Algorithm
UCP authority binding is the rule that a UCP entity may only declare a schema URL served from a host the entity’s own namespace authority controls. A platform derives the authority by reversing the URL’s hostname labels and checking it against the entity’s reverse-domain name. If the check fails, the platform must not fetch the schema and must reject the entity – treating it as if it were never declared. Introduced as a MUST in UCP 2026-08-25.
Proof that whoever published a capability actually owns the domain its name claims – enforced by reversing the schema URL’s hostname, not by matching strings.
Why it exists
UCP capability names encode governance in the name itself: dev.ucp.shopping.checkout is governed by ucp.dev, com.example.payments.installments by example.com. Without a check, anyone could publish an entity under any namespace and point its schema anywhere.
The binding establishes provenance, not trust. A valid binding proves only that the name is controlled by the party serving the schema. It says nothing about whether the entity is correct, safe or worth supporting – that remains the client’s decision.
The algorithm
For an entity named name declaring a schema URL, a platform must:
- Parse the URL with a conformant URL parser. It must parse, must use
https, and must not contain userinfo. Substring matching on the raw URL is not permitted. - Require a registered domain of at least two labels. IP literals and single-label hosts are not authorities.
- Take the hostname without the port, lowercase it, strip a trailing dot, convert internationalized domains to punycode, and reverse its labels – host
ucp.devbecomes authority prefixdev.ucp. - Accept if and only if
nameequals the authority prefix (exact), ornamebegins with the authority prefix followed by a.(label-aligned prefix).
Requiring a . immediately after the authority prefix keeps the match on a label boundary. Without it, com.example (host example.com) would match com.examplecorp.* – a textual prefix of a namespace someone else owns.
Accept and reject table
| Entity name | schema host | Authority prefix | Result |
|---|---|---|---|
dev.ucp.shopping.checkout | ucp.dev | dev.ucp | accept – prefix |
dev.ucp.shopping.checkout | shopping.ucp.dev | dev.ucp.shopping | accept – prefix |
com.example.payments.installments | example.com | com.example | accept – prefix |
com.example.pay | pay.example.com | com.example.pay | accept – exact |
com.example.pay | example.com | com.example | accept – prefix |
com.example.pay | evil.example | example.evil | reject |
dev.ucp.shopping.checkout | evil.example | example.evil | reject |
com.examplecorp.pay | example.com | com.example | reject – not label-aligned |
com.example.pay | cdn.example.com | com.example.cdn | reject – shared CDN |
The userinfo decoy
The specification calls this case out by name, because it is the one a naive implementation gets wrong:
https://ucp.dev@evil.example/checkout.jsonThe string contains ucp.dev. The host is evil.example. Any check written as str_contains($url, 'ucp.dev') accepts a schema served by an attacker. This is why the rule mandates a real URL parser and forbids userinfo outright.
What is bound and what is not
| Field | Rule |
|---|---|
schema | https, and authority-bound. This is the machine trust path – the platform fetches and composes it during negotiation |
spec | https only. Documentation is off the trust path, so a docs subdomain or third-party host is legitimate |
endpoint | https. Not authority-bound – it is your own store URL |
This split is new in 2026-08-25. Implementations written against 2026-04-08 often bound the spec URL too, which now produces false rejections.
Public suffixes are not special-cased
The check does not consult the Public Suffix List. A suffix under which independent parties can register names – from co.uk to github.io, object storage and app platforms – is treated as an ordinary authority, so co-tenants satisfy the same prefix. Declare entities only under a registrable domain you exclusively control.
Why merchants should check this locally
A platform that rejects an entity treats it as not present and never activates it. Nothing is logged on your side, no error is returned, and the capability simply does not exist as far as that agent is concerned. A store can pass JSON Schema validation and still lose half its declared capabilities.
angeo/module-ucp runs the derivation algorithm over every capability, service binding and payment handler in the generated profile:
bin/magento angeo:ucp:validateQuestions
- What is authority binding in UCP?
- The requirement that an entity’s
schemaURL is served from a host whose reversed labels are the entity’s name or a label-aligned prefix of it. It proves the publisher controls the namespace the name claims. - Does authority binding apply to the spec URL?
- No. Since 2026-08-25 only
schemais bound. AspecURL must be https but may be served from any host, because documentation is deliberately off the machine trust path. - What happens if authority binding fails?
- The platform must not fetch the schema and must reject the entity, treating it as not present. The rejection is silent, so nothing reaches the merchant.
- Can I host my UCP capability schema on a CDN subdomain?
- Only if the subdomain’s reversed labels line up with the namespace.
cdn.example.comreverses tocom.example.cdn, which is not a prefix ofcom.example.pay, so it is rejected. - Does authority binding mean a capability is trustworthy?
- No. It establishes provenance only. Whether to negotiate, trust or implement the entity remains the client’s decision.