Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
21 commits
Select commit Hold shift + click to select a range
ab4dcef
feat(supply-path): verify authoritative evidence with shared registry…
bokelley Sep 14, 2026
7eb6790
fix(build): budget the 34 supply-path package artifacts
bokelley Sep 14, 2026
06bb538
fix(supply-path): retain authority evidence and enforce shared publis…
bokelley Sep 14, 2026
03e5cf5
test(supply-path): consume corrected upstream authority vectors
bokelley Sep 14, 2026
a552b65
fix(supply-path): pin authority only after successful manifest valida…
bokelley Sep 14, 2026
af39c4b
fix(supply-path): retain denials before later authority failures
bokelley Sep 14, 2026
638dd3b
docs(supply-path): clarify authority store admission contract
bokelley Sep 14, 2026
1938495
fix(supply-path): reject fragment aliases without consuming pin admis…
bokelley Sep 14, 2026
d7e884b
test(cli): keep tunnel lifecycle checks independent of public agents
bokelley Sep 14, 2026
6de659a
fix(supply-path): consume merged canonical vectors
bokelley Sep 19, 2026
c4ca2de
fix(supply-path): reject malformed property grants
bokelley Sep 19, 2026
da59d98
fix(supply-path): close exact-head review gaps
bokelley Sep 19, 2026
41c9695
fix(supply-path): fail closed on unresolved scope
bokelley Sep 19, 2026
e3131bb
fix(supply-path): validate selector predicates
bokelley Sep 19, 2026
d877a79
fix(supply-path): bound retained authority state
bokelley Sep 19, 2026
6ff6d2e
fix(supply-path): validate manifests before pinning
bokelley Sep 19, 2026
967e640
fix(supply-path): bound selector evaluation work
bokelley Sep 19, 2026
a32ad56
fix(supply-path): cap compact selector preprocessing
bokelley Sep 19, 2026
51efa1c
fix(supply-path): preserve client compatibility
bokelley Sep 19, 2026
1a16bc6
fix(supply-path): preserve unchanged response shape
bokelley Sep 19, 2026
8c3330c
fix(supply-path): preserve failed poll results
bokelley Sep 19, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions .changeset/verify-authoritative-supply-paths.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
---
'@adcp/sdk': minor
---

Add supply-path verification with a typed canonical registry wrapper and a live authoritative mode that checks owner/host adagents.json declarations and ads.txt/app-ads.txt evidence. Return per-leg diagnostics and auditable fetch provenance, with DNS-pinned SSRF protection, bounded fetching and fail-closed handling of malformed or unresolved authorization constraints.

Add opt-in external collection path annotations for product discovery, public selector/distribution types, and an explicit distinction between authorization bulk grants and product selectors that require concrete collection IDs.

Support explicit publisher attribution on shared collection declarations, bounded process-local authority admission, durable tenant-scoped stores, and independent authority migration confirmation. Establish first-use pins only after successful manifest validation, with a read-only precheck and atomic successful-observation commit.

Persist parsed revocations before later fetch or authority-store failures, preserving their seven-day hold through failed affirmative verification.
3 changes: 3 additions & 0 deletions .prettierignore
Original file line number Diff line number Diff line change
Expand Up @@ -31,3 +31,6 @@ test/fixtures/media-buy-update-fields/

# Canonical reporting consumer-status source retained byte-for-byte as evidence.
test/fixtures/reporting-consumer-status/canonical-rc3.json

# Canonical supply-path verdict vectors, byte-identical to the upstream corpus.
test/fixtures/supply-path/vectors.json
2 changes: 2 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -1050,3 +1050,5 @@ Apache 2.0 License - see [LICENSE](LICENSE) file for details.
- **Documentation**: [docs.adcontextprotocol.org](https://docs.adcontextprotocol.org)
- **Issues**: [GitHub Issues](https://github.com/adcontextprotocol/adcp-client/issues)
- **Protocol Spec**: [AdCP Specification](https://github.com/adcontextprotocol/adcp)

Supply-path verification: use `verifySupplyPath` for authoritative evidence or the canonical registry verdict, and opt into external collection discovery annotations. See [the supply-path guide](docs/guides/SUPPLY-PATH-VERIFICATION.md).
101 changes: 101 additions & 0 deletions docs/guides/SUPPLY-PATH-VERIFICATION.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,101 @@
# Supply-path verification

Use `verifySupplyPath` to check an owner-sold collection on a host publisher. It returns a state and five independently diagnosed legs: owner collection declaration, owner distribution/carriage, owner agent declaration, host authorization, and `INVENTORYPARTNERDOMAIN` evidence.

```typescript
import { verifySupplyPath } from '@adcp/sdk';

const result = await verifySupplyPath({
owner_domain: 'channel-owner.example',
host_domain: 'hoststream.example',
agent_url: 'https://sales.channel-owner.example',
collection_id: 'retro_news',
}, { source: 'authoritative', timeoutMs: 15_000, retainEvidenceBodies: true });

if (result.state !== 'verified_owner_sold') {
// Apply your buying policy. Never treat owner_attested as authorization.
console.log(result.legs);
}
// Store this evidence with the decision, including exact bytes when enabled.
console.log(result.sources.evidence);
```

| State | Meaning |
| --- | --- |
| `verified_owner_sold` | The owner's collection and carriage references resolve, and a host grant covers the complete carried property scope for this agent and collection without unevaluated constraints. |
| `host_delegated` | The host's ads.txt/app-ads.txt names the owner, and the owner declares the agent and collection. This weaker evidence does not bind the host to this agent or collection. Accept only under an explicit buyer policy. |
| `owner_attested` | The owner asserts carriage. This is discovery information, never host sales authorization. |
| `unverified` | The evidence cannot establish a path. |

The state is a supply-path decision, not a purchase guarantee, exclusivity claim, proof of delivery, or blanket product authorization. Country, effective-time and placement restrictions require an applicable context; this API fails closed on owner or host entries carrying those restrictions, including unknown authorization fields. Independent unrestricted entries can still establish a path. Collection distribution identifiers identify channels in a catalog; they are not host property IDs and are never silently converted into property IDs.

`collection_id` is optional for a domain-level inquiry. The evaluator considers complete individual collection paths and returns the strongest one as `resolved_collection_id`; it never combines carriage from one collection with authorization for another. For a particular product, always check its explicit collection IDs.

## Registry mode

```typescript
import { RegistryClient, verifySupplyPath } from '@adcp/sdk';

const request = {
owner_domain: 'channel-owner.example',
host_domain: 'hoststream.example',
agent_url: 'https://sales.channel-owner.example',
collection_id: 'retro_news',
};
const registry = new RegistryClient();
const cached = await registry.verifySupplyPath(request);
// Equivalent:
await verifySupplyPath(request, { source: 'registry', registry });
```

This is a typed wrapper over `POST /api/registry/verify/supply-path`. It preserves the registry's verdict, diagnostics, URLs, `cached` flag, timestamp and additional response fields. HTTP failures and malformed/inconsistent response shapes reject the promise. The wrapper requires `semantics_version: "1"`; an older registry must upgrade before it can serve this API. Registry responses describe cached evidence; `checked_at` is the decision time, not proof that the origin files were fetched then. The registry includes `owner_fetched_at`, `host_fetched_at` and resolved URLs so cache provenance can be assessed separately. The wrapper does not promote registry provenance into authoritative evidence.

## Discovery annotations

```typescript
import { annotateProductsSupplyPaths } from '@adcp/sdk';

// products must be the actual products returned by your seller.
const annotated = await annotateProductsSupplyPaths(products, sellerAgentUrl, {
source: 'authoritative',
maxPaths: 64,
});
for (const product of annotated) {
console.log(product.supply_path_state, product.supply_path_verification);
}
```

Alternatively, configure a client with `validation.supplyPathVerification: { source: 'authoritative' }`. Completed `get_products` and `list_products` responses are annotated before completion handlers receive them, including resumed completion paths. Annotation is opt-in because it performs additional network requests.

Products combining `publisher_properties` with a collection selector in a different publisher namespace receive `supply_path_state`, the weakest state across their distinct external paths. Details live in `supply_path_verification.paths`. Authoritative mode uses `scope: 'product_properties'` and resolves every product selector against the host manifest; a verified path must cover all selected properties. Registry mode uses `scope: 'owner_host_collection'` because the endpoint accepts no product property context. Its annotation cannot certify the product's selected properties. Neither mode certifies placements, countries, effective dates, or other product restrictions. The weaker `host_delegated` state never establishes concrete product property coverage.
Products, ordering and unrelated seller fields are preserved. Computed annotation replaces any seller-authored verification fields. Local-only products have no external-path annotation. Invalid or omitted product `collection_ids` and path-limit overflow produce `unverified` with errors. Network policy refusal, unconfirmed authoritative-location changes, cancellation and registry failures reject the operation instead of returning a seller-authored or stale success. Batches deduplicate both paths and evidence fetches within the operation, run at most four paths concurrently, and default to 64 distinct paths (maximum 256).

## Selector types

`AuthorizationCollectionSelector.collection_ids` is optional: omission grants all collections declared by that exact publisher. Present `[]`, `null`, non-array values and mixed-type ID arrays are invalid, not bulk grants. `ProductCollectionSelector` requires a non-empty explicit ID tuple. `CollectionDistribution` accepts `property_ids`, `identifiers`, or both. Public discovery and registry authorization types preserve these distinctions.

## Network and evidence policy

Authoritative mode starts at each publisher's HTTPS `/.well-known/adagents.json`. It uses the SDK's existing SSRF-safe fetcher: every DNS address is checked, the connection is pinned to a validated address, TLS verification remains enabled, and private/link-local/metadata addresses are refused. It does not contact the agent endpoint. No authorization credentials are sent to publisher evidence URLs.

HTTP redirects are limited to three within the exact HTTPS origin. A publisher-origin `authoritative_location` pointer or `superseded_by` migration may explicitly delegate to another HTTPS origin once; that target cannot redirect again. Properties from a cross-origin document must explicitly name their `publisher_domain`; unscoped shared-network properties cannot authorize another publisher. Credentials, nonstandard ports, mixed pointer/catalog files and chained pointers fail closed. This stricter authoritative API does not use community catalogs, cached fallback documents or MANAGERDOMAIN discovery. Those discovery routes need additional publisher scope proofs before they can serve as enforcement evidence.

Collections in a cross-origin authoritative document must explicitly name their owning `publisher_domain`, just as shared host properties must identify their publisher. A domain pointing at an unrelated public catalog cannot borrow that catalog's collections, including through weaker inventory-partner evidence. Publisher-origin collection declarations may omit the field. Owner agent grants in shared cross-origin documents must also explicitly select that owner through `collections[].publisher_domain`; an absent `collections` constraint cannot authorize every member. Within that owner namespace, omitted `collection_ids` still grants all collections.

Authoritative locations are pinned only after the first successfully fetched, parsed, non-chained manifest with the required authorization envelope. Unavailable or malformed targets do not establish a pin. `SupplyPathAuthorityStore.check` is a non-mutating precheck that rejects a different existing pin before fetching its target. After validation, `observe` must atomically insert an absent pin or compare against the existing pin, rejecting a mismatch even when another request or operator changed it after the precheck. A successful `check` is neither a reservation nor authorization; verification requires a successful `observe`. Configure a durable shared store across restarts or workers, and perform the final comparison and insert in one transaction scoped to the trusted tenant and publisher. After independently confirming a publisher migration, update the durable pin or call `approveChange` on your in-memory instance. For the process default, import `defaultSupplyPathAuthorities` from `@adcp/sdk` and call `defaultSupplyPathAuthorities.approveChange(publisherDomain, confirmedHttpsLocation)`. Never approve changes from an automatic retry. First-successful-use pinning cannot detect an origin already compromised before that observation.

The default deadline is 15 seconds for the whole path (or whole annotation batch), configurable up to 60 seconds. Each decompressed response is capped at 256 KiB, configurable up to 20 MiB, with a 64 MiB aggregate evidence budget per operation. The evaluator rejects arrays above 1,024 entries, strings above 8,192 characters, total input above 32,768 values, or a conservative selector-work estimate above four million operations with `evaluation_limit_exceeded`. Cancellation is supported through `signal`. `trustedFetchFn` is an explicit advanced egress hook: it assumes responsibility for DNS resolution, address policy and DNS rebinding protection; its evidence reports `connection_pinned: false`. It must honor request cancellation and manual redirect handling.

Evidence contains requested/resolved URLs, HTTP status, fetch time, SHA-256 of exact decompressed bytes, byte count, connection-pinning status and structured failure codes. `retainEvidenceBodies` also retains those bytes as JSON-safe `body_base64`, including pointer and HTTP redirect documents. Retain the entire chain alongside an enforcement decision. Bodies are untrusted publisher content; store them as opaque evidence, not instructions or trusted log fields. A live fetch is an observation at `fetched_at`, not a permanent authorization grant; reverify before subsequent decisions when freshness matters.

`inventory_partner_domain.failure: 'not_evaluated'` means the IAB fetch was skipped because host authorization already established the strongest state. A 404 is fetched-and-absent (`not_declared`); transport failures remain `ads_txt_unavailable`, with the cause in evidence. Websites use ads.txt, apps use app-ads.txt, and mixed surfaces require the owner in every applicable file. `unsupported_constraints` identifies unevaluated grant fields in `detail`.

Validated publisher revocations are persisted immediately after parsing, before later fetches or authority-store operations can fail. They are held for seven days per publisher authority, including after the next manifest omits them. The default `InMemorySupplyPathRevocationStore` holds them for the process lifetime. For enforcement across restarts or multiple workers, configure a durable shared `SupplyPathRevocationStore`; its `observe` operation must be atomic and retain first-observation expiry by publisher domain within each authority, retaining the first-observation clock when `revoked_at` changes. Store failures and malformed revocation evidence reject verification. `sources.held_revocations` records the hold used in the decision. Keep observations from different publisher authorities isolated. The process-local store admits at most 1,024 live revocations per authority and 10,000 overall. Both process-local stores limit admission to 128 new authorities per 60-second window; the revocation store counts authorities with a new nonempty hold, and the pointer store counts first pins. Existing holds and pins remain readable during admission refusals. Pointer storage is capped at 10,000 authorities for the process lifetime. Overflow rejects verification without evicting live evidence or silently adopting a replacement pin.

These defaults are shared by callers in the process. A sustained many-domain attack can still exhaust their finite capacity, including domains controlled under a wildcard. Rate-limit verification requests by authenticated caller or tenant before invoking the API; publisher domain alone is not an abuse-control identity. For multi-tenant enforcement, pass tenant-scoped durable `revocationStore` and `authorityStore` instances. Capture the tenant from trusted application context in each instance, then key revocations by `(tenant, authority, publisher_domain)` and pins by `(tenant, publisher_domain)`. Make capacity/admission limits and transactions tenant-scoped, and reject exhausted writes instead of deleting live evidence. Neither store interface derives a tenant from counterparty evidence. Do not recover from capacity errors by silently replacing a store with an empty one.

Authority-store keys use the exact serialized HTTPS URL supplied by the verifier. URLs containing a fragment delimiter, including an empty trailing `#`, are refused. Preserve query and path spelling rather than merging potentially distinct server resources. The request deadline bounds the caller's wait; a durable `observe` transaction may complete after the caller times out. It still represents a successfully validated manifest, so retries must be idempotent and must not undo that pin or any retained denial.

## Contract and conformance

The state/leg contract originates in [adcp#6897](https://github.com/adcontextprotocol/adcp/pull/6897) and its fail-closed companion. Both implementations execute the same [canonical supply-path vectors](https://github.com/adcontextprotocol/adcp/tree/main/static/compliance/source/test-vectors/supply-path), including each verdict, resolved collection, leg failure, parser result, and applicable IAB-file policy. The SDK vendors the JSON byte-for-byte from a reviewed upstream commit; provenance and checksums are recorded in `test/fixtures/supply-path/source.json`. Updating it requires selecting a reviewed upstream commit and rerunning both implementations. The runtime `semantics_version` prevents silent acceptance of registries running the older fail-open evaluator.
2 changes: 2 additions & 0 deletions examples/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -202,3 +202,5 @@ npm run dev
```

See the main README for full testing framework documentation.

Supply-path verification: [supply-path-verification.ts](supply-path-verification.ts) reads owner, host, agent and collection from environment variables and prints a live evidence-bearing verdict.
29 changes: 29 additions & 0 deletions examples/supply-path-verification.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
/** Run with: npx tsx examples/supply-path-verification.ts */
import { verifySupplyPath } from '@adcp/sdk';

async function main(): Promise<void> {
const owner = process.env.SUPPLY_PATH_OWNER;
const host = process.env.SUPPLY_PATH_HOST;
const agent = process.env.SUPPLY_PATH_AGENT;
const collection = process.env.SUPPLY_PATH_COLLECTION;
if (!owner || !host || !agent || !collection) {
throw new Error('Set SUPPLY_PATH_OWNER, SUPPLY_PATH_HOST, SUPPLY_PATH_AGENT and SUPPLY_PATH_COLLECTION');
}
const result = await verifySupplyPath(
{
owner_domain: owner,
host_domain: host,
agent_url: agent,
collection_id: collection,
},
{ source: 'authoritative' }
);
console.log(JSON.stringify(result, null, 2));
// Example policy: only the strongest, authoritative supply-path state passes.
if (result.state !== 'verified_owner_sold') process.exitCode = 1;
}

main().catch(error => {
console.error(error instanceof Error ? error.message : String(error));
process.exitCode = 1;
});
1 change: 1 addition & 0 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -538,6 +538,7 @@
"examples/adcp.config.json",
"examples/reliable-reporting-service/README.md",
"examples/seller-3.2-starter.ts",
"examples/supply-path-verification.ts",
"examples/comply-controller-seller.ts",
"examples/seller-test-controller.ts",
"examples/gcp-kms-signing-provider.ts",
Expand Down
4 changes: 3 additions & 1 deletion scripts/check-package-size.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -62,7 +62,9 @@ const MAX_UNPACKED_PACKAGE_BYTES = 120 * 1024 * 1024;
// The durable buyer-writes adoption example adds two TypeScript files and one
// packaged guide, bringing the clean package to 6,135 published files. The
// remaining changes edit existing modules; byte budgets stay fixed.
const MAX_PACKED_FILE_COUNT = 6_135;
// Supply-path verification adds 32 runtime/declaration artifacts and its guide
// and packaged example (34 files total); byte and schema budgets stay unchanged.
const MAX_PACKED_FILE_COUNT = 6_135 + 34;
const MAX_BUNDLED_SCHEMA_BYTES = 1280 * 1024;
const MAX_CJS_SCHEMA_DECLARATION_BYTES = 45 * 1024 * 1024;
const MAX_ESM_SCHEMA_FACADE_BYTES = 1024;
Expand Down
Loading
Loading