Skip to main content

Integration Preview — Planned Mechanics

This appendix collects the preview material extracted from the agent and provider integration guides. The current spec uses only the <link rel="trstd-protocol"> link tag; the mechanics below describe planned future work tracked on the roadmap. They are not normative.

Discovery (Planned)​

Agents will first fetch /.well-known/trstd.json and fall back to the link tag. The manifest adds provider metadata, multi-entity matching, extension parameters, and an McpServer capability for MCP-native agents. MCP and WebMCP extend discovery to agents that do not know the #trstd <protocol>. See mcp-discovery.md and the roadmap for status.

Entity Matching (Planned)​

Entity matching applies only when using the manifest. With the link tag alone, the entityId is pre-computed.

The manifest contains one or more entities, each scoping a section of the site by hostname and path prefixes. The agent takes the URL it is visiting and matches it against these entities:

  1. Match the hostname — filter entities where host matches the URL's hostname exactly. The host field must be an exact hostname — subdomain wildcards (e.g., *.example.org) are not supported.
  2. Match the path — among those, find all entities where the URL path matches one of the pathPrefixes entries. A prefix matches if the URL path equals the prefix or the next character in the path is /. The root prefix / matches all paths. This prevents /de from matching /demo or /delivery.
  3. Pick the longest prefix — if multiple entities match, the one with the longest matching prefix is the most specific scope. For example, given the URL /de/products/123, an entity with prefix /de wins over one with prefix /.

Matching considers only the URL's hostname and path. Ignore query strings and fragments — they do not affect entity selection. If no entity matches, the URL is not covered by any verified scope — the agent stops here.

interface Entity {
  entityId: string;
  host: string;
  pathPrefixes: string[];
}

function matchEntity(url: URL, entities: Entity[]): Entity | undefined {
  const hostMatches = entities.filter(
    (c) => c.host.toLowerCase() === url.hostname.toLowerCase()
  );

  let bestMatch: Entity | undefined;
  let bestLength = -1;

  for (const entity of hostMatches) {
    for (const prefix of entity.pathPrefixes) {
      const isMatch =
        prefix === "/" ||
        url.pathname === prefix ||
        url.pathname.startsWith(prefix + "/");
      if (isMatch && prefix.length > bestLength) {
        bestMatch = entity;
        bestLength = prefix.length;
      }
    }
  }

  return bestMatch;
}

Transparency Log Verification (Planned)​

When a transparency log is available, agents will cross-reference responses using meta.responseId against log endpoints (/v1/log/responses/{responseId}, /v1/log/entries/{responseHash}/proof). Endpoint schemas live in openapi-experimental.yaml.

Caching of Manifest Responses (Planned)​

When manifest discovery is in use, agents would cache /.well-known/trstd.json for up to 24 hours and cache 404 responses for manifest requests for at least 1 hour. Stale-manifest handling on 400 entityMismatch: invalidate the cache, re-fetch, retry.

See also​