From 998ea750b701c9c07ba0df9c3d732bfd4999ddf0 Mon Sep 17 00:00:00 2001 From: "Constantine.mirin" Date: Mon, 16 Nov 2026 12:51:13 +0100 Subject: [PATCH] Make the edge, exchange, log and dispute pages match the protocol Delivery URLs are bound to the purchasing agent's key and a short window, and the edge records each delivery it authorizes in its delivery log; the edge, signed-URL and CDN adapter pages no longer describe single-use URLs. Signing keys belong to a tenant, which is its own Exchange with its own domain, key directory and keys, and signs every publisher it represents. Retroactive alteration of the transaction log is detectable even when the Exchange operator is the adversary, because the agent and the publisher's edge hold their own records; the storage layers are defense in depth. Dispute tiers are a recommended policy, with their time and share figures as design goals. The bot detection page states the reference edge's lists, settings and 403 body. The multi-tenant page drops application-level rate limits and price overrides and names Offer.signature. The Broker deployment page states its five-minute key cache. Pages that linked threat-model entries now state the protection or link the protocol section that defines it. --- proto/CHANGELOG.md | 2 +- .../docs/components/broker/deployment.mdx | 10 ++-- .../edge-function/bot-detection.mdx | 34 +++++------ .../components/edge-function/cdn-adapters.mdx | 36 +++--------- .../components/edge-function/overview.mdx | 27 ++++----- .../edge-function/signed-url-verification.mdx | 58 ++++--------------- .../docs/components/exchange/multi-tenant.mdx | 15 +---- .../components/exchange/request-flows.mdx | 4 +- .../components/exchange/storage-model.mdx | 2 +- .../transaction-log/event-types.mdx | 2 +- .../components/transaction-log/overview.mdx | 8 +-- .../transaction-log/reconciliation.mdx | 10 ++-- .../transaction-log/write-ahead-logging.mdx | 2 +- .../docs/getting-started/for-ai-agents.mdx | 2 +- .../for-exchange-operators.mdx | 5 +- .../docs/protocol/dispute-resolution.mdx | 10 +++- .../src/content/docs/protocol/ext-comp.mdx | 2 +- .../docs/protocol/transaction-flow.mdx | 2 +- .../src/content/docs/reference/changelog.mdx | 2 +- 19 files changed, 81 insertions(+), 152 deletions(-) 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/src/content/docs/components/broker/deployment.mdx b/website/src/content/docs/components/broker/deployment.mdx index a0e3709d..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 | |---|---|---| -| Hidden orchestration fee | Broker adds markup to relayed offers | Signed offers passed through. Agent verifies signature. Any fee is disclosed separately. | -| Kickback-driven selection | Broker has side deal with an Exchange | Selection rationale logged. Agent can spot-check by querying directly. | -| 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/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 d3246dbe..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 (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. diff --git a/website/src/content/docs/components/transaction-log/overview.mdx b/website/src/content/docs/components/transaction-log/overview.mdx index 2f8931e4..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 is undetectable -- Phantom transactions cannot be disproven -- Ghost billing (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 4ce169fd..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, 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 6485dd23..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 (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 9cc6417f..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,3 +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 [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 25f3cf97..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`](/protocol/licensing-terms/#term-semantics): +`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/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