diff --git a/proto/CHANGELOG.md b/proto/CHANGELOG.md index c37a721b..96ae2e74 100644 --- a/proto/CHANGELOG.md +++ b/proto/CHANGELOG.md @@ -36,7 +36,7 @@ and the onboarding page's code comments name an RSL license rather than a file. **A term can require usage reporting (additive protocol change).** `ObligationKind` gains `OBLIGATION_KIND_REPORTING`, and `Obligation` gains an optional `reporting` field, a `ReportingObligation` that states the `window` within which the agent files `ReportUsage` and the `required_fields` the report carries. The Exchange carries the obligation onto `Offer.reporting`: `required` is true, the window and fields are the obligation's where it states them and the Exchange's own where it does not, and the endpoint is the Exchange's. A term without one keeps the Exchange's own reporting policy. Four rules: `obligation.reporting.requires_reporting_kind` (the field only on that kind), `obligation.reporting.no_endpoint` (the Exchange sets the endpoint), `license_term.reporting.metering_none` (a term metered `NONE` needs no report, so it cannot carry one) and `offer.reporting.required_by_term` (an offer selling such a term requires a report). A revenue-share term now states its reporting duty on the term. The TypeScript and Python cross-field mirrors, the conformance corpus and the license-term vectors cover the four rules. Licensing Terms, Transaction Flow and the CoMP extension say the same. -**An offer carries restriction tokens in canonical form, and the party that sets a license URI supplies its digest (comments only; no wire change).** The `LicenseTerm` comment now says what an Exchange already does: the term on an offer carries each restriction token as ingest canonicalized it (trimmed, case-folded, alias-resolved), with no other translation or reformulation, so an agent compares tokens against the registry without folding them itself. The `License.uri_digest` comment no longer says the Exchange computes the digest at ingestion: the party that sets `uri` supplies the digest with it, the publisher on a term it pushes. Licensing Terms and the threat model (T-LIC-4) say the same. Proto examples use `news.example` and a generic collecting society in place of real company names. +**An offer carries restriction tokens in canonical form, and the party that sets a license URI supplies its digest (comments only; no wire change).** The `LicenseTerm` comment now says what an Exchange already does: the term on an offer carries each restriction token as ingest canonicalized it (trimmed, case-folded, alias-resolved), with no other translation or reformulation, so an agent compares tokens against the registry without folding them itself. The `License.uri_digest` comment no longer says the Exchange computes the digest at ingestion: the party that sets `uri` supplies the digest with it, the publisher on a term it pushes. Licensing Terms says the same. Proto examples use `news.example` and a generic collecting society in place of real company names. **fora-music-v1 carries the rights data a cue sheet needs, and finds tracks by key, version, publisher and IPI (additive; no wire change).** `music.publishers` lists the music publishers diff --git a/website/redirects.json b/website/redirects.json index a4c212c2..3789720f 100644 --- a/website/redirects.json +++ b/website/redirects.json @@ -3,5 +3,10 @@ "source": "https://www.fora-protocol.org", "status": "302", "target": "https://fora-protocol.org" + }, + { + "source": "/security/threat-model/", + "target": "/protocol/authentication/", + "status": "301" } ] diff --git a/website/routes.txt b/website/routes.txt index 804caf32..fdae2f45 100644 --- a/website/routes.txt +++ b/website/routes.txt @@ -96,4 +96,3 @@ /resources/music-dsp/ /resources/transparent-collective/ /resources/transparent-collective/evidence/ -/security/threat-model/ diff --git a/website/src/content/docs/components/broker/deployment.mdx b/website/src/content/docs/components/broker/deployment.mdx index e5c4fc1b..51567e05 100644 --- a/website/src/content/docs/components/broker/deployment.mdx +++ b/website/src/content/docs/components/broker/deployment.mdx @@ -306,9 +306,9 @@ Each Exchange scopes the key to the agent, whatever the route, so two agents beh | Threat | Attack | Countermeasure | |---|---|---| -| **T19**: Hidden orchestration fee | Broker adds markup to relayed offers | Signed offers passed through. Agent verifies signature. Any fee is disclosed separately. | -| **T20**: Kickback-driven selection | Broker has side deal with an Exchange | Selection rationale logged. Agent can spot-check by querying directly. | -| **T21**: Query intelligence harvesting | Broker logs queries and sells data | Data processing agreements. In sidecar mode, agent operator controls the Broker. | +| Altering offers in transit | Broker raises a price or changes the terms of a relayed offer | The Exchange signs every offer field. A changed offer fails its signature, and the agent's acceptance signs the offer it chose. | +| Steering discovery toward favored Exchanges | Broker has a side deal with an Exchange | Not stopped by the protocol. The agent can query Exchanges directly and buy there. | +| Collecting agents' queries | Broker logs queries and sells data | Not stopped by the protocol. A data-handling agreement covers it, or the agent operator runs its own Broker. | ### TLS Requirements @@ -316,9 +316,9 @@ All Exchange communication uses TLS 1.3 minimum. The Broker's HTTP clients are c ### Exchange Public Keys -The Broker fetches the Exchange's offer-signing keys from its WBA directory (the JWK Set at `/.well-known/http-message-signatures-directory`). Public keys are cached in Redis with a 24-hour TTL. On signature verification failure, the cache is refreshed before retrying. +The Broker fetches the Exchange's offer-signing keys from its WBA directory (the JWK Set at `/.well-known/http-message-signatures-directory`). It caches each Exchange's keys in memory, per Exchange domain, for five minutes and never past a key's `not_after`. -Key rotation: Exchanges SHOULD publish both current and previous keys during a rotation window (recommended: 7 days). +Key rotation: an Exchange publishes the new key beside the old one for the grace period [Key Rotation](/protocol/authentication/#key-rotation) describes, so offers signed with either key verify. ### Metrics diff --git a/website/src/content/docs/components/edge-function/bot-detection.mdx b/website/src/content/docs/components/edge-function/bot-detection.mdx index 3d458579..ff8311ba 100644 --- a/website/src/content/docs/components/edge-function/bot-detection.mdx +++ b/website/src/content/docs/components/edge-function/bot-detection.mdx @@ -21,11 +21,11 @@ Known AI crawler User-Agents. This is the primary detection mechanism. The AI co |---|---|---| | Training and datasets | Collects pages to train models or build datasets | `403` | | Live fetch | Loads a page because a person asked a question | `403` | -| AI search | Builds the index that the vendor's AI search and answers draw on | Let through by default; the provider may choose `403` | +| AI search | Builds the index that the vendor's AI search and answers draw on | The provider decides per crawler | -A live fetch and a training crawl are what an agent buys a license for, so both get the `403` that points to the Exchange. An AI search crawler decides whether the site appears in that vendor's AI search at all. The vendors document that blocking one removes the site from those results, so the provider chooses, and by default the edge function lets it through. +A live fetch and a training crawl are what an agent buys a license for, so both get the `403` that points to the Exchange. An AI search crawler decides whether the site appears in that vendor's AI search at all. The vendors document that blocking one removes the site from those results, so the provider chooses which to let through. The default deny list refuses most of them, including OAI-SearchBot and PerplexityBot, and its generic `bot` token catches others; a provider that wants to stay in a vendor's AI search lets that crawler through with its own lists. -
{[
+
{[
   '# Training and datasets: 403 on licensed paths',
   botLines('training'),
   '',
@@ -33,13 +33,13 @@ A live fetch and a training crawl are what an agent buys a license for, so both
   botLines('live-fetch'),
   `${'fora-ai-buyer'.padEnd(24)}- a FORA agent that names itself`,
   '',
-  '# AI search: let through unless the provider chooses 403',
+  '# AI search: the provider decides',
   botLines('ai-search'),
 ].join('\n')}
The lists come from one file, `website/src/data/ai-bots.ts`, with each bot's vendor documentation; they are also published as [`/registry/ai-bots.json`](/registry/ai-bots.json) and shown, with what refusing each one costs, on [What you can do about AI crawlers today](/resources/ai-crawlers/). -The edge function keeps these lists in configuration (KV store or inline config): the first two kinds in `bot_detection.user_agent_patterns`, the AI search crawlers in `bot_detection.ai_search_patterns`, with the provider's choice in `bot_detection.ai_search_policy` (see [Edge function deployment](/components/edge-function/deployment/)). A bot moves between lists when its vendor changes what it does, and leaves them when its vendor retires it. +The edge function has built-in lists: a deny list of AI bots, which also matches the generic tokens `bot`, `crawler` and `spider`, and an allow list of search crawlers that read for free, such as Googlebot and Bingbot. An empty User-Agent is treated as a bot. A provider replaces either list with `BOT_UA_DENY_JSON` or `BOT_UA_ALLOW_JSON` (see [Edge function deployment](/components/edge-function/deployment/)). A bot moves between lists when its vendor changes what it does, and leaves them when its vendor retires it. #### Search crawlers that also serve AI @@ -61,7 +61,7 @@ All major CDNs maintain their own bot classification databases: - **Fastly**: Signal Sciences WAF -- bot detection signals. - **CloudFront**: AWS WAF Bot Control -- managed rule group with bot categorization. -These are available as request metadata without any computation cost at the edge. The edge function can check CDN-native bot signals as a second layer. +These are available as request metadata without any computation cost at the edge. The edge function reads Cloudflare's verified-bot signal on Cloudflare, where it overrides User-Agent matching. On Fastly and CloudFront it reads none, so a crawler that claims a search crawler's User-Agent passes there. ### Layer 3: Behavioral Signals (0ms -- pattern matching) @@ -73,7 +73,7 @@ Heuristic patterns that indicate automated access: - **Sequential path access**: Bots tend to walk paths sequentially (`/premium/1`, `/premium/2`, ...). Humans jump around. - **TLS fingerprint**: JA3/JA4 fingerprint mismatches (User-Agent claims to be Chrome but TLS fingerprint is Python `requests`). -Layer 3 signals are supplementary. They can reduce false positives (bot with unknown User-Agent) but should not override a valid signed URL. +Layer 3 signals are supplementary. They can reduce false positives (bot with unknown User-Agent) but should not override a valid signed URL. The edge function does not compute them; they are what the CDN's own bot product uses, which is why it stays on beside the edge function. ## Bot Classification Tiers @@ -250,30 +250,26 @@ When a bot is detected on a protected path without a signed URL: ```http HTTP/1.1 403 Forbidden Content-Type: application/json -X-Content-Rules: https://techcrunch.com/.well-known/fora.json -X-FORA-Exchange: exchange.ssp-example.com -Cache-Control: no-store +X-Content-Rules: https://publisher.example/.well-known/fora.json +X-FORA-Exchange: exchange.example ``` ```json { - "error": "Licensed content. Negotiate access via the Exchange.", - "protocol": "FORA", - "version": "1.0", - "fora_json_url": "https://techcrunch.com/.well-known/fora.json" + "error": "Access denied. Negotiate access via the exchange.", + "reason": "ai_bot" } ``` **Header semantics** (the FORA edge discovery headers; the normative rules are in [Discovery Paths](/protocol/discovery-paths/#edge-discovery-headers)): - `X-Content-Rules` -- the absolute URL of the provider's own manifest, `https:///.well-known/fora.json`. This is the key discovery mechanism for bots that did not check `fora.json`: the manifest carries the licensing terms and, in `exchanges[]`, the Exchanges that sell this content. It never points at an Exchange. - `X-FORA-Exchange` -- optional. The bare domain of one Exchange that sells this content directly, in the same form as `Offer.exchange` (no scheme, no path). An agent can start discovery there without fetching the manifest first, resolving the Exchange's endpoint from the Exchange's own `fora.json`. It is an optimisation, not authorization: the edge sends it only beside `X-Content-Rules` and only for an Exchange the manifest lists, and when the two disagree the manifest wins. -- `Cache-Control: no-store` -- the 403 should not be cached. Content availability may change. **Body semantics**: -- `error` -- human/machine readable explanation. -- `protocol` -- identifies this as a FORA protocol response, not a generic 403. -- `version` -- protocol version for forward compatibility. -- `fora_json_url` -- same as the `X-Content-Rules` header, in the body for agents that parse JSON responses. The body is informative; the headers are the protocol. +- `error` -- a human-readable explanation. +- `reason` -- `ai_bot`, the same token the edge function's log record carries. Every edge refusal uses this `{error, reason}` shape. + +The body is informative; the headers are the protocol. ## Classification Algorithm diff --git a/website/src/content/docs/components/edge-function/cdn-adapters.mdx b/website/src/content/docs/components/edge-function/cdn-adapters.mdx index cb3b1d4a..846ade23 100644 --- a/website/src/content/docs/components/edge-function/cdn-adapters.mdx +++ b/website/src/content/docs/components/edge-function/cdn-adapters.mdx @@ -35,8 +35,6 @@ interface EdgeContext { /** Provider configuration loaded from config source. */ config: EdgeConfig; - /** Edge KV store (optional, for single-use enforcement). */ - kv?: EdgeKV; } interface EdgeResponse { @@ -45,13 +43,6 @@ interface EdgeResponse { body: string | ReadableStream | null; } -interface EdgeKV { - /** Atomic put-if-absent. Returns true if key was inserted (first use). */ - putIfAbsent(key: string, value: string, ttlSeconds: number): Promise; - /** Read a key. */ - get(key: string): Promise; -} - interface EdgeConfig { /** Glob patterns that require a license (carry FORA terms); all other paths * are open. Compiled from RSL/catalog entries — a local edge type, not a wire @@ -75,9 +66,6 @@ interface EdgeConfig { /** Optional pinned public keys; a covering `kid` skips the directory fetch. */ verifyKeys?: JsonWebKey[]; - /** Whether to enforce single-use URLs (best-effort). Requires kv. */ - singleUseEnabled: boolean; - /** Whether to enforce agent identity binding. Defaults to true. */ enforceBinding: boolean; } @@ -110,17 +98,15 @@ graph LR end subgraph "Optional" - LAMBDA["Lambda@Edge
(origin request)
Single-use enforcement
Agent identity binding"] - DDB["DynamoDB Global Table
(single-use tracking)"] + LAMBDA["Lambda@Edge
(origin request)
Agent identity binding"] end CF_FUNC --> BEHAVIOR BEHAVIOR --> LAMBDA - LAMBDA --> DDB ``` - **CloudFront Function** handles bot detection and signature passthrough, and hands `/.well-known/fora.json` and `/rsl.txt` back to CloudFront, which fetches them from the origin. CloudFront's `trusted_key_groups` on the cache behavior natively verifies RSA-signed URLs -- no custom code needed. -- **Lambda@Edge** (optional) handles agent identity binding and single-use enforcement. These require network access (DynamoDB lookup) which CloudFront Functions cannot do. +- **Lambda@Edge** (optional) handles agent identity binding, which needs an Ed25519 verification CloudFront Functions cannot run within their limits. **What CloudFront does natively that you do not reimplement**: - RSA signature verification on signed URLs via `trusted_key_groups` configured on the cache behavior. The CDN itself rejects invalid signatures before your function code runs. @@ -131,7 +117,6 @@ graph LR - Bot detection (User-Agent check against `botPatterns`). - Handing `/.well-known/fora.json` and `/rsl.txt` to the origin, ahead of bot detection. - Custom parameters validation (agent_id binding). -- Single-use enforcement (requires Lambda@Edge + DynamoDB, best-effort). - The 403 response body and the `X-Content-Rules` and `X-FORA-Exchange` headers. ```javascript @@ -190,29 +175,25 @@ function handler(event) { | Memory | 128 MB | | Network access | Yes (fetch) | | KV access | Workers KV (eventually consistent, ~60s) | -| Durable Objects | Yes (strongly consistent, for single-use) | | Native signed URL verification | No (no equivalent to CloudFront trusted_key_groups) | | Package size | 10 MB | | Languages | JavaScript, TypeScript, Rust (WASM) | **Key difference from CloudFront**: Cloudflare has no native signed URL verification. The Worker verifies the Ed25519 signature in code, using **only** the Exchange's public key. Nothing secret is deployed to the edge. -**Recommended approach**: Single Worker with optional Durable Objects. +**Recommended approach**: Single Worker. ```mermaid graph LR subgraph "Cloudflare Edge" WORKER["Cloudflare Worker
Bot detection
fora.json + rsl.txt passthrough
Ed25519 signature verification
Agent identity binding"] KV["Workers KV
Config cache
Bot pattern updates"] - DO["Durable Object
(optional)
Single-use enforcement
Atomic check-and-consume"] end WORKER --> KV - WORKER --> DO ``` - **Signature verification**: Must be done in Worker code. Use `crypto.subtle.verify` with the `Ed25519` algorithm and the imported public key. Workers support Ed25519 natively; Fastly does not, which is why the SDK's verifier accepts an injected implementation. -- **Single-use enforcement**: Workers KV is eventually consistent (up to 60 seconds propagation). For strict single-use, use Durable Objects which provide transactional consistency. For soft single-use (acceptable eventual consistency), Workers KV with a short TTL is cheaper. - **Config**: Store `EdgeConfig` in Workers KV. Refresh on a timer or via Cron Trigger. ## Akamai @@ -241,7 +222,6 @@ mean writing the Ed25519 verifier as an EdgeWorker, which the platform's 4 ms bu **Key advantages**: - No execution time limit (billed per request + compute duration). Complex verification logic is fine. -- Fastly KV Store is strongly consistent within a POP, making single-use enforcement reliable without the eventual-consistency problems of Workers KV or EdgeKV. - Full WASM runtime means you can compile the same Rust/Go verification logic that runs in the Exchange. **With the TypeScript SDK**: Fastly's JavaScript runtime has no WebCrypto Ed25519 and no `AbortController`. Pass `verifyEd25519` to the SDK's verifiers and directory readers; its document reads need no `AbortController`, and still end at their 30-second deadline. @@ -251,8 +231,8 @@ mean writing the Ed25519 verifier as an EdgeWorker, which the platform's 4 ms bu ```mermaid graph LR subgraph "Fastly Edge" - COMPUTE["Compute Service (WASM)
Bot detection
fora.json + rsl.txt passthrough
Ed25519 signature verification
Agent identity binding
Single-use enforcement"] - KV_STORE["KV Store
Config + single-use tracking
(strongly consistent in-POP)"] + COMPUTE["Compute Service (WASM)
Bot detection
fora.json + rsl.txt passthrough
Ed25519 signature verification
Agent identity binding"] + KV_STORE["KV Store
Config"] CONFIG_STORE["Config Store
Signing keys, bot patterns"] end @@ -268,8 +248,6 @@ graph LR | fora.json + rsl.txt passthrough | Yes | Yes | Yes | Yes | | Native signed URL verification | Yes (trusted_key_groups) | Yes (trusted_key_groups) | No (must implement) | No (must implement) | | Ed25519 signed-URL verification | No (1ms limit, no Ed25519) | Yes | Yes (native Web Crypto) | Yes (injected verifier) | -| Agent identity binding | No (no network) | Yes | Yes | Yes | -| Single-use enforcement | No (no KV write) | Yes (DynamoDB) | Yes (Durable Objects) | Yes (KV Store, strong) | -| Consistency model | N/A | Strong (DynamoDB) | Strong (Durable Objects) | Strong (in-POP) | +| Agent identity binding | No (no Ed25519) | Yes | Yes | Yes | | Latency overhead | <0.1ms | 1-5ms | <1ms | <1ms | -| Cost at 1M req/day | $0.10 | $0.70 + DDB | $0.50 | Usage-based | +| Cost at 1M req/day | $0.10 | $0.70 | $0.50 | Usage-based | diff --git a/website/src/content/docs/components/edge-function/overview.mdx b/website/src/content/docs/components/edge-function/overview.mdx index aca201f0..67816482 100644 --- a/website/src/content/docs/components/edge-function/overview.mdx +++ b/website/src/content/docs/components/edge-function/overview.mdx @@ -10,7 +10,7 @@ The Edge Function is the provider-side enforcement point of the FORA protocol. I The Edge Function has four jobs: 1. **Block unauthorized bots** -- detect AI crawlers hitting protected content without a signed URL and return `403` with an `X-Content-Rules` header pointing them at the provider's own `fora.json`, and optionally an `X-FORA-Exchange` header naming an Exchange that sells the content. -2. **Verify signed URL access** -- validate that incoming signed URLs are authentic, unexpired, bound to the correct agent identity, and (optionally) single-use. +2. **Verify signed URL access** -- validate that incoming signed URLs are authentic, unexpired and bound to the purchasing agent's key, and record each delivery in the edge's delivery log. 3. **Pass fora.json and rsl.txt through to the origin** -- forward `/.well-known/fora.json` and `/rsl.txt` to the provider's own origin for every client, ahead of both checks above, so protocol-aware agents discover the Exchange without triggering a 403. 4. **Serve verifier keys via the WBA directory (v1.0)** -- serve the JWK Set at `/.well-known/http-message-signatures-directory` for providers that self-attest resources. This publishes the provider's Ed25519 public keys in its WBA directory (the JWK Set at `/.well-known/http-message-signatures-directory`), with the claims schema in the `fora.json` `ext["fora.attestation.claims_schema"]`, so agents and Exchanges can verify attestation signatures. FORA has no dedicated verifier role; a verifier publishes under its operator's role (`role=ROLE_PUBLISHER` when a publisher self-attests). @@ -45,17 +45,14 @@ flowchart TD PROTECTED -->|Yes| HAS_SIG{Has signed URL
parameters?} HAS_SIG -->|Yes| VERIFY_SIG{Signature valid?} VERIFY_SIG -->|No| BLOCK_INVALID[403: Invalid signature
ALWAYS 403 regardless
of bot status] - VERIFY_SIG -->|Yes| CHECK_EXPIRY{URL expired?
TTL within max?} + VERIFY_SIG -->|Yes| CHECK_EXPIRY{URL expired?} CHECK_EXPIRY -->|Expired| BLOCK_EXPIRED[403: URL expired] CHECK_EXPIRY -->|OK| CHECK_AGENT{Agent binding
enabled?} CHECK_AGENT -->|Yes| VERIFY_AGENT{agent_id matches
requester?} - CHECK_AGENT -->|No| CHECK_SINGLE_USE + CHECK_AGENT -->|No| LOG_DELIVERY VERIFY_AGENT -->|No| BLOCK_AGENT[403: Agent mismatch] - VERIFY_AGENT -->|Yes| CHECK_SINGLE_USE{Single-use
enabled?} - CHECK_SINGLE_USE -->|Yes| KV_CHECK{KV: put-if-absent
transaction_id} - CHECK_SINGLE_USE -->|No| ALLOW[Allow request
to origin/cache] - KV_CHECK -->|Already consumed| BLOCK_REUSE[403: URL already used] - KV_CHECK -->|First use| ALLOW + VERIFY_AGENT -->|Yes| LOG_DELIVERY[Record the delivery
URL hash, kid, agent_id] + LOG_DELIVERY --> ALLOW[Allow request
to origin/cache] HAS_SIG -->|No| IS_BOT{AI bot detected?} IS_BOT -->|Yes| BLOCK_BOT[403 + X-Content-Rules
+ X-FORA-Exchange + JSON body] IS_BOT -->|No| PASSTHROUGH @@ -88,9 +85,9 @@ handleRequest(ctx): b. If signature invalid -> 403 (always, regardless of bot status) c. Check expiry (reject if exp has passed) d. Agent binding is enforced by default: validate agent_id param - e. If singleUseEnabled: atomic check-and-consume via KV - f. All pass -> allow request through to origin/cache - g. Any fail -> 403 with specific error + e. All pass -> record the delivery (URL hash, kid, agent_id) and + allow the request through to origin/cache + f. Any fail -> 403 with specific error 4. If request is from detected bot (no signed URL): -> 403 + X-Content-Rules + X-FORA-Exchange headers + JSON body @@ -115,7 +112,7 @@ This keeps one copy of each document, under the provider's control, and it works ### Signed URL Passthrough with Agent Identity Validation -When a request arrives with signed URL parameters, the edge function verifies the signature, checks expiry, validates agent identity binding (on by default), and enforces single-use (off by default, and best-effort). See [Signed URL Verification](/components/edge-function/signed-url-verification/) for the full verification flow. +When a request arrives with signed URL parameters, the edge function verifies the signature, checks expiry, validates agent identity binding (on by default), and records the delivery with the SHA-256 of the URL, the value reconciliation joins with the Exchange's transaction log. See [Signed URL Verification](/components/edge-function/signed-url-verification/) for the full verification flow. ## Performance Budget @@ -123,10 +120,10 @@ The edge function must add **< 5ms** to request latency (p99). Per-request opera - String comparison (User-Agent matching against bot patterns) - Signature verification (Ed25519 via Web Crypto, or CDN-native RSA) -- KV read (agent_id check, if agent binding is enabled) +- SHA-256 thumbprint of the presented key (agent identity binding) - URL parameter parsing -HTTP calls to external services, database queries (except edge KV for single-use), DNS resolution, signing key loading, and config parsing are all **forbidden** in the per-request hot path. +HTTP calls to external services, database queries, DNS resolution, signing key loading, and config parsing are all **forbidden** in the per-request hot path. ## Failure Mode Summary @@ -134,8 +131,6 @@ The edge function degrades gracefully: ``` Full functionality - | KV unavailable -Single-use disabled, everything else works | Config refresh fails Stale config, core functionality preserved | Origin cannot be reached diff --git a/website/src/content/docs/components/edge-function/signed-url-verification.mdx b/website/src/content/docs/components/edge-function/signed-url-verification.mdx index 211b4039..7d7da211 100644 --- a/website/src/content/docs/components/edge-function/signed-url-verification.mdx +++ b/website/src/content/docs/components/edge-function/signed-url-verification.mdx @@ -216,11 +216,11 @@ The edge resolves `kid` to a key from the Exchange's key directory at `/.well-kn **Directory keys carry no key identifier of their own.** The edge computes the map key locally as the RFC 7638 thumbprint of the key material. That is why `kid` on the URL is a thumbprint rather than an operator-chosen label: there is nothing a publisher could assert that the edge would have to trust. -**The directory is not tenant-scoped, so pin the keys if you need it to be.** An -Exchange publishes one directory for all its tenants, and the edge accepts any -`kid` that resolves in it. A URL signed with another tenant's key therefore -verifies on your edge, which matters when one Exchange serves publishers who do -not trust each other. Pinning the keys you expect in `verifyKeys` closes it: a +**Each tenant has its own directory.** A tenant of an Exchange operator is its +own Exchange, with its own domain, key directory and keys, and it signs the +delivery URLs of every publisher it represents with those keys. An edge resolves +`kid` in its tenant's directory, so a URL signed by another tenant does not +verify. Pinning the keys you expect in `verifyKeys` narrows trust further: a `kid` outside that set never resolves, and the fetch never happens. ```mermaid @@ -274,48 +274,12 @@ Configure a trusted key group on the cache behaviour for the protected path and Akamai is not a supported target. EdgeAuth is a symmetric token scheme built on a secret shared with the CDN, which is the model FORA deliberately does not use. -## Single-Use URL Enforcement +## Replay within a URL's lifetime -:::caution -Not implemented in the reference edge. This section describes the option and why it is not the primary defence. -::: - -A provider wanting additional replay protection can enforce single-use URLs through edge KV, keyed on the URL's `sig`. - -```mermaid -sequenceDiagram - participant Agent as Fetcher - participant Edge as Edge Function - participant KV as Edge KV Store - - Agent->>Edge: GET /premium/article.html?...&sig=k7Qm2xR9... - - Note over Edge: Signature verified OK - - Edge->>KV: PUT-IF-ABSENT
key: "used:#lt;sig#gt;"
value: timestamp
TTL: URL lifetime + 60s - - alt Key did not exist (first use) - KV-->>Edge: success (inserted) - Edge-->>Agent: 200 OK + content - else Key already exists (replay) - KV-->>Edge: conflict (already exists) - Edge-->>Agent: 403: URL already consumed - end -``` - -**It would be best-effort.** Edge KV stores are eventually consistent across locations, so two near-simultaneous fetches in different regions can both see an absent key. - -| Platform | KV Mechanism | Consistency Model | Propagation Delay | -|---|---|---|---| -| CloudFront | No native KV; Lambda@Edge + DynamoDB | Per-region, eventually consistent (DynamoDB Global Tables) | Seconds across regions | -| Cloudflare Workers KV | Workers KV | Eventually consistent | ~60s propagation across PoPs | -| Cloudflare Durable Objects | Durable Objects | Strong consistency | Single-location (latency tradeoff) | -| Fastly KV Store | KV Store | Eventually consistent | Seconds across PoPs | - -**The primary replay defences are the ones already in the request path:** +A delivery URL can be fetched more than once before it expires. What that allows is bounded by the binding, the window and the log: -1. **Agent identity binding** — the URL is bound to one key, and a replay by anyone else fails proof of possession. -2. **Short TTL** — five minutes in the reference deployment, which narrows the window. -3. **Reconciliation** — the Exchange transaction log and the edge delivery log both record the signed-URL hash. Cross-referencing them detects replay after the fact. +1. **Agent identity binding.** The URL is bound to the purchasing agent's key, so a fetch by anyone else fails proof of possession ([Agent Identity Binding](#agent-identity-binding)). +2. **A short window.** The URL's signed `exp` limits use to minutes, and nobody can extend it ([Expiry](#expiry)). +3. **The delivery log.** The edge function writes one delivery record for each request it authorizes, carrying the SHA-256 of the URL, its `kid` and its `agent_id`. The Exchange records the same hash on the transaction, so joining the two logs shows every delivery against every sale, repeated fetches included. -This matches ad-tech's approach to impression deduplication: real time is best-effort, reconciliation is authoritative. +Repeated fetches by the purchasing agent within the window are therefore served, attributable to one purchase, and auditable. This matches ad-tech's approach to impression deduplication: reconciliation is authoritative. diff --git a/website/src/content/docs/components/exchange/multi-tenant.mdx b/website/src/content/docs/components/exchange/multi-tenant.mdx index 3c9391eb..c6ca78a2 100644 --- a/website/src/content/docs/components/exchange/multi-tenant.mdx +++ b/website/src/content/docs/components/exchange/multi-tenant.mdx @@ -25,10 +25,6 @@ type TenantConfig struct { RSLURLs map[string]string // domain -> RSL URL (e.g., "style.example" -> "https://style.example/license.xml") RSLPollInterval time.Duration // How often to re-fetch RSL (default: 5m) - // Pricing overrides (Exchange is the price authority — RSL pricing is a fallback hint) - // Private pricing from Exchange config overrides RSL-derived pricing. - PricingOverrides map[string]*forav1.Pricing // path pattern -> pricing - // Content delivery ContentBaseURL string // CDN base URL (e.g., "https://cdn.meridian.example") Scheme SigningScheme // ED25519 or AWS_CLOUDFRONT_RSA @@ -41,9 +37,6 @@ type TenantConfig struct { // Reporting policy ReportingPolicy *forav1.ReportingObligation - // Application-level abuse thresholds (volumetric rate limiting is at infra layer) - MinQueryToTxnRatio float64 // If query:txn ratio drops below this, return 429 (e.g., 0.01) - // Revenue share (not protocol-relevant, but needed for billing) RevenueSharePct float64 // Provider's share (e.g., 0.85 = 85%) @@ -67,13 +60,11 @@ type TenantConfig struct { │ - Transaction log writer (WAL) │ │ - Billing adapter connection pool │ │ - Metrics collector │ -│ - (Volumetric rate limiting at infra layer) │ │ │ │ Per-Tenant (isolated): │ │ - Resource catalog (in CatalogSnapshot.Tenants) │ │ - Signing keys (in SigningEngine) │ │ - RSL ingestion goroutine │ -│ - Abuse detection counters (query:txn ratio) │ │ - Reporting obligations │ │ - Verifier trust configuration (v1.0) │ │ - Dispute thresholds (v1.0) │ @@ -90,7 +81,7 @@ type TenantConfig struct { ### Isolation Guarantees - **Data isolation**: No tenant can access another tenant's catalog, keys, or transaction records. Offer signatures are per-tenant (different Ed25519 key pairs). Transaction log records include tenant_id for filtering. -- **Performance isolation**: Per-tenant rate limiting prevents a noisy tenant from consuming all capacity. Optional: per-tenant goroutine pools for RSL ingestion. +- **Performance isolation**: The Exchange keeps no per-request state, so request volume is limited in front of it, per address or per verified identity, by the load balancer or API gateway. Optional: per-tenant goroutine pools for RSL ingestion. - **Failure isolation**: An RSL ingestion failure for tenant A does not affect tenant B's catalog. Each tenant's catalog is independently rebuildable. --- @@ -161,7 +152,7 @@ For managed providers, the Exchange supports automatic rotation on a configurabl ## Public Key Exchange -Brokers and agents fetch the Exchange's WBA directory (the JWK Set at `/.well-known/http-message-signatures-directory`) and read its `keys` to verify `exchange_signature` on Offers without manual key exchange. The Exchange's offer-signing Ed25519 public keys are inline in that directory as RFC 7517 JWKs, each identified by its RFC 7638 thumbprint (the RFC 9421 `keyid`). +Brokers and agents fetch the Exchange's WBA directory (the JWK Set at `/.well-known/http-message-signatures-directory`) and read its `keys` to verify `Offer.signature` without manual key exchange. The Exchange's offer-signing Ed25519 public keys are inline in that directory as RFC 7517 JWKs, each identified by its RFC 7638 thumbprint (the RFC 9421 `keyid`). **Note:** The Exchange's WBA directory keys serve the Exchange's offer-signing keys. Agent keys are separate — they are fetched from the agent's own WBA directory (self-signup) or stored from enterprise registration (out-of-band key exchange). @@ -197,7 +188,7 @@ Since the default offer signature algorithm is Ed25519, these are **public keys* - Returns current and previous keys (for rotation grace period); each key's validity window is half-open `[not_before, not_after)` - **No authentication required** — Ed25519 public keys are safe to expose (they can only verify, not sign) -- Brokers SHOULD cache with 24-hour TTL +- Brokers SHOULD cache with a TTL of minutes to hours, as the [Caching Contract](/protocol/authentication/#caching-contract) allows, and poll the directory's `revocation_url` every 300 seconds - On signature verification failure, refresh key cache before retrying - The `x` field contains the base64url-encoded Ed25519 public key (32 bytes) diff --git a/website/src/content/docs/components/exchange/request-flows.mdx b/website/src/content/docs/components/exchange/request-flows.mdx index cce383df..ffb4855d 100644 --- a/website/src/content/docs/components/exchange/request-flows.mdx +++ b/website/src/content/docs/components/exchange/request-flows.mdx @@ -964,6 +964,6 @@ sequenceDiagram A `DisputeResponse` is only returned when the dispute is **accepted for processing**. A refusal to file (transaction unknown, no preceding usage report, window expired, duplicate, ineligible) is a non-OK transport error carrying a typed `ErrorDetail.dispute_failure` (`DisputeFailureReason`) — not a `DisputeResponse` with a rejection field. -**Tier 1 resolution** completes in under 1 second using CDN access logs as the authoritative evidence source. CDN logs are infrastructure-level records that neither party controls, making them the most trustworthy evidence in the hierarchy. +**Tier 1 resolution** uses CDN access logs as the authoritative evidence source, with a design goal of under a second. CDN logs are infrastructure-level records that neither party controls, making them the most trustworthy evidence in the hierarchy. -See [Dispute Resolution](/protocol/dispute-resolution/) for the three-tier resolution system and abuse prevention. +See [Dispute Resolution](/protocol/dispute-resolution/) for the recommended three-tier resolution policy and abuse prevention. diff --git a/website/src/content/docs/components/exchange/scaling.mdx b/website/src/content/docs/components/exchange/scaling.mdx index d34523c5..7ae40419 100644 --- a/website/src/content/docs/components/exchange/scaling.mdx +++ b/website/src/content/docs/components/exchange/scaling.mdx @@ -513,7 +513,7 @@ type ReadinessCheck struct { All logs use `log/slog` with structured key-value pairs. No `log.Printf` or custom loggers. Every error path MUST log before returning. -**Redaction rules** (per threat model): +**Redaction rules**: - `billing_ref`: last 4 characters only (e.g., `****a1b2`) - Signing keys: never logged - Signed URLs: hash only, never full URL diff --git a/website/src/content/docs/components/exchange/storage-model.mdx b/website/src/content/docs/components/exchange/storage-model.mdx index da378496..7b66916b 100644 --- a/website/src/content/docs/components/exchange/storage-model.mdx +++ b/website/src/content/docs/components/exchange/storage-model.mdx @@ -294,7 +294,7 @@ Providers get read-only access to all signed Offers issued for their content. Th ## Signing Keys (Per-Tenant) -Each provider tenant brings their own CDN signing keys. The Exchange must store these securely and support rotation. +Each tenant has its own signing keys, and the Exchange signs the delivery URLs of every publisher that tenant represents with them. For a publisher on CloudFront, the tenant's RSA key is the one registered in that publisher's trusted key group. The Exchange must store the keys securely and support rotation. ```go // TenantSigningConfig holds the signing configuration for a single tenant. diff --git a/website/src/content/docs/components/transaction-log/event-types.mdx b/website/src/content/docs/components/transaction-log/event-types.mdx index 5ad0dedd..76922735 100644 --- a/website/src/content/docs/components/transaction-log/event-types.mdx +++ b/website/src/content/docs/components/transaction-log/event-types.mdx @@ -20,7 +20,7 @@ Every state transition in the transaction lifecycle produces a log event. There ## ResourceQueryReceived -Logged when a `DiscoverResources` RPC is received. Used for query-to-transaction ratio monitoring (threat T12: metadata harvesting) and demand analytics. +Logged when a `DiscoverResources` RPC is received. Used for query-to-transaction ratio analysis and demand analytics. Loss is acceptable -- this is telemetry, not financial data. @@ -40,7 +40,7 @@ Loss is acceptable -- this is telemetry, not financial data. ## OffersPresented -Logged when the Exchange returns a `ResourceResponse`. Captures what was offered and at what price -- critical for post-hoc price discrimination analysis (T2). +Logged when the Exchange returns a `ResourceResponse`. Captures what was offered and at what price -- critical for post-hoc price discrimination analysis. Rebuildable from supply query + catalog state. diff --git a/website/src/content/docs/components/transaction-log/overview.mdx b/website/src/content/docs/components/transaction-log/overview.mdx index 410edd1c..cd549dc5 100644 --- a/website/src/content/docs/components/transaction-log/overview.mdx +++ b/website/src/content/docs/components/transaction-log/overview.mdx @@ -9,9 +9,9 @@ The Transaction Log is the append-only audit trail that enables three-sided reco If the log is compromised: - Billing disputes are unresolvable -- Revenue skimming (T5) is undetectable -- Phantom transactions (T4) cannot be disproven -- Ghost billing (T9 -- systematic caching without payment) cannot be quantified +- Under-reported sales are undetectable +- Purchases nobody made cannot be disproven +- Repeated fetches of one delivery URL cannot be quantified The system specifies: - What gets logged and the schema for each event type @@ -121,7 +121,7 @@ Core reconciliation queries: **WAL-first.** No signed URL leaves the Exchange without a durable record on local disk. If the WAL write fails, the signed URL is never returned, even though billing was authorized. A "wasted" authorization is far safer than an "unbillable" delivery. -**Append-only, verifiable.** Three layers of defense: storage-level immutability (S3 Object Lock, PostgreSQL triggers), cryptographic hash chains (SHA-256), and Ed25519-signed records. Three-sided reconciliation is the ultimate arbiter. +**Append-only, verifiable.** Alteration is detectable even when the Exchange operator is the adversary: the agent holds the signed offer and its own acceptance, and the provider's edge keeps its own delivery log, so a changed record no longer matches theirs. Storage-level immutability (S3 Object Lock, PostgreSQL triggers), cryptographic hash chains (SHA-256) and Ed25519-signed records are defense in depth on top. **Tiered for cost.** The same WAL code and `DurableStore` interface serve both deployment tiers. Growth operators use PostgreSQL for ~$641/month. Scale operators get sub-second reconciliation queries on ClickHouse for ~$4,700/month. Both stay well under the $0.00005/transaction NFR ceiling. diff --git a/website/src/content/docs/components/transaction-log/reconciliation.mdx b/website/src/content/docs/components/transaction-log/reconciliation.mdx index 9978f57b..f683cc61 100644 --- a/website/src/content/docs/components/transaction-log/reconciliation.mdx +++ b/website/src/content/docs/components/transaction-log/reconciliation.mdx @@ -82,7 +82,7 @@ ORDER BY total_spend DESC; ### Q2: Revenue Leakage Detection -Identifies content accesses that appear in CDN logs but have no corresponding transaction. This detects signed URL leakage (T8), billing system failures, and Exchange bugs. +Identifies content accesses that appear in CDN logs but have no corresponding transaction. This detects deliveries no sale backs, billing system failures, and Exchange bugs. This query is run by the provider, joining their CDN logs against the Exchange transaction log export. @@ -101,7 +101,7 @@ WHERE mp.signed_url_hash IS NULL AND cdn.status_code = 200; ``` -For this to work, the `transaction_id` must be embedded in the signed URL parameters. The provider extracts it from their CDN logs and joins against the Exchange export. +The join key is `signed_url_hash`, the SHA-256 of the delivery URL verbatim. The delivery URL carries no transaction ID: the provider hashes each signed URL in its CDN or edge delivery log and joins on that hash against the Exchange export. ## Dispute Detection @@ -227,7 +227,7 @@ These are reference implementations. A full analytics product (anomaly detection ## Immutability Guarantees -Three layers of defense make retroactive alteration detectable, even if the Exchange operator is the adversary. +Retroactive alteration is detectable even when the Exchange operator is the adversary, because the evidence is held by separate parties. The agent holds the Exchange-signed offer and its own `AgentAcceptance` for every purchase, and the provider's edge keeps its own delivery log with the hash of every delivery URL it served. A record the operator changes, deletes or invents no longer matches what the agent and the edge hold, and three-sided reconciliation shows it. The three storage layers below are defense in depth on top of that. ### Layer 1: Storage-Level Immutability @@ -288,7 +288,7 @@ Each Exchange instance maintains its own hash chain, identified by an instance G ### Layer 3: Signed Event Records -Each event record is signed by the Exchange's Ed25519 private key. Providers and agents can independently verify that records were not altered. +Each event record is signed by the Exchange's Ed25519 private key. Providers and agents can verify that a record was not altered after the Exchange signed it; the signature does not show that the Exchange recorded it truthfully. ```go func SignEvent(event *TransactionEvent, privateKey ed25519.PrivateKey) { @@ -305,7 +305,7 @@ func SignEvent(event *TransactionEvent, privateKey ed25519.PrivateKey) { | Storage-level immutability | Record deletion/modification | -- | Doesn't prevent false record creation | | Cryptographic hash chain | -- | Modification, insertion, deletion after the fact | Single-instance chain | | Signed event records | -- | Modification by any party other than signing Exchange | Compromised key = forged records | -| Three-sided reconciliation | -- | All of the above | Requires provider participation | +| Separate parties' records | Purchases the agent did not accept | Any alteration by the operator: it no longer matches the agent's signed offer and acceptance or the edge's delivery log | Requires the agent's and the provider's records | ## Export Formats diff --git a/website/src/content/docs/components/transaction-log/write-ahead-logging.mdx b/website/src/content/docs/components/transaction-log/write-ahead-logging.mdx index f6b13991..59576ccc 100644 --- a/website/src/content/docs/components/transaction-log/write-ahead-logging.mdx +++ b/website/src/content/docs/components/transaction-log/write-ahead-logging.mdx @@ -16,7 +16,7 @@ The `ExecuteTransaction` flow has a critical ordering dependency: 6. Return TransactionResponse (signed URL + billing_id) ``` -If the Exchange crashes between steps 4 and 5, the signed URL is live on the CDN -- the agent can fetch content -- but no billing record exists. This is an unbillable content access (threat T5: revenue skimming). +If the Exchange crashes between steps 4 and 5, the signed URL is live on the CDN -- the agent can fetch content -- but no billing record exists. This is an unbillable content access. WAL ensures step 5 completes durably before step 6 executes. diff --git a/website/src/content/docs/getting-started/for-ai-agents.mdx b/website/src/content/docs/getting-started/for-ai-agents.mdx index f65aa21e..82353203 100644 --- a/website/src/content/docs/getting-started/for-ai-agents.mdx +++ b/website/src/content/docs/getting-started/for-ai-agents.mdx @@ -314,7 +314,7 @@ If something goes wrong -- delivery failure, content hash mismatch, token count ``` 1. ReportUsage -> get report_id 2. DisputeTransaction -> reference transaction_id + report_id + evidence -3. Exchange resolves automatically (< 1 second for routine disputes) +3. Exchange resolves it under its dispute policy, automatically for routine cases (the recommended policy's goal: under a second) ``` **What's auto-disputable at each attestation level:** diff --git a/website/src/content/docs/getting-started/for-exchange-operators.mdx b/website/src/content/docs/getting-started/for-exchange-operators.mdx index 831ec762..e7c3e75b 100644 --- a/website/src/content/docs/getting-started/for-exchange-operators.mdx +++ b/website/src/content/docs/getting-started/for-exchange-operators.mdx @@ -216,9 +216,9 @@ This prevents unauthorized parties from injecting false claims into your resourc ## Dispute Resolution -Your Exchange handles `DisputeTransaction` RPCs from agents. The dispute system operates in three tiers: +Your Exchange handles `DisputeTransaction` RPCs from agents. How it resolves an accepted dispute is your policy; the recommended policy has three tiers. The volume and time figures are design goals, not measurements: -| Tier | Scope | Volume | Response Time | +| Tier | Scope | Volume (goal) | Response time (goal) | |---|---|---|---| | **Tier 1 -- Automated** | Delivery failures, content hash mismatches, signed URL expiry | ~99% of disputes | < 1 second | | **Tier 2 -- Rule-Based** | Ambiguous evidence, delivery says 200 but content is suspect | ~0.9% of disputes | < 24 hours | @@ -320,4 +320,4 @@ Streaming transactions follow the same FORA flow, but the signed URL has a longe 1. Review the [Exchange design](/components/exchange/overview/) for architecture details 2. See the [Billing Adapter](/components/exchange/billing-adapter/) for the integration interface 3. Walk through the [Scenario Walkthrough](/protocol/scenario-walkthrough/) for a complete transaction trace -4. Review the [Threat Model](/security/threat-model/) -- it was built from 20 years of ad-tech fraud patterns +4. Review [Authentication](/protocol/authentication/) for the signatures and keys every request, offer and delivery URL depends on diff --git a/website/src/content/docs/protocol/dispute-resolution.mdx b/website/src/content/docs/protocol/dispute-resolution.mdx index e58478d1..275d6fab 100644 --- a/website/src/content/docs/protocol/dispute-resolution.mdx +++ b/website/src/content/docs/protocol/dispute-resolution.mdx @@ -41,7 +41,9 @@ The [attestation level](/protocol/content-attestation/) determines what evidence ## Three-Tier Resolution -### Tier 1 -- Automated (< 1 second, ~99% of disputes) +The protocol standardizes the filing, the evidence chain, the `DisputeStatus` lifecycle and the resolution types. How an Exchange resolves an accepted dispute is its own policy. The tiers, rules and thresholds below are the recommended policy, not wire requirements. The time and share figures in the tier headings are design goals, not measurements. + +### Tier 1 -- Automated (goal: under a second, about 99% of disputes) Evidence is independently verifiable from CDN logs or cryptographic comparison. @@ -55,7 +57,7 @@ Evidence is independently verifiable from CDN logs or cryptographic comparison. State transition: `FILED` -> `AUTO_RESOLVED` -### Tier 2 -- Rule-Based Review (< 24 hours, ~0.9%) +### Tier 2 -- Rule-based review (goal: under 24 hours, about 0.9%) Deterministic rules applied when Tier 1 evidence is inconclusive. @@ -68,7 +70,7 @@ Deterministic rules applied when Tier 1 evidence is inconclusive. State transition: `FILED` -> `EVIDENCE_NEEDED` -> `UNDER_REVIEW` -> `RESOLVED` -### Tier 3 -- Pattern Investigation (async, ~0.1%) +### Tier 3 -- Pattern investigation (goal: asynchronous, about 0.1%) Triggered by aggregate patterns indicating systematic abuse. @@ -134,6 +136,8 @@ For DYNAMIC content (e.g., stock quotes, credit reports, drug databases), a cont ## Abuse Prevention +The thresholds below are recommended monitoring for an Exchange operator. The protocol does not require them. + ### Per-Agent Monitoring | Metric | Threshold | Consequence | diff --git a/website/src/content/docs/protocol/ext-comp.mdx b/website/src/content/docs/protocol/ext-comp.mdx index 0bf9eced..290643f2 100644 --- a/website/src/content/docs/protocol/ext-comp.mdx +++ b/website/src/content/docs/protocol/ext-comp.mdx @@ -33,7 +33,7 @@ enum changes in the proto, update these tables in the same change. `comp.license_url`, `comp.report_url`, and `comp.retrieval_endpoint` are publisher-supplied URLs. A consumer that dereferences them (or POSTs usage to `comp.report_url`) MUST apply the SSRF countermeasures specified for the core -`License.uri` in the [threat model (T-LIC-1)](/security/threat-model/#t-lic-1-ssrf--phishing-via-licenseuri): +`License.uri` in [Licensing Terms](/protocol/licensing-terms/#term-semantics): scheme allowlist, block loopback/private/metadata addresses (resolve-then-check), fetch via an egress proxy, and treat the response as untrusted. ::: diff --git a/website/src/content/docs/protocol/licensing-terms.mdx b/website/src/content/docs/protocol/licensing-terms.mdx index e8656229..f8ff7f79 100644 --- a/website/src/content/docs/protocol/licensing-terms.mdx +++ b/website/src/content/docs/protocol/licensing-terms.mdx @@ -42,7 +42,7 @@ Restrictions ride on every offer. They are not an Exchange-side gate that a requ **`License.uri_digest`**: every `License` that sets `uri` must also set `uri_digest`, whatever the term's semantics (rule `license.digest_required_with_uri`). The party that sets `uri` supplies the digest: the publisher, on a term it pushes. The digest has the form `method:hexdigest`, where the method is `sha256`, `sha384` or `sha512` and the hex digest has the method's full length. `md5` and `sha1` are refused on the wire. The digest pins the document, so an agent can check that the bytes it fetched are the ones the offer was signed with. :::caution[Fetching `License.uri` safely] -`License.uri` MUST NOT be URL-validated, because TDL identifiers use non-URL schemes. That means *do not reject* a non-URL scheme, **not** *fetch blindly*. A consumer that dereferences the URI MUST apply the SSRF countermeasures in the [threat model (T-LIC-1)](/security/threat-model/#t-lic-1-ssrf--phishing-via-licenseuri): a scheme allowlist; blocking loopback, link-local, private and cloud-metadata addresses, resolving before checking; fetching client-side through an egress proxy; and treating the response as untrusted. It verifies the fetched bytes against `License.uri_digest` and refuses the document on a mismatch. +`License.uri` MUST NOT be URL-validated, because TDL identifiers use non-URL schemes. That means *do not reject* a non-URL scheme, **not** *fetch blindly*. A consumer that dereferences the URI MUST apply these SSRF countermeasures: a scheme allowlist; blocking loopback, link-local, private and cloud-metadata addresses, resolving before checking; fetching client-side through an egress proxy; and treating the response as untrusted. It verifies the fetched bytes against `License.uri_digest` and refuses the document on a mismatch. ::: ## Restrictions diff --git a/website/src/content/docs/protocol/transaction-flow.mdx b/website/src/content/docs/protocol/transaction-flow.mdx index 4f3a1b8e..0fd59697 100644 --- a/website/src/content/docs/protocol/transaction-flow.mdx +++ b/website/src/content/docs/protocol/transaction-flow.mdx @@ -778,7 +778,7 @@ Every Exchange implements `DisputeTransaction`; it is part of the core protocol, | `DISPUTE_FAILURE_REASON_INELIGIBLE` | The transaction's state admits no dispute under the Exchange's rules | | `DISPUTE_FAILURE_REASON_UNKNOWN_CRITICAL_EXTENSION` | The filing's `ext_critical` names a key the Exchange does not understand. Refused with `invalid_argument` (see [Extension Profiles](/protocol/extension-profiles/)) | -A dispute that is accepted and later found unsupported ends as `RESOLUTION_TYPE_REJECTED`; it is not a refusal to file. The Exchange resolves most accepted disputes automatically in under 1 second using CDN logs and cryptographic evidence. See [Dispute Resolution](/protocol/dispute-resolution/) for the three-tier resolution system, auto-credit rules, and the complete dispute lifecycle. +A dispute that is accepted and later found unsupported ends as `RESOLUTION_TYPE_REJECTED`; it is not a refusal to file. How an Exchange resolves an accepted dispute is its own policy; the recommended policy's goal is to resolve most of them automatically in under a second. See [Dispute Resolution](/protocol/dispute-resolution/) for the recommended three-tier policy, its auto-credit rules, and the complete dispute lifecycle. ## Resource Previews diff --git a/website/src/content/docs/reference/changelog.mdx b/website/src/content/docs/reference/changelog.mdx index 9c8546a8..7dc5b581 100644 --- a/website/src/content/docs/reference/changelog.mdx +++ b/website/src/content/docs/reference/changelog.mdx @@ -42,7 +42,7 @@ and the onboarding page's code comments name an RSL license rather than a file. **A term can require usage reporting (additive protocol change).** `ObligationKind` gains `OBLIGATION_KIND_REPORTING`, and `Obligation` gains an optional `reporting` field, a `ReportingObligation` that states the `window` within which the agent files `ReportUsage` and the `required_fields` the report carries. The Exchange carries the obligation onto `Offer.reporting`: `required` is true, the window and fields are the obligation's where it states them and the Exchange's own where it does not, and the endpoint is the Exchange's. A term without one keeps the Exchange's own reporting policy. Four rules: `obligation.reporting.requires_reporting_kind` (the field only on that kind), `obligation.reporting.no_endpoint` (the Exchange sets the endpoint), `license_term.reporting.metering_none` (a term metered `NONE` needs no report, so it cannot carry one) and `offer.reporting.required_by_term` (an offer selling such a term requires a report). A revenue-share term now states its reporting duty on the term. The TypeScript and Python cross-field mirrors, the conformance corpus and the license-term vectors cover the four rules. Licensing Terms, Transaction Flow and the CoMP extension say the same. -**An offer carries restriction tokens in canonical form, and the party that sets a license URI supplies its digest (comments only; no wire change).** The `LicenseTerm` comment now says what an Exchange already does: the term on an offer carries each restriction token as ingest canonicalized it (trimmed, case-folded, alias-resolved), with no other translation or reformulation, so an agent compares tokens against the registry without folding them itself. The `License.uri_digest` comment no longer says the Exchange computes the digest at ingestion: the party that sets `uri` supplies the digest with it, the publisher on a term it pushes. Licensing Terms and the threat model (T-LIC-4) say the same. Proto examples use `news.example` and a generic collecting society in place of real company names. +**An offer carries restriction tokens in canonical form, and the party that sets a license URI supplies its digest (comments only; no wire change).** The `LicenseTerm` comment now says what an Exchange already does: the term on an offer carries each restriction token as ingest canonicalized it (trimmed, case-folded, alias-resolved), with no other translation or reformulation, so an agent compares tokens against the registry without folding them itself. The `License.uri_digest` comment no longer says the Exchange computes the digest at ingestion: the party that sets `uri` supplies the digest with it, the publisher on a term it pushes. Licensing Terms says the same. Proto examples use `news.example` and a generic collecting society in place of real company names. **fora-music-v1 carries the rights data a cue sheet needs, and finds tracks by key, version, publisher and IPI (additive; no wire change).** `music.publishers` lists the music publishers diff --git a/website/src/content/docs/security/threat-model.mdx b/website/src/content/docs/security/threat-model.mdx deleted file mode 100644 index f772ec31..00000000 --- a/website/src/content/docs/security/threat-model.mdx +++ /dev/null @@ -1,324 +0,0 @@ ---- -title: "Threat Model" -description: "FORA threat model with 41 attack vectors and countermeasures, informed by 20 years of ad-tech fraud history" ---- - -## Methodology - -Three independent adversarial analyses were conducted: -1. **Ad-tech fraud history**: Every major fraud category from 20+ years of programmatic advertising, mapped to FORA equivalents -2. **Content licensing abuse brainstorm**: 56 attack vectors from each party's perspective (dishonest exchange, agent, provider, broker, attacker) -3. **STRIDE security threat model**: Formal threat modeling of the protocol's technical surface - -## Key Lesson from Ad-Tech History - -> **Every self-reported field gets gamed.** Any claim that is not cryptographically attested by a trusted party will be falsified if there's economic incentive. - -This single pattern accounts for most ad-tech fraud: domain spoofing (self-reported domain), geo spoofing (self-reported location), viewability fraud (self-reported measurement), and attribution fraud (self-reported conversion). FORA must learn from this. - -## 1. Supply-Side Threats (Dishonest Exchange Operator) - -### T1: Hidden fee inflation -**Attack**: Exchange charges agent $0.75 but tells provider the rate was $0.50, pocketing the spread. -**Ad-tech parallel**: The "unknown delta" from ISBA study -- 15% of spend unaccounted for. -**Countermeasure (protocol)**: Offers are cryptographically signed by the Exchange (Ed25519). Provider can verify prices weren't inflated beyond RSL terms. -**Countermeasure (reconciliation)**: Provider compares CDN access logs against Exchange-reported transaction volumes and revenue. - -### T2: Dynamic price discrimination -**Attack**: Exchange serves different prices to different requesters for identical content. -**Countermeasure (protocol)**: Not directly preventable -- price discrimination is a business decision. If prices are derived from RSL (provider-set), the Exchange can't inflate beyond RSL terms without detection. -**Countermeasure (reconciliation)**: Brokers querying from different identities can detect discrepancies. - -### T3: Bait-and-switch content -**Attack**: Offer describes "2026 Q4 Financial Report, 15,000 words" but signed URL delivers different content. -**Ad-tech parallel**: Inventory misrepresentation (declaring premium placement, serving remnant). -**Countermeasure (protocol)**: **Content hash in the Offer.** ResourceIdentity.content_hash commits to content at offer time. Agent verifies after fetch. Mismatch = dispute. - -### T4: Phantom transactions / ghost billing -**Attack**: Exchange fabricates billing_ids that never corresponded to real agent requests. -**Ad-tech parallel**: Impression inflation by exchanges. -**Countermeasure (protocol)**: **Mutual transaction receipts.** Agent's idempotency key in TransactionRequest is agent's proof; Exchange's billing_id is Exchange's proof. Neither can forge the other's Ed25519 signature. - -### T5: Provider revenue skimming -**Attack**: Exchange tells provider 1,000 transactions occurred; actually processed 1,500. -**Countermeasure (reconciliation)**: **Three-sided reconciliation.** Provider's CDN logs, Exchange's transaction log, and usage reports must all agree. -**Countermeasure (protocol)**: Both sides record `signed_url_hash` — SHA-256 of the delivery URL verbatim. The Exchange stores it on the transaction and the delivery endpoint stores it on its delivery event, so the two logs join on a value neither side chooses. - -### T6: Overly long signed URL expiry -**Attack**: Exchange issues 24-hour URLs instead of 5-minute, enabling reuse. -**Countermeasure (protocol)**: The delivery endpoint refuses any URL whose `exp` has passed, and the Exchange issues short expiries -- five minutes in the reference flows. No verifier enforces a second, independent upper bound on the TTL: the only bound is the `exp` the Exchange signed, so a 24-hour URL is detected by reconciliation (T5), not refused at the edge. A provider who wants a hard ceiling has to add that check to its own edge function. - -### T7: Signing key leakage -**Attack**: Exchange shares signing keys with a preferred requester, enabling URL forgery. -**Countermeasure (protocol)**: **Asymmetric signing, with per-tenant key isolation.** The Exchange holds a separate private key per tenant, loaded from a key store at startup; the delivery endpoint verifies with the matching public key, published in the Exchange's key directory. This bounds the damage rather than preventing the act -- the attacker here is the Exchange, so no control the Exchange operates can stop it from exporting its own key. What the design gives you is that a leaked verification key forges nothing, a compromised edge cannot mint URLs, and a leaked tenant key forges URLs for that one tenant and no other. Detection is T5's job: forged fetches appear in the provider's delivery log and not in the Exchange's transaction log, and the two join on `signed_url_hash`. - -## 2. Demand-Side Threats (Dishonest Agent / Requester) - -### T8: Signed URL sharing -**Attack**: Agent A pays, shares signed URL with Agents B, C, D before expiry. -**Countermeasure (protocol)**: **Agent-bound signed URLs.** Embed the agent's RFC 7638 JWK Thumbprint (`agent_identity_hash`) as the URL's `agent_id` parameter, covered by the URL's Ed25519 signature; a capable edge function requires the fetcher to present its public key + an RFC 9421 signature (proof-of-possession) and checks `thumbprint(presented key) == agent_identity_hash`. Implemented via `agent_identity_hash` on `TransactionResponse`. - -### T9: Systematic caching / content mirroring -**Attack**: Agent fetches every article once, caches locally forever, never pays again. -**Countermeasure (protocol)**: **Single-use signed URLs.** Edge function marks URL as consumed after first fetch. -**Countermeasure (legal)**: License terms prohibiting caching beyond session scope. - -### T10: Usage underreporting (token count) -**Attack**: Agent reports using 500 tokens of a 10,000-token document but ingested the entire thing. -**Countermeasure (protocol)**: **Never a refused report; monitoring is the operator's.** The reported quantity is unrestricted: an Exchange never refuses a usage report because its quantity differs from the estimate, in either direction. Monitoring discrepancies is the Exchange operator's own business, not part of the protocol: an operator may reconcile a quantity far below the document's known size against CDN logs (bytes served for the signed URL) and the size the attestations state, and pursue it through the account relationship or a dispute. The charge never depends on the reported count, in any pricing model: a metered purchase is charged at the estimate × rate the offer states (or one unit's rate without an estimate) when it is bought, and that charge is final. A publisher that wants the whole document paid for states an estimate that covers it, or prices it per access or flat. - -### T11: Function misreporting (RAG vs training) -**Attack**: Agent declares `function: ai-input` (cheaper) but uses content for `function: ai-train` (prohibited or more expensive). -**Countermeasure**: **Not solvable at protocol level.** Agent's internal processing is a black box. Legal/contractual enforcement only. - -### T12: Offer metadata harvesting -**Attack**: Agent calls DiscoverResources repeatedly, extracting metadata -- never transacting. -**Ad-tech parallel**: Bid stream data harvesting. -**Countermeasure (protocol)**: Rate limiting on DiscoverResources. Exchange tracks query-to-transaction ratio per agent. - -### T13: Credential sharing / proxy laundering -**Attack**: One agent identity (signing key) shared across organizations. -**Countermeasure (protocol + operational)**: Sharing a key cannot redirect costs: the request carries no self-supplied billing field, so every request signed with the shared key bills the one account of the key directory that publishes that key — the abuse lands on the sharer's own bill. Detection is behavioral, not cryptographic: the Exchange monitors usage patterns per verified identity (IP diversity, volume spikes, impossible concurrency) and can deactivate the account. The signature binding does not prevent sharing. It concentrates all shared usage under one identity so it can be seen and priced. - -## 3. Provider-Side Threats (Dishonest Provider) - -### T14: Paywall-gated garbage -**Attack**: Compelling headline, but behind the paywall: padding, filler, or unrelated content. -**Countermeasure (protocol)**: Content integrity hash catches *changed* content. Exchange curation/reputation systems address quality. - -### T15: Word count / token count inflation -**Attack**: Provider pads content to inflate word count, affecting unit_cost calculations. -**Countermeasure (protocol)**: Exchange independently verifies content length during RSL ingestion. Agent independently tokenizes after fetch. - -### T16: Content versioning fraud -**Attack**: Provider changes content at URL after Exchange has priced it. -**Countermeasure (protocol)**: **Content integrity hash in the Offer.** SHA-256 of content at offer creation time. Agent verifies after fetch. - -### T17: Double-selling with exclusivity claims -**Attack**: Provider grants "exclusive" licensing to multiple Exchanges. -**Countermeasure**: ResourceIdentity enables detection (same content_hash from different exchanges). Prevention requires legal contracts. - -### T18: Selective enforcement / preferential access -**Attack**: Edge function blocks some agents but quietly allows others to scrape freely. -**Countermeasure**: Not solvable at protocol level. Market dynamics address it. - -## 4. Broker Threats - -### T19: Hidden orchestration fee -**Attack**: Broker adds markup to every offer relayed to the agent. -**Countermeasure (protocol)**: **Exchange signs offers (Ed25519).** Broker passes through signed offers. Agent verifies the price was not tampered with. - -### T20: Kickback-driven offer selection -**Attack**: Broker always routes to a specific Exchange regardless of pricing. -**Countermeasure (protocol)**: Agent can bypass Broker and query and buy at Exchanges directly. A Broker signs every request it sends alone, with its own RFC 9421 HTTP Message Signature, so the Exchange knows which Broker sent it and the Broker cannot deny it. The agent's consent to a transaction is the `AgentAcceptance` it signed into the body, which a Broker cannot alter or forge, and `agent_request_acceptance` binds the full ordered set of offers the agent chose. - -### T21: Query intelligence harvesting -**Attack**: Broker logs every DiscoverResources query, sells the data. -**Countermeasure**: Not solvable at protocol level. Data handling agreements required. - -### T-BRK-1: Request-set mutation during execute fan-out -**Attack**: The agent commits to an ordered set of offers and hands execution to a Broker (`BrokerService.ExecuteTransaction`). While projecting the set into per-Exchange `ExecuteTransaction` subrequests, the Broker mutates it at the **item** level: it removes an item, appends one the agent never chose, reorders the items, or sends a valid subset first so the agent's idempotency key is consumed by a request the agent did not make — a later honest retry then replays the mutilated result instead of executing the real set. -**Why the transport signature does not cover this**: The Broker's RFC 9421 signature (T20, T-DEL-4) proves which Broker sent a subrequest. A projected subrequest is a new HTTP request the Broker authors and signs alone, so that signature says nothing about whether the projected body carries the items the agent chose — see [Projected execute requests](/protocol/authentication/#projected-execute-requests). -**Countermeasure (protocol)**: **`TransactionRequest.agent_request_acceptance`.** The agent signs the complete ordered set of `(offer signature, exchange)` references plus the requester and idempotency key with its own Ed25519 key, and the Broker must forward the envelope unchanged on every subrequest. Each Exchange verifies the signature and requires its subrequest to equal the complete in-order projection of the signed set addressed to itself, **before** creating or serving any request-level idempotency state. A removed, appended, reordered, or subset request fails the projection check: the Exchange denies every item of it with `DENIAL_REASON_SIGNATURE_INVALID`, in the body, purchases nothing and claims nothing. The field is optional for wire compatibility: an older client that omits it keeps per-item execution semantics (each item still carries its own `agent_acceptance`) but gets no request-level set claim. - -### T-BRK-2: Tampering with a relayed purchase -**Attack**: A Broker relaying a purchase (`BrokerService.ExecuteTransaction`) changes what an item buys: a different offer, a higher price, other terms, another Exchange, or a purchase on behalf of a different requester. -**Countermeasure (protocol)**: **Per-item integrity.** Each item is atomic and its integrity is per resource. The offer carries its issuing Exchange's Ed25519 signature over price, terms, expiry and `exchange`; the agent's `AgentAcceptance` binds that one offer to the requester and the idempotency key; and the Exchange that owns the resource executes it. Altering any of these breaks the offer signature or the acceptance, and the Exchange refuses the item. Combining items from several Exchanges into one response therefore needs no cross-item integrity. The Broker also checks that `requester.domain` is the agent's verified signing directory before relaying, and refuses a mismatch as `unauthenticated` with `request_auth_failure` `SIGNATURE_INVALID`; each Exchange resolves the acceptance keys from `requester.domain`, so a forged requester fails there in any case. - -### T-BRK-3: Misreporting a relayed purchase -**Attack**: A Broker relaying a purchase reports an outcome that differs from what an Exchange answered: it claims a refusal for an item that was bought, alters a reported cost or transaction id, or drops one Exchange's sub-request and reports it refused. -**Countermeasure (protocol)**: **Partial.** The combined `BrokerTransactionResponse` is unsigned; the one signed value in a result item is `retrieval_endpoint`, a URL the issuing Exchange signed, which the Broker cannot forge or alter. What the agent is charged is bounded by the signed offer the Exchange verified, whatever the Broker reports. An upstream refusal always rides in the body (`TransactionResultItem.refusal`, with the Exchange's own `ErrorDetail`), never as a Broker error, so the other Exchanges' results reach the agent. An agent that doubts an outcome can retry with the same `idempotency_key`, through the same Broker, another one or directly: each Exchange scopes the key to the agent whatever the route, and answers from its stored result. The agent can also reconcile with the Exchange that issued the offer directly, through its usage report and, where the outcome is wrong, a dispute, which it always files itself: the purchase is the agent's, never the Broker's (see [Accounts](/protocol/authentication/#accounts)). **Residual risk**: the per-item report fields are as trustworthy as the Broker; an agent that cannot accept that buys directly. - -## 5. Third-Party Attacks - -### T22: Exchange impersonation -**Attack**: Attacker sets up fake Exchange, poisons fora.json via DNS hijack. -**Countermeasure (protocol)**: fora.json served over HTTPS from provider's domain (TLS proves endorsement). Every Offer carries `exchange_signature` (Ed25519). Agent verifies against Exchange's public key. - -### T23: Signed URL interception (MITM) -**Attack**: Attacker intercepts TransactionResponse, steals signed URL. -**Countermeasure**: HTTPS everywhere. Agent identity binding prevents reuse. - -### T24: Transaction replay -**Attack**: Attacker captures valid TransactionRequest and replays it. -**Countermeasure (protocol)**: **Idempotency keys.** Every state-mutating call carries a required `idempotency_key` — `TransactionRequest`, `UsageReport`, and `DisputeRequest`. Servers dedupe per agent and key, whatever the route — the agent the RFC 9421 signature authenticates on a direct request, the agent its acceptances authenticate on a relayed purchase — so a replay returns the original result instead of re-charging or re-filing, and a captured purchase replayed through another Broker is a replay too. The agent's authorization is verified before any stored result is created or returned. A key reused by the same agent with a different request (different items, or another order) is refused with `already_exists` and changes nothing; a key another agent used is never a collision. Broker `Resolve` (`DiscoveryRequest`) is pure discovery — it executes no transaction, has no replay exposure, and carries no key. - -### T25: Billing_id forgery in usage reports -**Attack**: Attacker fabricates billing_ids in usage reports. -**Countermeasure (protocol)**: Exchange validates billing_id exists in transaction log before accepting usage reports. - -### T26: DiscoverResources flooding (DoS) -**Attack**: Flood DiscoverResources to exhaust Exchange resources. -**Countermeasure (protocol)**: Per-partner rate limiting keyed on the **verified requester identity** (RFC 9421 request signature — domain/key). Anonymous queries rejected. - -### T-EP-1: Manifest-advertised endpoint redirection -**Attack**: A party that answers for `{domain}/.well-known/fora.json` — the domain's operator, or anyone who can influence what a consumer reads there — advertises an `endpoint` on a host it controls, or on another port of the named host, or one carrying `user:password@` credentials. Every consumer that resolves that domain then sends signed calls (usage reports, disputes, execute) to the attacker's address, or stamps an `Authorization` header the SDK never chose. A dial-time SSRF guard raises no objection: the destination is an ordinary public host. -**Countermeasure (protocol)**: `WellKnownManifest.endpoint` states the binding as a **MUST** — the endpoint must be on the host **and port** that served the manifest, or a subdomain of that host on that port, and must not carry userinfo. The anchor is the host the consumer **fetched the document from**, never the self-asserted `domain` member inside it, since anchoring to a value the document supplies would let a hostile manifest validate itself. The host match is on a full dot-delimited label boundary, so `evil-a.com` is not under `a.com`. - -**Enforced below the caller, in all three SDKs.** The check runs inside the shared endpoint resolver, before the value is returned and before it is cached, so every consumer of that resolver inherits it rather than being trusted to remember. A refused endpoint surfaces as its own verdict, distinct from "no endpoint advertised" and from a transport failure, so a caller classifying retryability reads it as final. The rule is corpus-locked to shared conformance vectors the three SDKs replay, and a conformance guard holds the vectors to the normative text above — the two cannot drift apart silently. - -**Bounded, not eliminated.** The manifest fetch follows redirects, so the party that answers *for the document* may be one a redirect chose. What that party cannot do is change where the signed call lands: whatever the manifest says, the endpoint it advertises must still anchor to the domain the offer named. - -## 6. Systemic / Arbitrage Threats - -### T27: Content arbitrage (buy low, resell high) -**Attack**: Entity buys from Exchange A at $0.04, resells via own Exchange at $0.05. -**Countermeasure (protocol)**: ResourceIdentity enables detection. fora.json declares authorized providers. - -### T28: Free content laundering -**Attack**: Scrape freely available content, package behind paywall as "premium." -**Countermeasure**: Content fingerprinting against known free content databases. - -### T29: Synthetic content farming -**Attack**: Generate AI content at near-zero cost, sell as human-authored. -**Countermeasure**: CoMP's `Text.sourcetype` field. Future: C2PA content credentials. - -### T30: License tier arbitrage -**Attack**: Buy at grounding rate, use for training. Collapses pricing model at scale. -**Countermeasure**: Black box problem. Legal/contractual enforcement only. - -### T31: Absence-reason existence oracle -**Attack**: An unauthorized caller probes for a resource and reads the `absence_reason`. Authorization-flavored values (`NOT_AUTHORIZED`, `NOT_IN_CATALOG`, `CONTENT_BLOCKED`) distinguish "no such resource" from "it exists but you may not have it" — confirming existence and the reason for refusal. Broker `Resolve` (`DiscoveryResponse.absence_reason`) exposes the same oracle at the broker that `DiscoverResources` (`OfferGroup.absence_reason`) does at the Exchange, so hiding it on one surface but not the other still leaks. -**Countermeasure (protocol)**: A scope shortfall is never disclosed. When the requester's scopes leave no presentable offer for a resource, the Exchange answers with no offers and no absence reason, exactly as for any resource with nothing to offer, and a Broker adds no reason of its own (the existence-hiding rule on `Requester.scopes`). No absence or denial reason reports a scope shortfall. For the other reasons, the reason is a hint, not a guarantee: where existence itself must stay hidden, the Exchange/Broker **MAY omit** `absence_reason` (leave it unset) rather than reveal an authorization-flavored value, and this applies equally to `OfferGroup.absence_reason` and `DiscoveryResponse.absence_reason`. `ErrorDetail.message`/`metadata` are held to the same rule (T-LIC-adjacent leakage): servers SHOULD NOT restore the withheld detail there as free text. - -## Prevention Taxonomy - -| Level | Threat IDs | What It Means | -|---|---|---| -| **Preventable at protocol level** | T3, T4, T5, T6, T7, T8, T9, T12, T16, T19, T22, T23, T24, T25, T26, T-BRK-1, T-ATT-1, T-ATT-2, T-ATT-3, T-ATT-5, T-DEL-1, T-DEL-2, T-DEL-3, T-DEL-4, T-DEL-6 | Protocol changes make the attack structurally impossible | -| **Detectable via reconciliation** | T1, T2, T4, T5, T13, T14, T15, T17, T27, T-ATT-4, T-DEL-5 | Three-sided reconciliation catches it | -| **Legal/contractual only** | T10, T11, T13, T17, T18, T20, T21, T28, T29, T30, T-DEL-5 | Can't enforce technically | - -### The Three Lines of Defense - -``` -Line 1: Protocol-level prevention - Signed offers, content hashes, agent-bound URLs, idempotency keys, - agent-signed request-set proof (request acceptance, verified before - idempotency state), holder-bound JWT delegation chain (cnf), - RFC 9421 request signatures from every sender (with chain verification - on unchanged forwarding), subscription-level quota tracking - Makes attacks structurally impossible - -Line 2: Three-sided reconciliation - CDN logs + Exchange transactions + Usage reports - Detects discrepancies that slip past Line 1 - -Line 3: Legal/contractual enforcement - Audit rights, licensing terms, dispute resolution - Handles the black-box problem (what agent did internally) -``` - -## 7. Attestation-Specific Threats - -### T-ATT-1: Forged attestation injection - -**Attack**: Attacker crafts a fake `ResourceAttestation` with a fabricated `verifier` domain and pushes it via `CatalogService.PushResources`. -**Countermeasure (protocol)**: Exchange verifies that the request's signer is the provider itself or listed in the provider's `catalog_contributors` (from `fora.json`). Exchange verifies the attestation `signature` against the verifier's public key in its WBA directory (the JWK Set at `/.well-known/http-message-signatures-directory`). FORA has no dedicated verifier role; a verifier publishes under its operator's role (`ROLE_PUBLISHER` for a self-attesting publisher, `ROLE_EXCHANGE` for a standalone vendor). Both checks must pass. - -### T-ATT-2: Stale attestation exploitation - -**Attack**: Provider updates content (e.g., replaces article with filler) but the catalog retains the old attestation claiming 5000 tokens. Agent pays based on stale claims. -**Countermeasure (protocol)**: `attested_at` timestamp enables agent freshness checks. Agents reject attestations older than their threshold for the content type (e.g., 4 hours for breaking news). Content hash mismatch (Level 1) triggers auto-credit via the dispute system. -**Countermeasure (reconciliation)**: CDN response size corroborates discrepancies. 800 bytes for a 5000-token claim is auto-creditable regardless of hash match. - -### T-ATT-3: Verification vendor compromise - -**Attack**: Attacker compromises a third-party verifier's Ed25519 private key and signs fraudulent attestations for arbitrary content. -**Countermeasure (protocol)**: Key rotation via JWKS pattern -- keys have `not_before` / `not_after` windows. Exchange caches the verifier's WBA directory with TTL-based refresh (1 hour default). Compromised key can be revoked by removing it from the verifier's WBA directory (the JWK Set at `/.well-known/http-message-signatures-directory`). -**Countermeasure (operational)**: Exchange monitors attestation patterns per verifier. Sudden changes in claim distributions trigger investigation. - -### T-ATT-4: Claims inflation attack - -**Attack**: Provider self-attests inflated `estimated_quantity: 10000` for a 500-word article, computes a valid content hash for the actual (short) content, and prices based on the inflated count. -**Countermeasure (protocol)**: CDN response size is the corroboration signal. CDN log showing a 2KB response for a 10000-token claim is auto-creditable. Agent files dispute with `INCOMPLETE_CONTENT` reason; Tier 1 auto-resolution via CDN corroboration. -**Countermeasure (pattern)**: Provider flagged for investigation when token discrepancy rate exceeds 2%. Graduated consequences apply. - -### T-ATT-5: Catalog contributor spoofing - -**Attack**: Unauthorized party registers a domain similar to a legitimate verifier (e.g., `doub1everify.com`) and pushes attestations claiming to be a trusted vendor. -**Countermeasure (protocol)**: `catalog_contributors` in `fora.json` uses exact domain matching. The provider must explicitly list the contributor's domain. The Exchange fetches the WBA directory from the exact `verifier` domain in the attestation and verifies the signature against that domain's `keys` (the JWK Set at `/.well-known/http-message-signatures-directory`). - -## 8. Delegation and Authorization Threats - -### T-DEL-1: Delegation token theft - -**Attack**: Attacker steals a delegation token (e.g., via log exfiltration, memory dump, or network interception) and attempts to use it to access resources within the token's scope. -**Countermeasure (protocol)**: **Holder binding neutralizes theft.** A delegation token is bound to the holder's key (via `cnf.jkt` on the JWT), and verification requires the key the request proves possession of — the key that signs the HTTP request ([RFC 9421](/protocol/authentication/#request-signatures-rfc-9421)) on a direct call, the key the agent's `AgentAcceptance` verifies under on a purchase a Broker relays — to equal the bound key (see [Verification](/protocol/authentication/#verification)). A thief who steals the token bytes but not the private signing key cannot produce a valid request — the token is **not bearer-usable**, so theft alone grants nothing. Short expiry, the `aud` claim that names the one Exchange a token is for, and withdrawal of the issuer's configured key are **defense-in-depth** that bound the blast radius in the residual case where the holder's signing key is *also* compromised. This is why T-DEL-1 is listed as structurally preventable rather than merely mitigated. - -### T-DEL-2: Delegation scope escalation - -**Attack**: Attacker attempts to widen permissions by manipulating the delegation chain (e.g., editing a child JWT to escalate from `ai-search` to `ai-train`, or splicing in a forged link). -**Countermeasure (protocol)**: **The delegation chain narrows only, and is cryptographically linked.** Each delegation JWT is Ed25519-signed, and a child's `scope` MUST be covered by its parent's (verified) — it can narrow, never widen. The **chain-linkage invariant** requires each token to be signed by the key the parent named in `cnf`, and each child carries its complete parent inside its own signed `fora_parent` claim, so editing a link breaks that link's signature and splicing a different parent breaks the `jwk`-to-`cnf.jkt` match. A claim the profile does not list is refused rather than ignored, so an attacker cannot smuggle a restriction past a verifier that does not understand it. The Exchange verifies the full chain, root first with a configured key, and the key the request proves possession of against the final `cnf.jkt`, before honouring the delegation. - -### T-DEL-3: Revocation bypass - -**Attack**: Principal revokes a delegation but cached or stored tokens continue to work until their `expires_at` timestamp. -**Countermeasure (protocol)**: Short `exp` (2-4 hours for standard access) limits the window of continued access; the verifier allows 60 seconds of clock skew and no more. Trust is configured per subscription record, so removing the issuer's key from that record refuses every chain it signed at the next request. Per-token revocation through `revocation_uri` is not part of this profile. - -### T-DEL-4: Signer impersonation and forged forwarding - -FORA's Broker never forwards an agent's request unchanged: it originates discovery queries and re-packages purchases, and signs each alone. A purchase through a Broker is covered by T-BRK-1 and T-BRK-2. - -**Attack**: Attacker claims to be a trusted Broker, or another agent, to gain access or inject misleading provenance — or, where a third party forwards a request unchanged and signs it again, inserts, reorders or drops a signature. -**Countermeasure (protocol)**: **Every sender signs its own request (RFC 9421, Ed25519).** A Broker originates discovery queries and re-packages execute requests, and signs each alone with its own key, so it cannot claim to be another Broker: the Exchange verifies that signature against the key in the directory the Broker's own `Signature-Agent` member names (the JWK Set at `{origin}/.well-known/http-message-signatures-directory`, the key identified by its RFC 7638 thumbprint, the RFC 9421 `keyid`). The agent's identity and consent on a purchase cannot be forged or moved onto another request, because they are the `AgentAcceptance` signed into the body over the offer signature, requester and idempotency key. Where a party forwards a request unchanged and covers the signature before it, a forged, reordered, dropped or inserted hop breaks a later signature and the request is rejected. See [Multi-hop forwarding](/protocol/authentication/#multi-hop-forwarding). A signer cannot act for another requester unless the Exchange admits it as a Broker: a request whose `requester.domain` names a directory other than the signer's is refused as `unauthenticated` with `request_auth_failure` `SIGNATURE_INVALID` from any signer the Exchange does not admit, and nothing the sender states, such as its manifest role, admits it (see [Direct and relayed requests](/protocol/authentication/#direct-and-relayed-requests)). The refusal's typed reason (`RequestAuthFailureReason`) is deliberately coarse — missing, invalid or stale — so it never tells a forger which check its request failed or how far it got. - -### T-DEL-5: Scope pollution - -**Attack**: Agent declares scopes it doesn't actually have, hoping the Exchange returns premium content. -**Countermeasure (reconciliation + contractual)**: `Requester.scopes` is the requester's own statement, signed and attributable, and the Exchange does not verify it. The Exchange presents an offer for a term only when the stated scopes cover the term's `LicenseTerm.scopes`, which hides the term from a requester that does not state the scope but does not stop one that states it falsely, so a false statement is detected and settled rather than prevented. For every scoped term an account bought, the transaction record holds the Exchange-signed offer and the agent's acceptance of it, attributed to the signing key, its directory and its [account](/protocol/authentication/#accounts). Reconciling those purchases against what the term's issuer actually granted that account, such as a subscription roster, a revenue-share agreement or an enterprise grant, exposes a scope the agent never held, and the account relationship and the term's contract settle it. An Exchange that needs prevention MAY require a verified delegation that grants a term's scopes before it presents the term ([Delegation](/protocol/authentication/#delegation)), and answers a requester without one as if the term did not exist. Verifying stated scopes is deferred, not designed out. - -### T-DEL-6: Quota gaming via multiple tokens - -**Attack**: Agent obtains multiple delegation tokens for the same subscription (e.g., by requesting new delegations from different intermediaries) to exceed per-subscription quotas. -**Countermeasure (protocol)**: **Exchange tracks quotas by `subscription_id`, not by delegation token.** All tokens referencing the same subscription share one counter. Multiple tokens for the same subscription do not multiply the quota. Rate limiting is applied at the subscription level regardless of how many delegation tokens reference it. - -## 9. Licensing-Layer Threats - -### T-LIC-1: SSRF / phishing via `License.uri` - -**Attack**: A malicious publisher pushes a term whose `License.uri` points at an internal address — `http://169.254.169.254/latest/meta-data/…` (cloud metadata), `http://localhost:6379/`, or `file:///etc/passwd`. An agent platform that auto-fetches the document to "read the license before use" (REFERENCE_ONLY requires this) issues a server-side request into its own infrastructure — leaking cloud credentials, reaching internal services, or reading local files. A variant points `uri` at attacker-controlled HTTPS to harvest the fetcher's identity/IP or serve misleading terms. -**Countermeasure (protocol)**: `License.uri` is deliberately never *rejected* at ingest (data-labels TDL identifiers use non-URL schemes) — but "do not reject" is not "blindly fetch." A consumer that resolves `uri` MUST: (a) allowlist schemes (`https` + known TDL schemes); (b) block loopback, link-local, private, and cloud-metadata IP ranges, resolving-then-checking to defeat DNS rebinding; (c) fetch client-side through an egress proxy, never from the Exchange's privileged network; (d) treat the fetched bytes as untrusted content. The Exchange applies the same rules when it fetches to pin `uri_digest` (T-LIC-4). - -**Same class — the SDK's directory fetch.** The same SSRF discipline applies to the WBA / well-known **directory fetches** the SDKs perform to resolve a signer's keys: the directory host is derived from a caller-supplied `Signature-Agent` and fetched **before** the ed25519 signature check, so an unauthenticated caller controls the fetch target (pre-auth SSRF). Defense is layered, and the layers have distinct owners: -- **In-code (SDK, primary).** The SDKs ship a **safe-by-default** SSRF-guarded transport, and it is **two checks, not one**. The *address pin* is connection-level: it resolves-then-checks every candidate address against a shared reserved-range corpus and pins the checked IP to defeat rebinding, on a maintained HTTP client (`net/http` / `httpx` / `undici`). The *scheme allowlist* is http(s)-only on the initial URL and every redirect hop, and it is deliberately **not** part of the connector — by the time a connection-level hook runs, the URL has been reduced to a host and a port and the scheme is no longer visible. Go and Python wrap the transport, so one object carries both (`SSRFGuard` inside `NewGuardedTransport`, `ssrf_guard()` inside `guarded_client`). TypeScript composes `ssrfGuard()` as the undici connector and states the scheme rule beside it, in `requireScheme()`. Because both ship in the artifact, their correctness cannot depend on deployment — and a caller who replaces the dial replaces the address pin with it, so the scheme check sits **above** the dial in the client tier, where no injected transport can remove it. -- **Egress boundary (operator, recommended defense-in-depth).** Operators SHOULD additionally run any role that resolves directories from request-supplied hosts behind **restricted egress** (an egress proxy or network policy that cannot route to RFC1918 / link-local / metadata) and **IMDSv2 with hop-limit 1**. This neutralizes the entire class regardless of any in-code gap — but it is *defense-in-depth, not a substitute* for the SDK guard, which remains the primary control for an OSS artifact that runs in deployments the maintainers do not control. - -**Which fetches this covers, and where it does not reach yet.** The rule is the URL's **provenance**, not what is being fetched. A **request-derived** host is one another party chose — it arrives in a header, or on a signed message — so it takes the guarded transport; with one exception, named below, that is a gap rather than a choice. A **fixed, operator-chosen** address takes the plain transport deliberately: the operator rather than an attacker picked it, and an on-prem directory may legitimately sit on a private address a guard would refuse. Where each fetch stands today: - -| Fetch | URL comes from | Go | TypeScript | Python | -|---|---|---|---|---| -| WBA directory (`Signature-Agent`) | the request | guarded | guarded | guarded | -| Registration requirements (`RegisterRequest.exchange`) | the request | guarded | guarded | guarded | -| Exchange endpoint (`Offer.exchange`) | the request | guarded | **plain** | **plain** | -| Well-known JWKS | operator configuration | plain | plain | plain | - -The last row is the deliberate one — nobody but the operator can point that URL. The **third row is a known gap, not a decision**: that host comes off a signed offer, so by the rule above it belongs on the guarded transport in every language, and the two ports have not caught up. It is tracked separately. - -**What to do about it today.** TypeScript and Python require the application to supply the endpoint resolver — neither client builds one for you — so the remedy sits at a construction site you already own: pass the guarded transport explicitly, `guardedFetchFromEnv()` in TypeScript or `guarded_client()` in Python, rather than letting that resolver take its default. Conversely, a deployment that needs the guarded posture on a configured URL, or the plain one on a request-derived host, injects its own transport or sets `SKIP_SSRF` / `ALLOW_INSECURE`. - -### T-LIC-2: Silent restriction downgrade - -**Attack**: A publisher forbids training (`Restriction{kind: FUNCTION, prohibited: ["ai-train"]}`) but the consumer does not recognize a token, or the publisher forgot to mark the restriction binding. The consumer treats it as advisory and proceeds — silent infringement with plausible deniability. -**Countermeasure (protocol)**: `Restriction.advisory` is **fail-closed by default** (it inverts the COSE-`crit` opt-in). A restriction is binding unless `advisory = true`; a consumer that cannot evaluate every token in a binding restriction MUST decline the term. A forgotten flag therefore fails *safe* — publishers opt into leniency explicitly and never lose protection by omission. - -### T-LIC-3: Scope-gating escalation - -**Attack**: Term visibility is gated by scope coverage: the scopes in the requester's signed request must cover `LicenseTerm.scopes` (AND-semantics, empty = public). Two failure modes: (a) a publisher forgets `scopes` on a premium term → it defaults to public and leaks for free; (b) two implementations match scopes differently — naive prefix matching lets `sub:` cover `subscription:premium`, or `dist:*` is read as covering `dist:US:internal` on one Exchange but not another → an agent's grant is read as covering a term it should not. -**Countermeasure (protocol)**: Scope matching follows the single normative rule defined in [Scope Matching](/protocol/authentication/#scope-matching), and the **same rule applies to both** `Requester`/delegation scopes **and** `LicenseTerm.scopes` — there is exactly one matching algorithm: matching is **segment-wise** (`:`-delimited), never substring/prefix; a granted `*` segment matches one level and a **terminal `*` matches all remaining segments**; there is no implicit prefix match and a grant narrower than the requirement does not cover it. This is the authoritative string-segment definition. An Exchange MAY implement coverage however it likes (e.g. a compiled matcher rather than literal string comparison), but the result MUST be **identical** to the segment-wise definition — an alternate implementation is conformant only if it produces the same verdicts, never a second, divergent rule. So the example failures (`sub:` covering `subscription:premium`, or one Exchange reading `dist:*` as covering `dist:US:internal` and another not) are excluded by construction. `empty = public` stays the explicit, documented default; backfilling a sentinel scope (e.g. `r:all`) is **not** required — it only relocates the "forgot to set it" failure and forces every publisher to issue an extra scope grant, without adding enforcement. (cf. OAuth 2.0 and AWS IAM: exact-match with explicitly-defined wildcard expansion, no implicit hierarchy.) - -### T-LIC-4: Referenced-document swap - -**Attack**: A term carries a `License.uri`; the agent fetches and trusts the document. The publisher (or a MitM on the fetch) later changes the bytes at `uri` — which is just a URL — so the agent's understanding of the terms silently diverges from what was offered. `immutable: true` makes this worse (the agent caches and stops re-checking), but a mutable `uri` is swappable too. -**Countermeasure (protocol)**: `License.uri_digest` pins the document as `method:hexdigest` and is **required whenever `uri` is present** — any semantics, mutable or not. The party that sets `uri` supplies the digest with it: the publisher, on a term it pushes. Because the entire Offer is signed, the digest is tamper-evident; the agent verifies the bytes it fetches against it and refuses on mismatch. - -## Comparison to Ad-Tech Fixes - -| Ad-Tech Fix | Year | FORA Equivalent | Status | -|---|---|---|---| -| ads.txt | 2017 | fora.json (authorized providers) | In proto | -| sellers.json | 2019 | Exchange identity in ResourceResponse | In proto | -| SupplyChain Object | 2019 | exchange_signature on Offer | In proto | -| ads.cert | 2020 | exchange_signature + content_integrity_hash | In proto | -| MRC Viewability Standard | 2014 | A metered charge fixed at purchase (estimate × rate), never re-measured | Design principle | -| Open Measurement SDK | 2018 | Three-sided reconciliation | In protocol flow |