Security

Documentation Index

Fetch the complete documentation index at: https://docs.adcontextprotocol.org/llms.txt

Use this file to discover all available pages before exploring further.

​

Overview

• Financial transactions involve real advertising spend
• Multi-party trust requires coordination between authenticated agents, publishers, and orchestrators
• Sensitive data includes first-party signals, pre-launch creatives, and competitive targeting strategies
• Asynchronous operations span multiple systems and protocols

​

Risk Classification

​

High-Risk Operations (Financial)

• Short-lived credentials — right-sized to the blast radius of a leaked token. ≤1 hour is a reasonable default for tokens that can commit spend; ≤15 minutes is appropriate for tokens that can commit spend above a material threshold or that cross organizational boundaries. Document and justify the chosen window rather than defaulting to the lowest number.
• Request signing for transaction integrity
• Multi-factor authentication or approval workflows for large budgets
• Full audit trail with immutable logging

​

Medium-Risk Operations (Data Access)

​

Low-Risk Operations (Discovery)

​

Webhook Security

​

Legacy HMAC-SHA256 fallback (deprecated, removed in 4.0)

• Algorithm: HMAC-SHA256 only
• Signed message: {unix_timestamp}.{raw_http_body_bytes} — never re-serialize the JSON
• Byte-equality invariant: The HMAC is computed over raw bytes, not over a parsed JSON value. Signers and verifiers MUST compare the bytes on the wire directly; re-parsing and re-serializing a payload — even with matching libraries and compact separators — is not guaranteed to reproduce the signed bytes, because key ordering, unicode-escape policy, and number representation all diverge across serializers (see “Non-canonicalized aspects” below for concrete examples). This scheme does not define a canonical JSON form; the “Canonical on-wire form” and “Verifier input” rules below narrow the most common byte-drift failures on the signer and verifier sides respectively, but do not eliminate byte-level divergence.
• Canonical on-wire form: The {raw_http_body_bytes} MUST be byte-identical to the bytes the signer puts on the wire as the HTTP body. When the signer constructs the body by serializing a JSON value, it MUST use the JSON compact separators "," (item separator) and ":" (key separator) — no whitespace between tokens. The language-level serializers JavaScript JSON.stringify, Go encoding/json json.Marshal, Ruby JSON.generate, and Java Jackson writeValueAsString produce compact output by default; HTTP clients that wrap them (axios, Go net/http with a json.Marshal-ed body, Ruby Net::HTTP with JSON.generate, Java OkHttp with Jackson) inherit those defaults. In Python, httpx serializes with compact separators, but stdlib json.dumps defaults to ", " / ": " and HTTP clients that hand their payload to json.dumps without a separators kwarg (requests(json=...), aiohttp) emit spaced bodies — signers on those paths MUST pass separators=(",", ":") explicitly. This enumeration is non-exhaustive; signers MUST verify their HTTP client’s actual on-wire serialization (e.g., capture the request body via a proxy or hook) rather than rely on this list. The signature covers the bytes the receiver sees, not the object the signer serialized.
• Non-canonicalized aspects: Key ordering, unicode-escape policy, and number representation are NOT canonicalized by this scheme. For numbers in particular, language defaults diverge (JSON.stringify(1.0) → 1, Python json.dumps(1.0) → 1.0, Go json.Marshal(1.0) → 1; floats like 0.1 and scientific notation hit similar cliffs), so a signer that serializes with one library and then re-parses / re-serializes with another before sending can produce signer-verifier drift even with compact separators — the byte-equality invariant above is the only thing that holds the scheme together.
• Duplicate object keys: Signers MUST NOT emit duplicate object keys AND MUST reject duplicate-key input from upstream callers before serialization. The signer-side MUST is load-bearing because it is the only place this failure mode can be caught: a signer that silently collapses a duplicate-key payload emits a cryptographically-clean signed frame whose semantics differ from the caller’s intent, and the verifier cannot detect the upstream divergence from the wire — the signed bytes look normal. Signer-side conformance is unverifiable on the wire and is expected to be enforced by out-of-band audit / interop testing, not runtime detection (this shape is routine in signing specs; COSE and JOSE use the same pattern). Verifiers MUST reject bodies containing duplicate object keys after HMAC verification succeeds, returning a structured malformed-body error (distinct from a signature-mismatch error — the signature IS valid; the body is malformed). Per RFC 8259 §4, the names within a JSON object “SHOULD be unique” and the behavior of software that receives an object with non-unique names is unpredictable — so two verifiers parsing the same HMAC-valid bytes can disagree on the parsed value. This is a parser-differential attack class (cf. CVE-2017-12635 where one CouchDB parser read roles=[] and another read roles=["_admin"] from the same signed body). Every body carried on the legacy HMAC webhook scheme is a state-change notification (creative status, media-buy status, governance transitions), so the MUST applies unconditionally to this scheme. The detection MUST use a parser that exposes duplicate keys — a last-wins/first-wins default that silently discards them does not satisfy this requirement. Per-language strict-parse escape hatches for both signer input-validation and verifier body-checking: see step 14 of the webhook verifier checklist for the canonical non-exhaustive enumeration, including the libraries that only appear strict by default but silently collapse data-key duplicates. The verifier-side conformance fixture is duplicate-keys-conflicting-values in static/test-vectors/webhook-hmac-sha256.json, with expected_verifier_action: "reject-malformed". Signer-side conformance fixtures live in the same file under signer_side.rejection_vectors: signer-upstream-duplicate-key-rejection (top-level), signer-upstream-duplicate-key-deep-nested (verifies the signer’s check recurses into nested objects, not only top-level keys), signer-upstream-duplicate-key-array-contained (verifies the signer’s check descends into objects inside arrays — a blind spot in hand-rolled validators that recurse into objects but not array members), and signer-upstream-duplicate-key-three-deep (verifies the walker does not halt at a shallow fixed depth). A positive-case fixture signer-upstream-clean-input lives under signer_side.positive_vectors so that a signer rejecting everything does not trivially pass the negative fixtures — interop harnesses MUST assert both rejection of the duplicate-key inputs and acceptance of the clean input. Signers that surface upstream-input rejections via logs or error responses MUST apply the same key-name sanitization rules defined in step 14b of the webhook verifier checklist (truncate at first non-printable to <sanitized:N>, truncate to last UTF-8 codepoint at or below 32 bytes, cap count at 4) — the signer-side channel has the same attacker-controlled-byte shape as the verifier-side channel, just with the direction of trust inverted. Error identifier is normative; error-object internals are not. When a signer surfaces the rejection via an error, the error identifier (error-code string in a discriminated union, exception class name in typed-throw idioms, tag in a sum type) MUST be duplicate_key_input exactly — case-sensitive, no prefix or suffix — so that multi-SDK integrations can write if (error.code === 'duplicate_key_input') { ... } and have the dispatch work regardless of which SDK signed the frame. The internal shape of the error carrier (field names for the sanitized key list, overflow-marker string, typed-exception constructor arguments) is implementation-defined. Verifiers that crash / fail-closed are conformant-but-suboptimal (the request is not silently accepted, but senders receive no actionable error code); verifiers SHOULD return a structured malformed-body error instead. The non-conformant failure mode — silent accept where the signature verifier’s parse diverges from the downstream business-logic parse — is now forbidden; a verifier that does not detect duplicate keys before handing the payload to business logic does not conform to this scheme.
• Verifier input: Verifiers MUST use the raw HTTP body bytes as received on the wire, captured before any JSON parse or re-serialize. Every modern HTTP framework exposes a pre-parse raw-body hook (Express express.raw(), FastAPI Request.body(), aiohttp Request.read(), Go io.ReadAll(r.Body) before json.Unmarshal). The raw-capture hook MUST run before any JSON-parse middleware on the same route; a globally-mounted express.json() or FastAPI BaseModel body binding that consumes the request body before the verifier runs leaves the verifier operating on a re-stringified payload, not the signed bytes — this is a common deployment mistake. Verifiers SHOULD NOT re-serialize a parsed payload to reconstruct the signed bytes: re-serialization silently fails against signers whose output differs in key order, unicode escapes, or number formatting, and masks signer bugs the verifier should surface. A verifier that genuinely cannot capture raw bytes MUST fail closed and surface the infrastructure gap rather than accept a re-serialized approximation.
• Timestamp source: The {unix_timestamp} in the signed message MUST be the exact ASCII integer sent in the X-ADCP-Timestamp header. Signers and verifiers MUST NOT derive it from any body field.
• Timing-safe comparison: MUST use constant-time comparison (e.g., timingSafeEqual)
• Replay window: Reject requests where |current_time - timestamp| > 300 seconds
• Minimum secret length: 32 bytes
• Header format: X-ADCP-Signature: sha256=<hex digest> and X-ADCP-Timestamp: <unix seconds>. Any body-level signature field is a convenience copy and MUST NOT be trusted over the headers.

1. Reject if X-ADCP-Signature or X-ADCP-Timestamp header is missing
2. Reject if timestamp is non-numeric
3. Reject if timestamp is outside the 5-minute window
4. Compute and compare HMAC

• Receivers MUST accept signatures from both current and previous secret during rotation
• Rotation window SHOULD NOT exceed the replay window (5 minutes)
• Publishers begin signing with the new secret immediately upon rotation

​

Webhook URL validation (SSRF)

1. Reject non-HTTPS URLs in production.
2. Resolve the hostname and reject the fetch if the resolved IP falls in any reserved range:
   • IPv4: RFC 1918 (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16), RFC 6598 CGNAT (100.64.0.0/10), loopback (127.0.0.0/8), link-local (169.254.0.0/16 — explicitly includes 169.254.169.254 used by AWS/GCP/Azure/Alibaba instance metadata), broadcast (255.255.255.255), 0.0.0.0/8, multicast (224.0.0.0/4).
   • IPv6: loopback (::1), unique-local (fc00::/7), link-local (fe80::/10), IPv4-mapped (::ffff:0:0/96 — the most common bypass, mapping reserved IPv4 into IPv6), multicast (ff00::/8), and the AWS IMDSv2 fd00:ec2::254 address.
3. Pin the connection to the validated IP. DNS-based filtering alone is vulnerable to DNS rebinding: an attacker serves a public IP at validation time and a private IP at connect time. Fetchers MUST pin the connection. Preferred: (a) pass the validated IP directly to the TCP connect call and set the Host: header from the URL. Fallback (only when the HTTP client cannot accept a pre-resolved IP): (b) validate the socket’s post-handshake peer address against the reserved-range list before sending any request body. Note: (b) depends on the client library exposing a peer-address hook that fires before the first body byte ships; many common libraries do not, so implementations choosing (b) MUST verify the hook in testing. Re-resolving DNS without pinning is not sufficient.
4. Refuse to follow redirects when fetching counterparty-controlled URLs (a 30x response lets the origin redirect to a reserved address that bypassed the initial check).
5. Cap response size and timeouts. Recommended: 5 MB body cap, 10 s connect, 10 s read.
6. Do not echo fetch errors to the agent that supplied the URL. Detailed error messages (connection refused vs. timed out vs. TLS failure) are a side-channel for probing internal network topology.

• Offline reporting buckets — IAM-layer prefix scoping, credential revocation on account status change.
• Collection lists — auth_token scope and revocation, distribution-ID validation, webhook signature normative rules.
• Managed networks authoritative_location — validator fetch semantics, change detection, relationship termination.
• TMP provider registration — dynamic registration authentication, router-to-provider auth, /health info-leakage rules.

​

Authentication Best Practices

​

Credential Storage

// Use secure key management systems
// Never commit credentials to version control
// Use environment variables or secret managers

// Example: Secure credential retrieval
async function getCredentials(agentId) {
  // Retrieve from secure storage (AWS KMS, Vault, etc.)
  const encrypted = await secretManager.get(`agent/${agentId}/apiKey`);
  return decrypt(encrypted);
}

​

Token Expiration

const TOKEN_LIFETIMES = {
  discovery: 3600,     // 1 hour for read operations
  financial: 900,      // 15 minutes for financial operations
  refresh: 86400       // 24 hours for refresh tokens
};

function validateToken(token, operationType) {
  const decoded = jwt.verify(token, secret);
  const maxAge = TOKEN_LIFETIMES[operationType] || TOKEN_LIFETIMES.discovery;

  if (Date.now() - decoded.iat > maxAge * 1000) {
    throw new Error('Token expired for this operation type');
  }

  return decoded;
}

​

Agent and Account Isolation

1. Bind on create — permanently associate each object (media buy, creative, session, etc.) with the account used on the request that created it.
2. Verify on access — on every subsequent read or modification, verify the authenticated agent has access to the object’s bound account.
3. Fail closed — when verification fails, return a generic error (status 403 or 404 is acceptable, but the body MUST NOT distinguish “unauthorized” from “not found” or name the account). Never fall through to the resource query.

​

The two-step pattern

1. Auth precheck — the request’s account MUST be in the authenticated agent’s authorized set. Fail closed with a 403 or a generic “not found” (never “you are not authorized for that account” — that’s an existence leak).
2. Resource query — filter by the request’s account_id as the primary key constraint. Not by the whole authorized set — only by the specific account this request is acting on.

// Two-step: precheck request account is authorized, then scope the query to it.
// authorizedAccountIds is a Set<string> populated once at auth-time, not an Array.
// Set.has() is O(1); Array.includes() is O(n) and scans element-by-element, which
// on large authorized-account sets introduces a timing difference between early
// and late matches that a caller can probe across requests.
async function getMediaBuy(mediaBuyId, requestAccountId, authAgent) {
  // Step 1: auth precheck
  if (!authAgent.authorizedAccountIds.has(requestAccountId)) {
    // Generic error - don't reveal whether the account exists
    throw new NotFoundError("Media buy not found");
  }

  // Step 2: resource query scoped to the specific account
  const mediaBuy = await db.mediaBuys.findOne({
    id: mediaBuyId,
    account_id: requestAccountId  // Primary filter
  });

  if (!mediaBuy) {
    // Generic error - same shape as the precheck failure
    throw new NotFoundError("Media buy not found");
  }

  return mediaBuy;
}

​

Row-Level Security

-- PostgreSQL example
-- app.current_account is set by the auth layer AFTER the precheck above succeeds
CREATE POLICY account_isolation ON media_buys
  USING (account_id = current_setting('app.current_account')::uuid);

ALTER TABLE media_buys ENABLE ROW LEVEL SECURITY;

CREATE POLICY account_isolation_list ON media_buys
  FOR SELECT
  USING (account_id = ANY(current_setting('app.authorized_accounts')::uuid[]));

​

Client-side isolation: cross-principal tool-call confusion

1. Tag text with its principal of origin. Every string the LLM context ingests from the network (tool results, webhook bodies, registry documents, creative metadata) MUST be annotated internally with the {principal_domain, tool_name, response_field} triple that produced it. Dropping the annotation at ingest time is where this defense dies.
2. Restrict tool-call targets to the calling principal. A tool call whose target principal is not the same as the principal that supplied the string(s) driving the decision MUST either (a) be refused, (b) go through a human approval step, or (c) be mediated by an explicit per-principal policy the operator has declared up front. The default MUST be refuse, not allow.
3. Segregate credential scopes by LLM context. A single LLM planning loop MUST NOT hold live credentials for principals whose interests can conflict (e.g., two brands competing for the same inventory; a buyer credential and a governance agent’s signing key in one context). The scope-segregation is enforced at the process / tool-registration layer, not by instructing the LLM — the LLM MUST NOT have the affordance to misuse.
4. Log every cross-principal attempt, not just successes. Refusals under rule 2 are the signal operators MUST monitor — a rising refusal rate from a given principal is the earliest detectable sign of an injection campaign targeting your agent.

​

Time Semantics

​

Timestamp format

✅ 2026-04-19T10:00:00Z            // UTC, recommended
✅ 2026-04-19T10:00:00-04:00       // explicit offset
❌ 2026-04-19T10:00:00             // no offset — ambiguous
❌ 2026-04-19 10:00:00             // not ISO 8601

​

Intervals

​

Daypart targeting

• Buyer-declared zone — an IANA zone name alongside the daypart (e.g., timezone: "America/New_York"). The daypart is evaluated against that zone regardless of viewer or publisher location. Use this when the buyer wants “9–11pm New York time” enforced globally.
• Publisher-local — the daypart is evaluated in the publisher’s declared local zone. Use this when the buyer wants “prime time on the publisher’s schedule” and is willing to let the publisher decide what that means.
• Viewer-local — the daypart is evaluated against each viewer’s timezone, resolved at serve time from the viewer’s location signal. Use this when the buyer wants “serve at 8pm local” across a global audience.

​

Request Safety

​

Idempotency

​

Normative seller behavior

1. Schema validation runs first. Sellers MUST validate the request against its schema (including presence and format of idempotency_key) BEFORE consulting the idempotency cache. A malformed request returns INVALID_REQUEST without ever touching the cache — otherwise cache misses become a timing side channel that leaks whether schema validation accepted the key format. Validation errors are never cached (per rule 2).
2. First call is canonical. On task success (status: completed or status: submitted for async operations), the seller stores the inner response payload (not the protocol envelope) keyed by (authenticated_agent, account_id, idempotency_key) along with a hash of the canonical request payload. For async tasks, the cached response is the submitted result containing task_id. The cache entry is immutable — even if the async task subsequently completes, fails, or is canceled, a replay within the TTL MUST return the originally-cached submitted response (with replayed: true), NOT the current terminal state. The buyer uses the returned task_id to observe current state via tasks/get or webhook, exactly as it would have on the first call. This preserves the byte-stable cache property and keeps the idempotency layer decoupled from async task lifecycle — sellers don’t need to update cache entries when task state changes.
3. Only successful responses are cached. On any error — validation, governance denial, transport failure, internal error — the key is not stored. A retry re-executes. This matches buyer intent: a retry after a 5xx should try again, not replay a failure. It also prevents a buyer’s malformed request from being locked into a key for its full TTL.
4. Replay returns the cached response. A subsequent request with the same idempotency_key AND an equivalent canonical-form payload (see “Payload equivalence” below) MUST return the stored inner response without re-executing side effects. The seller injects replayed: true onto the outgoing protocol envelope at response time — replayed is an envelope-level field produced by the idempotency layer, NOT part of the cached inner response. Injection at replay time keeps the cached payload byte-stable across replays regardless of envelope changes (new timestamp, rotated governance_context, etc.). Transport-specific note for MCP: MCP tool responses do not have a separate envelope slot; servers MAY expose replayed inside the tool result object itself (e.g., at the top of the structured return) or via a response metadata field. REST and A2A responses use the envelope field directly.
5. Key reuse with a different canonical payload is a conflict. Same key, different canonical hash within the replay window MUST be rejected with IDEMPOTENCY_CONFLICT. Sellers MUST NOT silently apply the second request.
6. Expired keys are rejected explicitly. After replay_ttl_seconds elapses the seller MAY evict the cache entry. A request arriving after eviction with a key the seller has seen SHOULD be rejected with IDEMPOTENCY_EXPIRED rather than silently treated as new — silent re-execution is exactly the double-booking footgun the key was meant to prevent. Sellers SHOULD allow a ±60s clock-skew window at the TTL boundary (the same tolerance applied to JWS exp elsewhere in this document) so that a retry arriving seconds after nominal expiry is still replayed from cache rather than treated as fresh. Durability is normative. The declared replay_ttl_seconds is a durability contract, not a best-effort cache hint. Sellers MUST back the idempotency cache with storage that survives process restarts, pod replacements, region failovers, and operator-initiated cache flushes for the declared TTL. In-memory-only stores (plain Map, single-process LRU without a backing tier) are non-conformant whenever replay_ttl_seconds exceeds process lifetime — which is always true at the 3600 s floor. The consequence of silent eviction below declared TTL is a displaced-replay window: the sender legitimately retries with the same idempotency_key under a fresh signature nonce (which is how a signed retry is supposed to work — nonces are per-send, not per-event), passes the signature replay check, and finds the app-layer cache empty because the receiver’s in-memory state was dropped. The side effect runs twice. Sellers MUST NOT declare a replay_ttl_seconds higher than their cache tier can durably honor, and MUST fail-closed (IDEMPOTENCY_EXPIRED) rather than fail-open (silent re-execution) when they cannot distinguish “never seen” from “evicted under declared TTL.” A seller whose operational reality is “memory-only, lost on pod restart” is required to declare replay_ttl_seconds no higher than the shortest guaranteed pod lifetime — in practice, this forces a durable tier.
7. Replay window is declared, not inferred. Sellers MUST declare capabilities.idempotency.replay_ttl_seconds on get_adcp_capabilities (minimum 3600s / 1h, recommended 86400s / 24h, maximum 604800s / 7d). Clients MUST NOT fall back to an assumed default — a seller with no declaration is non-compliant and MUST be treated as unsafe for retry-sensitive operations.
8. Cache-growth defense. Sellers MUST apply per-(authenticated_agent, account) rate limits on idempotency cache inserts separately from request rate limits, and MUST return RATE_LIMITED (see error taxonomy) when the per-agent insert rate exceeds the configured ceiling rather than let the cache grow unbounded. A buyer submitting N fresh keys per second on a cheap success-path operation (e.g., log_event) would otherwise force unbounded storage, with amplification proportional to replay_ttl_seconds at the 3600 s floor. The natural bound is inserts_per_hour × replay_ttl_hours ≤ max_cache_rows_per_agent. Recommended ceiling: 60 inserts/sec per agent sustained (3,600/min), with burst allowance up to 300 inserts/sec over rolling 10-second windows. The sustained bound is a rolling 60-second window — a burst that empties a 10-second window still counts toward the next 50 seconds of the 60-second rolling bound. Sellers that adopt a different window shape (fixed-minute bucket, EWMA) MUST document it so buyers with retry logic can predict when RATE_LIMITED fires; silent window-shape divergence between sellers means identical buyer traffic passes one seller and is rejected by another on conformant implementations. At the 3600 s TTL floor the recommended rates bound per-agent residency to ~216,000 entries — the same order of magnitude as the 100,000-entry per-keyid webhook replay cap at Webhook replay dedup sizing, and an order of magnitude below the 1,000,000-entry per-keyid request-replay cap at Transport replay dedup. The numeric recommendations are SHOULD-level; the rate-limit-and-reject-with-RATE_LIMITED behavior itself is MUST. Sellers MUST expose the ceiling as a tunable configuration parameter — the 60/300/3,600 values are first-deployment starting points sized for a realistic high-volume launch pattern (≤10 media buys/min × 10 packages × 10 creatives, with 3–5× headroom for multi-campaign and retry patterns), not frozen defaults. Operators with burst onboarding or trafficking patterns larger than this ceiling MUST raise the limit rather than accept silent rejection of legitimate traffic; operators with steady low-volume traffic MAY tighten below the starting values. Sellers SHOULD NOT publish their exact configured ceiling numerically in capability responses — doing so makes the ceiling an ecosystem-wide attack target. Buyers discover the effective ceiling through the RATE_LIMITED + retry_after response, not through capability introspection. The ceiling is per (authenticated_agent, account) — the same scope as the idempotency key itself (bullet 1) — so a multi-account agency does not have its per-account budgets collapsed into a single shared quota. RATE_LIMITED rejections MUST populate retry_after (seconds) per the error handling taxonomy and MUST NOT be cached as idempotency responses (rule 3: only successful responses are cached). Sellers SHOULD enforce retry_after as a cheap rejection floor — a buyer retrying before retry_after elapses SHOULD hit a pre-auth token bucket (e.g., at a reverse-proxy layer) rather than re-entering the full schema-validate-and-cache-check pipeline on every retry. Without this discipline, misbehaving buyers can amplify load on the rate-limiter itself.

​

Payload equivalence

• idempotency_key — the key itself
• context — buyer-opaque echo data (trace IDs, correlation IDs) changes on retry by design
• governance_context — on the envelope; may be a refreshed signed token on retry
• push_notification_config.authentication.credentials — may be a rotated bearer token. The URL and scheme remain in the hash; only the credential value is excluded.

• TypeScript / JavaScript: @truestamp/canonify or canonicalize
• Python: pyjcs or the reference implementation from RFC 8785 appendix
• Go: gowebpki/jcs
• Rust: serde_jcs

​

Response-level replay indicator

{
  "status": "completed",
  "replayed": true,
  "timestamp": "2026-04-18T14:35:00Z",
  "payload": {
    "media_buy_id": "mb_01HW7J8K9P0Q1R2S3T4U5V6W7X"
  }
}

• Agent side-effect suppression — an agent that acts on response data before a human sees it (notifications, downstream tool calls, memory writes) MUST check replayed to avoid re-emitting on retry. “Campaign created!” notifications, LLM memory inserts, and downstream agent calls are exactly what silent replay breaks.
• Side-effect invariants — downstream systems expecting exactly-once event semantics read replayed before treating the response as a new event.
• Billing reconciliation — “we processed N buys this month” counts replayed: false only.
• Logging — distinguishing “retry succeeded by returning cache” from “retry triggered a new execution” (the latter usually signals a bug in the replay window or key management).

​

IDEMPOTENCY_CONFLICT response shape

• MUST include code: "IDEMPOTENCY_CONFLICT" and a human-readable message
• MUST NOT include the cached response, the original payload, a canonical-form diff, or any fingerprint derived from them. A field json-pointer hint seems harmless but reveals schema shape (e.g., /packages/0/budget tells an attacker the victim’s payload had a budget in the first package). Sellers MUST NOT emit one. A legitimate buyer debugging a retry can diff their own two payloads — they have both.

{
  "errors": [
    {
      "code": "IDEMPOTENCY_CONFLICT",
      "message": "idempotency_key was used with a different payload within the replay window. Either resend the exact original payload (to return the cached response) or generate a fresh UUID v4 to submit this new payload.",
      "recovery": "correctable"
    }
  ],
  "context": { "correlation_id": "..." }
}

​

SI send_message idempotency model

• Retry of turn N within the TTL returns the cached response for turn N, even if turn N+1 has since been accepted. Idempotency returns what you did, not rewinds what the session is. The buyer’s retry is asking “did my message get through” — the answer is still “yes, here’s what came back.”
• A new si_send_message with a fresh idempotency_key is a new turn, processed against the current session state. Buyers MUST generate a fresh key per logical turn, not per HTTP attempt.
• If the seller has advanced session state past turn N and cannot reproduce the cached response byte-for-byte (e.g., the session was pruned for storage), the seller MAY return SESSION_NOT_FOUND or IDEMPOTENCY_EXPIRED rather than reconstruct. Buyers retrying far past a session timeout should expect this.

​

Buyer obligations

• Network retry — socket timeout, 5xx, transient failure. The buyer has the same intent and sent the same bytes — and MUST resend them with the same key. This is what idempotency_key exists for.
• Agent re-plan — the buyer is an agent whose planner re-ran (prompt re-executed, tool output changed, policy re-evaluated) and produced a different payload. The intent has changed. The agent MUST mint a new key and treat the prior request as abandoned. Reusing the prior key with a different canonical payload returns IDEMPOTENCY_CONFLICT, which is the seller correctly telling the agent “you’re not retrying, you’re doing something new.”

import { canonicalize } from "@truestamp/canonify"; // RFC 8785 JCS
import { createHash } from "node:crypto";

const EXCLUDED_FROM_HASH = new Set([
  "idempotency_key",
  "context",
  "governance_context",
]);

function payloadHash(request) {
  const filtered = Object.fromEntries(
    Object.entries(request).filter(([k]) => !EXCLUDED_FROM_HASH.has(k)),
  );
  // If push_notification_config.authentication.credentials rotates, exclude it too
  if (filtered.push_notification_config?.authentication) {
    const { credentials, ...auth } = filtered.push_notification_config.authentication;
    filtered.push_notification_config = {
      ...filtered.push_notification_config,
      authentication: auth,
    };
  }
  return createHash("sha256").update(canonicalize(filtered)).digest("hex");
}

async function createMediaBuy(request, envelope) {
  if (!request.idempotency_key) {
    throw new InvalidRequestError("idempotency_key is required");
  }

  const requestHash = payloadHash(request);

  const existing = await db.findByIdempotencyKey({
    agent_id: currentAgent.id,
    account_id: request.account.account_id,
    idempotency_key: request.idempotency_key,
  });

  if (existing) {
    if (existing.expires_at < new Date()) {
      throw new IdempotencyExpiredError("idempotency_key is past replay window");
    }
    if (existing.request_hash !== requestHash) {
      throw new IdempotencyConflictError("idempotency_key reused with a different payload");
    }
    // Return the stored INNER payload; replayed: true is injected by the envelope layer
    envelope.replayed = true;
    return existing.response;
  }

  return db.transaction(async (tx) => {
    const response = await processMediaBuy(tx, request);
    // Cache ONLY on success, and cache only the inner response payload
    await tx.idempotencyKeys.insert({
      agent_id: currentAgent.id,
      account_id: request.account.account_id,
      key: request.idempotency_key,
      request_hash: requestHash,
      response,
      expires_at: new Date(Date.now() + TTL_SECONDS * 1000),
    });
    envelope.replayed = false;
    return response;
  });
}

​

Natural-key idempotency is not a substitute

​

Signed Governance Context

• Governance agents sign the token. They are the only party that signs.
• Buyers attach the token they received from their governance agent to the protocol envelope and forward to the seller. Buyers MUST NOT construct, modify, or re-sign the token. Buyers SHOULD retain the jti and check_id for their own audit record.
• Sellers persist the token as received and include it verbatim on all subsequent governance calls. Sellers that implement verification MUST verify per the checklist below before acting on the token. Sellers that have not yet implemented verification MUST still persist and forward the token unchanged so that verification-capable parties downstream (auditors, regulators) can act on it later.
• Auditors and regulators verify independently using the governance agent’s published keys — this is the accountability property the signed format exists to deliver.

​

Scope and dependencies

• In scope (3.0): buy-side governance. The governance_context token authorizes spend commitments made via AdCP tasks (create_media_buy, acquire_rights, activate_signal, creative_services). Sellers that run their own compliance policies (e.g., CTV political-ad rules, publisher brand-safety gates) express those via conditions responses on their own governance workflows; they do not issue signed tokens under this profile.
• Out of scope (3.0): seller-side governance authorities. A future RFC may extend this profile to cover seller-side signed decisions declared via adagents.json.
• Out of scope (ever): OpenRTB bid streams. Governance attestation terminates at the AdCP media buy boundary. Threading a signed attestation through per-impression bid requests is operationally infeasible (one token, many recipients, broadcast-fan-out) and unnecessary (spend authorization happens at media buy time, not per-impression).

​

AdCP JWS profile

• alg: EdDSA (Ed25519) RECOMMENDED on server-side runtimes. ES256 (ECDSA P-256) RECOMMENDED on edge runtimes (Cloudflare Workers, Vercel Edge, Deno Deploy) where Ed25519 may require explicit runtime configuration. Verifiers MUST reject none, HS*, and any RS* variant below 2048-bit. Verifiers MUST enforce the allowlist on the token header; they MUST NOT rely solely on library defaults.
• kid: REQUIRED. Identifies the signing key in the issuer’s JWKS.
• typ: REQUIRED. MUST be exactly adcp-gov+jws (byte-for-byte match; verifiers MUST NOT normalize or strip the +jws structured suffix per RFC 6838 §4.2.8). The typed header prevents a governance signing key from being tricked into validating a generic JWT for another purpose.
• crit: REQUIRED if any crit-listed claim is present. Per RFC 7515 §4.1.11, crit is an array of header/claim names that MUST be understood by the verifier. Verifiers MUST reject the token if any name in crit is not recognized. Governance agents MUST list in crit any claim whose omission or misinterpretation would change authorization semantics (e.g., a future budget_cap claim). This prevents silent downgrade attacks when the profile adds claims in later versions.

​

Buyer identity resolution

1. mTLS: buyer presents a client certificate; the certificate Subject/SAN resolves to the buyer’s registered domain; the seller fetches https://{domain}/.well-known/brand.json.
2. Pre-provisioned buyer identity: an API key or OAuth client identifier issued by the seller at onboarding, mapped to the buyer’s domain in the seller’s records.
3. Signed requests per #2307 (3.1 normative): RFC 9421 HTTP Signatures with keyid resolving to a buyer-declared public key in the buyer’s adagents-style agent registry.

​

Key discovery (JWKS)

1. Establish the buyer domain via the rules in Buyer identity resolution.
2. Fetch the buyer’s brand.json. Locate the agents[] entry whose type is governance and whose url byte-for-byte equals the token’s iss. Reject if no matching entry exists.
3. Use the entry’s jwks_uri if declared. If absent, default to {origin of iss}/.well-known/jwks.json where origin = scheme+host+port per RFC 6454. Multi-tenant governance agents serving multiple buyers from a shared origin MUST declare explicit per-tenant jwks_uri so tenant key material is not pooled across the origin.
4. Fetch the JWKS over HTTPS.
5. Locate the key in the JWKS whose kid matches the token header. On cache miss for a kid, refetch the JWKS once (respecting a minimum 30-second cooldown to prevent unbounded refetches) before rejecting.

​

Seller verification checklist

1. Parse the compact JWS. Reject if malformed.
2. Reject if header alg is none or not in the allowed list (EdDSA, ES256). Library defaults MUST NOT be relied upon.
3. Reject if header typ is not exactly adcp-gov+jws (no normalization).
4. Reject if the header contains a crit array and any listed name is not recognized by the verifier.
5. Resolve iss to a JWKS via the discovery rules above. Reject if the JWKS cannot be fetched (after SSRF validation) or the kid is not present after one refetch.
6. Verify the JWKS entry’s use is "sig" and key_ops includes "verify". Reject keys marked for other uses.
7. Cryptographically verify the signature.
8. Reject if aud does not byte-for-byte equal the seller’s own canonical URL as declared in the relevant adagents.json entry.
9. Reject if exp is in the past or iat is more than 60 seconds in the future (±60 s clock-skew tolerance, symmetric on both bounds). If nbf is present, reject if now < nbf − 60 s.
10. Reject if sub does not equal the plan_id in the governance call this token is attached to (prevents plan swap).
11. Reject if phase does not match the operation: purchase for create_media_buy; modification for update_media_buy; delivery for delivery-reporting callbacks; intent only for pre-seller buyer-side evaluation.
12. For non-intent tokens, reject if media_buy_id does not equal the media buy ID in the request.
13. Cross-check: the token’s iss MUST appear as a governance-typed agent in the buyer’s current brand.json (established via Buyer identity resolution). Sellers SHOULD cache brand.json with reasonable TTLs (recommend 1 hour) and refresh on verification failure.
14. Check the revocation list (see Revocation). Reject if jti ∈ revoked_jtis or if the token header’s kid ∈ revoked_kids. This check runs on every verification, not only on cache miss.
15. Reject if jti has been seen before for this (iss, aud) tuple. See Replay dedup for storage guidance.

​

Replay dedup

• Cap execution-token exp at 30 days (enforced by governance agents; sellers reject anything longer). This bounds the dedup window.
• Use a bloom filter keyed on (iss, aud, jti) with a small false-positive rate (~1 in 10⁶) as the fast-path check, with authoritative lookup in a bounded store (Redis SET jti NX EX <remaining_ttl>, Postgres unique index with TTL cleanup) only on bloom-filter hits.
• Governance agents SHOULD issue jti values in a time-orderable format (UUID v7 or ULID) so sellers can partition the dedup store by time window and drop expired partitions cheaply.

​

Revocation

{
  "payload": "<base64url of the JSON below>",
  "signatures": [
    { "protected": "<b64url header with kid, alg, typ=adcp-gov-revocation+jws>",
      "signature": "<b64url signature>" }
  ]
}

{
  "version": 1,
  "issuer": "https://gov.example.com",
  "updated": "2026-04-18T14:00:00Z",
  "next_update": "2026-04-18T14:15:00Z",
  "revoked_jtis": ["01HWZX..."],
  "revoked_kids": ["gov-2026-03"]
}

• revoked_jtis invalidates individual decisions (e.g., a plan was rescinded). Revocation applies to any token with that jti, regardless of signing key.
• revoked_kids invalidates every token ever signed under that kid (before or after the revocation timestamp), not just tokens issued after.
• issuer MUST match the iss origin of tokens this list governs. Prevents cache substitution across issuers by a shared CDN.
• The list is signed so a compromised CDN or DNS origin cannot serve a stale or tampered list to un-revoke a compromised key.

• Sellers MUST poll the list on the cadence declared in next_update.
• Floor: 1 minute. Ceiling: 15 minutes for any seller accepting execution-phase tokens. Governance agents MUST NOT declare next_update more than 15 minutes in the future for issuers covered by execution-phase traffic. The next_update value is a JSON timestamp, not an HTTP cache header — standard HTTP caches will not respect it; sellers MUST parse and honor it themselves.
• Polling is optional for intent-phase tokens with ≤15 min exp.
• Use HTTP conditional requests (If-Modified-Since / ETag) to avoid unnecessary body transfers.

• Governance agents MUST retain revoked public keys as discoverable for the audit retention period (recommend 7 years) so auditors can verify historical tokens after the current rotation. Revoked keys SHOULD be served at {origin}/.well-known/jwks-archive.json (separate from the active JWKS).

​

Key rotation

• Governance agents rotate by adding a new key to JWKS with a new kid, signing fresh tokens with the new kid, and leaving the old key published until the longest-lived outstanding token expires.
• Seller JWKS caches MUST invalidate and refetch on a missing-kid failure before rejecting (with a 30-second cooldown to prevent unbounded refetches).
• Emergency rotation (key compromise) proceeds by adding the old kid to the signed revoked_kids list and rotating to a new key immediately. Short exp on intent tokens, capped exp on execution tokens, and revocation-list polling together bound the fraud window.

​

Verification error taxonomy

​

Privacy considerations

​

Reference implementation

{
  "alg": "EdDSA",
  "kid": "gov-2026-04",
  "typ": "adcp-gov+jws"
}

{
  "iss": "https://gov.scope3.com",
  "sub": "plan_q1_2026_launch",
  "plan_hash": "EiCW8FkxgZ2wKqGv3Z9XuT4n2LwcJm1fK7vRaTpQ0sU",
  "aud": "https://seller.example.com/adcp",
  "iat": 1744934400,
  "exp": 1744935300,
  "jti": "01HWZXABCDEFG1234567890",
  "phase": "intent",
  "caller": "https://orchestrator.example.com",
  "check_id": "chk_001",
  "policy_decision_hash": "9b2a...f41c",
  "audit_log_pointer": "https://gov.scope3.com/plans/plan_q1_2026_launch/logs/01HWZXABCDEFG1234567890"
}

import { createRemoteJWKSet, decodeProtectedHeader, decodeJwt, jwtVerify } from "jose";

class GovTokenError extends Error {
  constructor(public code: string) { super(code); }
}

const jwksCache = new Map<string, ReturnType<typeof createRemoteJWKSet>>();
function jwksFor(jwksUri: string) {
  let jwks = jwksCache.get(jwksUri);
  if (!jwks) {
    // ssrfValidatedFetch enforces the Webhook URL validation rules on the JWKS URL
    jwks = createRemoteJWKSet(new URL(jwksUri), { cacheMaxAge: 15 * 60 * 1000, cooldownDuration: 30 * 1000, [Symbol.for("fetch")]: ssrfValidatedFetch });
    jwksCache.set(jwksUri, jwks);
  }
  return jwks;
}

export async function verifyGovernanceContext(token: string, ctx: {
  sellerId: string; planId: string; mediaBuyId?: string; phase: "intent" | "purchase" | "modification" | "delivery";
  resolveBrandJsonGovernanceAgent: (iss: string) => Promise<{ jwks_uri: string } | null>;
  seenJti: (iss: string, aud: string, jti: string) => Promise<boolean>;
  isRevoked: (iss: string, jti: string, kid: string) => Promise<boolean>;
  revocationFresh: (iss: string) => Promise<boolean>;
}) {
  const header = decodeProtectedHeader(token);
  if (header.typ !== "adcp-gov+jws") throw new GovTokenError("governance_token_invalid");
  if (!["EdDSA", "ES256"].includes(header.alg ?? "")) throw new GovTokenError("governance_token_invalid");
  const { iss } = decodeJwt(token);
  const agent = await ctx.resolveBrandJsonGovernanceAgent(iss as string);
  if (!agent) throw new GovTokenError("governance_issuer_not_authorized");

  const { payload } = await jwtVerify(token, jwksFor(agent.jwks_uri), {
    issuer: iss as string, audience: ctx.sellerId, typ: "adcp-gov+jws",
    algorithms: ["EdDSA", "ES256"], clockTolerance: 60,
  }).catch(() => { throw new GovTokenError("governance_token_invalid"); });

  if (payload.sub !== ctx.planId) throw new GovTokenError("governance_token_not_applicable");
  if (payload.phase !== ctx.phase) throw new GovTokenError("governance_token_not_applicable");
  if (ctx.phase !== "intent" && payload.media_buy_id !== ctx.mediaBuyId)
    throw new GovTokenError("governance_token_not_applicable");
  if (!(await ctx.revocationFresh(iss as string))) throw new GovTokenError("governance_revocation_stale");
  if (await ctx.isRevoked(iss as string, payload.jti as string, header.kid as string))
    throw new GovTokenError("governance_token_revoked");
  if (await ctx.seenJti(iss as string, ctx.sellerId, payload.jti as string))
    throw new GovTokenError("governance_token_replayed");
  return payload;
}

const JWS_COMPACT = /^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/;

function handleGovernanceContext(value: string, ctx) {
  persistOpaque(value); // always persist and forward for auditor use
  if (!JWS_COMPACT.test(value)) return; // pre-3.0 opaque value, nothing to verify
  return verifyGovernanceContext(value, ctx); // throws on any failure
}

​

Migration (3.0 → 3.1)

• 3.0: governance agents MUST emit compact JWS per this profile, including the required plan_hash audit-layer claim (see Plan binding and audit for semantics). Sellers MAY verify the 15-step checklist; sellers that do not verify MUST persist and forward the token unchanged. Values that are not JWS are deprecated and SHOULD only appear from pre-3.0 governance agents during the transition; governance agents that emit non-JWS values in 3.0 MUST declare this in their capabilities so sellers can detect unverifiable deployments.
• 3.1: all sellers MUST verify per the 15-step checklist. Governance agents MUST emit JWS. Non-JWS values will be rejected end-to-end. plan_hash remains audit-layer (governance-agent / auditor / buyer-compliance verification only — not seller verification).

​

Signed Requests (Transport Layer)

• Agents sign requests with a key published at their own jwks_uri in their operator’s brand.json agents[] entry. The operator (the domain hosting brand.json) may be a house buying direct or an authorized third party — this profile does not distinguish. The signer is always an agent.
• Sellers verify the signature against the signing agent’s published key, establishing agent identity. Sellers then perform the separate brand-operator authorization check (outside this profile’s scope).
• Sellers calling agent-side AdCP endpoints (e.g., buyer-hosted mutation callbacks that are themselves AdCP protocol calls) sign their outgoing requests symmetrically; the receiving agent verifies against the seller’s keys published under the seller’s adagents.json agent entries. Push-notification webhook callbacks (push_notification_config.url and similar asynchronous one-way notifications) are covered by the symmetric Webhook callbacks variant of this profile — the seller signs outbound with an adcp_use: "webhook-signing" key and the buyer verifies.

• Shares JWKS discovery, SSRF rules, alg allowlist, revocation semantics, and key rotation with the AdCP JWS profile above. Cross-purpose key reuse is forbidden: a request-signing JWK MUST declare "adcp_use": "request-signing", "use": "sig", "key_ops": ["verify"], and a kid that does not appear on any other JWKS entry with a different adcp_use. Verifiers enforce all four; see Agent key publication.
• Resolves the identity-bootstrapping dependency in Buyer identity resolution for governance: a seller that verifies a request signature has a cryptographically established signing agent identity and MAY use the signing agent’s operator domain as the brand.json resolution input for the governance verification step.

​

Transport scope

​

Quickstart: opt into request signing in 3.0

0. Call get_adcp_capabilities on the target seller. Read request_signing.supported_for and required_for to see which AdCP operations the seller expects you to sign, and read request_signing.protocol_methods_supported_for / protocol_methods_required_for to see which JSON-RPC protocol methods (e.g., tasks/cancel) the seller’s verifier covers. Read covers_content_digest ("required" / "forbidden" / "either") to see whether you must, must not, or may cover content-digest.
1. Generate an Ed25519 keypair: openssl genpkey -algorithm ed25519 -out signing-key.pem.
2. Export the public key as a JWK. Add "kid", "use": "sig", "key_ops": ["verify"], "adcp_use": "request-signing", and "alg": "EdDSA".
3. Publish the JWK at your agent’s jwks_uri (the URL declared on your agents[] entry in brand.json; defaults to /.well-known/jwks.json at your agent URL’s origin).
4. Configure your AdCP client with the private key and agent URL. Your SDK signs requests automatically for any operation listed in the seller’s supported_for or required_for capability and any JSON-RPC method listed in protocol_methods_supported_for or protocol_methods_required_for, honoring the seller’s covers_content_digest policy. SDKs SHOULD support pluggable signers so the private key can live in a managed key store (KMS / HSM / Vault) rather than in process memory — see Production key storage below.
5. Validate end-to-end with the conformance vectors at /compliance/latest/test-vectors/request-signing/ (published per AdCP version; source lives at static/compliance/source/test-vectors/request-signing/) — if your client produces signatures that match the positive vectors’ expected_signature_base, you’re done.

1. Advertise request_signing.supported: true in get_adcp_capabilities. Leave required_for: [] during the pilot; add operations incrementally per counterparty.
2. Enable signature verification middleware on mutating routes. Implement the verifier checklist — all 14 checks (13 numbered steps plus sub-step 9a), short-circuit on first failure.
3. Start in shadow mode (verify and log; do not reject on failure) for a pilot counterparty before populating required_for. Surface verification failures in monitoring rather than operations for the first few weeks.
4. Run the conformance negative vectors against your verifier — each rejection MUST produce the vector’s stated error_code. The vector’s failed_step is informational; an implementation that rejects with the correct error code is conformant even if its internal step numbering differs.

​

Production key storage

• ECDSA-P256 signatures returned by most KMS APIs are DER-encoded; this profile and RFC 9421 §3.3.1 require IEEE P1363 (r‖s, 64 bytes for P-256). Convert at the adapter boundary.
• Treat the KMS key as single-purpose. The tag parameter in this profile protects verifiers, not signers — an operator who reuses the same KMS key for AdCP request-signing and any other signing protocol creates a cross-protocol oracle. Bind the KMS access policy (GCP roles/cloudkms.signer scoped to the specific cryptoKey, AWS kms:Sign conditioned on the key ARN) so only the AdCP signing path can invoke the key.

{
  "keys": [
    {
      "kty": "OKP", "crv": "Ed25519",
      "x": "SRYr8eSvjkZF6dAUquI1sKuU4YGZkoGH-2jwkz4dRJg",
      "kid": "acme-signing-2026-04",
      "alg": "EdDSA", "use": "sig",
      "adcp_use": "request-signing",
      "key_ops": ["verify"]
    },
    {
      "kty": "OKP", "crv": "Ed25519",
      "x": "lHJI-IvBwCE36heDNOyBmCk5UMKRIs4b4BAWJRgao-M",
      "kid": "acme-webhook-2026-04",
      "alg": "EdDSA", "use": "sig",
      "adcp_use": "webhook-signing",
      "key_ops": ["verify"]
    }
  ]
}

​

AdCP RFC 9421 profile

1. Signers MUST emit base64url-no-padding only. A signer that emits a Signature or Content-Digest value containing +, /, or = is non-conformant.
2. Verifiers MUST accept base64url-no-padding. Verifiers SHOULD ALSO lenient-decode pure standard-base64 tokens (translate +→- then /→_, then strip any trailing =, then base64url-decode) for interop with counterparties that predate this clarification. This lenience is a compatibility affordance scheduled for removal in AdCP 3.2 — signers relying on it MUST migrate to base64url-no-padding before then.
3. Verifiers MUST reject any token that mixes alphabets (any character in [+/=] AND any character in [-_] within the same token value) with request_signature_header_malformed. Mixed-alphabet tokens are ambiguous: A+B- could decode to different bytes depending on the order of “translate standard-base64 chars” and “base64url-decode” steps, and differing Content-Digest bytes across verifiers let an attacker stage a digest mismatch that one verifier accepts and another rejects.
4. The expected_signature_base field in the conformance vectors is independent of binary-value encoding — it contains the canonical signature base bytes, not any header-field encoding. Only the emitted Signature token itself is encoded.

​

Agent key publication

• governance-keys.{org}.example/.well-known/jwks.json — governance-signing JWKs only
• keys.{org}.example/.well-known/jwks.json — request-signing, webhook-signing, TMP keys

1. The verifier resolves the signing agent’s URL to its brand.json agents[] entry. Discovery MAY come from prior onboarding, MAY come from a registry cache, but the canonical on-wire bootstrap is the identity.brand_json_url field on the agent’s get_adcp_capabilities response — see Discovering an agent’s signing keys via brand_json_url.
2. Fetch the agent’s jwks_uri (or default to /.well-known/jwks.json at the origin of the agent’s url) with SSRF validation per Webhook URL validation. JWKS cache TTL bounded above by the revocation-list polling interval.
3. If the kid is absent from the cached JWKS, refetch the JWKS immediately (step 2’s first fetch may have been cached). If a refetch was already performed in the last 30 seconds for the same jwks_uri, the cooldown applies: the verifier MUST NOT refetch again and MUST reject with request_signature_key_unknown. The cooldown is between refetches, not before the first.

​

Discovering an agent’s signing keys via brand_json_url

1. Fetch A’s get_adcp_capabilities response with SSRF validation per Webhook URL validation (HTTPS only — the URL A is supplied by the caller and MUST go through the same address-family + private-IP filtering used for webhook callbacks). On unreachable/timeout, reject with request_signature_capabilities_unreachable.
2. Read identity.brand_json_url. If absent and the request is signed, reject with request_signature_brand_json_url_missing. Reject with the same code if the value is non-HTTPS (the schema enforces ^https:// but verifiers MUST restate the check; a 3.x parser tolerating a malformed value MUST NOT proceed). The required-when rule is: identity.brand_json_url MUST be present when the agent declares request_signing.supported_for/required_for non-empty, webhook_signing.supported === true, or any field under identity.key_origins. This is storyboard-enforced in 3.x. In 4.0 the rule becomes schema-required when the response declares supported_versions containing any 4.x release; cross-version verifiers (4.0 talking to a 3.x agent that does not advertise 4.x support) MUST continue to accept absent identity.brand_json_url.
3. Origin binding. The agent URL A’s host eTLD+1 MUST equal the brand_json_url’s host eTLD+1. eTLD+1 computation MUST use a pinned, dated Public Suffix List snapshot (ICANN+PRIVATE sections both in scope so platforms like vercel.app, pages.dev, github.io are treated as suffixes); two verifiers running different PSL versions are non-conformant against each other. If eTLD+1 mismatches, fetch brand.json and check that authorized_operators[] lists A’s eTLD+1. If neither holds, reject with request_signature_brand_origin_mismatch. This closes the shared-tenancy spoofing vector where an attacker stands up an agent on attacker.example/mcp and points its brand_json_url at an unrelated operator’s brand.json that happens to legitimately list attacker.example/mcp (e.g., a SaaS multi-tenant deployment).
4. Fetch brand.json at brand_json_url with SSRF validation per Webhook URL validation. Verifiers MUST NOT follow redirects on this fetch (the single-redirect carve-out for authoritative_location documented elsewhere in this profile is scoped to that field and MUST NOT be inherited by the brand.json bootstrap). Recommended budgets: connect 5 s, total deadline 10 s, body cap 256 KiB. Cache TTL on a successful fetch MUST be bounded above by the JWKS revocation polling interval (so a key rotation cannot be masked by a stale brand.json). Negative responses (404, network failure) MUST NOT be cached for more than 60 s — operators fixing a misconfiguration must not be locked out for a full revocation cycle.
5. Find the entry in agents[] whose url byte-equals A (no canonicalization at this step — same rule as the iss-to-brand.json match for governance JWS, see Buyer identity resolution; the most common failure mode is a trailing-slash or scheme mismatch, e.g. https://x.com/mcp ≠ https://x.com/mcp/). If none matches, reject with request_signature_agent_not_in_brand_json. If multiple match (operator misconfig — the brand.json schema does not currently constrain agents[] to be unique-by-URL), reject with request_signature_brand_json_ambiguous.
6. Resolve the JWKS source by purpose AND role (sender-vs-receiver position, not just signing purpose):
   • Sell-side webhook-signing only — i.e., the seller signing an outbound webhook to the buyer about media-buy delivery: the publisher’s adagents.json signing_keys pin (when present) is authoritative per the publisher-pin precedence rule above and overrides everything below. The pin is scoped to (agent, webhook-signing purpose, sell-side role) — it does NOT override operator-side webhook-signing (e.g., a buyer-hosted webhook receiving operator status callbacks).
   • All other (purpose, role) tuples — request-signing (any direction), operator-side webhook-signing, governance-signing, TMP-signing: use the matched agents[] entry’s jwks_uri, defaulting to /.well-known/jwks.json at the origin of A when absent.
7. identity.key_origins consistency check (mandatory when signing). For every purpose declared under identity.key_origins on the capabilities response whose JWKS source in step 6 was the operator brand.json (i.e., not a publisher adagents.json signing_keys pin), the host of the resolved jwks_uri MUST equal the declared origin for that purpose. Mismatch on any purpose → reject with request_signature_key_origin_mismatch carrying { purpose, expected_origin, actual_origin }. Skip the check only for the specific (agent, purpose, role) tuple whose source was a publisher pin — operator-side use of the same purpose is still checked. If the agent declares signing without a corresponding identity.key_origins.{purpose} entry, reject with request_signature_key_origin_missing carrying { purpose, posture }.
8. Fetch JWKS, find the kid, verify per the existing RFC 9421 profile (steps 7+ of the verifier checklist).

Quickstart: implement a brand_json_url-based verifier

1. Fetch capabilities for the signing agent’s URL A. This is a protocol-level call — invoke get_adcp_capabilities via the agent’s declared transport (MCP tools/call or A2A skill invocation), not a raw HTTP GET against A. The agent URL is the protocol endpoint, not a JSON capabilities document. Use SSRF-safe transport per Webhook URL validation: HTTPS only, address-family + private-IP filtering, no redirects, with budgets { connect: 5000, total: 10000, body: MAX_CAPABILITIES_BYTES, maxRedirects: 0 }.
2. Read identity.brand_json_url. Reject request_signature_brand_json_url_missing if absent (and the request is signed) or non-HTTPS.
3. eTLD+1 origin binding. Compute eTLD+1(A) and eTLD+1(brand_json_url) using a pinned PSL snapshot. Use tldts (TS), publicsuffixlist (Python), or golang.org/x/net/publicsuffix (Go) with a vendored, dated snapshot. Do NOT fetch the PSL at runtime — a runtime fetch creates a denial-of-service oracle and a non-deterministic eTLD+1 across deployments. If they match, proceed. Otherwise fetch brand.json and check authorized_operators[] — if eTLD+1(A) is delegated, proceed. Else reject request_signature_brand_origin_mismatch. Origin comparisons throughout this algorithm MUST canonicalize both sides: ASCII-lowercase the host, then convert to IDNA-2008 A-label form (Punycode) before byte-equality. A non-canonical comparison (e.g., raw Example.COM vs example.com, or U-label vs A-label) silently rejects legitimate traffic.
4. Fetch brand.json with the same SSRF rules + no redirects, body cap MAX_BRAND_JSON_BYTES, connect 5 s, total 10 s. Parse with a strict JSON parser that rejects duplicate keys (e.g., secure-json-parse in TS, the stdlib json.JSONDecoder in Python with an object_pairs_hook that raises on duplicates, encoding/json Decoder.DisallowUnknownFields paired with a duplicate-key check in Go) — duplicate keys are the parser-differential vector that step 14 closes on the request surface, and the same trust-root document MUST NOT parse to two different shapes across verifiers. On duplicate-key detection, reject request_signature_brand_json_malformed. Cache successful responses up to (but no longer than) the JWKS revocation polling interval; cache failures for at most 60 s.
5. Find the agents[] entry whose url byte-equals A (no canonicalization). Reject request_signature_agent_not_in_brand_json on miss; request_signature_brand_json_ambiguous on multiple matches.
6. Resolve jwks_uri from the matched entry — for sell-side webhook-signing only, prefer the publisher’s adagents.json signing_keys pin (when present) over the operator’s jwks_uri. For all other (purpose, role) tuples, use the matched entry’s jwks_uri (default: /.well-known/jwks.json at the origin of A).
7. Consistency check. For every purpose declared under capabilities identity.key_origins, apply canonicalizeOrigin() (ASCII-lowercase + IDNA-2008 A-label) to both the resolved jwks_uri host and the declared origin, then byte-compare (skip only the specific (agent, purpose, role) tuple sourced from a publisher pin). Reject request_signature_key_origin_mismatch / _missing as appropriate.
8. Hand off to step 8+ of the verifier checklist — fetch the JWKS (with the same byte budget MAX_JWKS_BYTES and 5/10 s connect/total deadlines), find the kid (already resolved here in step 7’s preamble — the verifier checklist’s step 7 is the discovery preamble itself), verify per RFC 9421.

const MAX_CAPABILITIES_BYTES = 65_536;
const MAX_BRAND_JSON_BYTES   = 262_144;
const MAX_JWKS_BYTES         = 65_536;
const FETCH_BUDGETS          = { connect: 5_000, total: 10_000, maxRedirects: 0 };

function canonicalizeOrigin(hostOrUrl: string): string {
  const host = hostOrUrl.includes('://') ? new URL(hostOrUrl).hostname : hostOrUrl;
  return toAsciiIdna2008(host.toLowerCase());                                 // A-label form
}

async function resolveAgent(agentUrl: string): Promise<AgentResolution> {
  const caps = await getAdcpCapabilities(agentUrl, {                          // step 1: protocol-level call
    ...FETCH_BUDGETS, body: MAX_CAPABILITIES_BYTES, ssrf: true,
  });
  const brandJsonUrl = caps.identity?.brand_json_url;
  if (!brandJsonUrl?.startsWith('https://')) throw new Err('brand_json_url_missing');  // step 2
  const agentEtld1 = etldPlusOne(new URL(agentUrl).hostname, PINNED_PSL_SNAPSHOT);     // step 3
  const brandEtld1 = etldPlusOne(new URL(brandJsonUrl).hostname, PINNED_PSL_SNAPSHOT);
  const brandJson = await safeFetch(brandJsonUrl, {                            // step 4
    ...FETCH_BUDGETS, body: MAX_BRAND_JSON_BYTES, ssrf: true, parse: 'strict-json',
  });
  if (agentEtld1 !== brandEtld1
      && !brandJson.authorized_operators?.some(o => o.domain === agentEtld1)) {
    throw new Err('brand_origin_mismatch');
  }
  const entries = brandJson.agents.filter(e => e.url === agentUrl);            // step 5 (byte-equal)
  if (entries.length === 0) throw new Err('agent_not_in_brand_json');
  if (entries.length > 1) throw new Err('brand_json_ambiguous');
  const entry = entries[0];
  const jwksUri = entry.jwks_uri ?? `${origin(agentUrl)}/.well-known/jwks.json`;  // step 6
  for (const [purpose, declared] of Object.entries(caps.identity?.key_origins ?? {})) { // step 7
    if (canonicalizeOrigin(jwksUri) !== canonicalizeOrigin(declared)) {
      throw new Err('key_origin_mismatch', { purpose });
    }
  }
  const jwks = await safeFetch(jwksUri, {                                      // step 8 setup
    ...FETCH_BUDGETS, body: MAX_JWKS_BYTES, ssrf: true, parse: 'strict-json',
  });
  return { agentUrl, brandJsonUrl, agentEntry: entry, jwksUri, jwks, /* trace, freshness */ };
}

Reference implementations

• TypeScript (@adcp/sdk): resolveAgent(url) returns { agentUrl, brandJsonUrl, agentEntry, jwksUri, jwks, identityPosture, consistency, freshness, trace }. getAgentJwks(url) is the JWKS-only fast path. createAgentJwksSet(url, opts) returns a JWTVerifyGetKey for handing to jose’s jwtVerify.
• Python (adcp): resolve_agent(url) returns an AgentResolution dataclass with fields agent_url, brand_json_url, agent_entry, jwks_uri, jwks, identity_posture, consistency, freshness, trace. verify_request_signature(request, *, agent_url, allowed_algs) is the one-shot helper that runs the discovery chain and the verifier checklist in one call.
• Go (adcp-go): ResolveAgent(ctx, agentURL) (*AgentResolution, error) returns a struct with fields AgentURL, BrandJSONURL, AgentEntry, JWKSUri, JWKS, IdentityPosture, Consistency, Freshness, Trace. VerifyRequestSignature(ctx, req, opts) (*VerifiedIdentity, error) mirrors the TS/Python one-shot.

​

Agent identity

​

Verifier checklist (requests)

• If the operation is in the verifier’s required_for capability, AND no Signature-Input header is present, AND the caller presents no other credential the verifier accepts for this operation (bearer, API key, or mTLS), THEN reject with request_signature_required. Unsigned requests that fall into this branch never enter the checklist. See Composition with fallback authenticators for the rule governing unsigned-but-otherwise-authenticated callers.
• If either Signature or Signature-Input is present without the other, reject with request_signature_header_malformed. The two headers are a bound pair; one without the other is malformed, not “signed with a missing piece we can guess at.” This rule closes a downgrade vector where a proxy strips Signature-Input but leaves Signature.
• If a Signature-Input header is present but malformed, reject with request_signature_header_malformed. Verifiers MUST NOT fall back to bearer-only authentication when a malformed signature is present, even for operations not in required_for — a present-but-broken signature signals signer intent; silent fallback enables downgrade attacks.

1. Parse Signature-Input and Signature headers per RFC 9421 §4. Reject if malformed.
2. Reject if any of created, expires, nonce, keyid, alg, or tag is absent from the Signature-Input parameters (request_signature_params_incomplete).
3. Reject if tag is not exactly adcp/request-signing/v1 (request_signature_tag_invalid).
4. Reject if alg is not in the allowlist (ed25519, ecdsa-p256-sha256). Library defaults MUST NOT be relied upon (request_signature_alg_not_allowed).
5. Reject if expires ≤ created, created > now + 60 s, expires < now − 60 s, or expires − created > 300 s (request_signature_window_invalid).
6. Reject (request_signature_components_incomplete) if covered components do not include all of: @method, @target-uri, @authority. If a body is present, reject if content-type is not covered. If the verifier’s covers_content_digest capability is "required", reject if content-digest is not covered. If the verifier’s covers_content_digest capability is "forbidden" and content-digest IS covered, reject with request_signature_components_unexpected.
7. Resolve keyid to a JWK via Agent key publication. If the verifier has no cached agent → JWKS mapping for the signing agent, run Discovering an agent’s signing keys via brand_json_url before this step — its 8-step preamble (capabilities → identity.brand_json_url → brand.json → agents[] → jwks_uri) is a precondition for keyid resolution and short-circuits with the request_signature_brand_* and request_signature_key_origin_* codes from that section. On kid miss within an established mapping, refetch once (subject to the 30-second cooldown between refetches) before rejecting with request_signature_key_unknown. Reject if keyid cannot be resolved to a specific agents[] entry.
8. Verify the JWK’s use is "sig", key_ops includes "verify", and adcp_use equals "request-signing". Reject (request_signature_key_purpose_invalid) on any mismatch — including absent adcp_use, which MUST be treated as non-conforming.
9. Check the Transport revocation list. Reject if keyid ∈ revoked_kids (request_signature_key_revoked). Reject with request_signature_revocation_stale if the verifier has not refreshed the revocation list within grace. 9a. Per-keyid cap check. Check the per-keyid replay-cache cap. Reject with request_signature_rate_abuse if the cap has been reached for this keyid. Runs before cryptographic verify (step 10) — same rationale as step 9: a compromised or misconfigured signer exhausting its cap MUST NOT force amplified Ed25519/ECDSA work on the verifier. Runs after keyid resolution (step 7) so the cap-state oracle only responds for keys the verifier has already committed to recognizing — running 9a earlier would let an attacker probe verifier-internal rate-limit state across the full keyid space, including keyids not published in JWKS.
10. Compute the canonical signature base per RFC 9421 §2.5 using the covered components, after applying @target-uri canonicalization AND @authority derivation per the profile above. The @authority rule is load-bearing: verifiers MUST derive @authority from the HTTP/2+ :authority pseudo-header when present, otherwise from the as-received HTTP/1.1 Host header — NOT from reverse-proxy routing state, load-balancer metadata, or any Host value a forward proxy may have rewritten in transit. If both :authority and Host are present on the as-received request, they MUST be byte-equal after canonicalization (RFC 7540 §8.1.2.3 equivalence); divergence rejects with request_target_uri_malformed. The canonicalized @authority MUST byte-for-byte match the authority component of the canonical @target-uri; mismatch rejects with request_target_uri_malformed. That byte-match against the signed @target-uri — not the choice of source header — is the only safe gate, because Host itself can be rewritten in transit. Implementers building from this checklist alone — without cross-referencing the profile’s canonicalization section — MUST apply this rule; skipping it silently accepts a cross-vhost replay vector (an attacker intercepts a TLS-terminated request and replays it to a second vhost on the same verifier pool: same cert SAN, different Host). After canonicalization completes, verify the signature against the JWK (request_signature_invalid on failure).
11. If content-digest is covered, recompute the digest from the received body bytes and compare (request_signature_digest_mismatch on mismatch).
12. Check the nonce against the replay cache (see Transport replay dedup). Reject if (keyid, nonce) has been seen within the replay-cache TTL (request_signature_replayed).
13. Only after steps 1–9, 9a, and 10–12 have all passed, insert (keyid, nonce) into the replay cache with TTL = (expires − now) + 60 s (the +60 s matches the skew tolerance applied at step 5). This insert MUST happen before the body-well-formedness check at step 14 so that a captured frame carrying a valid signature over a malformed body cannot be replayed to burn crypto-verify CPU on each retry — the nonce is burned on first sighting of a cryptographically-valid frame, regardless of body shape.
14. Body well-formedness. Verifiers MUST reject bodies containing duplicate object keys (request_body_malformed). Per RFC 8259 §4, duplicate-key parse behavior is unpredictable — the signature is valid over the bytes on the wire, but two parsers can disagree on the parsed value, which is a parser-differential attack class (cf. CVE-2017-12635). This check closes the gap between the signature verifier’s view of the payload and the downstream consumer’s view. Request bodies carry state-change and spend-committing payloads (create_media_buy, update_media_buy_delivery, etc.) whose parser-differential blast radius is larger than webhooks’ status-flip blast radius, making this check at least as load-bearing here as on the webhook surface. request_body_malformed is distinct from request_signature_digest_mismatch: the signature IS valid; the body parses to ambiguous state. A verifier that crashes rather than returning a structured request_body_malformed error is conformant-but-suboptimal — senders receive no actionable error code. Idempotency_key coverage follows from this check: step 14 runs before schema validation and idempotency-cache lookup (see idempotency), so a request body whose idempotency_key is itself duplicated (different parsers seeing different keys) is rejected here and never reaches the cache. No separate idempotency-layer audit is required. 14a. Strict-parse requirement. The check MUST use a parser that exposes duplicate keys — a last-wins/first-wins default that silently discards them does not satisfy this requirement. The per-language strict-parse escape-hatch enumeration in step 14a of the webhook verifier checklist applies identically here. 14b. Logging discipline. Verifiers SHOULD NOT log full request body bytes on a request_body_malformed rejection; log keyid, nonce, byte length, and the specific duplicate key names only. The key-name sanitization rules (truncate at first non-printable to <sanitized:N>, truncate to last UTF-8 codepoint at or below 32 bytes, cap count at 4) from step 14b of the webhook verifier checklist apply identically here — the attacker-controlled-byte channel has the same shape on the request surface.

​

Composition with fallback authenticators

• An unauthenticated request to a required_for operation MUST be rejected with request_signature_required.
• An unsigned but otherwise authenticated request (valid bearer, API key, or mTLS identity; no Signature-Input) to a required_for operation MUST NOT be rejected for missing signature. The fallback credential is what the verifier advertised as sufficient for that caller, and required_for does not retroactively invalidate the verifier’s own authenticator configuration.
• A signed request enters the verifier checklist and is evaluated on its cryptographic merits, whether or not the operation is in required_for.
• A malformed signature blocks fallback regardless, per the malformed-signature rule in the checklist preamble. Broken signatures signal signer intent and MUST NOT downgrade silently to bearer.

​

Content-digest and proxy compatibility

​

Transport replay dedup

• TTL on each entry = (expires − now) + 60 s to match the symmetric clock-skew tolerance applied at window validation. Typical TTL ≤ 360 s (5 min + 60 s skew).
• In-memory LRU keyed on (keyid, nonce) with TTL eviction, sized to expected request rate × max signature validity.
• Above ~10K req/s per signer: Redis SETNX with EX = remaining_validity_seconds + 60.
• Distributed verifiers (multi-region): per-region replay cache is acceptable. The only attack this enables is a single replay within (expires − now + 60 s) across regions, bounded by ~6 min and only effective if the attacker controls intermediate routing.

​

Transport revocation

• revoked_kids invalidates every request ever signed under that kid (before or after the revocation timestamp).
• revoked_jtis is not used (request signatures don’t have a jti; nonce uniqueness is per-key).

​

Transport capability advertisement

{
  "request_signing": {
    "supported": true,
    "covers_content_digest": "either",
    "required_for": [],
    "warn_for": ["create_media_buy"],
    "supported_for": [
      "create_media_buy",
      "update_media_buy",
      "sync_creatives",
      "activate_signal"
    ]
  }
}

• supported: when true, the verifier validates signatures when present. When false or absent, signatures are ignored.
• covers_content_digest: one of "required", "forbidden", or "either" (default). "required": signers MUST cover content-digest; unsigned-body signatures are rejected. "forbidden": signers MUST NOT cover content-digest; body-bound signatures are rejected. "either": signer chooses; verifier accepts both.
• required_for: AdCP protocol operation names (not transport-specific) for which unsigned requests that present no other valid credential are rejected with request_signature_required. Empty in 3.0 by default. Signers MUST sign any listed operation. Composition with bearer, API key, or mTLS fallbacks is governed by Composition with fallback authenticators — in particular, unsigned requests that present a valid fallback credential are accepted, and sellers that intend signing to be unconditional MUST configure their fallback authenticators to reject other credential types for the operation.
• warn_for: operations for which the verifier verifies signatures when present, logs failures in monitoring, but does NOT reject. Used as a shadow-mode bridge from supported_for to required_for. Enables per-counterparty pilots where the seller watches real-traffic failure rates before enforcing. Precedence: required_for > warn_for > supported_for. Signers SHOULD sign operations in warn_for; verifiers MUST NOT reject unsigned or failed-verify requests to these operations.
• supported_for: operations for which signatures are verified when present but not required. Signers SHOULD sign these. Typically a superset of required_for and warn_for.

1. Announce signing readiness: add the operation to supported_for. Counterparties can begin signing but nothing changes if they don’t.
2. Promote to shadow mode: move the operation to warn_for. The verifier logs verification failures; traffic is unaffected. Operators monitor the failure rate and debug.
3. Enforce: when the failure rate drops below the operator’s threshold, move to required_for. Unsigned or invalid-signature requests to that operation are now rejected.

​

Transport error taxonomy

​

Webhook callbacks

{
  "webhook_signing": {
    "supported": true,
    "profile": "adcp/webhook-signing/v1",
    "algorithms": ["ed25519", "ecdsa-p256-sha256"],
    "legacy_hmac_fallback": false
  }
}

• supported: MUST be true when the seller advertises mutating-webhook emission elsewhere in its capability surface. Buyers reject onboarding when supported: false or the block is missing and the seller’s surface advertises webhook emission. Sellers that emit no webhooks SHOULD omit the entire block.
• profile: MUST be exactly adcp/webhook-signing/v1 for this profile version. Future profile versions bump the string.
• algorithms: subset of ["ed25519", "ecdsa-p256-sha256"] — the algorithm set this seller will sign with. Matches the webhook-signing verifier allowlist (see step 4 of the verifier checklist, reused for webhooks via the substitutions noted above). Buyers MUST reject onboarding with a user-actionable error if the advertised algorithms array contains any value outside this set; an out-of-set algorithm indicates a misconfigured or non-conforming seller and silent acceptance would defeat the allowlist.
• legacy_hmac_fallback: true iff the seller supports the legacy HMAC-SHA256 scheme when the buyer populates push_notification_config.authentication.credentials. false is the recommended posture in 3.x.

1. Seller agent URL A → fetch /.well-known/brand.json at the operator domain of A with SSRF validation per Webhook URL validation. brand.json resolution follows one redirect (authoritative_location or house redirect variant) and stops.
2. In the fetched brand.json, find the agents[] entry whose url byte-for-byte matches A.
3. Fetch that entry’s jwks_uri (or default to /.well-known/jwks.json at the origin of A) with SSRF validation. JWKS cache TTL bounded above by the revocation-list polling interval (floor 1 min, ceiling 15 min). Long-running task flows cross JWKS rotations; verifiers MUST NOT pin a single JWKS snapshot for the lifetime of a task.
4. Resolve keyid on the incoming Signature-Input to a JWK in the fetched set. On kid miss, refetch once (subject to the 30-second cooldown between refetches) before rejecting with webhook_signature_key_unknown. The refetch-on-miss path is the load-bearing mechanism for handling mid-task key rotation — clients that skip it will reject legitimate post-rotation deliveries.

• Sellers MUST log every request that arrives with a non-empty authentication block. Ops alarms on unexpected HMAC selection protect the buyer side when the buyer thought it was getting 9421.
• Sellers that support request signing MUST require the inbound request to be 9421-signed (per the request verifier checklist) when authentication is present on push_notification_config, rejecting with request_signature_required (the same code used for required_for operations — see Transport error taxonomy). When a signed request cryptographically commits to the body, the authentication block cannot be injected or stripped without also invalidating the signature. Sellers that do not support request signing at all have no way to enforce this rule and fall back to the log-and-alarm posture in the preceding bullet — 3.0 migration note, not an exemption: the request-signing migration timeline makes request signing required for spend-committing operations in 4.0, at which point no seller is unsigned-only.
• Buyers MUST reject with webhook_mode_mismatch and alarm, not silently downgrade, when they receive a 9421-signed webhook after registering with authentication.credentials, or when they receive HMAC-signed webhooks after registering without authentication. Rejection is the safety property; alarming is the telemetry — a buyer that alarms but accepts the payload has already handed authority to the mismatched signing scheme. The rejection surfaces as HTTP 401 with the stable error code so sender-side retry logic can route it to incident response rather than replaying identically.
• Buyers SHOULD negotiate HMAC-mode out-of-band at onboarding when interoperating with sellers that have not yet implemented 9421. Durable per-counterparty mode selection in operator records is not MITM-mutable the way a per-request field is.

1. Parse Signature-Input and Signature headers per RFC 9421 §4. Reject if malformed (webhook_signature_header_malformed). If Signature or Signature-Input is present without the other, reject with the same code — a bound pair, not a guessable one.
2. Reject if any of created, expires, nonce, keyid, alg, or tag is absent from the Signature-Input parameters (webhook_signature_params_incomplete).
3. Reject if tag is not exactly adcp/webhook-signing/v1 (webhook_signature_tag_invalid). Byte-for-byte match; no case-folding.
4. Reject if alg is not in the allowlist (ed25519, ecdsa-p256-sha256). Library defaults MUST NOT be relied upon (webhook_signature_alg_not_allowed).
5. Reject if expires ≤ created, created > now + 60 s, expires < now − 60 s, or expires − created > 300 s (webhook_signature_window_invalid).
6. Reject if covered components do not include ALL of: @method, @target-uri, @authority, content-type, content-digest (webhook_signature_components_incomplete). content-digest is REQUIRED; there is no policy branch.
7. Resolve keyid to a JWK via the JWKS discovery steps above. On kid miss, refetch once (30-second cooldown between refetches) before rejecting (webhook_signature_key_unknown). Reject if keyid cannot be resolved to a specific agents[] entry in the signer’s brand.json.
8. Verify the JWK’s use is "sig", key_ops includes "verify", and adcp_use equals "webhook-signing". Reject on any mismatch, including absent adcp_use (webhook_signature_key_purpose_invalid).
9. Check the Transport revocation list (reused across signing purposes). Reject if keyid ∈ revoked_kids (webhook_signature_key_revoked). Reject with webhook_signature_revocation_stale if the verifier has not refreshed within grace. 9a. Per-keyid cap check. Check the webhook replay-cache cap. Reject with webhook_signature_rate_abuse if exceeded. Runs before cryptographic verify (step 10) for the same cheap-rejection rationale as request signing.
10. Compute the canonical signature base per RFC 9421 §2.5 using the covered components, after applying @target-uri canonicalization AND @authority derivation per the request-signing profile. The @authority rule is load-bearing for webhook security: verifiers MUST derive @authority from the HTTP/2+ :authority pseudo-header when present, otherwise from the as-received HTTP/1.1 Host header — NOT from reverse-proxy routing state, load-balancer metadata, or any Host value a forward proxy may have rewritten in transit. If both :authority and Host are present on the as-received request, they MUST be byte-equal after canonicalization (RFC 7540 §8.1.2.3 equivalence); divergence rejects with webhook_target_uri_malformed. The canonicalized @authority MUST byte-for-byte match the authority component of the canonical @target-uri; mismatch rejects with webhook_target_uri_malformed. That byte-match against the signed @target-uri — not the choice of source header — is the only safe gate, because Host itself can be rewritten in transit. Implementers building from this checklist alone — without cross-referencing the profile — MUST apply this rule; skipping it silently accepts a cross-vhost replay vector (an attacker intercepts a TLS-terminated webhook and replays it to a second vhost on the same verifier pool: same cert SAN, different Host). After canonicalization completes, verify the signature against the JWK (webhook_signature_invalid on failure).
11. Recompute content-digest from the received body bytes and compare (webhook_signature_digest_mismatch on mismatch). REQUIRED — no policy branch.
12. Check the nonce against the replay cache. Reject if (keyid, nonce) has been seen within the replay-cache TTL (webhook_signature_replayed).
13. Only after steps 1–12 have all passed, insert (keyid, nonce) into the replay cache with TTL = (expires − now) + 60 s. This insert MUST happen before the body-well-formedness check at step 14 so that a captured frame carrying a valid signature over a malformed body cannot be replayed to burn crypto-verify CPU on each retry — the nonce is burned on first sighting of a cryptographically-valid frame, regardless of body shape. The load-bearing cap invariant this ordering preserves is documented after step 14b.
14. Body well-formedness. Verifiers MUST reject bodies containing duplicate object keys (webhook_body_malformed). Per RFC 8259 §4, duplicate-key parse behavior is unpredictable — the signature is valid over the bytes on the wire, but two parsers can disagree on the parsed value, which is a parser-differential attack class (cf. CVE-2017-12635). This check closes the gap between the signature verifier’s view of the payload and the downstream consumer’s view. A verifier that crashes rather than returning a structured webhook_body_malformed error is conformant-but-suboptimal — senders receive no actionable error code. The conformance fixture for this check is the duplicate-keys-conflicting-values vector in static/test-vectors/webhook-hmac-sha256.json — the 9421 profile MUST apply the same body-well-formedness rule after signature verification succeeds. webhook_body_malformed is distinct from webhook_signature_digest_mismatch: the signature IS valid; the body parses to ambiguous state. 14a. Strict-parse requirement. The check MUST use a parser that exposes duplicate keys — a last-wins/first-wins default that silently discards them does not satisfy this requirement. Query libraries that happily return a value on duplicate-key input without surfacing the collision also do not satisfy this requirement, regardless of marketing as “safe” or “strict” (cf. tidwall/gjson in Go — a query library, not a validator). Per-language strict-parse escape hatches, canonical non-exhaustive list:
    • Python: stdlib json.loads(..., object_pairs_hook=...) — detect duplicates inside the hook and raise. Satisfies the check.
    • Node: no strict mode in JSON.parse. Use a streaming parser (stream-json, jsonparse) with a duplicate-key event handler. secure-json-parse is NOT sufficient by default: its protections target prototype-pollution keys (__proto__, constructor), not data-key duplicates, which it still collapses last-wins. Configure it to reject data-key duplicates explicitly or layer a streaming parser underneath.
    • Go: encoding/json has no strict mode and does not detect duplicates. Use json.Decoder token-walk with an explicit map[string]struct{} unique-key guard per object scope, OR goccy/go-json with decoder.DisallowDuplicateKey() explicitly enabled (NOT the default). Do NOT use tidwall/gjson for this check — it is a query library that returns the last value on duplicate-key input without signaling the collision.
    • Java: Jackson DeserializationFeature.FAIL_ON_READING_DUP_TREE_KEY (disabled by default, enable explicitly).
    • Ruby: stdlib JSON.parse has no detection hook. Use Oj.load(..., mode: :strict) with the allow_nan: false / duplicate-rejection options explicitly configured.
    14b. Logging discipline. Verifiers SHOULD NOT log full request body bytes on a webhook_body_malformed rejection; log keyid, nonce, byte length, and the specific duplicate key names only. An attacker holding a compromised signer key can otherwise force attacker-chosen bytes into defender logs at scale, burning a replay-cache slot per frame but leaving an attacker-controlled log trail for SIEM poisoning or credential exfiltration follow-on attacks. When logging duplicate key names, verifiers MUST sanitize each name with the following rules applied in order:
    • (a) Truncate at the first non-printable codepoint and emit <sanitized:N> where N is the byte length of the truncation prefix. This elides position information (the placement of a non-printable within the key name would otherwise itself be an attacker channel, encodable as bit positions) while preserving the “something was wrong here” diagnostic signal. The non-printable set MUST include at minimum: C0 controls (U+0000–U+001F), DEL (U+007F), C1 controls (U+0080–U+009F, terminal control semantics in multi-byte form), bidi controls and isolates (U+200E, U+200F, U+202A–U+202E, U+2066–U+2069 — reverse rendering in terminals and SIEM UIs), line and paragraph separators (U+2028, U+2029 — render as line breaks in many log viewers, enabling row-injection), zero-width characters (U+200B–U+200D — invisible obfuscation), and the byte-order mark (U+FEFF — parser corruption). Implementations MAY extend the set to a broader Unicode non-printable classification but MUST NOT narrow it — an ASCII-only check misses bidi-override and line-separator attacks that reopen exactly the log-injection channel this rule exists to close.
    • (b) Truncate to at most 32 bytes at the last complete UTF-8 codepoint boundary. Realistic AdCP field names top at roughly 24 characters (signed_authorized_agents), so 32 is a generous cap while still bounding the attacker-controlled-byte surface. Truncation MUST occur at the last complete UTF-8 codepoint boundary at or below 32 bytes so multi-byte sequences are not split mid-codepoint and invalid-UTF-8 does not land in logs (different verifiers truncating the same input to different invalid-UTF-8 tails would also break log aggregation).
    • (c) Cap the number of duplicate key names logged per rejection at 4, emitting <...N more> if exceeded. Diagnostic value of knowing 4 vs 8 vs 16 colliding keys is near zero.
    Without these constraints, the key-name channel remains an attacker-controlled-byte side channel — smaller than full-body logging but non-zero, and well-precedented as a log-injection vector. Signers that log upstream-input rejections (see the duplicate-object-keys signer-side rule) MUST apply the same (a)/(b)/(c) sanitization rules to any key names surfaced in signer-side error output; the channel shape is identical even though the wire direction is inverted.

Webhook replay dedup sizing

• Per-keyid entry cap: recommended 100,000 entries (10× lower than the request-side 1,000,000 ceiling). A seller emitting 100K unique webhooks in a 6-minute window is 275/sec sustained from a single signer — plenty of headroom for normal operations and still a strong signal of misconfiguration or key compromise.
• Aggregate cache cap: recommended min(aggregate_memory_budget, 10,000,000) entries across all signers. On aggregate-cap exceeded, verifiers MUST reject new signatures with webhook_signature_rate_abuse and SHOULD alert operators — silent eviction creates replay windows precisely when the verifier is under attack.
• Per-seller budget: operators SHOULD budget per-seller by integration criticality rather than equal-weighting all sellers at 100K each. A spend-committing seller’s webhook fan-in differs from a discovery-only seller’s.
• New-keyid admission pressure (MUST track, SHOULD alert). Verifiers MUST track the rate of cache entries admitted from previously-unseen keyids per unit time (e.g., a 5-minute rolling count of distinct keyids inserting their first entry). A sudden spike in new-keyid admission rate is the signature of a distributed-compromise attack: an attacker holding N compromised signer keys can drive N entries per TTL window each, every key staying well within its per-keyid cap (step 9a), while collectively saturating the aggregate cache. Each key’s traffic individually looks like a low-volume legitimate signer; the aggregate shape is the signal. Verifiers SHOULD alert when new-keyid admission exceeds any of four thresholds (whichever triggers first), each closing a distinct attacker pattern:
  • (a) a short-window ratio threshold comparing the current admission rate against a short-horizon moving-average baseline — catches sudden spikes against a stable baseline.
  • (b) a medium-window ratio threshold against a medium-horizon percentile baseline — catches multi-week ramp-up attacks, whose traffic is dominated by the baseline tail at that horizon.
  • (c) a long-window ratio threshold against a long-horizon percentile baseline — catches multi-month ramp-up attacks that drift the medium-horizon anchor with them.
  • (d) a proportional ceiling combining an absolute floor with a fraction of the unique-keyid count over a documented window — catches sparse-traffic verifiers whose ratio baselines are near zero, AND auto-scales to operators of any size (small verifiers get a low proportional floor; enterprise verifiers get a proportionally larger one).
  The four categories are normative; the concrete threshold values are NOT. Operators MUST treat any published example values as starting points, baseline their own traffic, and tune accordingly — published normative threshold numbers would hand attackers an oracle into the detection posture. Concrete starting values, baselining methodology, and attack-scenario walkthroughs are published in the non-normative Webhook Verifier Tuning Guide. Implementations MAY ship the guide’s starting values as first-deployment defaults but MUST expose each threshold as a tunable configuration parameter (e.g., environment variable, config file) — hardcoded starting values become de facto operator-visible defaults and re-introduce the attacker oracle. Implementations SHOULD log or alarm a threshold_tuning_overdue event when any threshold remains at its shipped starting value more than 30 days past the verifier’s first admission; this gives the operator-tuning obligation a testable, auditable hook rather than relying on operator diligence alone. The alarm payload MUST name which clause (a, b, c, or d) tripped so operator triage can respond to the right threat shape. Alarming here catches the slow-burn distributed-compromise pattern before the aggregate cap triggers — once webhook_signature_rate_abuse fires on the aggregate cap, the cache is already full and every legitimate signer is being rejected. Alarms SHOULD route to incident response, not to automatic revocation: the distinguishing signal between “attack” and “onboarding a batch of new sellers” is operator context, not machine-derivable, and automatic revocation on alarm creates a denial-of-service vector (any party driving legitimate new-signer onboarding can trip the alarm and cause mass revocation).

1. Share a single logical replay cache across every endpoint a given signer can reach (Redis / shared dedup service — not per-process in-memory), so that a (keyid, nonce) inserted by endpoint A is visible to endpoint B before step 12 runs; or
2. Include the canonical destination URL in the replay key, scoping dedup to (keyid, canonical destination URL, nonce). The canonical form is the @target-uri after normalisation per the request-signing profile (scheme lowercased, host IDNA-normalised, default port elided, fragment stripped).

Webhook revocation and rotation

Webhook error taxonomy

Webhook migration timeline

​

TMP cross-reference

​

Transport migration timeline

​

Request verifier reference (TypeScript)

import { createRemoteJWKSet } from "jose";

class RequestSignatureError extends Error {
  constructor(public code: string) { super(code); }
}

const ALLOWED_ALGS = new Set(["ed25519", "ecdsa-p256-sha256"]);
const REQUIRED_TAG = "adcp/request-signing/v1";
const REQUIRED_COMPONENTS = new Set(["@method", "@target-uri", "@authority"]);
const REQUIRED_PARAMS = ["created", "expires", "nonce", "keyid", "alg", "tag"] as const;

export async function verifyAdcpRequestSignature(req: Request, ctx: {
  operationName: string;
  requiredFor: Set<string>;
  contentDigestPolicy: "required" | "forbidden" | "either";
  resolveJwk: (keyid: string) => Promise<{ jwk: unknown; agentUrl: string }>; // throws _key_unknown after refetch
  isKeyRevoked: (keyid: string) => Promise<boolean>;
  isRevocationStale: () => Promise<boolean>;
  isKeyidAtCapacity: (keyid: string) => Promise<boolean>;
  isReplayed: (keyid: string, nonce: string) => Promise<boolean>;
  recordNonce: (keyid: string, nonce: string, ttlSeconds: number) => Promise<void>;
  verify9421: (req: Request, jwk: unknown, covered: string[]) => Promise<void>; // throws on signature or digest failure
  parseSignatureInput: (header: string) => {
    keyid?: string; alg?: string; created?: number; expires?: number;
    nonce?: string; tag?: string; components: string[];
  };
}) {
  const sigInput = req.headers.get("signature-input");

  // Pre-check: required_for / downgrade protection.
  if (!sigInput) {
    if (ctx.requiredFor.has(ctx.operationName)) throw new RequestSignatureError("request_signature_required");
    return; // operation doesn't require a signature; verify nothing.
  }

  let parsed;
  try { parsed = ctx.parseSignatureInput(sigInput); }
  catch { throw new RequestSignatureError("request_signature_header_malformed"); }

  // 2: presence
  for (const p of REQUIRED_PARAMS) {
    if ((parsed as any)[p] == null) throw new RequestSignatureError("request_signature_params_incomplete");
  }
  // 3: tag
  if (parsed.tag !== REQUIRED_TAG) throw new RequestSignatureError("request_signature_tag_invalid");
  // 4: alg
  if (!ALLOWED_ALGS.has(parsed.alg!)) throw new RequestSignatureError("request_signature_alg_not_allowed");
  // 5: window (including expires > created)
  const now = Math.floor(Date.now() / 1000);
  if (parsed.expires! <= parsed.created! ||
      parsed.created! > now + 60 ||
      parsed.expires! < now - 60 ||
      parsed.expires! - parsed.created! > 300) {
    throw new RequestSignatureError("request_signature_window_invalid");
  }
  // 6: components
  for (const c of REQUIRED_COMPONENTS) {
    if (!parsed.components.includes(c)) throw new RequestSignatureError("request_signature_components_incomplete");
  }
  const coversCd = parsed.components.includes("content-digest");
  if (ctx.contentDigestPolicy === "required" && !coversCd) {
    throw new RequestSignatureError("request_signature_components_incomplete");
  }
  if (ctx.contentDigestPolicy === "forbidden" && coversCd) {
    throw new RequestSignatureError("request_signature_components_unexpected");
  }
  // 7: JWK resolution
  const { jwk } = await ctx.resolveJwk(parsed.keyid!); // throws _key_unknown
  // 8: key purpose
  const j = jwk as any;
  if (j.use !== "sig" || !Array.isArray(j.key_ops) || !j.key_ops.includes("verify") || j.adcp_use !== "request-signing") {
    throw new RequestSignatureError("request_signature_key_purpose_invalid");
  }
  // 9: revocation (BEFORE crypto verify)
  if (await ctx.isRevocationStale()) throw new RequestSignatureError("request_signature_revocation_stale");
  if (await ctx.isKeyRevoked(parsed.keyid!)) throw new RequestSignatureError("request_signature_key_revoked");
  // 9a: per-keyid cap (BEFORE crypto verify) — prevents amplified crypto work by abusive/misconfigured signer.
  if (await ctx.isKeyidAtCapacity(parsed.keyid!)) {
    throw new RequestSignatureError("request_signature_rate_abuse");
  }
  // 10 + 11: crypto verify, content-digest recompute — both inside verify9421.
  try { await ctx.verify9421(req, jwk, parsed.components); }
  catch (e: any) {
    if (e?.code === "digest_mismatch") throw new RequestSignatureError("request_signature_digest_mismatch");
    throw new RequestSignatureError("request_signature_invalid");
  }
  // 12: replay check
  if (await ctx.isReplayed(parsed.keyid!, parsed.nonce!)) {
    throw new RequestSignatureError("request_signature_replayed");
  }
  // 13: replay insert (only after all checks pass)
  await ctx.recordNonce(parsed.keyid!, parsed.nonce!, (parsed.expires! - now) + 60);
}

​

Budget Validation

async function validateBudget(request, account) {
  const { budget } = request;

  // Check positive amount
  if (budget.amount <= 0) {
    throw new ValidationError('Budget must be positive');
  }

  // Check against account limits
  const limits = await getAccountLimits(account.account_id);
  if (budget.amount > limits.daily_spend_limit) {
    throw new BudgetError('Exceeds daily spend limit');
  }

  // Check available balance
  const balance = await getAvailableBalance(account.account_id);
  if (budget.amount > balance) {
    throw new BudgetError('Insufficient balance');
  }
}

​

Transport Security

​

TLS version policy

• TLS 1.3 is RECOMMENDED for every AdCP endpoint.
• TLS 1.2 is the minimum. Endpoints MUST reject TLS 1.1 and below at the handshake.
• Client-side verifiers (e.g., an AdCP server fetching a counterparty’s JWKS, brand.json, or revocation list) MUST refuse to negotiate below TLS 1.2. Libraries that still default to TLS 1.0 for “compatibility” MUST be configured explicitly.
• SSL 2.0, SSL 3.0, TLS 1.0, and TLS 1.1 MUST NOT be enabled — not for any endpoint, not for any legacy partner, not even on a separate port.

​

Cipher suites and algorithms

• TLS 1.3: use the IETF-defined suites (TLS_AES_128_GCM_SHA256, TLS_AES_256_GCM_SHA384, TLS_CHACHA20_POLY1305_SHA256). All three are AEAD; no other TLS 1.3 suites exist. Do not disable any of them arbitrarily — operators who disable ChaCha20 on “speed” grounds are one client quirk away from broken mobile clients.
• TLS 1.2: restrict to AEAD-only ECDHE suites. The permitted set is ECDHE-ECDSA-AES128-GCM-SHA256, ECDHE-ECDSA-AES256-GCM-SHA384, ECDHE-ECDSA-CHACHA20-POLY1305, ECDHE-RSA-AES128-GCM-SHA256, ECDHE-RSA-AES256-GCM-SHA384, ECDHE-RSA-CHACHA20-POLY1305.
• CBC-MAC, RC4, 3DES, DES, NULL, EXPORT, anonymous DH, and static RSA key-exchange suites MUST be disabled on TLS 1.2 — their presence silently downgrades the security properties of everything built above the handshake.
• Server certificates MUST use ECDSA (P-256 or P-384) or RSA ≥ 2048 bits. RSA < 2048 MUST NOT be used.
• Endpoints MUST prefer server-side cipher ordering (OpenSSL SSL_OP_CIPHER_SERVER_PREFERENCE, nginx ssl_prefer_server_ciphers on) so a weak client cannot force a weak suite when a strong one is mutually available.

​

Certificate validation (outbound fetches)

• Trust chain MUST terminate at a public root the operator has intentionally included. No --insecure, no verify=False, no rejectUnauthorized: false anywhere in production code paths. This is the single most common production compromise — an engineer turns off verification to work around a cert issue in staging, the flag ships.
• SAN match is the authoritative identity check. The certificate MUST have a Subject Alternative Name entry matching the URL host. CN-only fallback MUST NOT be accepted; major HTTP clients still support it for legacy reasons, but AdCP verifiers MUST require SAN.
• Expiry MUST be checked against the current clock. Fetching a JWKS from a domain whose TLS cert expired last week is a governance red flag, not a compatibility problem.
• Hostname verification MUST be enabled in the library config. Several popular HTTP client libraries ship with hostname verification on by default; a surprising number have a flag that disables it. AdCP implementations MUST assert hostname verification is on, not assume it.
• OCSP stapling SHOULD be accepted when offered; OCSP must-staple on operator-controlled certificates is RECOMMENDED. Must-staple turns a missing staple into a hard failure, which closes the soft-fail-on-OCSP loophole.
• Certificate Transparency (CT) SCTs SHOULD be checked on endpoints serving regulated spend. Browsers already enforce CT; AdCP SDKs fetching governance JWKS on a regulated-category workflow SHOULD too, so a hidden mis-issued cert is detectable.
• Pinning is NOT required at the protocol layer and SHOULD be avoided for counterparty-supplied URLs (brand.json, JWKS) because it collides with legitimate operator cert rotation. Pinning to a public-CA chain (intermediate-pin) is acceptable; pinning to a specific leaf cert is discouraged.

​

Inbound server-side headers

app.use((req, res, next) => {
  // HSTS: 1 year, include subdomains, preload-eligible. MUST be on every HTTPS response.
  res.setHeader('Strict-Transport-Security', 'max-age=31536000; includeSubDomains; preload');

  // No framing of AdCP API responses — even though they're JSON, frame isolation
  // protects any error or debug HTML that could leak through.
  res.setHeader('X-Frame-Options', 'DENY');

  // MIME sniffing off: responses declare their type, clients MUST respect it.
  res.setHeader('X-Content-Type-Options', 'nosniff');

  // Prevent referrers leaking to external URLs supplied by counterparties.
  res.setHeader('Referrer-Policy', 'no-referrer');

  // AdCP endpoints serve no browser-facing HTML — block script-source loading outright.
  // If your operator reuses the same origin for a dashboard, adjust this per-path.
  res.setHeader('Content-Security-Policy', "default-src 'none'; frame-ancestors 'none'");

  next();
});

​

Client / outbound TLS hardening

• Use a connection pool with a fixed per-host cap and a fixed overall cap. Unbounded pools are a resource-exhaustion surface.
• Cap TLS handshake time at 10 s and total request time at 30 s by default — counterparty-supplied URLs are a tarpit DoS vector otherwise.
• Pin the connection to the IP address that passed the SSRF controls — DNS re-resolution between the SSRF check and the actual connect is how TOCTOU bypasses land.
• Refuse redirects on security-sensitive fetches. JWKS, brand.json, revocation list, and webhook-callback fetches MUST NOT follow redirects; the brand.json resolution rule already says “one redirect (authoritative_location or house variant), no chains” — everywhere else, zero.
• Disable session resumption across trust boundaries. Resuming a TLS session with an attacker-controlled counterparty onto a later verified counterparty (same IP via DNS rebind) is a well-known class of confusion; library defaults are usually fine, but the operator MUST audit.

​

TLS renegotiation and downgrade

• TLS 1.2 secure renegotiation (RFC 5746) MUST be enabled if renegotiation is supported at all. Insecure-renegotiation-tolerant stacks are a MUST-disable.
• TLS compression (CRIME) MUST be off.
• Heartbeat extension MUST be off on TLS 1.2 endpoints (Heartbleed lineage).
• 0-RTT / early-data on TLS 1.3 MUST NOT be enabled for any endpoint that accepts mutating AdCP operations. 0-RTT is replayable by design; idempotency and signature-nonce dedup are not free rescues once the request has hit application logic. Read-only discovery endpoints (get_adcp_capabilities, list_creative_formats) MAY use 0-RTT; everything else MUST NOT.

​

mTLS transport

• The client certificate SAN / Subject MUST match the buyer’s registered domain as declared in adagents.json or brand.json. Relying on any header field (X-Forwarded-Client-Cert, X-Client-DN, etc.) is explicitly forbidden — header fields can be injected across misconfigured proxies.
• The terminating edge (load balancer, mesh sidecar) MUST forward the verified certificate identity to the AdCP server over an in-cluster channel the server can authenticate. Unauthenticated sidecar headers are a bypass — deploy mTLS end-to-end, or pin the in-cluster channel.
• Client certificates MUST be checked against a CRL or OCSP responder operated by the operator. “Issued by us” is not the same as “still valid.”

​

Private-network and metadata protection

​

What this section does NOT replace

• Application-layer body integrity (request signing and webhook callbacks) — TLS protects the wire, not the payload after a compromised intermediary.
• Governance attestation (signed governance context) — TLS does not tell the seller whether the buyer’s governance agent authorized this spend.
• Idempotency (request safety) — TLS does not prevent the sender from retrying after a network timeout.

​

Input Validation

​

Request Validation

const INPUT_LIMITS = {
  targeting_brief_max_length: 5000,
  creative_upload_max_size: 100 * 1024 * 1024, // 100MB
  max_formats_per_request: 50,
  max_products_per_query: 100
};

function validateRequest(request) {
  // Check string lengths
  if (request.brief?.length > INPUT_LIMITS.targeting_brief_max_length) {
    throw new ValidationError('Brief exceeds maximum length');
  }

  // Validate IDs are proper UUIDs
  if (request.product_id && !isValidUUID(request.product_id)) {
    throw new ValidationError('Invalid product_id format');
  }

  // Reject unexpected fields
  const allowedFields = ['brief', 'product_id', 'budget', 'context_id'];
  for (const field of Object.keys(request)) {
    if (!allowedFields.includes(field)) {
      throw new ValidationError(`Unexpected field: ${field}`);
    }
  }
}

​

SQL Injection Prevention

// GOOD: Parameterized query (request-supplied account_id after auth precheck)
const result = await db.query(
  'SELECT * FROM media_buys WHERE id = $1 AND account_id = $2',
  [mediaBuyId, request.account.account_id]
);

// BAD: String concatenation (NEVER do this)
// const result = await db.query(
//   `SELECT * FROM media_buys WHERE id = '${mediaBuyId}'`
// );

​

Audit Logging

​

Required Log Events

const LOG_EVENTS = {
  AUTH_SUCCESS: 'auth_success',
  AUTH_FAILURE: 'auth_failure',
  BUDGET_COMMIT: 'budget_commit',
  BUDGET_MODIFY: 'budget_modify',
  ACCESS_DENIED: 'access_denied',
  WEBHOOK_VERIFIED: 'webhook_verified',
  WEBHOOK_REJECTED: 'webhook_rejected'
};

function logSecurityEvent(eventType, details) {
  console.log(JSON.stringify({
    event: eventType,
    timestamp: new Date().toISOString(),
    agent_id: details.agentId,
    account_id: details.accountId,
    ip_address: details.ipAddress,
    resource: details.resource,
    outcome: details.outcome,
    // NEVER log: credentials, PII, targeting briefs
  }));
}

​

Log Retention

• Security logs: 90 days minimum (365 days recommended)
• Financial logs: 7 years (compliance requirement)
• Access logs: 30 days minimum

​

Security Checklist

​

For Publishers (AdCP Servers)

• Implement strong authentication (OAuth 2.0, API keys, or mTLS)
• Enforce agent and account isolation in all database queries
• Implement idempotency for financial operations
• Validate all input with strict schema validation
• Use TLS 1.3+ for all communications
• Verify webhook signatures cryptographically
• Log all security events immutably

​

For Buyer Agents (AdCP Clients)

• Store credentials in secure key management system
• Rotate credentials every 90 days
• Use HTTPS for all AdCP communications
• Validate responses from publishers
• Implement alerts for unusual spending patterns

​

For Orchestrators (Multi-Agent, Multi-Account)

• Store each agent’s credentials separately (encrypted)
• Enforce agent and account filtering in ALL queries
• Use row-level security in databases
• Log all operations with agent and account identity
• Implement per-agent rate limiting