ADR-007: Security and Anti-Gaming

Status: Accepted Date: 2026-03-20

Context

Trust data is high-value — if an attacker can manipulate trust signals, they can redirect agent-driven commerce toward malicious services. The protocol must ensure that trust signals cannot be forged, tampered with, or retroactively altered.

The threat model (context/threat-model.md) identifies signal spoofing, manipulation in transit, replay attacks, and authority corruption as key threats.

Decision

Use signed responses today, with a transparency log on the roadmap. All trust responses are cryptographically signed by the authority at the application layer. A public, append-only transparency log will add auditability once the trust model and Merkle tree design are fully specified.

Response Signatures

The trust authority signs every response using its private key. The signature covers the entire response body (entity metadata + signals + timestamp + expiration).

Signing algorithm: Ed25519 (EdDSA). Compact signatures, fast verification, no configuration choices.

Signature format: The response body includes a kid field (key identifier) and a signature field containing the base64url-encoded raw Ed25519 signature. The signing input is the JCS-canonicalized (RFC 8785) response body with the signature field excluded.

Key publication: The authority publishes its public signing keys at a well-known endpoint (e.g., https://trust-authority.example.org/.well-known/jwks.json). Agents fetch and cache these keys.

Key rotation: The authority MAY rotate signing keys. Old keys remain published for verification of responses signed before rotation. The response body's kid field identifies which key was used.

Verification Requirements

Agents MUST:

1. Verify the response signature against the authority's published public key
2. Check that the response has not expired (expires field)
3. Reject responses with invalid or missing signatures

Agents SHOULD:

• Cache the authority's public keys with a reasonable TTL

Binding the Signed Response to the Request

The signed meta object includes meta.url and meta.context so the signed payload binds the request that produced it. Without this binding, a cached signed response is portable across any page covered by the same entity scope: a phishing page at a subpath could present a legitimate cached signature obtained for a different page within the same scope. The expires field handles temporal replay; meta.url and meta.context close the contextual-replay class within an entity's scope. Canonicalization rules and agent verification steps are normative and live in architecture/api.md — URL Canonicalization and architecture/security.md — Verification.

URL granularity choice. The signed meta.url is the canonical scheme + "://" + host + path — origin and path only. Four alternatives were considered:

• Sign the full URL as sent. Bakes session identifiers, tracking parameters, and other user-specific state into a signed, cacheable artifact. Conflicts with the URL-privacy tradeoff in architecture/api.md. Rejected.
• Sign origin + path + sorted query string. Captures pages where a query parameter is semantically meaningful (e.g., ?productId=123), but forces the protocol to define which query parameters are "safe" to sign and which carry tracking data — expanding spec surface and creating a per-deployment allowlist problem. Rejected.
• Sign origin + path (chosen). Matches the granularity of entity-scope matching, which already ignores query and fragment. Privacy-preserving. Two URLs that differ only in query string share a signed response — consistent with scope matching, not a regression. Canonicalization rules are short enough that two independent implementations can agree without an interop test suite.
• Don't bind URL; tighten scope guidance instead. Recommends authorities issue narrow pathPrefixes. Addresses the symptom but leaves signature portability open as a class of attack, depending on per-deployment configuration discipline rather than a protocol guarantee. Rejected.

This decision does not address in-scope phishing, where the attacker controls a real page within the entity's legitimate scope. That is a scope-tightness problem and is out of scope here.

Transparency Log (planned)

The transparency log is on the roadmap, not in the current spec. The signed-response mechanism is sufficient for present-day integrity. The log adds governance transparency — the ability to detect authority misbehavior — which requires a complete trust model (signed checkpoints, consistency proofs, third-party monitors) not yet specified.

The planned design follows the Certificate Transparency model (RFC 6962): a public, append-only Merkle tree of all responses. See architecture/security.md for the forward-looking design.

Anti-Gaming Measures

Threat	Mitigation
Forged signals	Agents verify the authority's signature — only the authority can produce valid signatures
Tampered responses	Application-layer signatures detect any modification after signing
Stale/replayed responses	expires field enforces freshness
Contextual replay across URLs within entity scope	meta.url and meta.context bind the signed response to the request that produced it (see Binding the Signed Response to the Request)
Silent revocation	Tracked on the roadmap (transparency log)
Backdated signals	Tracked on the roadmap (transparency log)
Authority misbehavior	Tracked on the roadmap (transparency log)

Options Considered

A. Signed responses only. Tamper-evident. No public auditability — the authority can silently issue, revoke, or alter signals without external oversight. Sufficient for transport integrity but not for governance.

B. TLS-only. Relies on HTTPS transport security. No application-layer integrity. Cached, proxied, or stored responses become unverifiable. Insufficient for trust data that may be forwarded or persisted.

C. Signed responses with transparency log (chosen as the long-term direction). Combines transport integrity (signatures) with governance transparency (public log). The authority's actions become auditable. Higher operational cost, but the trust authority is a single entity (ADR-005) — it operates one log. The current spec ships signed responses (Option A); the transparency log follows on the roadmap once the trust model is complete.

Consequences

• Every response carries a cryptographic signature — agents verify before processing
• Signed responses remain verifiable when cached — reduces load on the authority
• Key management is required: key publication, rotation, and revocation
• The planned transparency log will add infrastructure cost and operational responsibility
• The current spec does not provide external auditability of the authority's behavior — agents trust the authority based on signatures alone

References

• ADR-005 — Trust Authority Model (single authority operates the log)
• context/threat-model.md — T1, T3, T4, T9 (addressed by this decision)
• RFC 6962 — Certificate Transparency
• RFC 8037 — CFRG Elliptic Curve Diffie-Hellman and Signatures (Ed25519)
• RFC 8785 — JSON Canonicalization Scheme (JCS)