Skip to main content

Validation Scenarios

This document tests the #trstd <protocol> specification against real-world use cases. Each scenario walks through the full flow — discovery, verification, and agent decision — to identify gaps or ambiguities.

Scenario 1: E-Commerce Purchase​

Context: A consumer's shopping agent searches for a laptop. It finds https://www.shop.example.org offering the best price. Before placing an order, the agent assesses trustworthiness.

Flow​

1. Discovery

The agent is on https://www.shop.example.org/de/laptops/thinkpad-x1. It scans the HTML <head> and finds:

<link
  rel="trstd-protocol"
  href="https://trust-authority.example.org/v1/entities/d6f2fdf4-f829-4ce6-a1cc-e2bd957709db/trust-signals"
  type="application/json"
  title="Trust Verification"
>

The agent validates that the href domain (trust-authority.example.org) is on its authority allowlist.

2. Verification

The agent builds the url parameter from the actual page URL it is visiting (not from the link tag) and appends it along with the context:

GET /v1/entities/d6f2fdf4-f829-4ce6-a1cc-e2bd957709db/trust-signals?url=https%3A%2F%2Fwww.shop.example.org%2Fde%2Flaptops%2Fthinkpad-x1&context=purchase HTTP/1.1
Host: trust-authority.example.org
Authorization: Bearer eyJhbGciOiJFZERTQSJ9.eyJpc3MiOiJkaWQ6d2ViOmFnZW50LmV4YW1wbGUuY29tIiwiYXVkIjoiYXBpLnRyc3RkLmNvbSJ9...
Accept: application/json

4. Response

{
  "meta": {
    "responseId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "entityId": "d6f2fdf4-f829-4ce6-a1cc-e2bd957709db",
    "status": "verified",
    "url": "https://www.shop.example.org/de/laptops/thinkpad-x1",
    "context": "purchase",
    "timestamp": "2026-03-20T10:00:00Z",
    "expires": "2026-03-21T00:00:00Z"
  },
  "signals": [
    {
      "type": "identity",
      "verifiedAt": "2025-08-10T00:00:00Z",
      "data": {
        "legalName": "Example Electronics GmbH",
        "country": "DE",
        "registrationNumber": "HRB 12345",
        "registrationAuthority": "Amtsgericht München",
        "incorporationDate": "2019-06-01"
      }
    },
    {
      "type": "reputation",
      "verifiedAt": "2026-03-15T00:00:00Z",
      "data": {
        "aggregateRating": 4.2,
        "reviewCount": 1247,
        "sourceCount": 3,
        "periodMonths": 12
      }
    },
    {
      "type": "compliance",
      "verifiedAt": "2025-11-01T00:00:00Z",
      "data": {
        "certifications": ["PCI-DSS", "GDPR"],
        "lastAudit": "2025-11-01",
        "auditor": "TÜV Rheinland"
      }
    },
    {
      "type": "recourse",
      "verifiedAt": "2026-01-15T00:00:00Z",
      "data": {
        "mechanism": "ombudsman",
        "provider": "EU ODR Platform",
        "responseTimeDays": 14,
        "url": "https://ec.europa.eu/consumers/odr"
      }
    },
    {
      "type": "contact",
      "verifiedAt": "2025-08-10T00:00:00Z",
      "data": {
        "emailVerified": true,
        "phoneVerified": true,
        "addressVerified": true,
        "supportUrl": "https://www.shop.example.org/support"
      }
    }
  ],
  "assessment": {
    "action": "proceed",
    "safeToPurchase": "yes",
    "reasoning": "Verified German business operating since 2019 with 4.2-star rating across 1,247 reviews, PCI-DSS and GDPR compliant, and EU ODR recourse available.",
    "highlights": [
      "Business profile verified and published",
      "Customer satisfaction ratings available (4.2/5 from 1,247 reviews)",
      "PCI-DSS and GDPR compliant, audited by TÜV Rheinland",
      "EU ODR recourse with 14-day response commitment"
    ]
  },
  "kid": "authority-key-1",
  "signature": "pV2qFz8kRn0LhVbUqSSR3IyzQlDu5XbE0MwvMXfBjlNRqIjmGT6c2Eq..."
}

5. Agent Decision

The agent uses the assessment as a fast path: action: "proceed" with supporting reasoning and highlights. For more detail, the agent can evaluate individual signals:

  • Identity verified, registered in Germany since 2019
  • 4.2/5 rating from 1,247 reviews across 3 sources
  • PCI-DSS and GDPR compliant, audited 4 months ago
  • EU ODR recourse available
  • All contact channels verified

The agent proceeds with the purchase.

What This Tests​

  • Full discovery-to-decision flow with link tag discovery
  • Agent constructs url from its own navigation state, not from page content
  • Multiple signal types in a single response
  • Agent verifies signature before processing
  • camelCase field naming throughout

Scenario 2: Unknown Entity​

Context: An agent visits https://shady-deals.example.org. The site has no trstd discovery mechanism.

Flow​

1. Discovery

  • No <link rel="trstd-protocol"> tag in HTML

2. Agent Decision

Discovery failed. The agent cannot assess trust through the #trstd <protocol>. Per the specification, the absence of discovery means the service has not opted into the protocol. The agent treats this as an unknown-trust scenario and applies its default policy (e.g., warn the user, refuse to transact, or proceed with heightened caution).

What This Tests​

  • Graceful handling of missing discovery
  • Protocol does not force a binary trusted/untrusted decision — "unknown" is a valid state
  • Agent platform policies govern behavior when trstd data is unavailable

Scenario 3: Expired Response and Cache Behavior​

Context: An agent previously cached a trust response for https://www.shop.example.org. The meta.expires timestamp has passed. The trust authority is temporarily unreachable.

Flow​

1. Cache Check

The agent has a cached response with "expires": "2026-03-19T12:00:00Z". The current time is 2026-03-20T09:00:00Z. The response has expired.

2. Re-query

The agent queries the trust authority. The authority returns a network error (connection timeout).

3. Agent Decision

The specification requires agents to reject expired cached responses (see architecture/api.md). The agent cannot verify trust. Options:

  • Retry after a delay
  • Inform the user that trust verification is temporarily unavailable
  • Apply a fallback policy (e.g., allow low-value transactions, block high-value ones)

What This Tests​

  • Expiration enforcement
  • Authority unavailability does not silently degrade to stale trust data
  • Agent platforms need a fallback policy for authority outages

Scenario 4: Tampered Response Detection​

Context: A man-in-the-middle intercepts the trust response and changes the aggregateRating from 2.1 to 4.8.

Flow​

1. Agent Receives Tampered Response

The response body has been modified, but the signature field still contains the original signature.

2. Signature Verification

The agent:

  1. Fetches the authority's JWKS from https://trust-authority.example.org/.well-known/jwks.json
  2. Selects the key matching the kid field in the response body
  3. Removes the signature field, JCS-canonicalizes the remaining body, and verifies the Ed25519 signature
  4. Verification fails — the body has been modified

3. Agent Decision

The agent rejects the response. Per architecture/security.md, agents reject responses with invalid signatures and treat them as if no trust data is available.

What This Tests​

  • Application-layer signature catches modification that TLS alone would not (e.g., if the response was cached by a compromised proxy)
  • Agent behavior on signature failure is well-defined: reject entirely

Scenario 5: Entity Mismatch​

Context: An agent sends an incorrect entityId for the URL it is visiting.

Flow​

1. Discovery and Matching Error

The agent visits https://www.shop.example.org/fr/products/123 but due to a bug sends the entity for /de instead of /.

2. Verification

GET /v1/entities/d6f2fdf4-f829-4ce6-a1cc-e2bd957709db/trust-signals?url=https%3A%2F%2Fwww.shop.example.org%2Ffr%2Fproducts%2F123 HTTP/1.1

3. Response

{
  "error": "entityMismatch",
  "message": "URL does not fall within the scope of the specified entity"
}

The server returns 400 because /fr/products/123 does not match the /de path prefix of the specified entity.

4. Agent Decision

An entityMismatch error indicates the link tag on the page contains an incorrect entityId — the agent cannot self-correct and treats the result as a discovery failure.

What This Tests​

  • Server-side validation of URL-to-entity scope matching
  • entityMismatch error response
  • Agent failure reporting on link-tag misconfiguration

See also: Planned validation scenarios cover scenarios that depend on planned manifest discovery (multi-entity matching, API-only services with no HTML, manifest-based recovery from entityMismatch).