Skip to main content

Discovery

This document specifies how agents discover the trstd verification endpoint for a given service provider.

Normative language follows RFC 2119: MUST, SHOULD, MAY indicate requirement levels.

Overview​

Service providers embed a <link rel="trstd-protocol"> tag in their HTML pages. The tag points agents directly to the trust authority's HTTP verify endpoint with the entity's entityId already in the URL path. Agents scan HTML, extract the endpoint URL, append the page URL as a query parameter, and make a single HTTP GET.

Service providers MUST include a link tag in the <head> of their HTML pages pointing to the trust authority's verify endpoint:

<link
  rel="trstd-protocol"
  href="https://trust-authority.example.org/v1/entities/09b765de-08ed-4b95-bd38-35d6d9ed9c19/trust-signals"
  type="application/json"
  title="Trust Verification"
>

The href attribute MUST contain the trust authority's verify endpoint URL with the entity's entityId as the final path segment (/v1/entities/{entityId}/trust-signals). The provider determines the correct entityId for the page at render time. The trust authority provides the entityId values during onboarding.

Agents MUST build the url parameter from the actual page URL they are visiting — not from any value in the link tag. The agent appends ?url=...&context=... to the href and makes an HTTP GET request. This prevents a crafted link tag from redirecting verification to a different resource.

The href domain MUST match a known trust authority (see Authority Domain Allowlist below). Agents MUST NOT send requests to endpoints on unrecognized domains.

The entityId format is opaque to agents — they receive it from the link tag and pass it unchanged to the verify endpoint. The authority defines the format. Because the entityId appears as a URL path segment, it MUST match ^[A-Za-z0-9._~-]+$ (RFC 3986 unreserved characters); examples in this specification use UUIDs, but any string from this character set is valid.

Rendering. Service providers SHOULD include the link tag in the server-rendered HTML response for broadest agent compatibility. Service providers MAY inject the tag via client-side JavaScript (e.g., a plugin or tag manager); when doing so, the tag MUST be present in the DOM after initial page load completes — before the page is considered interactive. Agents that operate a browser or rendering engine SHOULD process the fully rendered DOM rather than the raw HTTP response. Agents that parse only the raw HTTP response body MAY miss dynamically injected tags; this is a known limitation of raw-HTML discovery.

Agent Discovery Procedure​

Agents MUST discover the <link rel="trstd-protocol"> tag from the page's <head>. Agents that operate a browser or rendering engine SHOULD process the rendered DOM. Agents that parse only the raw HTTP response body MAY miss tags injected by client-side JavaScript. If found, agents extract the verify endpoint URL (which already contains the entityId as its final path segment), validate the domain against the authority allowlist, append ?url=...&context=..., and make an HTTP GET request.

Agents MUST NOT proceed with trust verification if no link tag is found. The absence of a trstd discovery pointer means the service provider has not opted into the protocol.

Validation​

Agents MUST validate the link tag before sending a request:

  • The href URL MUST use HTTPS
  • The href domain MUST match a known trust authority (see Authority Domain Allowlist below)
  • The href path MUST end with /v1/entities/{entityId}/trust-signals where {entityId} matches ^[A-Za-z0-9._~-]+$. Agents MUST reject link tags whose final path segment violates this constraint.

Authority Domain Allowlist​

Agents MUST maintain an allowlist of trusted authorities and reject link tags whose endpoint domain is not on the list. This is the primary defense against authority impersonation — without it, any domain can claim to be a trust authority.

Each allowlist entry MUST contain at minimum:

FieldTypeDescription
domainstringFully-qualified domain of the authority. The link-tag href domain MUST match this value exactly.
jwksUrlstring (URL)HTTPS URL where the authority's JWKS is served. The URL is pinned in the allowlist — agents MUST NOT infer the JWKS URL from domain.

Agents MUST enforce these rejection rules:

  • Reject link tags whose href domain does not match any allowlist entry's domain, before sending any request.
  • Reject any JWKS fetched from a URL other than the pinned jwksUrl for the corresponding authority.
  • jwksUrl MUST use HTTPS. The URL MAY be on a different host than domain (for example, a CDN or separate operational boundary).

The way an allowlist is delivered (hardcoded list, configuration file, signed remote registry) is the agent operator's choice; every distribution path MUST produce entries with the fields above. See ADR-009 for trust-model rationale and security.md — Key Rotation for JWKS refresh and revocation semantics.

For testing and development, agents MAY support a configuration override that disables this check — such overrides MUST NOT be enabled in production.

Integrity​

The link tag's integrity depends on the HTML page's HTTPS transport. If a provider's domain is compromised (CDN misconfiguration, DNS hijack), an attacker can inject a malicious link tag pointing agents to a rogue endpoint. The protocol mitigates this at the response layer: agents verify the authority's Ed25519 signature on every response using the authority's published JWKS. A rogue endpoint cannot forge valid signed responses. The authority domain allowlist provides an additional check — agents reject link tags whose href domain is not on the allowlist.

Caching​

Agents cache verify responses per the expires field in the response.

Future work​

Additional discovery mechanisms — a /.well-known/trstd.json manifest, MCP server, and WebMCP registration — are tracked on the roadmap to reach agents that do not know the #trstd <protocol>.

References​