Download the PHP package angeo/module-ucp without Composer

Angeo UCP — /.well-known/ucp for Magento 2

Publishes a Universal Commerce Protocol business profile at /.well-known/ucp so AI shopping agents (Google/Gemini, ChatGPT, etc.) can discover your store's commerce capabilities.

• Profile generated per UCP spec 2026-08-25 (current release), following the official JSON Schemas from the spec repository (schemas/profile.json#business_schema)
• Authority binding enforced locally. 2026-08-25 makes it a MUST that a platform reject any entity whose schema host does not match its namespace — and it does so silently. angeo:ucp:validate runs the spec's own derivation algorithm so you find out before a platform does
• Signing keys published in the canonical top-level keys[] JWK Set (RFC 7517), public keys only. ES256, ES384 and Ed25519 supported, with RFC 7638 thumbprint key ids for Web Bot Auth interop, and zero-downtime rotation via --add
• Multi-transport service bindings: REST out of the box, optional MCP binding — extensible to further transports and services via Api\ServiceBindingProviderInterface and the di.xml provider pool
• Served by a PHP controller — correct Content-Type: application/json, CORS, and cache headers, with no nginx/Apache changes

How the endpoint is served

/.well-known/ucp is delivered by a controller, not a static file, because the UCP spec requires Content-Type: application/json and CORS headers (Access-Control-Allow-Origin: *) — neither of which a static file without an extension can provide without editing the web server.

Why this reaches PHP without web-server changes

The stock Magento nginx config ends its main location with try_files $uri $uri/ /index.php$is_args$args. A request for /.well-known/ucp with no matching static file falls through to index.php, where the custom router dispatches it. The official Magento nginx sample has no location ~ /\. deny rule, so the dot-segment is not blocked.

If your host added a custom location ~ /\. { deny all; } rule it blocks all dot-paths, and the profile then needs a one-line nginx allow for ^~ /.well-known/. The stock config does not have this problem.

Do not leave a static file at pub/.well-known/ucp: nginx would serve it first (as application/octet-stream, no CORS) and the controller would never run.

Inbound signature verification (2.1.0)

The profile publishes keys. 2.1.0 adds the half that uses them: verification of RFC 9421 signatures on requests arriving at your UCP endpoints.

This direction is the one the spec puts a MUST on — a business rejects a request whose counterparty profile cannot be fetched or fails validation. Before 2.1.0, endpoints advertised by a signed profile answered anyone who sent a POST.

Stores → Configuration → Angeo UCP → Request Security:

Start in optional. An invalid signature is refused there too — only a missing one is tolerated — so you get real enforcement while you find out, from the log, which agents actually sign. There is no way to know that in advance, which is why required is not the default.

Endpoint modules consume this through Api\SignatureVerifierInterface; angeo/module-ucp-catalog 2.1.0 already does.

Not yet implemented: signing our own responses. Tracked for a later release.

Upgrading from 1.x

1.4.0 is not broken — it publishes a valid 2026-04-08 profile, and the spec allows a business to keep serving an older version. This release adopts 2026-08-25, which is a package deal: the protocol version, the key field and the capability documentation URLs all move together.

Existing keys keep working and are simply republished under keys[]; no regeneration is needed unless you want Web Bot Auth interop. If a platform already integrates against your current profile, freeze a copy of it and declare it under Advanced → Supported Versions — this module serves only the version it advertises.

Install

Generate signing keys, then verify:

CLI

Which key type?

• ES256 (default) — the universal baseline. Every counterparty accepts it, and AP2 mandate signing requires it. Start here.
• Ed25519 — RECOMMENDED by the spec for Web Bot Auth interop on HTTP transport. Needs ext-sodium. It does not cover AP2, so if you sign mandates, publish both.
• ES384 — for deployments with a stricter curve policy.

Rotating without downtime

A key is not effectively revoked until it is absent from keys[] — which also means it is not published until it is present. So rotate in that order:

Configuration

Stores → Configuration → Angeo UCP — enable the module and declare which capabilities your store supports: catalog search/lookup, cart, checkout, order, identity linking, permalink, plus the fulfillment, discount and buyer consent extensions, payment handlers, and supported protocol versions.

Since 2.2.0, a toggle alone does not advertise cart, checkout, order, fulfillment, discount or buyer consent. They appear in the profile only when an installed module serves them:

Capability	Served by
dev.ucp.shopping.catalog.search / .lookup	angeo/module-ucp-catalog (not gated)
dev.ucp.shopping.checkout + .discount + .fulfillment	angeo/module-ucp-checkout 1.0+ (MCP tools: angeo/module-ucp-checkout-mcp)
dev.ucp.shopping.order (Get Order + webhooks)	angeo/module-ucp-checkout 1.1+
dev.ucp.shopping.permalink	a stock Magento cart URL (not gated)
cart, buyer consent	not available yet

bin/magento angeo:ucp:validate lists toggles that are on but have no effect. A module registers what it serves through the implementations argument of Angeo\Ucp\Model\Config in its di.xml.

REST endpoint. Leave Transport → REST Endpoint URL empty to advertise {baseUrl}/ucp/v1, where the catalog and checkout modules answer. Before 2.2.0 the default was {baseUrl}/rest/V1/ucp, which nothing served.

Security

• The profile is public and unauthenticated by design (per the UCP spec). Never put secrets, internal URLs, or admin contacts in it.
• Only public keys are published. The private key never leaves the server; ProfileGenerator reads public keys only (Config::getPublicKeys()), and any private JWK member (d, p, q, dp, dq, qi, oth, k) found in stored config is stripped before serving, with a warning telling you to rotate. See SECURITY.md.
• The endpoint sends X-Content-Type-Options: nosniff, X-Frame-Options: DENY, and Referrer-Policy: no-referrer.
• Rate-limiting is the operator's responsibility (reverse proxy / WAF).
• If a CDN/Varnish fronts the site, the Cache-Control header lets it cache the profile; purge /.well-known/ucp after rotating keys or changing config.