Skip to content

Docs: edge, Exchange, transaction-log and dispute pages match the protocol - #83

Merged
EugeneDymo merged 1 commit into
docs/unpublish-threat-modelfrom
docs/protocol-accuracy
Nov 16, 2026
Merged

EugeneDymo merged 1 commit into
docs/unpublish-threat-modelfrom
docs/protocol-accuracy

Conversation

@KonstantinMirin

@KonstantinMirin KonstantinMirin commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Stacked on #81. Makes the edge, Exchange, transaction-log and dispute pages say what the protocol and the reference edge do.

  • Delivery URLs. "Single-use" is removed from the edge overview, signed-URL verification and CDN adapters pages. A delivery URL is bound to the buying agent's key and a short time window, and the edge records each delivery with the URL hash in its log.
  • Keys per tenant. Each tenant (seat) has its own Exchange domain, directory and keys, and signs for every publisher it represents. Signed-URL verification and the storage model now say so.
  • Reconciliation. The pages lead with the point that tampering is detectable even when the Exchange operator is the adversary, because the agent, the Exchange and the publisher's edge are separate parties. Storage protections are defence in depth on top. The join key is signed_url_hash.
  • Disputes. The tiers are the recommended policy. The timing and share figures are stated as design goals.
  • Bot detection. The page uses the real BOT_UA_*_JSON settings and the {error, reason} body, the publisher decides per crawler, and the example uses publisher.example.
  • Multi-tenant. Price overrides and application-level abuse counters are removed, and volume is limited in front of the stateless Exchange. Offer.signature replaces exchange_signature.
  • Broker deployment. Exchange keys are cached in memory per Exchange for five minutes, never past a key's not_after.

npm run build, npm test, npm run routes, routes:check and doc conformance all pass. No page links to the threat model.

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.
@EugeneDymo
EugeneDymo merged commit ac462a8 into docs/unpublish-threat-model Nov 16, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants