Clear ExchangeDocs Live demo

What is built, stubbed and on the roadmap

Everything under Roadmap below is not built. It describes intended direction, not current behaviour, and has no committed dates.

Built and running

  • Query, routing across sources, fan-out under a 0.9 s routing budget (slow sources dropped, stage timings on every response and per source at GET /v1/admin/timings), central re-scoring, relevance-band selection (0.5 floor, 0.9 of top, explicit "no good match"), recency-aware ranking and freshness on offers, rate card pricing with a clearing fee on top.
  • Single-call purchase: POST /v1/acquire returns the selected offer already accepted, with its entitlement and content, alongside the multi-step flow.
  • Signed Ed25519 entitlements, offline-verifiable via /.well-known/jwks.json.
  • Structured licence terms on every offer and entitlement (commercial use, attribution, share-alike, caching and duration, reuse across end users, display), set on rate cards with defaults, with a one-line summary and query filters. See Licence terms.
  • Durable state: sessions, offers, entitlements, the ledger and telemetry survive restarts and deploys (JSONL on a Fly volume).
  • Licensed retrieval with content-hash binding and an idempotent ledger (a record; no money moves).
  • SPUR Content Telemetry v1.0: content_retrieved emitted by the exchange, agent-reported grounded, cited, presented and engaged, deduplicated per event id.
  • Supply: three fictional demo verticals (finance and business news, developer documentation, research abstracts: twelve publishers, about 300 dated items, listed at /coverage and GET /v1/coverage); the seeded fictional catalogue (four publishers, sixteen articles); live, openly licensed Wikinews and Wikipedia; any publisher implementing the v1 offer contract, by configuration (http-offer); five fictional demo publishers speaking that contract (DEMO_PUBLISHERS=on).
  • Web UI (marketing page, agent console, read-only operator and publisher views), the agent-user harness, CI and continuous deployment to Fly.io.

Stubbed

  • TollbitAdapter (marketplace) and PrebidTrustedServerAdapter (Prebid seller module in IAB Tech Lab's Trusted Server) are registered in src/supply/stubs.ts so the integration shape is visible in GET /v1/supply. They return no candidates, make no network calls and are never routed to. Each lists its integration TODOs in the source.

Known limits of the MVP

  • Agent identity is self-declared (agent_id). Entitlements are bearer tokens.
  • Currency: no conversion; offers in another currency than the query's are excluded.
  • Persistence: sessions, offers, entitlements, the ledger and telemetry are JSONL files on one Fly volume, reloaded at startup, so they survive restarts and deploys. A volume attaches to one machine, so the demo runs one; more machines need a shared database behind the same interfaces. Routing statistics are still in memory.
  • Admin: one shared ADMIN_TOKEN, read-only views, no per-user accounts or audit trail.
  • Keys: one signing key, no multi-key rotation.
  • Indemnity and liability: not defined. Offers and entitlements carry a placeholder saying no position is given (see Licence terms); the position is for the founder to decide.
  • Licence terms are recorded, not policed: the exchange states and signs them, and telemetry warnings flag some misuse, but it cannot see what a buyer does with cached content or how many end users it serves.

Roadmap (not built)

  • Agent key directories for Web Bot Auth (Signature-Agent and the well-known key directory), so signing agents need not be pre-registered. API keys, budgets, rate limits, signed-request verification and entitlement binding are built: see Agent authentication.
  • Payments and settlement on top of the ledger.
  • Publisher logins and rate card upload. Today the publisher view is read-only behind the operator token, and rate cards change only by editing files and redeploying.
  • SPUR telemetry manifest (/.well-known/content-telemetry.json) and delivery of telemetry to publishers.
  • Shared storage: a database behind AppendLog and ExchangeState, so the service can run more than one machine (state already survives restarts on one volume).
  • Key rotation with multiple keys in the JWKS.
  • Rate limiting.
  • Marketplace integration (TollBit-style) and the open Prebid / Trusted Server seller module, the planned home of the same offer contract at the publisher's edge, with response signatures and attestation checks.
  • IAB Tech Lab CoMP field mapping where the specification defines fields.
  • Confidential VM attestation layer, below.

Plan for the confidential VM attestation layer

Not built. The code is shaped so it can be added without touching business logic:

  1. Keys behind interfaces. Token code depends only on Signer (async sign, publicJwk) and VerificationKeyResolver (src/entitlement/keys.ts). LocalEd25519Signer holds the key in process memory today. The attested implementation would generate its key inside the confidential VM, or receive it from a key broker only after remote attestation, and never export it.
  2. Attested JWKS. /.well-known/jwks.json would publish, alongside each key, a reference to the attestation report that binds that public key to a measured exchange build, so verifiers can check an entitlement was signed by genuine, unmodified exchange code.
  3. Credentials for supply. Publisher and marketplace API credentials would be released to the VM by the same key broker, behind the same kind of interface.
  4. Small trusted computing base. There are no runtime dependencies, and the composition root (src/app.ts) is the single place where the signer, storage and adapters are chosen.

Standards referenced

SPUR Coalition Content Telemetry v1.0 (Apache-2.0); RFC 7515 (JWS), RFC 7519 (JWT), RFC 8037 (EdDSA in JOSE); ISO 4217 currency codes. Integration targets: IAB Tech Lab Trusted Server and CoMP, Prebid, Web Bot Auth.