From ab4dcef964407d3745cb3c781f45eabc75f45643 Mon Sep 17 00:00:00 2001 From: Brian O'Kelley Date: Mon, 14 Sep 2026 14:56:51 +0000 Subject: [PATCH 01/21] feat(supply-path): verify authoritative evidence with shared registry semantics --- .../verify-authoritative-supply-paths.md | 7 + .prettierignore | 3 + README.md | 2 + docs/guides/SUPPLY-PATH-VERIFICATION.md | 93 + examples/README.md | 2 + examples/supply-path-verification.ts | 29 + package.json | 1 + scripts/sync-supply-path-vectors.mjs | 52 + src/lib/core/SingleAgentClient.ts | 49 +- src/lib/discovery/adagents-redirects.ts | 16 +- src/lib/discovery/types.ts | 30 + src/lib/index.ts | 9 + src/lib/net/ssrf-fetch.ts | 69 +- src/lib/registry/index.ts | 10 + src/lib/registry/types.ts | 6 +- src/lib/supply-path/evaluate.ts | 448 ++ src/lib/supply-path/fetch-evidence.ts | 230 + src/lib/supply-path/index.ts | 13 + src/lib/supply-path/products.ts | 186 + src/lib/supply-path/revocations.ts | 52 + .../supply-path/supply-path.type-checks.ts | 59 + src/lib/supply-path/types.ts | 167 + src/lib/supply-path/validation.ts | 120 + src/lib/supply-path/verify.ts | 153 + src/lib/v2/projection/creative-delivery.ts | 13 +- test/fixtures/supply-path/README.md | 17 + test/fixtures/supply-path/source.json | 7 + test/fixtures/supply-path/vectors.json | 6102 +++++++++++++++++ .../product-property-policy-client.test.js | 77 + test/lib/supply-path.test.js | 667 ++ tsconfig.examples.json | 1 + 31 files changed, 8652 insertions(+), 38 deletions(-) create mode 100644 .changeset/verify-authoritative-supply-paths.md create mode 100644 docs/guides/SUPPLY-PATH-VERIFICATION.md create mode 100644 examples/supply-path-verification.ts create mode 100644 scripts/sync-supply-path-vectors.mjs create mode 100644 src/lib/supply-path/evaluate.ts create mode 100644 src/lib/supply-path/fetch-evidence.ts create mode 100644 src/lib/supply-path/index.ts create mode 100644 src/lib/supply-path/products.ts create mode 100644 src/lib/supply-path/revocations.ts create mode 100644 src/lib/supply-path/supply-path.type-checks.ts create mode 100644 src/lib/supply-path/types.ts create mode 100644 src/lib/supply-path/validation.ts create mode 100644 src/lib/supply-path/verify.ts create mode 100644 test/fixtures/supply-path/README.md create mode 100644 test/fixtures/supply-path/source.json create mode 100644 test/fixtures/supply-path/vectors.json create mode 100644 test/lib/supply-path.test.js diff --git a/.changeset/verify-authoritative-supply-paths.md b/.changeset/verify-authoritative-supply-paths.md new file mode 100644 index 000000000..dae2798bd --- /dev/null +++ b/.changeset/verify-authoritative-supply-paths.md @@ -0,0 +1,7 @@ +--- +'@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. diff --git a/.prettierignore b/.prettierignore index 9b9129720..b3968b863 100644 --- a/.prettierignore +++ b/.prettierignore @@ -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 diff --git a/README.md b/README.md index c35e8b4ec..4f405496c 100644 --- a/README.md +++ b/README.md @@ -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). diff --git a/docs/guides/SUPPLY-PATH-VERIFICATION.md b/docs/guides/SUPPLY-PATH-VERIFICATION.md new file mode 100644 index 000000000..b0d9944c1 --- /dev/null +++ b/docs/guides/SUPPLY-PATH-VERIFICATION.md @@ -0,0 +1,93 @@ +# 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 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, 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. 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. + +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`. + +Previously observed publisher revocations 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 for each `(publisher_domain, revoked_at)` tuple. 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. + +## 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. diff --git a/examples/README.md b/examples/README.md index 0c56abb41..5f3ecc354 100644 --- a/examples/README.md +++ b/examples/README.md @@ -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. diff --git a/examples/supply-path-verification.ts b/examples/supply-path-verification.ts new file mode 100644 index 000000000..af06d48a6 --- /dev/null +++ b/examples/supply-path-verification.ts @@ -0,0 +1,29 @@ +/** Run with: npx tsx examples/supply-path-verification.ts */ +import { verifySupplyPath } from '@adcp/sdk'; + +async function main(): Promise { + 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; +}); diff --git a/package.json b/package.json index e1d7b3687..6c0c30259 100644 --- a/package.json +++ b/package.json @@ -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", diff --git a/scripts/sync-supply-path-vectors.mjs b/scripts/sync-supply-path-vectors.mjs new file mode 100644 index 000000000..a33436290 --- /dev/null +++ b/scripts/sync-supply-path-vectors.mjs @@ -0,0 +1,52 @@ +#!/usr/bin/env node +/** Vendor the upstream canonical corpus at an explicitly reviewed immutable commit. */ +import { createHash } from 'node:crypto'; +import { readFile, writeFile } from 'node:fs/promises'; +import { fileURLToPath } from 'node:url'; +import path from 'node:path'; +const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..'); +const directory = path.join(root, 'test/fixtures/supply-path'); +const upstreamPath = 'static/compliance/source/test-vectors/supply-path/vectors.json'; +const args = process.argv.slice(2); +const sha256 = bytes => createHash('sha256').update(bytes).digest('hex'); +if (args.length === 2 && args[0] === '--commit' && /^[a-f0-9]{40}$/.test(args[1])) { + const commit = args[1]; + const response = await fetch(`https://raw.githubusercontent.com/adcontextprotocol/adcp/${commit}/${upstreamPath}`, { + signal: AbortSignal.timeout(30000), + }); + if (!response.ok) throw new Error(`Cannot fetch canonical corpus: HTTP ${response.status}`); + const bytes = Buffer.from(await response.arrayBuffer()); + const corpus = JSON.parse(bytes.toString('utf8')); + if (corpus.semantics_version !== '1' || !Array.isArray(corpus.vectors) || !corpus.vectors.length) + throw new Error('Unsupported canonical corpus'); + await writeFile(path.join(directory, 'vectors.json'), bytes); + await writeFile( + path.join(directory, 'source.json'), + JSON.stringify( + { + repository: 'adcontextprotocol/adcp', + commit, + path: upstreamPath, + sha256: sha256(bytes), + semantics_version: corpus.semantics_version, + }, + null, + 2 + ) + '\n' + ); + console.log(`Pinned canonical supply-path vectors at ${commit}`); +} else if (!args.length || (args.length === 1 && args[0] === '--check')) { + const source = JSON.parse(await readFile(path.join(directory, 'source.json'), 'utf8')); + const bytes = await readFile(path.join(directory, 'vectors.json')); + if ( + source.repository !== 'adcontextprotocol/adcp' || + source.path !== upstreamPath || + !/^[a-f0-9]{40}$/.test(source.commit) || + source.sha256 !== sha256(bytes) || + source.semantics_version !== JSON.parse(bytes.toString('utf8')).semantics_version + ) + throw new Error('Canonical supply-path fixture provenance mismatch'); + console.log(`Canonical supply-path fixture integrity verified (${source.commit})`); +} else { + throw new Error('Usage: node scripts/sync-supply-path-vectors.mjs [--check | --commit ]'); +} diff --git a/src/lib/core/SingleAgentClient.ts b/src/lib/core/SingleAgentClient.ts index 6966f7393..5e0f742aa 100644 --- a/src/lib/core/SingleAgentClient.ts +++ b/src/lib/core/SingleAgentClient.ts @@ -1,3 +1,4 @@ +import { annotateProductsSupplyPaths, type ProductSupplyPathOptions } from '../supply-path/products'; // Main ADCP Client - Type-safe conversation-aware client for AdCP agents import { z } from 'zod'; @@ -1499,6 +1500,8 @@ export interface SingleAgentClientConfig extends ConversationConfig { * violates an exclusion for `ladbible.com`. */ productPropertyPolicy?: ClientProductPropertyPolicy | false; + /** Opt in to computed, evidence-bearing external collection path annotations on product discovery. */ + supplyPathVerification?: ProductSupplyPathOptions; }; /** Governance configuration for buyer-side campaign governance */ governance?: import('./GovernanceTypes').GovernanceConfig; @@ -5331,6 +5334,23 @@ export class SingleAgentClient { // configured. This runs on the same completion chokepoint so it covers the // sync, polling, track, and webhook paths uniformly. result = this.enforceProductPricingOptions(result, taskType); + if ( + this.config.validation?.supplyPathVerification && + (taskType === 'get_products' || taskType === 'list_products') && + result.success && + result.status === 'completed' && + result.data + ) { + const data = result.data as { products?: object[] }; + if (Array.isArray(data.products)) { + const products = await annotateProductsSupplyPaths( + data.products, + this.agent.agent_uri, + this.config.validation.supplyPathVerification + ); + result = { ...result, data: { ...result.data, products } }; + } + } const policyConfig = this.config.validation?.productPropertyPolicy; if (policyConfig === false || taskType !== 'get_products') return result; @@ -5525,7 +5545,11 @@ export class SingleAgentClient { result: TaskResult, options?: TaskOptions ): void { - if (taskType !== 'get_products') return; + if ( + taskType !== 'get_products' && + !(taskType === 'list_products' && this.config.validation?.supplyPathVerification) + ) + return; if (result.status !== 'submitted' && result.status !== 'working') return; const keys = new Set(); @@ -5609,7 +5633,13 @@ export class SingleAgentClient { requestParams: Record, options?: TaskOptions ): TaskResult { - if (taskType !== 'get_products' || result.status !== 'submitted' || !result.submitted) return result; + if ( + (taskType !== 'get_products' && + !(taskType === 'list_products' && this.config.validation?.supplyPathVerification)) || + result.status !== 'submitted' || + !result.submitted + ) + return result; const submitted = result.submitted; const policyState: { request?: Readonly> } = { @@ -5675,7 +5705,13 @@ export class SingleAgentClient { taskType: string, requestParams: Record ): Promise { - if (taskType !== 'get_products' || taskInfo.status !== 'completed' || !taskInfo.result) return taskInfo; + if ( + (taskType !== 'get_products' && + !(taskType === 'list_products' && this.config.validation?.supplyPathVerification)) || + taskInfo.status !== 'completed' || + !taskInfo.result + ) + return taskInfo; const policyResult = await this.applyProductPropertyPolicy( attachMatch({ @@ -5734,7 +5770,12 @@ export class SingleAgentClient { result: AdCPAsyncResponseData | undefined, metadata: WebhookMetadata ): Promise<{ result: AdCPAsyncResponseData | undefined; metadata: WebhookMetadata; suppressHandler: boolean }> { - if (metadata.task_type !== 'get_products' || metadata.status !== 'completed' || !result) { + if ( + (metadata.task_type !== 'get_products' && + !(metadata.task_type === 'list_products' && this.config.validation?.supplyPathVerification)) || + metadata.status !== 'completed' || + !result + ) { return { result, metadata, suppressHandler: false }; } diff --git a/src/lib/discovery/adagents-redirects.ts b/src/lib/discovery/adagents-redirects.ts index 8fc13cd5a..dee62eed2 100644 --- a/src/lib/discovery/adagents-redirects.ts +++ b/src/lib/discovery/adagents-redirects.ts @@ -30,21 +30,23 @@ export class AdAgentsRedirectRefusedError extends Error { export type AdAgentsRedirectPolicy = | { mode: 'none' } + | { mode: 'same-origin'; originUrl: string; maxRedirects?: number } | { mode: 'same-registrable-domain'; originUrl: string; maxRedirects?: number }; export async function ssrfSafeFetchAdAgents( url: string, options: SsrfFetchOptions, - policy: AdAgentsRedirectPolicy + policy: AdAgentsRedirectPolicy, + onResponse?: (response: SsrfFetchResult) => void ): Promise { let currentUrl = url; let redirects = 0; - const originUrl = policy.mode === 'same-registrable-domain' ? policy.originUrl : url; - const maxRedirects = - policy.mode === 'same-registrable-domain' ? (policy.maxRedirects ?? DEFAULT_WELL_KNOWN_REDIRECT_HOPS) : 0; + const originUrl = policy.mode !== 'none' ? policy.originUrl : url; + const maxRedirects = policy.mode !== 'none' ? (policy.maxRedirects ?? DEFAULT_WELL_KNOWN_REDIRECT_HOPS) : 0; while (true) { const result = await ssrfSafeFetch(currentUrl, options); + onResponse?.(result); if (!REDIRECT_STATUSES.has(result.status)) return result; const location = result.headers['location']; @@ -89,6 +91,12 @@ export async function ssrfSafeFetchAdAgents( ); } + if (policy.mode === 'same-origin' && new URL(originUrl).origin !== next.origin) { + throw new AdAgentsRedirectRefusedError('redirect_refused', 'Authoritative evidence redirect changed origin', { + url: currentUrl, + location: scrubUrl(next), + }); + } validateSameRegistrableDomainRedirect(originUrl, currentUrl, nextUrl); redirects++; currentUrl = nextUrl; diff --git a/src/lib/discovery/types.ts b/src/lib/discovery/types.ts index f55e16d0b..e966d6435 100644 --- a/src/lib/discovery/types.ts +++ b/src/lib/discovery/types.ts @@ -104,6 +104,33 @@ export type CompactPublisherPropertySelector = | { selection_type: 'all'; publisher_domains: string[] } | { selection_type: 'by_tag'; publisher_domains: string[]; property_tags: string[] }; +/** Authorization-scoped omission grants all collections in this publisher namespace. */ +export interface AuthorizationCollectionSelector { + publisher_domain: string; + collection_ids?: string[]; +} +/** Products always select concrete collection IDs; omission is not a product wildcard. */ +export interface ProductCollectionSelector extends AuthorizationCollectionSelector { + collection_ids: [string, ...string[]]; +} +/** Carriage entries can carry host property IDs, catalog identifiers, or both. */ +export type CollectionDistribution = { publisher_domain: string } & ( + | { + property_ids: [string, ...string[]]; + identifiers?: [{ type: string; value: string }, ...Array<{ type: string; value: string }>]; + } + | { + property_ids?: [string, ...string[]]; + identifiers: [{ type: string; value: string }, ...Array<{ type: string; value: string }>]; + } +); +export interface DiscoveryCollection { + collection_id: string; + name: string; + kind?: string; + distribution?: CollectionDistribution[]; +} + /** * Entry in `adagents.json` `authorized_agents[]`. The schema requires * every entry to carry `authorization_type` plus the matching selector @@ -117,6 +144,8 @@ export type CompactPublisherPropertySelector = export interface AuthorizedAgent { url: string; authorized_for: string; + collections?: AuthorizationCollectionSelector[]; + delegation_type?: string; /** Discriminator. Required by the schema; absent in pre-schema-3 files. */ authorization_type?: AuthorizationType; /** Selector for `authorization_type: 'property_ids'`. */ @@ -194,6 +223,7 @@ export interface AdAgentsJson { authoritative_location?: string; authorized_agents?: AuthorizedAgent[]; properties?: Property[]; + collections?: DiscoveryCollection[]; /** * Publisher-published format catalog (AdCP 3.1). Each entry declares * a v2 `ProductFormatDeclaration` (or v1 named-format ref) the diff --git a/src/lib/index.ts b/src/lib/index.ts index 3420cf994..3025aa90c 100644 --- a/src/lib/index.ts +++ b/src/lib/index.ts @@ -2318,3 +2318,12 @@ export type { SellerActionResolutionOptions, SellerActionResolution, } from './server/media-buy-action-resolver'; + +// Authoritative supply-path evidence and the canonical registry wrapper. +export * from './supply-path'; +export type { + AuthorizationCollectionSelector, + ProductCollectionSelector, + CollectionDistribution, + DiscoveryCollection, +} from './discovery/types'; diff --git a/src/lib/net/ssrf-fetch.ts b/src/lib/net/ssrf-fetch.ts index dfdd03969..98bba81f6 100644 --- a/src/lib/net/ssrf-fetch.ts +++ b/src/lib/net/ssrf-fetch.ts @@ -240,6 +240,7 @@ export async function ssrfSafeFetch(url: string, options: SsrfFetchOptions = {}) if (options.signal?.aborted) onExternalAbort(); const timer = setTimeout(() => ac.abort(new Error('ssrf-fetch: timeout')), timeoutMs); let dispatcher: Agent | undefined; + let cancelBody: (() => void) | undefined; let pinned: { address: string; family: number } | undefined; let pinnedFamily: 4 | 6 | undefined; @@ -317,22 +318,25 @@ export async function ssrfSafeFetch(url: string, options: SsrfFetchOptions = {}) }); } - const res = options.trustedFetchFn - ? await options.trustedFetchFn(checkedUrl, { - method: options.method ?? 'GET', - redirect: 'manual', - signal: ac.signal, - headers: options.headers, - ...(options.body !== undefined && { body: options.body as BodyInit }), - }) - : await undiciFetch(checkedUrl, { - method: options.method ?? 'GET', - redirect: 'manual', - signal: ac.signal, - headers: options.headers, - dispatcher, - ...(options.body !== undefined && { body: options.body }), - }); + const res = await raceWithAbort>>( + options.trustedFetchFn + ? options.trustedFetchFn(checkedUrl, { + method: options.method ?? 'GET', + redirect: 'manual', + signal: ac.signal, + headers: options.headers, + ...(options.body !== undefined && { body: options.body as BodyInit }), + }) + : undiciFetch(checkedUrl, { + method: options.method ?? 'GET', + redirect: 'manual', + signal: ac.signal, + headers: options.headers, + dispatcher, + ...(options.body !== undefined && { body: options.body }), + }), + ac.signal + ); const headers: Record = {}; res.headers.forEach((v, k) => { @@ -351,14 +355,17 @@ export async function ssrfSafeFetch(url: string, options: SsrfFetchOptions = {}) }; } + cancelBody = () => { + void reader.cancel().catch(() => {}); + }; const chunks: Uint8Array[] = []; let bytes = 0; while (true) { - const { done, value } = await reader.read(); + const { done, value } = await raceWithAbort(reader.read(), ac.signal); if (done) break; bytes += value.byteLength; if (bytes > maxBodyBytes) { - await reader.cancel(); + void reader.cancel().catch(() => {}); throw new SsrfRefusedError('body_exceeds_limit', `Response body exceeded ${maxBodyBytes} bytes`, { url, hostname: parsed.hostname, @@ -386,7 +393,10 @@ export async function ssrfSafeFetch(url: string, options: SsrfFetchOptions = {}) } finally { clearTimeout(timer); options.signal?.removeEventListener('abort', onExternalAbort); - await dispatcher?.close().catch(() => {}); + if (ac.signal.aborted) { + cancelBody?.(); + await dispatcher?.destroy().catch(() => {}); + } else await dispatcher?.close().catch(() => {}); } } @@ -397,11 +407,24 @@ export async function ssrfSafeFetch(url: string, options: SsrfFetchOptions = {}) * branch has already won the race. */ function raceWithAbort(operation: Promise, signal: AbortSignal): Promise { - throwIfSignalAborted(signal); return new Promise((resolve, reject) => { - const onAbort = () => reject(signalAbortError(signal)); - signal.addEventListener('abort', onAbort, { once: true }); - operation.then(resolve, reject).finally(() => signal.removeEventListener('abort', onAbort)); + const cleanup = () => signal.removeEventListener('abort', onAbort); + const onAbort = () => { + cleanup(); + reject(signalAbortError(signal)); + }; + operation.then( + value => { + cleanup(); + resolve(value); + }, + error => { + cleanup(); + reject(error); + } + ); + if (signal.aborted) onAbort(); + else signal.addEventListener('abort', onAbort, { once: true }); }); } diff --git a/src/lib/registry/index.ts b/src/lib/registry/index.ts index 4148b4a83..40213592f 100644 --- a/src/lib/registry/index.ts +++ b/src/lib/registry/index.ts @@ -1,3 +1,5 @@ +import type { SupplyPathRequest, RegistrySupplyPathResult } from '../supply-path/types'; +import { validateSupplyPathRequest, assertRegistrySupplyPathResult } from '../supply-path/validation'; import type { ResolvedBrand, LookupBrandOptions, @@ -914,6 +916,14 @@ export class RegistryClient { return this.get(`${this.baseUrl}/api/registry/validate/property-authorization?${params}`); } + /** Cached registry verdict. Fetch authoritative evidence for enforcement. */ + async verifySupplyPath(request: SupplyPathRequest): Promise { + const normalized = validateSupplyPathRequest(request); + const response: unknown = await this.post(`${this.baseUrl}/api/registry/verify/supply-path`, normalized); + assertRegistrySupplyPathResult(response, normalized); + return response; + } + /** Validate product authorization for an agent across publisher properties. */ async validateProductAuthorization( agentUrl: string, diff --git a/src/lib/registry/types.ts b/src/lib/registry/types.ts index 31a6e5a1c..807a6f8c8 100644 --- a/src/lib/registry/types.ts +++ b/src/lib/registry/types.ts @@ -300,7 +300,11 @@ type RegistryCreateAdagentsRequest = NonNullable< type RegistryCreateAdagentsResponse = operations['createAdagents']['responses']['200']['content']['application/json']; /** Agent authorization entry accepted by the registry adagents.json generator. */ -export type AdagentsAuthorizedAgent = RegistryCreateAdagentsRequest['authorized_agents'][number] & { +export type AdagentsAuthorizedAgent = Omit< + RegistryCreateAdagentsRequest['authorized_agents'][number], + 'collections' +> & { + collections?: import('../discovery/types').AuthorizationCollectionSelector[]; [key: string]: unknown; }; diff --git a/src/lib/supply-path/evaluate.ts b/src/lib/supply-path/evaluate.ts new file mode 100644 index 000000000..e434a7fc4 --- /dev/null +++ b/src/lib/supply-path/evaluate.ts @@ -0,0 +1,448 @@ +/** + * Pure, fail-closed implementation of the adcp#6897 verification ladder. + * Inputs are evidence, never seller-supplied verdicts. Each collection is + * evaluated independently so domain-level queries cannot join unrelated legs. + */ +import { resolveAgentProperties } from '../discovery/resolve-agent-properties'; +import { + parsePublisherPropertySelector, + expandPublisherPropertySelector, +} from '../discovery/publisher-property-selector'; +import type { AdAgentsJson, AuthorizedAgent } from '../discovery/types'; +import type { SupplyPathInput, SupplyPathLegs, SupplyPathManifest, SupplyPathVerdict } from './types'; +import { agentIdentity, domain, record, records, strings } from './validation'; + +export const SUPPLY_PATH_STATES = ['unverified', 'owner_attested', 'host_delegated', 'verified_owner_sold'] as const; + +export function parseInventoryPartnerDomains(content: string): string[] { + const partners = new Set(); + for (const line of content.split(/\r?\n/)) { + const match = line.trim().match(/^inventorypartnerdomain\s*=\s*([A-Za-z0-9.-]+)\s*(?:#.*)?$/i); + const value = match ? domain(match[1]) : null; + if (value) partners.add(value); + } + return [...partners]; +} + +function revoked(manifest: SupplyPathManifest, publisher: string): boolean { + if (manifest.revoked_publisher_domains === undefined) return false; + if (!Array.isArray(manifest.revoked_publisher_domains)) return true; + return manifest.revoked_publisher_domains.some( + item => + !domain(record(item) ? item.publisher_domain : item) || + domain(record(item) ? item.publisher_domain : item) === publisher + ); +} + +function coversCollection(entry: Record, owner: string, id: string | undefined): boolean { + // Absent is an unconstrained property grant; present malformed is never broad. + if (entry.collections === undefined) return true; + if (!Array.isArray(entry.collections) || entry.collections.length === 0) return false; + if ( + !entry.collections.every( + selector => + record(selector) && + domain(selector.publisher_domain) && + (selector.collection_ids === undefined || strings(selector.collection_ids)) + ) + ) + return false; + return entry.collections.some( + selector => + domain(selector.publisher_domain) === owner && + (selector.collection_ids === undefined || (id !== undefined && selector.collection_ids.includes(id))) + ); +} + +/** Resolve one entry at a time: separate grants are alternatives, never merged across collection scopes. */ +function propertyScope(entry: Record, host: string, manifest: SupplyPathManifest): Set { + if (revoked(manifest, host)) return new Set(); + if (entry.authorization_type === 'publisher_properties') { + if (!Array.isArray(entry.publisher_properties) || entry.publisher_properties.length === 0) return new Set(); + const properties = records(manifest.properties).filter( + p => p.publisher_domain === undefined || domain(p.publisher_domain) === host + ); + const ids = new Set(); + try { + for (const raw of entry.publisher_properties) { + const selector = parsePublisherPropertySelector(raw); + if ('property_ids' in selector && !strings(selector.property_ids)) return new Set(); + if ('property_tags' in selector && !strings(selector.property_tags)) return new Set(); + for (const single of expandPublisherPropertySelector(selector)) { + if (domain(single.publisher_domain) !== host) continue; + for (const property of properties) { + if (typeof property.property_id !== 'string') continue; + if ( + single.selection_type === 'all' || + (single.selection_type === 'by_id' && single.property_ids.includes(property.property_id)) || + (single.selection_type === 'by_tag' && + strings(property.tags) && + property.tags.some(t => single.property_tags.includes(t))) + ) { + ids.add(property.property_id); + } + } + } + } + } catch { + return new Set(); + } + return ids; + } + if (entry.authorization_type === 'property_ids' && !strings(entry.property_ids)) return new Set(); + if (entry.authorization_type === 'property_tags' && !strings(entry.property_tags)) return new Set(); + // Reuse discovery's discriminator, missing-selector, and revocation semantics. + const result = resolveAgentProperties( + { ...manifest, authorized_agents: [entry as unknown as AuthorizedAgent] } as AdAgentsJson, + String(entry.url) + ); + return new Set( + result.properties + .filter(p => p.publisher_domain === undefined || domain(p.publisher_domain) === host) + .map(p => p.property_id) + .filter((id): id is string => typeof id === 'string' && id.length > 0) + ); +} + +export function isUnqualifiedPropertySelector(value: unknown): boolean { + return ( + record(value) && + Object.keys(value).every(key => + ['publisher_domain', 'publisher_domains', 'selection_type', 'property_ids', 'property_tags'].includes(key) + ) + ); +} + +const UNDERSTOOD_GRANT_FIELDS = new Set([ + 'url', + 'authorized_for', + 'authorization_type', + 'property_ids', + 'property_tags', + 'properties', + 'publisher_properties', + 'collections', + 'delegation_type', + 'exclusive', + 'signing_keys', + 'encryption_keys', + 'last_updated', +]); +function unsupportedConstraints(entry: Record): string[] { + // Unknown extensions may narrow authorization. They need a reviewed semantic + // version before this context-free verifier can safely accept the entry. + const unknown = Object.keys(entry).filter(key => !UNDERSTOOD_GRANT_FIELDS.has(key)); + for (const selector of records(entry.collections)) { + unknown.push( + ...Object.keys(selector) + .filter(key => !['publisher_domain', 'collection_ids'].includes(key)) + .map(key => `collections[].${key}`) + ); + } + for (const selector of records(entry.publisher_properties)) { + unknown.push( + ...Object.keys(selector) + .filter( + key => + !['publisher_domain', 'publisher_domains', 'selection_type', 'property_ids', 'property_tags'].includes(key) + ) + .map(key => `publisher_properties[].${key}`) + ); + } + return unknown; +} + +/** Bound nested input and worst-case selector work before any traversal. */ +function nodeCost(value: unknown): number { + const stack = [value]; + let cost = 0; + while (stack.length) { + const item = stack.pop(); + if (++cost > 32768) return Infinity; + if (typeof item === 'string' && item.length > 8192) return Infinity; + if (Array.isArray(item)) { + if (item.length > 1024) return Infinity; + stack.push(...item); + } else if (record(item)) { + const values = Object.values(item); + if (values.length > 1024) return Infinity; + stack.push(...values); + } + } + return cost; +} + +function limitVerdict(): SupplyPathVerdict { + const failure = { ok: false, failure: 'evaluation_limit_exceeded' as const }; + return { + semantics_version: '1', + state: 'unverified', + legs: { + owner_collection_declared: { ...failure }, + owner_distribution_carriage: { ...failure }, + owner_agent_declared: { ...failure }, + host_authorization: { ...failure }, + inventory_partner_domain: { ...failure }, + }, + }; +} + +export function evaluateSupplyPath(input: SupplyPathInput): SupplyPathVerdict { + const total = nodeCost(input); + if (!Number.isFinite(total)) return limitVerdict(); + const grants = nodeCost(input.hostManifest?.authorized_agents); + const properties = nodeCost(input.hostManifest?.properties); + const collections = records(input.ownerManifest?.collections).length; + if (!Number.isFinite(total) || grants * properties + Math.max(1, collections) * total * 4 > 4_000_000) { + return limitVerdict(); + } + // Bulk inquiry is existential over complete individual paths, not a union + // of owner collection A's carriage and collection B's host authorization. + if (input.collectionId === undefined) { + const collections = records(input.ownerManifest?.collections).filter( + c => typeof c.collection_id === 'string' && c.collection_id.length > 0 + ); + if (collections.length) { + const verdicts = collections.map(c => evaluateSupplyPath({ ...input, collectionId: c.collection_id as string })); + return verdicts.reduce((best, next) => + SUPPLY_PATH_STATES.indexOf(next.state) > SUPPLY_PATH_STATES.indexOf(best.state) ? next : best + ); + } + } + const owner = domain(input.ownerDomain); + const host = domain(input.hostDomain); + const agent = agentIdentity(input.agentUrl); + const ownerManifest = record(input.ownerManifest) ? input.ownerManifest : null; + const hostManifest = record(input.hostManifest) ? input.hostManifest : null; + const isRevoked = (role: 'owner' | 'host', publisher: string): boolean => { + const manifest = role === 'owner' ? ownerManifest : hostManifest; + return ( + (manifest !== null && revoked(manifest, publisher)) || + (input.heldRevocations?.[role] ?? []).some(value => domain(value) === publisher) + ); + }; + const collectionLeg: SupplyPathLegs['owner_collection_declared'] = { ok: false }; + const declared = records(ownerManifest?.collections); + const targets = declared.filter(c => c.collection_id === input.collectionId && typeof c.collection_id === 'string'); + if (!ownerManifest) collectionLeg.failure = 'manifest_not_found'; + else if (owner && isRevoked('owner', owner)) collectionLeg.failure = 'publisher_revoked'; + else if (!input.collectionId && !declared.length) collectionLeg.failure = 'no_collections_declared'; + else if (!owner || !input.collectionId?.trim() || targets.length !== 1) { + collectionLeg.failure = 'collection_not_declared'; + collectionLeg.detail = `owner declares ${declared.length} collection(s); none has an unambiguous collection_id "${input.collectionId}"`; + } else { + collectionLeg.ok = true; + if (typeof targets[0]!.kind === 'string') collectionLeg.detail = `kind: ${targets[0]!.kind}`; + } + + const carriage: SupplyPathLegs['owner_distribution_carriage'] = { ok: false }; + const entries = collectionLeg.ok + ? records(targets[0]!.distribution).filter(e => domain(e.publisher_domain) === host) + : []; + let claimed: string[] = []; + if (!collectionLeg.ok) carriage.failure = 'collection_leg_failed'; + else if (!host || !entries.length) carriage.failure = 'no_distribution_for_host'; + else { + const valid = entries.every( + e => + Object.keys(e).every(key => ['publisher_domain', 'property_ids', 'identifiers'].includes(key)) && + (e.property_ids === undefined || strings(e.property_ids)) && + (e.identifiers === undefined || + (Array.isArray(e.identifiers) && + e.identifiers.length > 0 && + e.identifiers.every( + i => + record(i) && + typeof i.type === 'string' && + i.type.length > 0 && + typeof i.value === 'string' && + i.value.length > 0 + ))) && + (e.property_ids !== undefined || e.identifiers !== undefined) + ); + claimed = [...new Set(entries.flatMap(e => (strings(e.property_ids) ? e.property_ids : [])))]; + if (!valid) { + carriage.failure = 'property_ids_unresolved'; + carriage.detail = 'Malformed distribution constraints'; + } else if (!claimed.length) { + carriage.ok = true; + carriage.detail = 'carriage asserted without host property_ids (identifiers only)'; + } else if (!hostManifest) { + carriage.failure = 'host_manifest_not_found'; + carriage.property_ids_unmatched = claimed; + } else { + const properties = records(hostManifest.properties).filter( + p => p.publisher_domain === undefined || domain(p.publisher_domain) === host + ); + const counts = new Map(); + for (const property of properties) counts.set(property.property_id, (counts.get(property.property_id) ?? 0) + 1); + const known = new Set([...counts].filter(([, count]) => count === 1).map(([id]) => id)); + carriage.property_ids_matched = claimed.filter(id => known.has(id)); + carriage.property_ids_unmatched = claimed.filter(id => !known.has(id)); + carriage.ok = carriage.property_ids_unmatched.length === 0; + if (!carriage.ok) carriage.failure = 'property_ids_unresolved'; + } + } + const ownerAgent: SupplyPathLegs['owner_agent_declared'] = !ownerManifest + ? { ok: false, failure: 'manifest_not_found' } + : agent && + records(ownerManifest.authorized_agents).some( + e => + agentIdentity(e.url) === agent && + owner && + coversCollection(e, owner, input.collectionId) && + !unsupportedConstraints(e).length + ) + ? { ok: true } + : { ok: false, failure: 'agent_not_declared_by_owner' }; + + const hostLeg: SupplyPathLegs['host_authorization'] = { ok: false }; + if (!hostManifest) hostLeg.failure = 'manifest_not_found'; + else { + const agents = agent ? records(hostManifest.authorized_agents).filter(e => agentIdentity(e.url) === agent) : []; + const covered = + owner && !isRevoked('host', owner) && !(host && isRevoked('owner', host)) + ? agents.filter(e => e.collections !== undefined && coversCollection(e, owner, input.collectionId)) + : []; + if (!agents.length) hostLeg.failure = 'no_agent_entry'; + else if (!covered.length) hostLeg.failure = 'collection_scope_mismatch'; + else { + const matched = + host && + !isRevoked('host', host) && + carriage.ok && + collectionLeg.ok && + covered.find(e => { + if (unsupportedConstraints(e).length) return false; + const scope = propertyScope(e, host, hostManifest); + const required = input.requiredHostPropertyIds ?? claimed; + if ( + input.requiredHostPropertyIds && + (!required.length || (claimed.length && !required.every(id => claimed.includes(id)))) + ) + return false; + // With identifier-only owner carriage, the host must affirmatively + // bind the collection to its own property scope. + if (!claimed.length) return false; + return required.length ? required.every(id => scope.has(id)) : scope.size > 0; + }); + if (!matched) { + const constraints = [...new Set(covered.flatMap(unsupportedConstraints))].sort(); + hostLeg.failure = covered.every(e => unsupportedConstraints(e).length) + ? 'unsupported_constraints' + : 'property_scope_mismatch'; + hostLeg.detail = constraints.length + ? `Unevaluated grant fields: ${constraints.join(', ')}` + : 'No grant proves the complete carried property scope'; + } else { + hostLeg.ok = true; + hostLeg.matched_entry = { + url: String(matched.url), + ...(typeof matched.authorization_type === 'string' ? { authorization_type: matched.authorization_type } : {}), + ...(typeof matched.delegation_type === 'string' ? { delegation_type: matched.delegation_type } : {}), + ...(Array.isArray(matched.collections) + ? { + collections: matched.collections.map(s => ({ + publisher_domain: String(s.publisher_domain), + ...(s.collection_ids !== undefined ? { collection_ids: [...s.collection_ids] } : {}), + })), + } + : {}), + }; + } + } + } + const partners = input.hostInventoryPartnerDomainsByFile + ? inventoryPartnersForInput(input) + : input.hostInventoryPartnerDomains; + const partner: SupplyPathLegs['inventory_partner_domain'] = + input.inventoryPartnerDomainEvaluated === false + ? { ok: false, failure: 'not_evaluated' } + : partners === null + ? { ok: false, failure: 'ads_txt_unavailable' } + : owner && partners.some(d => domain(d) === owner) + ? { ok: true } + : { ok: false, failure: 'not_declared' }; + const attested = collectionLeg.ok && entries.length > 0; + const state = + hostLeg.ok && collectionLeg.ok && carriage.ok + ? 'verified_owner_sold' + : partner.ok && + ownerAgent.ok && + collectionLeg.ok && + !((owner && isRevoked('host', owner)) || (host && isRevoked('host', host))) && + !(host && isRevoked('owner', host)) + ? 'host_delegated' + : attested + ? 'owner_attested' + : 'unverified'; + return { + semantics_version: '1', + ...(collectionLeg.ok ? { resolved_collection_id: input.collectionId } : {}), + state, + legs: { + owner_collection_declared: collectionLeg, + owner_distribution_carriage: carriage, + owner_agent_declared: ownerAgent, + host_authorization: hostLeg, + inventory_partner_domain: partner, + }, + }; +} + +/** Choose applicable IAB files from the carried host properties, never from catalog channel identifiers. */ +export function supplyPathAdsTxtPolicy(input: SupplyPathInput): { + files: Array<'ads.txt' | 'app-ads.txt'>; + requireAll: boolean; +} { + if (input.collectionId === undefined) { + const candidates = records(input.ownerManifest?.collections).filter( + c => typeof c.collection_id === 'string' && c.collection_id.length > 0 + ); + if (candidates.length) { + const policies = candidates.map(c => supplyPathAdsTxtPolicy({ ...input, collectionId: String(c.collection_id) })); + return { files: [...new Set(policies.flatMap(policy => policy.files))].sort(), requireAll: false }; + } + } + const collectionIds = new Set( + records(input.ownerManifest?.collections) + .filter(c => input.collectionId === undefined || c.collection_id === input.collectionId) + .flatMap(c => + records(c.distribution) + .filter(d => domain(d.publisher_domain) === domain(input.hostDomain)) + .flatMap(d => (strings(d.property_ids) ? d.property_ids : [])) + ) + ); + const requested = input.requiredHostPropertyIds ? new Set(input.requiredHostPropertyIds) : collectionIds; + const properties = records(input.hostManifest?.properties).filter(p => requested.has(String(p.property_id))); + const files = new Set<'ads.txt' | 'app-ads.txt'>(); + for (const property of properties) { + if (property.property_type === 'website') files.add('ads.txt'); + if (property.property_type === 'mobile_app' || property.property_type === 'ctv_app') files.add('app-ads.txt'); + } + // Unknown surfaces have no applicable typed evidence. Without a host + // manifest, the canonical interim path can only inspect domain-level files. + if (!input.hostManifest || !properties.length) return { files: ['app-ads.txt', 'ads.txt'], requireAll: false }; + return { files: [...files].sort(), requireAll: true }; +} + +export function combineInventoryPartnerDomains(contents: Array, requireAll: boolean): string[] | null { + if (!contents.length || (requireAll && contents.some(c => c === null))) return null; + const fetched = contents.filter((c): c is string => c !== null).map(parseInventoryPartnerDomains); + if (!fetched.length) return null; + return requireAll + ? fetched[0]!.filter(d => fetched.every(domains => domains.includes(d))) + : [...new Set(fetched.flat())]; +} + +/** Select parsed IAB evidence for one complete path; called after bulk inquiry expansion. */ +export function inventoryPartnersForInput(input: SupplyPathInput): string[] | null { + const policy = supplyPathAdsTxtPolicy(input); + const values = policy.files.map(file => input.hostInventoryPartnerDomainsByFile?.[file] ?? null); + if (!values.length || (policy.requireAll && values.some(value => value === null))) return null; + const fetched = values.filter((value): value is string[] => value !== null); + if (!fetched.length) return null; + return policy.requireAll + ? fetched[0]!.filter(domain => fetched.every(value => value.includes(domain))) + : [...new Set(fetched.flat())]; +} diff --git a/src/lib/supply-path/fetch-evidence.ts b/src/lib/supply-path/fetch-evidence.ts new file mode 100644 index 000000000..0dcff0fb9 --- /dev/null +++ b/src/lib/supply-path/fetch-evidence.ts @@ -0,0 +1,230 @@ +import { withAbortSignal } from '../protocols/abort'; +import { createHash } from 'node:crypto'; +import { parse } from 'secure-json-parse'; +import { SsrfRefusedError, SSRF_TRANSIENT_CODES, type SsrfFetchResult } from '../net/ssrf-fetch'; +import { ssrfSafeFetchAdAgents, AdAgentsRedirectRefusedError } from '../discovery/adagents-redirects'; +import type { AuthoritativeSupplyPathOptions, SupplyPathEvidence, SupplyPathManifest } from './types'; +import { defaultSupplyPathRevocations, parseRevocations } from './revocations'; +import { record } from './validation'; + +export function boundedOption(value: number | undefined, fallback: number, maximum: number, name: string): number { + if (value === undefined) return fallback; + if (!Number.isSafeInteger(value) || value <= 0 || value > maximum) + throw new TypeError(`${name} must be an integer between 1 and ${maximum}`); + return value; +} + +/** A verification-local evidence session. No cached verdict survives a request. */ +export class SupplyPathEvidenceSession { + readonly evidence: SupplyPathEvidence[] = []; + readonly revocations = new Map(); + readonly signal: AbortSignal; + private readonly maxBodyBytes: number; + private readonly timeoutMs: number; + private readonly timer: ReturnType; + private readonly controller = new AbortController(); + private readonly abort: () => void; + private readonly responses = new Map>(); + private readonly provenance = new WeakMap(); + private observedBytes = 0; + private readonly documents = new Map>(); + + constructor(private readonly options: AuthoritativeSupplyPathOptions) { + this.timeoutMs = boundedOption(options.timeoutMs, 15_000, 60_000, 'timeoutMs'); + this.maxBodyBytes = boundedOption(options.maxBodyBytes, 256 * 1024, 20 * 1024 * 1024, 'maxBodyBytes'); + this.signal = this.controller.signal; + this.abort = () => this.controller.abort(options.signal?.reason); + options.signal?.addEventListener('abort', this.abort, { once: true }); + if (options.signal?.aborted) this.abort(); + this.timer = setTimeout( + () => this.controller.abort(new Error('Supply-path verification deadline exceeded')), + this.timeoutMs + ); + } + close(): void { + clearTimeout(this.timer); + this.controller.abort(new Error('Supply-path evidence session closed')); + this.options.signal?.removeEventListener('abort', this.abort); + } + adagents(publisher: string): Promise { + let pending = this.documents.get(publisher); + if (!pending) { + pending = this.readAndRemember(publisher); + this.documents.set(publisher, pending); + } + return pending; + } + read( + publisher: string, + kind: SupplyPathEvidence['kind'], + url: string, + pointer = false + ): Promise { + const key = JSON.stringify([publisher, kind, url, pointer]); + let pending = this.responses.get(key); + if (!pending) { + pending = this.fetchEvidence(publisher, kind, url, pointer); + this.responses.set(key, pending); + } + return pending; + } + private async fetchEvidence( + publisher: string, + kind: SupplyPathEvidence['kind'], + url: string, + pointer = false + ): Promise { + this.signal.throwIfAborted(); + try { + if (this.observedBytes >= 64 * 1024 * 1024) throw new Error('evidence_budget_exceeded'); + const parsed = new URL(url); + if ( + parsed.protocol !== 'https:' || + parsed.username || + parsed.password || + parsed.hash || + (parsed.port && parsed.port !== '443') + ) { + throw new Error('invalid_evidence_url'); + } + const response = await ssrfSafeFetchAdAgents( + url, + { + timeoutMs: this.timeoutMs, + maxBodyBytes: this.maxBodyBytes, + signal: this.signal, + trustedFetchFn: this.options.trustedFetchFn, + headers: { Accept: kind === 'adagents' ? 'application/json' : 'text/plain', 'Cache-Control': 'no-cache' }, + }, + pointer ? { mode: 'none' } : { mode: 'same-origin', originUrl: url, maxRedirects: 3 }, + result => { + this.observedBytes += result.body.byteLength; + const evidence: SupplyPathEvidence = { + kind, + publisher_domain: publisher, + requested_url: url, + resolved_url: result.url, + fetched_at: new Date().toISOString(), + status: result.status, + byte_length: result.body.byteLength, + sha256: createHash('sha256').update(result.body).digest('hex'), + connection_pinned: result.connectionPinned, + ...(result.status >= 300 && result.status < 400 && result.headers.location + ? { delegated_to: result.headers.location } + : {}), + ...(this.options.retainEvidenceBodies ? { body_base64: Buffer.from(result.body).toString('base64') } : {}), + }; + this.evidence.push(evidence); + this.provenance.set(result, evidence); + if (this.observedBytes > 64 * 1024 * 1024) throw new Error('evidence_budget_exceeded'); + } + ); + if (response.status === 404 && kind !== 'adagents') return { ...response, body: new Uint8Array() }; + if (response.status !== 200) return null; + const contentType = response.headers['content-type']?.split(';')[0]?.trim().toLowerCase(); + const validType = + kind === 'adagents' + ? contentType === 'application/json' || contentType?.endsWith('+json') + : contentType === 'text/plain'; + if (!validType) throw new Error('invalid_content_type'); + return response; + } catch (error) { + this.signal.throwIfAborted(); + const code = + error instanceof SsrfRefusedError || error instanceof AdAgentsRedirectRefusedError + ? error.code + : error instanceof Error && + ['invalid_evidence_url', 'invalid_content_type', 'evidence_budget_exceeded'].includes(error.message) + ? error.message + : 'fetch_failed'; + this.evidence.push({ + kind, + publisher_domain: publisher, + requested_url: url, + fetched_at: new Date().toISOString(), + error: code, + }); + // Preserve the repository's explicit network-policy refusal boundary. + if (error instanceof SsrfRefusedError && !SSRF_TRANSIENT_CODES.has(error.code)) throw error; + return null; + } + } + private parseManifest(publisher: string, response: SsrfFetchResult): SupplyPathManifest | null { + try { + const document: unknown = parse(new TextDecoder('utf-8', { fatal: true }).decode(response.body)); + if (!record(document)) throw new Error('not_object'); + return document; + } catch { + this.evidence.push({ + kind: 'adagents', + publisher_domain: publisher, + requested_url: response.url, + fetched_at: new Date().toISOString(), + error: 'invalid_document', + }); + return null; + } + } + private documentError(publisher: string, response: SsrfFetchResult, error: string): void { + this.evidence.push({ + kind: 'adagents', + publisher_domain: publisher, + requested_url: response.url, + fetched_at: new Date().toISOString(), + error, + }); + } + private async readAdagents(publisher: string): Promise { + const url = `https://${publisher}/.well-known/adagents.json`; + const initial = await this.read(publisher, 'adagents', url); + if (!initial) return null; + let manifest = this.parseManifest(publisher, initial); + if (!manifest) return null; + if (manifest.authoritative_location !== undefined || manifest.superseded_by !== undefined) { + const target = manifest.authoritative_location ?? manifest.superseded_by; + if ( + typeof target !== 'string' || + (manifest.authoritative_location !== undefined && + (manifest.authorized_agents !== undefined || manifest.superseded_by !== undefined)) + ) { + this.documentError(publisher, initial, 'ambiguous_authoritative_pointer'); + return null; + } + const evidence = this.provenance.get(initial); + if (evidence) evidence.delegated_to = target; + const response = await this.read(publisher, 'adagents', target, true); + if (!response) return null; + manifest = this.parseManifest(publisher, response); + if (!manifest) return null; + if (manifest.authoritative_location !== undefined || manifest.superseded_by !== undefined) { + this.documentError(publisher, response, 'chained_authoritative_pointer'); + return null; + } + } + if (!Array.isArray(manifest.authorized_agents)) { + this.documentError(publisher, initial, 'missing_authorized_agents'); + return null; + } + return manifest; + } + private async readAndRemember(publisher: string): Promise { + const manifest = await this.readAdagents(publisher); + const observed = parseRevocations(manifest?.revoked_publisher_domains); + if (observed === null) { + this.evidence.push({ + kind: 'adagents', + publisher_domain: publisher, + requested_url: `https://${publisher}/.well-known/adagents.json`, + fetched_at: new Date().toISOString(), + error: 'invalid_revocations', + }); + throw new TypeError('Invalid publisher revocation evidence'); + } + const held = await withAbortSignal([this.signal], undefined, () => + (this.options.revocationStore ?? defaultSupplyPathRevocations).observe(publisher, observed ?? []) + ); + this.signal.throwIfAborted(); + this.revocations.set(publisher, held); + return manifest ? { ...manifest, revoked_publisher_domains: [...held] } : null; + } +} diff --git a/src/lib/supply-path/index.ts b/src/lib/supply-path/index.ts new file mode 100644 index 000000000..4bccd3245 --- /dev/null +++ b/src/lib/supply-path/index.ts @@ -0,0 +1,13 @@ +export * from './types'; +export { verifySupplyPath } from './verify'; +export { evaluateSupplyPath, parseInventoryPartnerDomains, SUPPLY_PATH_STATES } from './evaluate'; +export { + annotateProductsSupplyPaths, + type ProductSupplyPathAnnotation, + type ProductSupplyPathOptions, +} from './products'; +export { + InMemorySupplyPathRevocationStore, + type SupplyPathRevocationStore, + type SupplyPathRevocation, +} from './revocations'; diff --git a/src/lib/supply-path/products.ts b/src/lib/supply-path/products.ts new file mode 100644 index 000000000..701b8e4b5 --- /dev/null +++ b/src/lib/supply-path/products.ts @@ -0,0 +1,186 @@ +import type { SinglePublisherPropertySelector } from '../discovery/types'; +import { verifySupplyPath, verifyAuthoritativeSupplyPath } from './verify'; +import { SUPPLY_PATH_STATES, isUnqualifiedPropertySelector } from './evaluate'; +import { boundedOption, SupplyPathEvidenceSession } from './fetch-evidence'; +import { domain, record, strings, validateSupplyPathRequest } from './validation'; +import { + parsePublisherPropertySelector, + expandPublisherPropertySelector, +} from '../discovery/publisher-property-selector'; +import type { + SupplyPathRequest, + SupplyPathState, + RegistrySupplyPathResult, + AuthoritativeSupplyPathResult, + VerifySupplyPathOptions, +} from './types'; + +export interface ProductSupplyPathAnnotation { + /** Weakest external owner/host/collection path. Not a whole-product authorization decision. */ + supply_path_state?: SupplyPathState; + supply_path_verification?: ( + | { source: 'registry'; scope: 'owner_host_collection'; paths: RegistrySupplyPathResult[] } + | { source: 'authoritative'; scope: 'product_properties'; paths: AuthoritativeSupplyPathResult[] } + ) & { errors: string[] }; +} +export type ProductSupplyPathOptions = VerifySupplyPathOptions & { + /** Maximum distinct paths in one discovery response. Default 64, max 256. */ + maxPaths?: number; + /** Overall batch deadline, including all paths. Default 15 seconds, max 60 seconds. */ + timeoutMs?: number; + signal?: AbortSignal; +}; + +/** + * Annotate products with external-domain collection paths. Preserves actual + * seller products, order, and all unrelated fields. Seller-authored verification + * fields are replaced. No result means no evidence, never a synthetic product. + * + * Authoritative mode also proves the selected host property scope. The registry + * endpoint accepts only path identity. Neither mode supplies placement, country, + * or time context or replaces the caller's buying policy. + */ +export async function annotateProductsSupplyPaths( + products: readonly T[], + agentUrl: string, + options: ProductSupplyPathOptions = { source: 'authoritative' } +): Promise> { + const maxPaths = boundedOption(options.maxPaths, 64, 256, 'maxPaths'); + const requests = new Map(); + const selections = products.map(product => { + const value = product as Record; + const keys: string[] = []; + const errors: string[] = []; + if (value.collections === undefined) return { keys, errors }; + if ( + !Array.isArray(value.collections) || + !value.collections.length || + !Array.isArray(value.publisher_properties) || + !value.publisher_properties.length || + value.collections.length > 1024 || + value.publisher_properties.length > 1024 || + value.collections.some(s => record(s) && Array.isArray(s.collection_ids) && s.collection_ids.length > 1024) || + value.publisher_properties.some( + s => + record(s) && + [s.publisher_domains, s.property_ids, s.property_tags].some(v => Array.isArray(v) && v.length > 1024) + ) + ) { + return { keys, errors: ['invalid_product_selectors'] }; + } + try { + if (!value.publisher_properties.every(isUnqualifiedPropertySelector)) + throw new Error('unsupported_product_selector_fields'); + const propertySelectors = value.publisher_properties.flatMap(raw => + expandPublisherPropertySelector(parsePublisherPropertySelector(raw)) + ); + const hosts = [...new Set(propertySelectors.map(s => s.publisher_domain))]; + for (const selector of value.collections) { + if ( + !record(selector) || + !Object.keys(selector).every(key => ['publisher_domain', 'collection_ids'].includes(key)) || + !domain(selector.publisher_domain) || + !strings(selector.collection_ids) + ) + throw new Error('invalid_collection_selector'); + const owner = domain(selector.publisher_domain)!; + for (const host of hosts) { + if (domain(host) === owner) continue; + for (const id of selector.collection_ids) { + const request = validateSupplyPathRequest({ + owner_domain: owner, + host_domain: host, + agent_url: agentUrl, + collection_id: id, + }); + const selectors = propertySelectors.filter(s => s.publisher_domain === host); + const key = JSON.stringify({ request, selectors }); + if (!requests.has(key) && requests.size >= maxPaths) { + if (!errors.includes('path_limit_exceeded')) errors.push('path_limit_exceeded'); + return { keys, errors }; + } + requests.set(key, { request, selectors }); + if (!keys.includes(key)) keys.push(key); + } + } + } + } catch { + errors.push('invalid_product_selectors'); + } + return { keys, errors }; + }); + const outcomes = new Map(); + // Bound fan-out without allocating one network operation per product. + const pending = [...requests.entries()]; + let position = 0; + const timeoutMs = boundedOption(options.timeoutMs, 15_000, 60_000, 'timeoutMs'); + const controller = new AbortController(); + const onAbort = () => controller.abort(options.signal?.reason); + options.signal?.addEventListener('abort', onAbort, { once: true }); + if (options.signal?.aborted) onAbort(); + const timer = setTimeout(() => controller.abort(new Error('Supply-path discovery deadline exceeded')), timeoutMs); + const session = + options.source === 'authoritative' + ? new SupplyPathEvidenceSession({ ...options, signal: controller.signal }) + : undefined; + let onDeadline: () => void = () => {}; + try { + controller.signal.throwIfAborted(); + const aborted = new Promise((_, reject) => { + onDeadline = () => reject(controller.signal.reason); + controller.signal.addEventListener('abort', onDeadline, { once: true }); + }); + await Promise.race([ + aborted, + Promise.all( + Array.from({ length: Math.min(4, pending.length) }, async () => { + while (position < pending.length) { + controller.signal.throwIfAborted(); + const [key, { request, selectors }] = pending[position++]!; + outcomes.set( + key, + options.source === 'authoritative' + ? await verifyAuthoritativeSupplyPath(request, { ...options, propertySelectors: selectors }, session!) + : await verifySupplyPath(request, options) + ); + } + }) + ), + ]); + } finally { + session?.close(); + controller.abort(new Error('Supply-path annotation batch closed')); + clearTimeout(timer); + options.signal?.removeEventListener('abort', onAbort); + controller.signal.removeEventListener('abort', onDeadline); + } + return products.map((product, index) => { + const { + supply_path_state: _state, + supply_path_verification: _verification, + ...rest + } = product as T & ProductSupplyPathAnnotation; + void _state; + void _verification; + const { keys, errors } = selections[index]!; + if (!keys.length && !errors.length) return rest as T & ProductSupplyPathAnnotation; + const paths = keys.map(key => outcomes.get(key)!); + const state = errors.length + ? 'unverified' + : paths.reduce( + (least, result) => + SUPPLY_PATH_STATES.indexOf(result.state) < SUPPLY_PATH_STATES.indexOf(least) ? result.state : least, + 'verified_owner_sold' + ); + return { + ...rest, + supply_path_state: state, + supply_path_verification: { + source: options.source, + scope: options.source === 'authoritative' ? 'product_properties' : 'owner_host_collection', + paths, + errors, + }, + } as T & ProductSupplyPathAnnotation; + }); +} diff --git a/src/lib/supply-path/revocations.ts b/src/lib/supply-path/revocations.ts new file mode 100644 index 000000000..acb54a290 --- /dev/null +++ b/src/lib/supply-path/revocations.ts @@ -0,0 +1,52 @@ +import { domain, record } from './validation'; + +export interface SupplyPathRevocation { + publisher_domain: string; + revoked_at: string; +} +/** + * Atomic, authority-scoped seven-day revocation hold. Durable implementations + * must preserve the first observation of each (publisher_domain, revoked_at) + * tuple, and reject on storage failure instead of returning an empty set. + */ +export interface SupplyPathRevocationStore { + observe(authority: string, revoked: readonly SupplyPathRevocation[]): Promise; +} + +/** Process-local default. Use a durable shared store across workers/restarts. */ +export class InMemorySupplyPathRevocationStore implements SupplyPathRevocationStore { + private readonly entries = new Map(); + async observe(authority: string, revoked: readonly SupplyPathRevocation[]): Promise { + const now = Date.now(); + for (const [key, value] of this.entries) if (value.expires <= now) this.entries.delete(key); + for (const entry of revoked) { + const key = JSON.stringify([authority, entry.publisher_domain, entry.revoked_at]); + if (this.entries.has(key)) continue; + // Never evict a live revocation to accommodate counterparty-controlled data. + if (this.entries.size >= 10000) throw new Error('Supply-path revocation store capacity exceeded'); + this.entries.set(key, { authority, entry: { ...entry }, expires: now + 7 * 86400000 }); + } + return [...this.entries.values()].filter(value => value.authority === authority).map(value => ({ ...value.entry })); + } +} +export const defaultSupplyPathRevocations = new InMemorySupplyPathRevocationStore(); + +export function parseRevocations(value: unknown): SupplyPathRevocation[] | null { + if (value === undefined) return []; + if (!Array.isArray(value) || value.length > 1024) return null; + const entries: SupplyPathRevocation[] = []; + for (const raw of value) { + const publisher = domain(record(raw) ? raw.publisher_domain : raw); + if (!publisher) return null; + const timestamp = record(raw) ? raw.revoked_at : undefined; + if (timestamp !== undefined && (typeof timestamp !== 'string' || !Number.isFinite(Date.parse(timestamp)))) + return null; + // Legacy domain-only revocations still hold from observation, never from a + // publisher-controlled timestamp. The marker is stable across refreshes. + entries.push({ + publisher_domain: publisher, + revoked_at: typeof timestamp === 'string' ? timestamp : 'unspecified', + }); + } + return entries; +} diff --git a/src/lib/supply-path/supply-path.type-checks.ts b/src/lib/supply-path/supply-path.type-checks.ts new file mode 100644 index 000000000..9d95d3b21 --- /dev/null +++ b/src/lib/supply-path/supply-path.type-checks.ts @@ -0,0 +1,59 @@ +import { + verifySupplyPath, + annotateProductsSupplyPaths, + type AuthorizationCollectionSelector, + type ProductCollectionSelector, + type CollectionDistribution, + type AuthorizedAgent, + type AdagentsAuthorizedAgent, +} from '../index'; + +const bulk: AuthorizationCollectionSelector = { publisher_domain: 'owner.example' }; +const product: ProductCollectionSelector = { publisher_domain: 'owner.example', collection_ids: ['channel'] }; +// @ts-expect-error Product selectors cannot use authorization bulk grants. +const invalidProduct: ProductCollectionSelector = bulk; +// @ts-expect-error Explicit product selection cannot be empty. +const emptyProduct: ProductCollectionSelector = { publisher_domain: 'owner.example', collection_ids: [] }; +const byId: CollectionDistribution = { publisher_domain: 'host.example', property_ids: ['ctv'] }; +const byIdentifier: CollectionDistribution = { + publisher_domain: 'host.example', + identifiers: [{ type: 'publisher_channel_id', value: 'channel' }], +}; +const both: CollectionDistribution = { ...byId, identifiers: [{ type: 'publisher_channel_id', value: 'channel' }] }; +// @ts-expect-error A distribution entry must identify carriage. +const emptyDistribution: CollectionDistribution = { publisher_domain: 'host.example' }; +const discoveryGrant: AuthorizedAgent = { + url: 'https://agent.example', + authorized_for: 'channel', + collections: [bulk], +}; +const registryGrant: AdagentsAuthorizedAgent = { + url: 'https://agent.example', + authorized_for: 'channel', + authorization_type: 'property_ids', + property_ids: ['ctv'], + collections: [bulk], +}; +const request = { + owner_domain: 'owner.example', + host_domain: 'host.example', + agent_url: 'https://agent.example', + collection_id: 'channel', +}; +async function check(): Promise { + const live = await verifySupplyPath(request); + live.sources.evidence[0]?.sha256; + const cached = await verifySupplyPath(request, { source: 'registry' }); + cached.legs.host_authorization.matched_entry?.collections?.[0]?.collection_ids; + const products = await annotateProductsSupplyPaths( + [{ product_id: 'seller-product', collections: [product] }], + request.agent_url + ); + products[0]?.product_id; + const annotation = products[0]?.supply_path_verification; + if (annotation?.source === 'authoritative') annotation.paths[0]?.sources.evidence; + // @ts-expect-error Cached registry results cannot be passed off as live evidence. + const forged: typeof live = cached; + void forged; +} +void [invalidProduct, emptyProduct, byId, byIdentifier, both, emptyDistribution, discoveryGrant, registryGrant, check]; diff --git a/src/lib/supply-path/types.ts b/src/lib/supply-path/types.ts new file mode 100644 index 000000000..78aea62e9 --- /dev/null +++ b/src/lib/supply-path/types.ts @@ -0,0 +1,167 @@ +/** Supply-path contract from adcontextprotocol/adcp#6897. */ +import type { SsrfFetchOptions } from '../net/ssrf-fetch'; +import type { RegistryClient } from '../registry'; + +/** Untrusted evidence. The evaluator validates every authorization-relevant field. */ +export interface SupplyPathManifest { + authorized_agents?: unknown; + properties?: unknown; + collections?: unknown; + revoked_publisher_domains?: unknown; + [key: string]: unknown; +} + +export type SupplyPathState = 'verified_owner_sold' | 'host_delegated' | 'owner_attested' | 'unverified'; + +export type OwnerCollectionFailure = + | 'manifest_not_found' + | 'no_collections_declared' + | 'collection_not_declared' + | 'publisher_revoked'; + +export type OwnerCarriageFailure = + | 'collection_leg_failed' + | 'no_distribution_for_host' + | 'property_ids_unresolved' + | 'host_manifest_not_found'; + +export type OwnerAgentFailure = 'manifest_not_found' | 'agent_not_declared_by_owner'; + +export type HostAuthorizationFailure = + | 'manifest_not_found' + | 'no_agent_entry' + | 'collection_scope_mismatch' + | 'property_scope_mismatch' + | 'unsupported_constraints'; + +export interface Leg { + ok: boolean; + failure?: F | 'evaluation_limit_exceeded'; + detail?: string; +} + +export interface SupplyPathLegs { + /** Owner's adagents.json declares the collection (kind noted in detail). */ + owner_collection_declared: Leg; + /** The collection's distribution[] names the host, and any property_ids resolve in the host manifest. */ + owner_distribution_carriage: Leg & { + property_ids_matched?: string[]; + property_ids_unmatched?: string[]; + }; + /** Owner's own adagents.json lists the sales agent. */ + owner_agent_declared: Leg; + /** Host adagents.json authorizes the agent for the property, collection-scoped. */ + host_authorization: Leg & { + matched_entry?: { + url: string; + authorization_type?: string; + delegation_type?: string; + collections?: Array<{ publisher_domain: string; collection_ids?: string[] }>; + }; + }; + /** Host ads.txt / app-ads.txt names the owner via inventorypartnerdomain=. */ + inventory_partner_domain: Leg<'not_declared' | 'ads_txt_unavailable' | 'not_evaluated'>; +} + +export interface SupplyPathVerdict { + /** Version of the canonical evaluator semantics and shared vector corpus. */ + semantics_version: '1'; + /** Concrete winning collection, including domain-level inquiries. */ + resolved_collection_id?: string; + state: SupplyPathState; + legs: SupplyPathLegs; +} + +export interface SupplyPathInput { + /** Canonicalized owner (channel publisher) domain. */ + ownerDomain: string; + /** Canonicalized host (carrying property publisher) domain. */ + hostDomain: string; + /** Seller agent URL as the buyer sees it. */ + agentUrl: string; + /** Owner-assigned collection ID. Omit to verify the path at domain level (bulk deals). */ + collectionId?: string; + /** Optional concrete product scope, resolved from the host manifest. Empty means unresolved. */ + requiredHostPropertyIds?: string[]; + ownerManifest: SupplyPathManifest | null; + hostManifest: SupplyPathManifest | null; + /** + * inventorypartnerdomain values from the host's ads.txt/app-ads.txt, + * already canonicalized. null = the files could not be fetched (distinct + * from fetched-and-absent, which is an empty array). + */ + hostInventoryPartnerDomains: string[] | null; + /** Per-file parsed evidence, so bulk inquiries evaluate each collection's applicable surfaces independently. */ + hostInventoryPartnerDomainsByFile?: Partial>; + /** Previously observed authority-scoped revocations, even when a current manifest is unavailable. */ + heldRevocations?: { owner?: string[]; host?: string[] }; + /** False when the caller deliberately skipped IAB evidence after host authorization succeeded. */ + inventoryPartnerDomainEvaluated?: boolean; +} + +/** Canonical registry request; collection_id omission is a domain-level inquiry. */ +export interface SupplyPathRequest { + owner_domain: string; + host_domain: string; + agent_url: string; + collection_id?: string; +} + +export interface RegistrySupplyPathResult extends SupplyPathRequest, Omit { + legs: { [K in keyof SupplyPathLegs]: Omit & { failure?: string } }; + sources: { owner_adagents_url: string; host_adagents_url: string; cached: boolean }; + checked_at: string; +} + +export interface SupplyPathEvidence { + kind: 'adagents' | 'ads.txt' | 'app-ads.txt'; + publisher_domain: string; + requested_url: string; + resolved_url?: string; + fetched_at: string; + status?: number; + /** Hash of the exact decompressed response bytes, including pointer/redirect bodies. */ + sha256?: string; + byte_length?: number; + connection_pinned?: boolean; + error?: string; + /** Present for HTTP redirects and authoritative_location delegation. */ + delegated_to?: string; + /** Exact bytes for audit/replay when retainEvidenceBodies is enabled. */ + body_base64?: string; +} + +export interface AuthoritativeSupplyPathResult extends RegistrySupplyPathResult { + source: 'authoritative'; + legs: SupplyPathLegs; + property_selectors?: import('../discovery/types').SinglePublisherPropertySelector[]; + sources: RegistrySupplyPathResult['sources'] & { + cached: false; + evidence: SupplyPathEvidence[]; + held_revocations: Array<{ authority: string; entries: readonly import('./revocations').SupplyPathRevocation[] }>; + }; +} + +export interface AuthoritativeSupplyPathOptions { + source: 'authoritative'; + /** Defaults to a process-local seven-day hold; supply durable storage across workers/restarts. */ + revocationStore?: import('./revocations').SupplyPathRevocationStore; + /** Optional product property scope. Every selected host property must be proven. */ + propertySelectors?: import('../discovery/types').SinglePublisherPropertySelector[]; + /** Overall deadline, including all evidence and redirect fetches. Default 15 seconds, max 60 seconds. */ + timeoutMs?: number; + /** Per-response decompressed byte cap. Default 256 KiB, max 20 MiB. */ + maxBodyBytes?: number; + signal?: AbortSignal; + /** Default false. Bodies contain counterparty-controlled content; store as opaque evidence. */ + retainEvidenceBodies?: boolean; + /** Trusted egress implementation; takes responsibility for DNS and address policy. */ + trustedFetchFn?: SsrfFetchOptions['trustedFetchFn']; +} + +export interface RegistrySupplyPathOptions { + source: 'registry'; + /** Caller-configured registry; omitted uses the canonical registry client. */ + registry?: Pick; +} +export type VerifySupplyPathOptions = AuthoritativeSupplyPathOptions | RegistrySupplyPathOptions; diff --git a/src/lib/supply-path/validation.ts b/src/lib/supply-path/validation.ts new file mode 100644 index 000000000..78d56b144 --- /dev/null +++ b/src/lib/supply-path/validation.ts @@ -0,0 +1,120 @@ +import { isIP } from 'node:net'; +import { canonicalizeAgentUrl } from '../discovery/resolve-agent-properties'; +import type { SupplyPathRequest } from './types'; + +export function record(value: unknown): value is Record { + return value !== null && typeof value === 'object' && !Array.isArray(value); +} +export function records(value: unknown): Record[] { + return Array.isArray(value) ? value.filter(record) : []; +} +export function strings(value: unknown): value is string[] { + return Array.isArray(value) && value.length > 0 && value.every(v => typeof v === 'string' && v.trim().length > 0); +} +/** Domain identity never strips www or conflates sibling publisher namespaces. */ +export function domain(value: unknown): string | null { + if (typeof value !== 'string') return null; + const normalized = value.toLowerCase().replace(/\.$/, ''); + if (normalized.length > 253 || isIP(normalized) || !normalized.includes('.')) return null; + return normalized.split('.').every(label => /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(label)) ? normalized : null; +} +export function agentIdentity(value: unknown): string | null { + if (typeof value !== 'string' || /[\s\x00-\x1f\x7f]/.test(value)) return null; + const canonical = canonicalizeAgentUrl(value); + return canonical?.startsWith('https://') ? canonical : null; +} +export function validateSupplyPathRequest(input: SupplyPathRequest): SupplyPathRequest { + if (!record(input)) throw new TypeError('Supply-path request must be an object'); + const owner = domain(input.owner_domain); + const host = domain(input.host_domain); + if (!owner || !host) throw new TypeError('owner_domain and host_domain must be DNS publisher domains'); + if (!agentIdentity(input.agent_url)) throw new TypeError('agent_url must be an HTTPS URL without credentials'); + if ( + input.collection_id !== undefined && + (typeof input.collection_id !== 'string' || !input.collection_id.trim() || input.collection_id.length > 256) + ) { + throw new TypeError('collection_id must be a non-empty string of at most 256 characters'); + } + return { + owner_domain: owner, + host_domain: host, + agent_url: input.agent_url, + ...(input.collection_id !== undefined ? { collection_id: input.collection_id } : {}), + }; +} + +/** Runtime boundary for cached remote verdicts. Unknown extensions are preserved. */ +export function assertRegistrySupplyPathResult( + value: unknown, + request: SupplyPathRequest +): asserts value is import('./types').RegistrySupplyPathResult { + const fail = (): never => { + throw new TypeError('Invalid registry supply-path response'); + }; + if (!record(value) || value.semantics_version !== '1' || !record(value.legs) || !record(value.sources)) return fail(); + if (!['verified_owner_sold', 'host_delegated', 'owner_attested', 'unverified'].includes(String(value.state))) + return fail(); + if ( + domain(value.owner_domain) !== request.owner_domain || + domain(value.host_domain) !== request.host_domain || + agentIdentity(value.agent_url) !== agentIdentity(request.agent_url) || + value.collection_id !== request.collection_id + ) + return fail(); + if ( + typeof value.checked_at !== 'string' || + !Number.isFinite(Date.parse(value.checked_at)) || + typeof value.sources.cached !== 'boolean' + ) + return fail(); + for (const key of ['owner_adagents_url', 'host_adagents_url']) { + if (typeof value.sources[key] !== 'string') return fail(); + try { + const url = new URL(value.sources[key]); + if (url.protocol !== 'https:' || url.username || url.password) return fail(); + } catch { + return fail(); + } + } + const failures: Record = { + owner_collection_declared: ['manifest_not_found', 'no_collections_declared', 'collection_not_declared'], + owner_distribution_carriage: [ + 'collection_leg_failed', + 'no_distribution_for_host', + 'property_ids_unresolved', + 'host_manifest_not_found', + ], + owner_agent_declared: ['manifest_not_found', 'agent_not_declared_by_owner'], + host_authorization: [ + 'manifest_not_found', + 'no_agent_entry', + 'collection_scope_mismatch', + 'property_scope_mismatch', + ], + inventory_partner_domain: ['not_declared', 'ads_txt_unavailable'], + }; + for (const key of Object.keys(failures)) { + const leg = value.legs[key]; + if (!record(leg) || typeof leg.ok !== 'boolean' || (leg.detail !== undefined && typeof leg.detail !== 'string')) + return fail(); + if (leg.ok ? leg.failure !== undefined : typeof leg.failure !== 'string' || !leg.failure.length) return fail(); + for (const ids of ['property_ids_matched', 'property_ids_unmatched']) { + if (leg[ids] !== undefined && (!Array.isArray(leg[ids]) || !leg[ids].every(id => typeof id === 'string'))) + return fail(); + } + } + const ok = (key: string) => (value.legs as Record>)[key]?.ok === true; + // Check the registry's documented ladder; do not silently recompute a remote + // verdict using assumptions about evidence that was not returned. + if ( + value.state === 'verified_owner_sold' && + !(ok('owner_collection_declared') && ok('owner_distribution_carriage') && ok('host_authorization')) + ) + return fail(); + if ( + value.state === 'host_delegated' && + !(ok('owner_collection_declared') && ok('owner_agent_declared') && ok('inventory_partner_domain')) + ) + return fail(); + if (value.state === 'owner_attested' && !ok('owner_collection_declared')) return fail(); +} diff --git a/src/lib/supply-path/verify.ts b/src/lib/supply-path/verify.ts new file mode 100644 index 000000000..8bacf58fb --- /dev/null +++ b/src/lib/supply-path/verify.ts @@ -0,0 +1,153 @@ +import { withAbortSignal } from '../protocols/abort'; +import { + parsePublisherPropertySelector, + expandPublisherPropertySelector, +} from '../discovery/publisher-property-selector'; +import { domain, records, strings } from './validation'; +import { RegistryClient } from '../registry'; +import { SupplyPathEvidenceSession } from './fetch-evidence'; +import { + isUnqualifiedPropertySelector, + evaluateSupplyPath, + supplyPathAdsTxtPolicy, + parseInventoryPartnerDomains, +} from './evaluate'; +import { validateSupplyPathRequest } from './validation'; +import type { + SupplyPathRequest, + VerifySupplyPathOptions, + RegistrySupplyPathOptions, + AuthoritativeSupplyPathOptions, + RegistrySupplyPathResult, + AuthoritativeSupplyPathResult, +} from './types'; + +export function verifySupplyPath( + request: SupplyPathRequest, + options: RegistrySupplyPathOptions +): Promise; +export function verifySupplyPath( + request: SupplyPathRequest, + options?: AuthoritativeSupplyPathOptions +): Promise; +export function verifySupplyPath( + request: SupplyPathRequest, + options: VerifySupplyPathOptions +): Promise; +/** Verify a single owner/host/agent path. Defaults to live authoritative evidence. */ +export async function verifySupplyPath( + request: SupplyPathRequest, + options: VerifySupplyPathOptions = { source: 'authoritative' } +): Promise { + const normalized = validateSupplyPathRequest(request); + if (options.source === 'registry') return (options.registry ?? new RegistryClient()).verifySupplyPath(normalized); + if (options.source !== 'authoritative') throw new TypeError('source must be registry or authoritative'); + const session = new SupplyPathEvidenceSession(options); + try { + return await withAbortSignal([session.signal], undefined, () => + verifyAuthoritativeSupplyPath(normalized, options, session) + ); + } finally { + session.close(); + } +} + +/** Internal batch entrypoint; callers cannot supply evidence through the public API. */ +export async function verifyAuthoritativeSupplyPath( + normalized: SupplyPathRequest, + options: AuthoritativeSupplyPathOptions, + session: SupplyPathEvidenceSession +): Promise { + const [ownerManifest, hostManifest] = await Promise.all([ + session.adagents(normalized.owner_domain), + session.adagents(normalized.host_domain), + ]); + const input = { + ownerDomain: normalized.owner_domain, + hostDomain: normalized.host_domain, + agentUrl: normalized.agent_url, + collectionId: normalized.collection_id, + ownerManifest, + hostManifest, + hostInventoryPartnerDomains: null as string[] | null, + hostInventoryPartnerDomainsByFile: + undefined as import('./types').SupplyPathInput['hostInventoryPartnerDomainsByFile'], + heldRevocations: { + owner: session.revocations.get(normalized.owner_domain)?.map(r => r.publisher_domain), + host: session.revocations.get(normalized.host_domain)?.map(r => r.publisher_domain), + }, + }; + const scopedInput: typeof input & { requiredHostPropertyIds?: string[] } = input; + if (options.propertySelectors !== undefined) { + if (!Array.isArray(options.propertySelectors) || !options.propertySelectors.length) + throw new TypeError('propertySelectors must be non-empty'); + const ids = new Set(); + const properties = records(hostManifest?.properties).filter( + p => p.publisher_domain === undefined || domain(p.publisher_domain) === normalized.host_domain + ); + let unresolved = false; + for (const raw of options.propertySelectors) { + if (!isUnqualifiedPropertySelector(raw)) throw new TypeError('Unsupported product property selector fields'); + const selector = parsePublisherPropertySelector(raw); + for (const single of expandPublisherPropertySelector(selector)) { + if (domain(single.publisher_domain) !== normalized.host_domain) + throw new TypeError('propertySelectors must name host_domain'); + if (single.selection_type === 'by_id') { + if (!strings(single.property_ids)) throw new TypeError('Invalid product property IDs'); + for (const id of single.property_ids) ids.add(id); + } else { + if (single.selection_type === 'by_tag' && !strings(single.property_tags)) + throw new TypeError('Invalid product property tags'); + let matched = false; + for (const property of properties) { + if (typeof property.property_id !== 'string') continue; + if ( + single.selection_type === 'all' || + (strings(property.tags) && property.tags.some(tag => single.property_tags.includes(tag))) + ) { + ids.add(property.property_id); + matched = true; + } + } + if (!matched) unresolved = true; + } + } + } + scopedInput.requiredHostPropertyIds = unresolved ? [] : [...ids]; + } + let verdict = evaluateSupplyPath(scopedInput); + if (!verdict.legs.host_authorization.ok && verdict.legs.host_authorization.failure !== 'evaluation_limit_exceeded') { + const policy = supplyPathAdsTxtPolicy(scopedInput); + const responses = await Promise.all( + policy.files.map(kind => session.read(normalized.host_domain, kind, `https://${normalized.host_domain}/${kind}`)) + ); + input.hostInventoryPartnerDomainsByFile = Object.fromEntries( + policy.files.map((file, index) => [ + file, + responses[index] ? parseInventoryPartnerDomains(new TextDecoder().decode(responses[index]!.body)) : null, + ]) + ); + verdict = evaluateSupplyPath(scopedInput); + } else if (verdict.legs.host_authorization.ok) { + verdict = evaluateSupplyPath({ ...scopedInput, inventoryPartnerDomainEvaluated: false }); + } + session.signal.throwIfAborted(); + return { + ...verdict, + ...normalized, + source: 'authoritative', + ...(options.propertySelectors ? { property_selectors: options.propertySelectors } : {}), + sources: { + owner_adagents_url: `https://${normalized.owner_domain}/.well-known/adagents.json`, + host_adagents_url: `https://${normalized.host_domain}/.well-known/adagents.json`, + cached: false, + held_revocations: [...session.revocations] + .filter(([authority]) => authority === normalized.owner_domain || authority === normalized.host_domain) + .map(([authority, entries]) => ({ authority, entries })), + evidence: session.evidence.filter( + e => e.publisher_domain === normalized.owner_domain || e.publisher_domain === normalized.host_domain + ), + }, + checked_at: new Date().toISOString(), + }; +} diff --git a/src/lib/v2/projection/creative-delivery.ts b/src/lib/v2/projection/creative-delivery.ts index 71a4fc355..0f101f50f 100644 --- a/src/lib/v2/projection/creative-delivery.ts +++ b/src/lib/v2/projection/creative-delivery.ts @@ -95,12 +95,13 @@ export type CanonicalPlacement = Omit, 'for export type CanonicalProduct = Omit< CanonicalCreativeResponse, 'format_ids' | 'format_options' | 'placements' -> & { - product_id: string; - format_ids?: never; - format_options: NonEmptyCanonicalFormatDeclarations; - placements?: CanonicalPlacement[]; -}; +> & + import('../../supply-path/products').ProductSupplyPathAnnotation & { + product_id: string; + format_ids?: never; + format_options: NonEmptyCanonicalFormatDeclarations; + placements?: CanonicalPlacement[]; + }; type CanonicalGetProductsField = Exclude[number], 'format_ids'>; /** Primary product discovery request cannot ask the SDK to expose legacy format IDs. */ export type CanonicalGetProductsRequest = Omit & { diff --git a/test/fixtures/supply-path/README.md b/test/fixtures/supply-path/README.md new file mode 100644 index 000000000..3874493dc --- /dev/null +++ b/test/fixtures/supply-path/README.md @@ -0,0 +1,17 @@ +# Canonical supply-path verification vectors + +`vectors.json` is vendored byte-for-byte from the official protocol repository, under its Apache-2.0 license. `source.json` records the reviewed immutable commit, repository path, semantics version and SHA-256. The upstream registry's `supply-path-golden.test.ts` and this SDK's `test/lib/supply-path.test.js` consume the same expected states, resolved collections, five leg diagnostics, IAB parser results, and applicable-file policy. + +Verify the pinned fixture offline: + +```sh +node scripts/sync-supply-path-vectors.mjs --check +``` + +After reviewing an upstream contract change, vendor its exact commit: + +```sh +node scripts/sync-supply-path-vectors.mjs --commit <40-character-upstream-commit> +``` + +Run both implementations' golden tests before accepting a semantics update. Never edit client expectations to accommodate a divergent implementation. These are test evidence fixtures; runtime product discovery uses only actual seller responses. diff --git a/test/fixtures/supply-path/source.json b/test/fixtures/supply-path/source.json new file mode 100644 index 000000000..88e1528d1 --- /dev/null +++ b/test/fixtures/supply-path/source.json @@ -0,0 +1,7 @@ +{ + "repository": "adcontextprotocol/adcp", + "commit": "87b09d10cea7ee93e5badc4ce702a7d2aff02254", + "path": "static/compliance/source/test-vectors/supply-path/vectors.json", + "sha256": "c70298c8cf3db46c3d9c685f2efb790198a35ec1f9eaf8b113d23dc983106226", + "semantics_version": "1" +} diff --git a/test/fixtures/supply-path/vectors.json b/test/fixtures/supply-path/vectors.json new file mode 100644 index 000000000..02122e974 --- /dev/null +++ b/test/fixtures/supply-path/vectors.json @@ -0,0 +1,6102 @@ +{ + "semantics_version": "1", + "description": "Canonical owner-sold supply-path verdicts and machine-readable leg diagnostics. Human-readable detail and ancillary evidence fields are not compared.", + "vectors": [ + { + "id": "exact-owner-collection-and-carried-property", + "input": { + "ownerDomain": "channel-owner.example", + "hostDomain": "hoststream.example", + "agentUrl": "https://sales.channel-owner.example", + "collectionId": "retro_news", + "hostInventoryPartnerDomains": null, + "ownerManifest": { + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails" + } + ], + "collections": [ + { + "collection_id": "retro_news", + "name": "Retro News", + "kind": "channel", + "distribution": [ + { + "publisher_domain": "hoststream.example", + "property_ids": [ + "hoststream_ctv" + ] + } + ] + } + ] + }, + "hostManifest": { + "properties": [ + { + "property_id": "hoststream_ctv", + "name": "HostStream CTV", + "property_type": "ctv_app", + "identifiers": [ + { + "type": "roku_channel_id", + "value": "123" + } + ] + } + ], + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "hoststream_ctv" + ], + "collections": [ + { + "publisher_domain": "channel-owner.example", + "collection_ids": [ + "retro_news" + ] + } + ] + } + ] + } + }, + "expected": { + "semantics_version": "1", + "state": "verified_owner_sold", + "legs": { + "owner_collection_declared": { + "ok": true + }, + "owner_distribution_carriage": { + "ok": true + }, + "owner_agent_declared": { + "ok": true + }, + "host_authorization": { + "ok": true + }, + "inventory_partner_domain": { + "ok": false, + "failure": "ads_txt_unavailable" + } + }, + "resolved_collection_id": "retro_news" + } + }, + { + "id": "bulk-authorization-selector", + "input": { + "ownerDomain": "channel-owner.example", + "hostDomain": "hoststream.example", + "agentUrl": "https://sales.channel-owner.example", + "collectionId": "retro_news", + "hostInventoryPartnerDomains": null, + "ownerManifest": { + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails" + } + ], + "collections": [ + { + "collection_id": "retro_news", + "name": "Retro News", + "kind": "channel", + "distribution": [ + { + "publisher_domain": "hoststream.example", + "property_ids": [ + "hoststream_ctv" + ] + } + ] + } + ] + }, + "hostManifest": { + "properties": [ + { + "property_id": "hoststream_ctv", + "name": "HostStream CTV", + "property_type": "ctv_app", + "identifiers": [ + { + "type": "roku_channel_id", + "value": "123" + } + ] + } + ], + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "hoststream_ctv" + ], + "collections": [ + { + "publisher_domain": "channel-owner.example" + } + ] + } + ] + } + }, + "expected": { + "semantics_version": "1", + "state": "verified_owner_sold", + "legs": { + "owner_collection_declared": { + "ok": true + }, + "owner_distribution_carriage": { + "ok": true + }, + "owner_agent_declared": { + "ok": true + }, + "host_authorization": { + "ok": true + }, + "inventory_partner_domain": { + "ok": false, + "failure": "ads_txt_unavailable" + } + }, + "resolved_collection_id": "retro_news" + } + }, + { + "id": "absent-host-collection-selector", + "input": { + "ownerDomain": "channel-owner.example", + "hostDomain": "hoststream.example", + "agentUrl": "https://sales.channel-owner.example", + "collectionId": "retro_news", + "hostInventoryPartnerDomains": null, + "ownerManifest": { + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails" + } + ], + "collections": [ + { + "collection_id": "retro_news", + "name": "Retro News", + "kind": "channel", + "distribution": [ + { + "publisher_domain": "hoststream.example", + "property_ids": [ + "hoststream_ctv" + ] + } + ] + } + ] + }, + "hostManifest": { + "properties": [ + { + "property_id": "hoststream_ctv", + "name": "HostStream CTV", + "property_type": "ctv_app", + "identifiers": [ + { + "type": "roku_channel_id", + "value": "123" + } + ] + } + ], + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "hoststream_ctv" + ] + } + ] + } + }, + "expected": { + "semantics_version": "1", + "state": "owner_attested", + "legs": { + "owner_collection_declared": { + "ok": true + }, + "owner_distribution_carriage": { + "ok": true + }, + "owner_agent_declared": { + "ok": true + }, + "host_authorization": { + "ok": false, + "failure": "collection_scope_mismatch" + }, + "inventory_partner_domain": { + "ok": false, + "failure": "ads_txt_unavailable" + } + }, + "resolved_collection_id": "retro_news" + } + }, + { + "id": "malformed-collection-selector-1", + "input": { + "ownerDomain": "channel-owner.example", + "hostDomain": "hoststream.example", + "agentUrl": "https://sales.channel-owner.example", + "collectionId": "retro_news", + "hostInventoryPartnerDomains": null, + "ownerManifest": { + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails" + } + ], + "collections": [ + { + "collection_id": "retro_news", + "name": "Retro News", + "kind": "channel", + "distribution": [ + { + "publisher_domain": "hoststream.example", + "property_ids": [ + "hoststream_ctv" + ] + } + ] + } + ] + }, + "hostManifest": { + "properties": [ + { + "property_id": "hoststream_ctv", + "name": "HostStream CTV", + "property_type": "ctv_app", + "identifiers": [ + { + "type": "roku_channel_id", + "value": "123" + } + ] + } + ], + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "hoststream_ctv" + ], + "collections": null + } + ] + } + }, + "expected": { + "semantics_version": "1", + "state": "owner_attested", + "legs": { + "owner_collection_declared": { + "ok": true + }, + "owner_distribution_carriage": { + "ok": true + }, + "owner_agent_declared": { + "ok": true + }, + "host_authorization": { + "ok": false, + "failure": "collection_scope_mismatch" + }, + "inventory_partner_domain": { + "ok": false, + "failure": "ads_txt_unavailable" + } + }, + "resolved_collection_id": "retro_news" + } + }, + { + "id": "malformed-collection-selector-2", + "input": { + "ownerDomain": "channel-owner.example", + "hostDomain": "hoststream.example", + "agentUrl": "https://sales.channel-owner.example", + "collectionId": "retro_news", + "hostInventoryPartnerDomains": null, + "ownerManifest": { + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails" + } + ], + "collections": [ + { + "collection_id": "retro_news", + "name": "Retro News", + "kind": "channel", + "distribution": [ + { + "publisher_domain": "hoststream.example", + "property_ids": [ + "hoststream_ctv" + ] + } + ] + } + ] + }, + "hostManifest": { + "properties": [ + { + "property_id": "hoststream_ctv", + "name": "HostStream CTV", + "property_type": "ctv_app", + "identifiers": [ + { + "type": "roku_channel_id", + "value": "123" + } + ] + } + ], + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "hoststream_ctv" + ], + "collections": {} + } + ] + } + }, + "expected": { + "semantics_version": "1", + "state": "owner_attested", + "legs": { + "owner_collection_declared": { + "ok": true + }, + "owner_distribution_carriage": { + "ok": true + }, + "owner_agent_declared": { + "ok": true + }, + "host_authorization": { + "ok": false, + "failure": "collection_scope_mismatch" + }, + "inventory_partner_domain": { + "ok": false, + "failure": "ads_txt_unavailable" + } + }, + "resolved_collection_id": "retro_news" + } + }, + { + "id": "malformed-collection-selector-3", + "input": { + "ownerDomain": "channel-owner.example", + "hostDomain": "hoststream.example", + "agentUrl": "https://sales.channel-owner.example", + "collectionId": "retro_news", + "hostInventoryPartnerDomains": null, + "ownerManifest": { + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails" + } + ], + "collections": [ + { + "collection_id": "retro_news", + "name": "Retro News", + "kind": "channel", + "distribution": [ + { + "publisher_domain": "hoststream.example", + "property_ids": [ + "hoststream_ctv" + ] + } + ] + } + ] + }, + "hostManifest": { + "properties": [ + { + "property_id": "hoststream_ctv", + "name": "HostStream CTV", + "property_type": "ctv_app", + "identifiers": [ + { + "type": "roku_channel_id", + "value": "123" + } + ] + } + ], + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "hoststream_ctv" + ], + "collections": [] + } + ] + } + }, + "expected": { + "semantics_version": "1", + "state": "owner_attested", + "legs": { + "owner_collection_declared": { + "ok": true + }, + "owner_distribution_carriage": { + "ok": true + }, + "owner_agent_declared": { + "ok": true + }, + "host_authorization": { + "ok": false, + "failure": "collection_scope_mismatch" + }, + "inventory_partner_domain": { + "ok": false, + "failure": "ads_txt_unavailable" + } + }, + "resolved_collection_id": "retro_news" + } + }, + { + "id": "malformed-collection-selector-4", + "input": { + "ownerDomain": "channel-owner.example", + "hostDomain": "hoststream.example", + "agentUrl": "https://sales.channel-owner.example", + "collectionId": "retro_news", + "hostInventoryPartnerDomains": null, + "ownerManifest": { + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails" + } + ], + "collections": [ + { + "collection_id": "retro_news", + "name": "Retro News", + "kind": "channel", + "distribution": [ + { + "publisher_domain": "hoststream.example", + "property_ids": [ + "hoststream_ctv" + ] + } + ] + } + ] + }, + "hostManifest": { + "properties": [ + { + "property_id": "hoststream_ctv", + "name": "HostStream CTV", + "property_type": "ctv_app", + "identifiers": [ + { + "type": "roku_channel_id", + "value": "123" + } + ] + } + ], + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "hoststream_ctv" + ], + "collections": "all" + } + ] + } + }, + "expected": { + "semantics_version": "1", + "state": "owner_attested", + "legs": { + "owner_collection_declared": { + "ok": true + }, + "owner_distribution_carriage": { + "ok": true + }, + "owner_agent_declared": { + "ok": true + }, + "host_authorization": { + "ok": false, + "failure": "collection_scope_mismatch" + }, + "inventory_partner_domain": { + "ok": false, + "failure": "ads_txt_unavailable" + } + }, + "resolved_collection_id": "retro_news" + } + }, + { + "id": "malformed-collection-selector-5", + "input": { + "ownerDomain": "channel-owner.example", + "hostDomain": "hoststream.example", + "agentUrl": "https://sales.channel-owner.example", + "collectionId": "retro_news", + "hostInventoryPartnerDomains": null, + "ownerManifest": { + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails" + } + ], + "collections": [ + { + "collection_id": "retro_news", + "name": "Retro News", + "kind": "channel", + "distribution": [ + { + "publisher_domain": "hoststream.example", + "property_ids": [ + "hoststream_ctv" + ] + } + ] + } + ] + }, + "hostManifest": { + "properties": [ + { + "property_id": "hoststream_ctv", + "name": "HostStream CTV", + "property_type": "ctv_app", + "identifiers": [ + { + "type": "roku_channel_id", + "value": "123" + } + ] + } + ], + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "hoststream_ctv" + ], + "collections": [ + { + "publisher_domain": "channel-owner.example", + "collection_ids": null + } + ] + } + ] + } + }, + "expected": { + "semantics_version": "1", + "state": "owner_attested", + "legs": { + "owner_collection_declared": { + "ok": true + }, + "owner_distribution_carriage": { + "ok": true + }, + "owner_agent_declared": { + "ok": true + }, + "host_authorization": { + "ok": false, + "failure": "collection_scope_mismatch" + }, + "inventory_partner_domain": { + "ok": false, + "failure": "ads_txt_unavailable" + } + }, + "resolved_collection_id": "retro_news" + } + }, + { + "id": "malformed-collection-selector-6", + "input": { + "ownerDomain": "channel-owner.example", + "hostDomain": "hoststream.example", + "agentUrl": "https://sales.channel-owner.example", + "collectionId": "retro_news", + "hostInventoryPartnerDomains": null, + "ownerManifest": { + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails" + } + ], + "collections": [ + { + "collection_id": "retro_news", + "name": "Retro News", + "kind": "channel", + "distribution": [ + { + "publisher_domain": "hoststream.example", + "property_ids": [ + "hoststream_ctv" + ] + } + ] + } + ] + }, + "hostManifest": { + "properties": [ + { + "property_id": "hoststream_ctv", + "name": "HostStream CTV", + "property_type": "ctv_app", + "identifiers": [ + { + "type": "roku_channel_id", + "value": "123" + } + ] + } + ], + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "hoststream_ctv" + ], + "collections": [ + { + "publisher_domain": "channel-owner.example", + "collection_ids": [] + } + ] + } + ] + } + }, + "expected": { + "semantics_version": "1", + "state": "owner_attested", + "legs": { + "owner_collection_declared": { + "ok": true + }, + "owner_distribution_carriage": { + "ok": true + }, + "owner_agent_declared": { + "ok": true + }, + "host_authorization": { + "ok": false, + "failure": "collection_scope_mismatch" + }, + "inventory_partner_domain": { + "ok": false, + "failure": "ads_txt_unavailable" + } + }, + "resolved_collection_id": "retro_news" + } + }, + { + "id": "malformed-collection-selector-7", + "input": { + "ownerDomain": "channel-owner.example", + "hostDomain": "hoststream.example", + "agentUrl": "https://sales.channel-owner.example", + "collectionId": "retro_news", + "hostInventoryPartnerDomains": null, + "ownerManifest": { + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails" + } + ], + "collections": [ + { + "collection_id": "retro_news", + "name": "Retro News", + "kind": "channel", + "distribution": [ + { + "publisher_domain": "hoststream.example", + "property_ids": [ + "hoststream_ctv" + ] + } + ] + } + ] + }, + "hostManifest": { + "properties": [ + { + "property_id": "hoststream_ctv", + "name": "HostStream CTV", + "property_type": "ctv_app", + "identifiers": [ + { + "type": "roku_channel_id", + "value": "123" + } + ] + } + ], + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "hoststream_ctv" + ], + "collections": [ + { + "publisher_domain": "channel-owner.example", + "collection_ids": [ + "retro_news", + 42 + ] + } + ] + } + ] + } + }, + "expected": { + "semantics_version": "1", + "state": "owner_attested", + "legs": { + "owner_collection_declared": { + "ok": true + }, + "owner_distribution_carriage": { + "ok": true + }, + "owner_agent_declared": { + "ok": true + }, + "host_authorization": { + "ok": false, + "failure": "collection_scope_mismatch" + }, + "inventory_partner_domain": { + "ok": false, + "failure": "ads_txt_unavailable" + } + }, + "resolved_collection_id": "retro_news" + } + }, + { + "id": "wrong-owner-namespace", + "input": { + "ownerDomain": "channel-owner.example", + "hostDomain": "hoststream.example", + "agentUrl": "https://sales.channel-owner.example", + "collectionId": "retro_news", + "hostInventoryPartnerDomains": null, + "ownerManifest": { + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails" + } + ], + "collections": [ + { + "collection_id": "retro_news", + "name": "Retro News", + "kind": "channel", + "distribution": [ + { + "publisher_domain": "hoststream.example", + "property_ids": [ + "hoststream_ctv" + ] + } + ] + } + ] + }, + "hostManifest": { + "properties": [ + { + "property_id": "hoststream_ctv", + "name": "HostStream CTV", + "property_type": "ctv_app", + "identifiers": [ + { + "type": "roku_channel_id", + "value": "123" + } + ] + } + ], + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "hoststream_ctv" + ], + "collections": [ + { + "publisher_domain": "other-owner.example", + "collection_ids": [ + "retro_news" + ] + } + ] + } + ] + } + }, + "expected": { + "semantics_version": "1", + "state": "owner_attested", + "legs": { + "owner_collection_declared": { + "ok": true + }, + "owner_distribution_carriage": { + "ok": true + }, + "owner_agent_declared": { + "ok": true + }, + "host_authorization": { + "ok": false, + "failure": "collection_scope_mismatch" + }, + "inventory_partner_domain": { + "ok": false, + "failure": "ads_txt_unavailable" + } + }, + "resolved_collection_id": "retro_news" + } + }, + { + "id": "wrong-collection-id", + "input": { + "ownerDomain": "channel-owner.example", + "hostDomain": "hoststream.example", + "agentUrl": "https://sales.channel-owner.example", + "collectionId": "retro_news", + "hostInventoryPartnerDomains": null, + "ownerManifest": { + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails" + } + ], + "collections": [ + { + "collection_id": "retro_news", + "name": "Retro News", + "kind": "channel", + "distribution": [ + { + "publisher_domain": "hoststream.example", + "property_ids": [ + "hoststream_ctv" + ] + } + ] + } + ] + }, + "hostManifest": { + "properties": [ + { + "property_id": "hoststream_ctv", + "name": "HostStream CTV", + "property_type": "ctv_app", + "identifiers": [ + { + "type": "roku_channel_id", + "value": "123" + } + ] + } + ], + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "hoststream_ctv" + ], + "collections": [ + { + "publisher_domain": "channel-owner.example", + "collection_ids": [ + "other" + ] + } + ] + } + ] + } + }, + "expected": { + "semantics_version": "1", + "state": "owner_attested", + "legs": { + "owner_collection_declared": { + "ok": true + }, + "owner_distribution_carriage": { + "ok": true + }, + "owner_agent_declared": { + "ok": true + }, + "host_authorization": { + "ok": false, + "failure": "collection_scope_mismatch" + }, + "inventory_partner_domain": { + "ok": false, + "failure": "ads_txt_unavailable" + } + }, + "resolved_collection_id": "retro_news" + } + }, + { + "id": "host-property-scope-mismatch", + "input": { + "ownerDomain": "channel-owner.example", + "hostDomain": "hoststream.example", + "agentUrl": "https://sales.channel-owner.example", + "collectionId": "retro_news", + "hostInventoryPartnerDomains": null, + "ownerManifest": { + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails" + } + ], + "collections": [ + { + "collection_id": "retro_news", + "name": "Retro News", + "kind": "channel", + "distribution": [ + { + "publisher_domain": "hoststream.example", + "property_ids": [ + "hoststream_ctv" + ] + } + ] + } + ] + }, + "hostManifest": { + "properties": [ + { + "property_id": "hoststream_ctv", + "name": "HostStream CTV", + "property_type": "ctv_app", + "identifiers": [ + { + "type": "roku_channel_id", + "value": "123" + } + ] + } + ], + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "other" + ], + "collections": [ + { + "publisher_domain": "channel-owner.example", + "collection_ids": [ + "retro_news" + ] + } + ] + } + ] + } + }, + "expected": { + "semantics_version": "1", + "state": "owner_attested", + "legs": { + "owner_collection_declared": { + "ok": true + }, + "owner_distribution_carriage": { + "ok": true + }, + "owner_agent_declared": { + "ok": true + }, + "host_authorization": { + "ok": false, + "failure": "property_scope_mismatch" + }, + "inventory_partner_domain": { + "ok": false, + "failure": "ads_txt_unavailable" + } + }, + "resolved_collection_id": "retro_news" + } + }, + { + "id": "partially-dangling-carriage", + "input": { + "ownerDomain": "channel-owner.example", + "hostDomain": "hoststream.example", + "agentUrl": "https://sales.channel-owner.example", + "collectionId": "retro_news", + "hostInventoryPartnerDomains": null, + "ownerManifest": { + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails" + } + ], + "collections": [ + { + "collection_id": "retro_news", + "name": "Retro News", + "kind": "channel", + "distribution": [ + { + "publisher_domain": "hoststream.example", + "property_ids": [ + "hoststream_ctv", + "missing" + ] + } + ] + } + ] + }, + "hostManifest": { + "properties": [ + { + "property_id": "hoststream_ctv", + "name": "HostStream CTV", + "property_type": "ctv_app", + "identifiers": [ + { + "type": "roku_channel_id", + "value": "123" + } + ] + } + ], + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "hoststream_ctv" + ], + "collections": [ + { + "publisher_domain": "channel-owner.example", + "collection_ids": [ + "retro_news" + ] + } + ] + } + ] + } + }, + "expected": { + "semantics_version": "1", + "state": "owner_attested", + "legs": { + "owner_collection_declared": { + "ok": true + }, + "owner_distribution_carriage": { + "ok": false, + "failure": "property_ids_unresolved" + }, + "owner_agent_declared": { + "ok": true + }, + "host_authorization": { + "ok": false, + "failure": "property_scope_mismatch" + }, + "inventory_partner_domain": { + "ok": false, + "failure": "ads_txt_unavailable" + } + }, + "resolved_collection_id": "retro_news" + } + }, + { + "id": "entirely-dangling-carriage", + "input": { + "ownerDomain": "channel-owner.example", + "hostDomain": "hoststream.example", + "agentUrl": "https://sales.channel-owner.example", + "collectionId": "retro_news", + "hostInventoryPartnerDomains": null, + "ownerManifest": { + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails" + } + ], + "collections": [ + { + "collection_id": "retro_news", + "name": "Retro News", + "kind": "channel", + "distribution": [ + { + "publisher_domain": "hoststream.example", + "property_ids": [ + "hoststream_ctv" + ] + } + ] + } + ] + }, + "hostManifest": { + "properties": [], + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "hoststream_ctv" + ], + "collections": [ + { + "publisher_domain": "channel-owner.example", + "collection_ids": [ + "retro_news" + ] + } + ] + } + ] + } + }, + "expected": { + "semantics_version": "1", + "state": "owner_attested", + "legs": { + "owner_collection_declared": { + "ok": true + }, + "owner_distribution_carriage": { + "ok": false, + "failure": "property_ids_unresolved" + }, + "owner_agent_declared": { + "ok": true + }, + "host_authorization": { + "ok": false, + "failure": "property_scope_mismatch" + }, + "inventory_partner_domain": { + "ok": false, + "failure": "ads_txt_unavailable" + } + }, + "resolved_collection_id": "retro_news" + } + }, + { + "id": "identifier-only-carriage-is-not-property-proof", + "input": { + "ownerDomain": "channel-owner.example", + "hostDomain": "hoststream.example", + "agentUrl": "https://sales.channel-owner.example", + "collectionId": "retro_news", + "hostInventoryPartnerDomains": null, + "ownerManifest": { + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails" + } + ], + "collections": [ + { + "collection_id": "retro_news", + "name": "Retro News", + "kind": "channel", + "distribution": [ + { + "publisher_domain": "hoststream.example", + "identifiers": [ + { + "type": "publisher_channel_id", + "value": "retro" + } + ] + } + ] + } + ] + }, + "hostManifest": { + "properties": [ + { + "property_id": "hoststream_ctv", + "name": "HostStream CTV", + "property_type": "ctv_app", + "identifiers": [ + { + "type": "roku_channel_id", + "value": "123" + } + ] + } + ], + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "hoststream_ctv" + ], + "collections": [ + { + "publisher_domain": "channel-owner.example", + "collection_ids": [ + "retro_news" + ] + } + ] + } + ] + } + }, + "expected": { + "semantics_version": "1", + "state": "owner_attested", + "legs": { + "owner_collection_declared": { + "ok": true + }, + "owner_distribution_carriage": { + "ok": true + }, + "owner_agent_declared": { + "ok": true + }, + "host_authorization": { + "ok": false, + "failure": "property_scope_mismatch" + }, + "inventory_partner_domain": { + "ok": false, + "failure": "ads_txt_unavailable" + } + }, + "resolved_collection_id": "retro_news" + } + }, + { + "id": "distribution-with-both-identifiers-and-property-ids", + "input": { + "ownerDomain": "channel-owner.example", + "hostDomain": "hoststream.example", + "agentUrl": "https://sales.channel-owner.example", + "collectionId": "retro_news", + "hostInventoryPartnerDomains": null, + "ownerManifest": { + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails" + } + ], + "collections": [ + { + "collection_id": "retro_news", + "name": "Retro News", + "kind": "channel", + "distribution": [ + { + "publisher_domain": "hoststream.example", + "property_ids": [ + "hoststream_ctv" + ], + "identifiers": [ + { + "type": "publisher_channel_id", + "value": "retro" + } + ] + } + ] + } + ] + }, + "hostManifest": { + "properties": [ + { + "property_id": "hoststream_ctv", + "name": "HostStream CTV", + "property_type": "ctv_app", + "identifiers": [ + { + "type": "roku_channel_id", + "value": "123" + } + ] + } + ], + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "hoststream_ctv" + ], + "collections": [ + { + "publisher_domain": "channel-owner.example", + "collection_ids": [ + "retro_news" + ] + } + ] + } + ] + } + }, + "expected": { + "semantics_version": "1", + "state": "verified_owner_sold", + "legs": { + "owner_collection_declared": { + "ok": true + }, + "owner_distribution_carriage": { + "ok": true + }, + "owner_agent_declared": { + "ok": true + }, + "host_authorization": { + "ok": true + }, + "inventory_partner_domain": { + "ok": false, + "failure": "ads_txt_unavailable" + } + }, + "resolved_collection_id": "retro_news" + } + }, + { + "id": "distribution-with-neither", + "input": { + "ownerDomain": "channel-owner.example", + "hostDomain": "hoststream.example", + "agentUrl": "https://sales.channel-owner.example", + "collectionId": "retro_news", + "hostInventoryPartnerDomains": null, + "ownerManifest": { + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails" + } + ], + "collections": [ + { + "collection_id": "retro_news", + "name": "Retro News", + "kind": "channel", + "distribution": [ + { + "publisher_domain": "hoststream.example" + } + ] + } + ] + }, + "hostManifest": { + "properties": [ + { + "property_id": "hoststream_ctv", + "name": "HostStream CTV", + "property_type": "ctv_app", + "identifiers": [ + { + "type": "roku_channel_id", + "value": "123" + } + ] + } + ], + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "hoststream_ctv" + ], + "collections": [ + { + "publisher_domain": "channel-owner.example", + "collection_ids": [ + "retro_news" + ] + } + ] + } + ] + } + }, + "expected": { + "semantics_version": "1", + "state": "owner_attested", + "legs": { + "owner_collection_declared": { + "ok": true + }, + "owner_distribution_carriage": { + "ok": false, + "failure": "property_ids_unresolved" + }, + "owner_agent_declared": { + "ok": true + }, + "host_authorization": { + "ok": false, + "failure": "property_scope_mismatch" + }, + "inventory_partner_domain": { + "ok": false, + "failure": "ads_txt_unavailable" + } + }, + "resolved_collection_id": "retro_news" + } + }, + { + "id": "unevaluated-countries", + "input": { + "ownerDomain": "channel-owner.example", + "hostDomain": "hoststream.example", + "agentUrl": "https://sales.channel-owner.example", + "collectionId": "retro_news", + "hostInventoryPartnerDomains": null, + "ownerManifest": { + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails" + } + ], + "collections": [ + { + "collection_id": "retro_news", + "name": "Retro News", + "kind": "channel", + "distribution": [ + { + "publisher_domain": "hoststream.example", + "property_ids": [ + "hoststream_ctv" + ] + } + ] + } + ] + }, + "hostManifest": { + "properties": [ + { + "property_id": "hoststream_ctv", + "name": "HostStream CTV", + "property_type": "ctv_app", + "identifiers": [ + { + "type": "roku_channel_id", + "value": "123" + } + ] + } + ], + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "hoststream_ctv" + ], + "collections": [ + { + "publisher_domain": "channel-owner.example", + "collection_ids": [ + "retro_news" + ] + } + ], + "countries": "malformed" + } + ] + } + }, + "expected": { + "semantics_version": "1", + "state": "owner_attested", + "legs": { + "owner_collection_declared": { + "ok": true + }, + "owner_distribution_carriage": { + "ok": true + }, + "owner_agent_declared": { + "ok": true + }, + "host_authorization": { + "ok": false, + "failure": "unsupported_constraints" + }, + "inventory_partner_domain": { + "ok": false, + "failure": "ads_txt_unavailable" + } + }, + "resolved_collection_id": "retro_news" + } + }, + { + "id": "unevaluated-effective_from", + "input": { + "ownerDomain": "channel-owner.example", + "hostDomain": "hoststream.example", + "agentUrl": "https://sales.channel-owner.example", + "collectionId": "retro_news", + "hostInventoryPartnerDomains": null, + "ownerManifest": { + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails" + } + ], + "collections": [ + { + "collection_id": "retro_news", + "name": "Retro News", + "kind": "channel", + "distribution": [ + { + "publisher_domain": "hoststream.example", + "property_ids": [ + "hoststream_ctv" + ] + } + ] + } + ] + }, + "hostManifest": { + "properties": [ + { + "property_id": "hoststream_ctv", + "name": "HostStream CTV", + "property_type": "ctv_app", + "identifiers": [ + { + "type": "roku_channel_id", + "value": "123" + } + ] + } + ], + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "hoststream_ctv" + ], + "collections": [ + { + "publisher_domain": "channel-owner.example", + "collection_ids": [ + "retro_news" + ] + } + ], + "effective_from": "malformed" + } + ] + } + }, + "expected": { + "semantics_version": "1", + "state": "owner_attested", + "legs": { + "owner_collection_declared": { + "ok": true + }, + "owner_distribution_carriage": { + "ok": true + }, + "owner_agent_declared": { + "ok": true + }, + "host_authorization": { + "ok": false, + "failure": "unsupported_constraints" + }, + "inventory_partner_domain": { + "ok": false, + "failure": "ads_txt_unavailable" + } + }, + "resolved_collection_id": "retro_news" + } + }, + { + "id": "unevaluated-effective_until", + "input": { + "ownerDomain": "channel-owner.example", + "hostDomain": "hoststream.example", + "agentUrl": "https://sales.channel-owner.example", + "collectionId": "retro_news", + "hostInventoryPartnerDomains": null, + "ownerManifest": { + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails" + } + ], + "collections": [ + { + "collection_id": "retro_news", + "name": "Retro News", + "kind": "channel", + "distribution": [ + { + "publisher_domain": "hoststream.example", + "property_ids": [ + "hoststream_ctv" + ] + } + ] + } + ] + }, + "hostManifest": { + "properties": [ + { + "property_id": "hoststream_ctv", + "name": "HostStream CTV", + "property_type": "ctv_app", + "identifiers": [ + { + "type": "roku_channel_id", + "value": "123" + } + ] + } + ], + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "hoststream_ctv" + ], + "collections": [ + { + "publisher_domain": "channel-owner.example", + "collection_ids": [ + "retro_news" + ] + } + ], + "effective_until": "malformed" + } + ] + } + }, + "expected": { + "semantics_version": "1", + "state": "owner_attested", + "legs": { + "owner_collection_declared": { + "ok": true + }, + "owner_distribution_carriage": { + "ok": true + }, + "owner_agent_declared": { + "ok": true + }, + "host_authorization": { + "ok": false, + "failure": "unsupported_constraints" + }, + "inventory_partner_domain": { + "ok": false, + "failure": "ads_txt_unavailable" + } + }, + "resolved_collection_id": "retro_news" + } + }, + { + "id": "unevaluated-placement_ids", + "input": { + "ownerDomain": "channel-owner.example", + "hostDomain": "hoststream.example", + "agentUrl": "https://sales.channel-owner.example", + "collectionId": "retro_news", + "hostInventoryPartnerDomains": null, + "ownerManifest": { + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails" + } + ], + "collections": [ + { + "collection_id": "retro_news", + "name": "Retro News", + "kind": "channel", + "distribution": [ + { + "publisher_domain": "hoststream.example", + "property_ids": [ + "hoststream_ctv" + ] + } + ] + } + ] + }, + "hostManifest": { + "properties": [ + { + "property_id": "hoststream_ctv", + "name": "HostStream CTV", + "property_type": "ctv_app", + "identifiers": [ + { + "type": "roku_channel_id", + "value": "123" + } + ] + } + ], + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "hoststream_ctv" + ], + "collections": [ + { + "publisher_domain": "channel-owner.example", + "collection_ids": [ + "retro_news" + ] + } + ], + "placement_ids": "malformed" + } + ] + } + }, + "expected": { + "semantics_version": "1", + "state": "owner_attested", + "legs": { + "owner_collection_declared": { + "ok": true + }, + "owner_distribution_carriage": { + "ok": true + }, + "owner_agent_declared": { + "ok": true + }, + "host_authorization": { + "ok": false, + "failure": "unsupported_constraints" + }, + "inventory_partner_domain": { + "ok": false, + "failure": "ads_txt_unavailable" + } + }, + "resolved_collection_id": "retro_news" + } + }, + { + "id": "unevaluated-placement_tags", + "input": { + "ownerDomain": "channel-owner.example", + "hostDomain": "hoststream.example", + "agentUrl": "https://sales.channel-owner.example", + "collectionId": "retro_news", + "hostInventoryPartnerDomains": null, + "ownerManifest": { + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails" + } + ], + "collections": [ + { + "collection_id": "retro_news", + "name": "Retro News", + "kind": "channel", + "distribution": [ + { + "publisher_domain": "hoststream.example", + "property_ids": [ + "hoststream_ctv" + ] + } + ] + } + ] + }, + "hostManifest": { + "properties": [ + { + "property_id": "hoststream_ctv", + "name": "HostStream CTV", + "property_type": "ctv_app", + "identifiers": [ + { + "type": "roku_channel_id", + "value": "123" + } + ] + } + ], + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "hoststream_ctv" + ], + "collections": [ + { + "publisher_domain": "channel-owner.example", + "collection_ids": [ + "retro_news" + ] + } + ], + "placement_tags": "malformed" + } + ] + } + }, + "expected": { + "semantics_version": "1", + "state": "owner_attested", + "legs": { + "owner_collection_declared": { + "ok": true + }, + "owner_distribution_carriage": { + "ok": true + }, + "owner_agent_declared": { + "ok": true + }, + "host_authorization": { + "ok": false, + "failure": "unsupported_constraints" + }, + "inventory_partner_domain": { + "ok": false, + "failure": "ads_txt_unavailable" + } + }, + "resolved_collection_id": "retro_news" + } + }, + { + "id": "unknown-or-non-property-grant-future", + "input": { + "ownerDomain": "channel-owner.example", + "hostDomain": "hoststream.example", + "agentUrl": "https://sales.channel-owner.example", + "collectionId": "retro_news", + "hostInventoryPartnerDomains": null, + "ownerManifest": { + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails" + } + ], + "collections": [ + { + "collection_id": "retro_news", + "name": "Retro News", + "kind": "channel", + "distribution": [ + { + "publisher_domain": "hoststream.example", + "property_ids": [ + "hoststream_ctv" + ] + } + ] + } + ] + }, + "hostManifest": { + "properties": [ + { + "property_id": "hoststream_ctv", + "name": "HostStream CTV", + "property_type": "ctv_app", + "identifiers": [ + { + "type": "roku_channel_id", + "value": "123" + } + ] + } + ], + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails", + "authorization_type": "future", + "property_ids": [ + "hoststream_ctv" + ], + "collections": [ + { + "publisher_domain": "channel-owner.example", + "collection_ids": [ + "retro_news" + ] + } + ] + } + ] + } + }, + "expected": { + "semantics_version": "1", + "state": "owner_attested", + "legs": { + "owner_collection_declared": { + "ok": true + }, + "owner_distribution_carriage": { + "ok": true + }, + "owner_agent_declared": { + "ok": true + }, + "host_authorization": { + "ok": false, + "failure": "property_scope_mismatch" + }, + "inventory_partner_domain": { + "ok": false, + "failure": "ads_txt_unavailable" + } + }, + "resolved_collection_id": "retro_news" + } + }, + { + "id": "unknown-or-non-property-grant-signal_ids", + "input": { + "ownerDomain": "channel-owner.example", + "hostDomain": "hoststream.example", + "agentUrl": "https://sales.channel-owner.example", + "collectionId": "retro_news", + "hostInventoryPartnerDomains": null, + "ownerManifest": { + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails" + } + ], + "collections": [ + { + "collection_id": "retro_news", + "name": "Retro News", + "kind": "channel", + "distribution": [ + { + "publisher_domain": "hoststream.example", + "property_ids": [ + "hoststream_ctv" + ] + } + ] + } + ] + }, + "hostManifest": { + "properties": [ + { + "property_id": "hoststream_ctv", + "name": "HostStream CTV", + "property_type": "ctv_app", + "identifiers": [ + { + "type": "roku_channel_id", + "value": "123" + } + ] + } + ], + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails", + "authorization_type": "signal_ids", + "property_ids": [ + "hoststream_ctv" + ], + "collections": [ + { + "publisher_domain": "channel-owner.example", + "collection_ids": [ + "retro_news" + ] + } + ] + } + ] + } + }, + "expected": { + "semantics_version": "1", + "state": "owner_attested", + "legs": { + "owner_collection_declared": { + "ok": true + }, + "owner_distribution_carriage": { + "ok": true + }, + "owner_agent_declared": { + "ok": true + }, + "host_authorization": { + "ok": false, + "failure": "property_scope_mismatch" + }, + "inventory_partner_domain": { + "ok": false, + "failure": "ads_txt_unavailable" + } + }, + "resolved_collection_id": "retro_news" + } + }, + { + "id": "unknown-or-non-property-grant-None", + "input": { + "ownerDomain": "channel-owner.example", + "hostDomain": "hoststream.example", + "agentUrl": "https://sales.channel-owner.example", + "collectionId": "retro_news", + "hostInventoryPartnerDomains": null, + "ownerManifest": { + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails" + } + ], + "collections": [ + { + "collection_id": "retro_news", + "name": "Retro News", + "kind": "channel", + "distribution": [ + { + "publisher_domain": "hoststream.example", + "property_ids": [ + "hoststream_ctv" + ] + } + ] + } + ] + }, + "hostManifest": { + "properties": [ + { + "property_id": "hoststream_ctv", + "name": "HostStream CTV", + "property_type": "ctv_app", + "identifiers": [ + { + "type": "roku_channel_id", + "value": "123" + } + ] + } + ], + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails", + "authorization_type": null, + "property_ids": [ + "hoststream_ctv" + ], + "collections": [ + { + "publisher_domain": "channel-owner.example", + "collection_ids": [ + "retro_news" + ] + } + ] + } + ] + } + }, + "expected": { + "semantics_version": "1", + "state": "owner_attested", + "legs": { + "owner_collection_declared": { + "ok": true + }, + "owner_distribution_carriage": { + "ok": true + }, + "owner_agent_declared": { + "ok": true + }, + "host_authorization": { + "ok": false, + "failure": "property_scope_mismatch" + }, + "inventory_partner_domain": { + "ok": false, + "failure": "ads_txt_unavailable" + } + }, + "resolved_collection_id": "retro_news" + } + }, + { + "id": "host-revokes-owner", + "input": { + "ownerDomain": "channel-owner.example", + "hostDomain": "hoststream.example", + "agentUrl": "https://sales.channel-owner.example", + "collectionId": "retro_news", + "hostInventoryPartnerDomains": null, + "ownerManifest": { + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails" + } + ], + "collections": [ + { + "collection_id": "retro_news", + "name": "Retro News", + "kind": "channel", + "distribution": [ + { + "publisher_domain": "hoststream.example", + "property_ids": [ + "hoststream_ctv" + ] + } + ] + } + ] + }, + "hostManifest": { + "properties": [ + { + "property_id": "hoststream_ctv", + "name": "HostStream CTV", + "property_type": "ctv_app", + "identifiers": [ + { + "type": "roku_channel_id", + "value": "123" + } + ] + } + ], + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "hoststream_ctv" + ], + "collections": [ + { + "publisher_domain": "channel-owner.example", + "collection_ids": [ + "retro_news" + ] + } + ] + } + ], + "revoked_publisher_domains": [ + "channel-owner.example" + ] + } + }, + "expected": { + "semantics_version": "1", + "state": "owner_attested", + "legs": { + "owner_collection_declared": { + "ok": true + }, + "owner_distribution_carriage": { + "ok": true + }, + "owner_agent_declared": { + "ok": true + }, + "host_authorization": { + "ok": false, + "failure": "collection_scope_mismatch" + }, + "inventory_partner_domain": { + "ok": false, + "failure": "ads_txt_unavailable" + } + }, + "resolved_collection_id": "retro_news" + } + }, + { + "id": "host-manifest-missing", + "input": { + "ownerDomain": "channel-owner.example", + "hostDomain": "hoststream.example", + "agentUrl": "https://sales.channel-owner.example", + "collectionId": "retro_news", + "hostInventoryPartnerDomains": null, + "ownerManifest": { + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails" + } + ], + "collections": [ + { + "collection_id": "retro_news", + "name": "Retro News", + "kind": "channel", + "distribution": [ + { + "publisher_domain": "hoststream.example", + "property_ids": [ + "hoststream_ctv" + ] + } + ] + } + ] + }, + "hostManifest": null + }, + "expected": { + "semantics_version": "1", + "state": "owner_attested", + "legs": { + "owner_collection_declared": { + "ok": true + }, + "owner_distribution_carriage": { + "ok": false, + "failure": "host_manifest_not_found" + }, + "owner_agent_declared": { + "ok": true + }, + "host_authorization": { + "ok": false, + "failure": "manifest_not_found" + }, + "inventory_partner_domain": { + "ok": false, + "failure": "ads_txt_unavailable" + } + }, + "resolved_collection_id": "retro_news" + } + }, + { + "id": "owner-manifest-missing", + "input": { + "ownerDomain": "channel-owner.example", + "hostDomain": "hoststream.example", + "agentUrl": "https://sales.channel-owner.example", + "collectionId": "retro_news", + "hostInventoryPartnerDomains": null, + "ownerManifest": null, + "hostManifest": { + "properties": [ + { + "property_id": "hoststream_ctv", + "name": "HostStream CTV", + "property_type": "ctv_app", + "identifiers": [ + { + "type": "roku_channel_id", + "value": "123" + } + ] + } + ], + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "hoststream_ctv" + ], + "collections": [ + { + "publisher_domain": "channel-owner.example", + "collection_ids": [ + "retro_news" + ] + } + ] + } + ] + } + }, + "expected": { + "semantics_version": "1", + "state": "unverified", + "legs": { + "owner_collection_declared": { + "ok": false, + "failure": "manifest_not_found" + }, + "owner_distribution_carriage": { + "ok": false, + "failure": "collection_leg_failed" + }, + "owner_agent_declared": { + "ok": false, + "failure": "manifest_not_found" + }, + "host_authorization": { + "ok": false, + "failure": "property_scope_mismatch" + }, + "inventory_partner_domain": { + "ok": false, + "failure": "ads_txt_unavailable" + } + } + } + }, + { + "id": "collection-not-declared", + "input": { + "ownerDomain": "channel-owner.example", + "hostDomain": "hoststream.example", + "agentUrl": "https://sales.channel-owner.example", + "collectionId": "unknown", + "hostInventoryPartnerDomains": null, + "ownerManifest": { + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails" + } + ], + "collections": [ + { + "collection_id": "retro_news", + "name": "Retro News", + "kind": "channel", + "distribution": [ + { + "publisher_domain": "hoststream.example", + "property_ids": [ + "hoststream_ctv" + ] + } + ] + } + ] + }, + "hostManifest": { + "properties": [ + { + "property_id": "hoststream_ctv", + "name": "HostStream CTV", + "property_type": "ctv_app", + "identifiers": [ + { + "type": "roku_channel_id", + "value": "123" + } + ] + } + ], + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "hoststream_ctv" + ], + "collections": [ + { + "publisher_domain": "channel-owner.example", + "collection_ids": [ + "retro_news" + ] + } + ] + } + ] + } + }, + "expected": { + "semantics_version": "1", + "state": "unverified", + "legs": { + "owner_collection_declared": { + "ok": false, + "failure": "collection_not_declared" + }, + "owner_distribution_carriage": { + "ok": false, + "failure": "collection_leg_failed" + }, + "owner_agent_declared": { + "ok": true + }, + "host_authorization": { + "ok": false, + "failure": "collection_scope_mismatch" + }, + "inventory_partner_domain": { + "ok": false, + "failure": "ads_txt_unavailable" + } + } + } + }, + { + "id": "domain-level-complete-path", + "input": { + "ownerDomain": "channel-owner.example", + "hostDomain": "hoststream.example", + "agentUrl": "https://sales.channel-owner.example", + "hostInventoryPartnerDomains": null, + "ownerManifest": { + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails" + } + ], + "collections": [ + { + "collection_id": "retro_news", + "name": "Retro News", + "kind": "channel", + "distribution": [ + { + "publisher_domain": "hoststream.example", + "property_ids": [ + "hoststream_ctv" + ] + } + ] + } + ] + }, + "hostManifest": { + "properties": [ + { + "property_id": "hoststream_ctv", + "name": "HostStream CTV", + "property_type": "ctv_app", + "identifiers": [ + { + "type": "roku_channel_id", + "value": "123" + } + ] + } + ], + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "hoststream_ctv" + ], + "collections": [ + { + "publisher_domain": "channel-owner.example", + "collection_ids": [ + "retro_news" + ] + } + ] + } + ] + } + }, + "expected": { + "semantics_version": "1", + "state": "verified_owner_sold", + "legs": { + "owner_collection_declared": { + "ok": true + }, + "owner_distribution_carriage": { + "ok": true + }, + "owner_agent_declared": { + "ok": true + }, + "host_authorization": { + "ok": true + }, + "inventory_partner_domain": { + "ok": false, + "failure": "ads_txt_unavailable" + } + }, + "resolved_collection_id": "retro_news" + } + }, + { + "id": "domain-level-disjoint-collection-legs", + "input": { + "ownerDomain": "channel-owner.example", + "hostDomain": "hoststream.example", + "agentUrl": "https://sales.channel-owner.example", + "hostInventoryPartnerDomains": null, + "ownerManifest": { + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails" + } + ], + "collections": [ + { + "collection_id": "retro_news", + "name": "Retro News", + "kind": "channel", + "distribution": [ + { + "publisher_domain": "hoststream.example", + "property_ids": [ + "hoststream_ctv" + ] + } + ] + }, + { + "collection_id": "other", + "name": "Other", + "kind": "channel", + "distribution": [] + } + ] + }, + "hostManifest": { + "properties": [ + { + "property_id": "hoststream_ctv", + "name": "HostStream CTV", + "property_type": "ctv_app", + "identifiers": [ + { + "type": "roku_channel_id", + "value": "123" + } + ] + } + ], + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "hoststream_ctv" + ], + "collections": [ + { + "publisher_domain": "channel-owner.example", + "collection_ids": [ + "other" + ] + } + ] + } + ] + } + }, + "expected": { + "semantics_version": "1", + "state": "owner_attested", + "legs": { + "owner_collection_declared": { + "ok": true + }, + "owner_distribution_carriage": { + "ok": true + }, + "owner_agent_declared": { + "ok": true + }, + "host_authorization": { + "ok": false, + "failure": "collection_scope_mismatch" + }, + "inventory_partner_domain": { + "ok": false, + "failure": "ads_txt_unavailable" + } + }, + "resolved_collection_id": "retro_news" + } + }, + { + "id": "host-delegated", + "input": { + "ownerDomain": "channel-owner.example", + "hostDomain": "hoststream.example", + "agentUrl": "https://sales.channel-owner.example", + "collectionId": "retro_news", + "hostInventoryPartnerDomains": [ + "channel-owner.example" + ], + "ownerManifest": { + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails" + } + ], + "collections": [ + { + "collection_id": "retro_news", + "name": "Retro News", + "kind": "channel", + "distribution": [ + { + "publisher_domain": "hoststream.example", + "property_ids": [ + "hoststream_ctv" + ] + } + ] + } + ] + }, + "hostManifest": { + "properties": [ + { + "property_id": "hoststream_ctv", + "name": "HostStream CTV", + "property_type": "ctv_app", + "identifiers": [ + { + "type": "roku_channel_id", + "value": "123" + } + ] + } + ], + "authorized_agents": [] + } + }, + "expected": { + "semantics_version": "1", + "state": "host_delegated", + "legs": { + "owner_collection_declared": { + "ok": true + }, + "owner_distribution_carriage": { + "ok": true + }, + "owner_agent_declared": { + "ok": true + }, + "host_authorization": { + "ok": false, + "failure": "no_agent_entry" + }, + "inventory_partner_domain": { + "ok": true + } + }, + "resolved_collection_id": "retro_news" + } + }, + { + "id": "host-delegated-without-host-adagents", + "input": { + "ownerDomain": "channel-owner.example", + "hostDomain": "hoststream.example", + "agentUrl": "https://sales.channel-owner.example", + "collectionId": "retro_news", + "hostInventoryPartnerDomains": [ + "channel-owner.example" + ], + "ownerManifest": { + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails" + } + ], + "collections": [ + { + "collection_id": "retro_news", + "name": "Retro News", + "kind": "channel", + "distribution": [ + { + "publisher_domain": "hoststream.example", + "property_ids": [ + "hoststream_ctv" + ] + } + ] + } + ] + }, + "hostManifest": null + }, + "expected": { + "semantics_version": "1", + "state": "host_delegated", + "legs": { + "owner_collection_declared": { + "ok": true + }, + "owner_distribution_carriage": { + "ok": false, + "failure": "host_manifest_not_found" + }, + "owner_agent_declared": { + "ok": true + }, + "host_authorization": { + "ok": false, + "failure": "manifest_not_found" + }, + "inventory_partner_domain": { + "ok": true + } + }, + "resolved_collection_id": "retro_news" + } + }, + { + "id": "partner-does-not-bind-undeclared-agent", + "input": { + "ownerDomain": "channel-owner.example", + "hostDomain": "hoststream.example", + "agentUrl": "https://sales.channel-owner.example", + "collectionId": "retro_news", + "hostInventoryPartnerDomains": [ + "channel-owner.example" + ], + "ownerManifest": { + "authorized_agents": [], + "collections": [ + { + "collection_id": "retro_news", + "name": "Retro News", + "kind": "channel", + "distribution": [ + { + "publisher_domain": "hoststream.example", + "property_ids": [ + "hoststream_ctv" + ] + } + ] + } + ] + }, + "hostManifest": { + "properties": [ + { + "property_id": "hoststream_ctv", + "name": "HostStream CTV", + "property_type": "ctv_app", + "identifiers": [ + { + "type": "roku_channel_id", + "value": "123" + } + ] + } + ], + "authorized_agents": [] + } + }, + "expected": { + "semantics_version": "1", + "state": "owner_attested", + "legs": { + "owner_collection_declared": { + "ok": true + }, + "owner_distribution_carriage": { + "ok": true + }, + "owner_agent_declared": { + "ok": false, + "failure": "agent_not_declared_by_owner" + }, + "host_authorization": { + "ok": false, + "failure": "no_agent_entry" + }, + "inventory_partner_domain": { + "ok": true + } + }, + "resolved_collection_id": "retro_news" + } + }, + { + "id": "absent-inventory-partner", + "input": { + "ownerDomain": "channel-owner.example", + "hostDomain": "hoststream.example", + "agentUrl": "https://sales.channel-owner.example", + "collectionId": "retro_news", + "hostInventoryPartnerDomains": [], + "ownerManifest": { + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails" + } + ], + "collections": [ + { + "collection_id": "retro_news", + "name": "Retro News", + "kind": "channel", + "distribution": [ + { + "publisher_domain": "hoststream.example", + "property_ids": [ + "hoststream_ctv" + ] + } + ] + } + ] + }, + "hostManifest": { + "properties": [ + { + "property_id": "hoststream_ctv", + "name": "HostStream CTV", + "property_type": "ctv_app", + "identifiers": [ + { + "type": "roku_channel_id", + "value": "123" + } + ] + } + ], + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "hoststream_ctv" + ], + "collections": [ + { + "publisher_domain": "channel-owner.example", + "collection_ids": [ + "retro_news" + ] + } + ] + } + ] + } + }, + "expected": { + "semantics_version": "1", + "state": "verified_owner_sold", + "legs": { + "owner_collection_declared": { + "ok": true + }, + "owner_distribution_carriage": { + "ok": true + }, + "owner_agent_declared": { + "ok": true + }, + "host_authorization": { + "ok": true + }, + "inventory_partner_domain": { + "ok": false, + "failure": "not_declared" + } + }, + "resolved_collection_id": "retro_news" + } + }, + { + "id": "case-sensitive-agent-path", + "input": { + "ownerDomain": "channel-owner.example", + "hostDomain": "hoststream.example", + "agentUrl": "https://sales.channel-owner.example/Sales", + "collectionId": "retro_news", + "hostInventoryPartnerDomains": null, + "ownerManifest": { + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails" + } + ], + "collections": [ + { + "collection_id": "retro_news", + "name": "Retro News", + "kind": "channel", + "distribution": [ + { + "publisher_domain": "hoststream.example", + "property_ids": [ + "hoststream_ctv" + ] + } + ] + } + ] + }, + "hostManifest": { + "properties": [ + { + "property_id": "hoststream_ctv", + "name": "HostStream CTV", + "property_type": "ctv_app", + "identifiers": [ + { + "type": "roku_channel_id", + "value": "123" + } + ] + } + ], + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example/sales", + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "hoststream_ctv" + ], + "collections": [ + { + "publisher_domain": "channel-owner.example", + "collection_ids": [ + "retro_news" + ] + } + ] + } + ] + } + }, + "expected": { + "semantics_version": "1", + "state": "owner_attested", + "legs": { + "owner_collection_declared": { + "ok": true + }, + "owner_distribution_carriage": { + "ok": true + }, + "owner_agent_declared": { + "ok": false, + "failure": "agent_not_declared_by_owner" + }, + "host_authorization": { + "ok": false, + "failure": "no_agent_entry" + }, + "inventory_partner_domain": { + "ok": false, + "failure": "ads_txt_unavailable" + } + }, + "resolved_collection_id": "retro_news" + } + }, + { + "id": "invalid-agent-identities-never-match", + "input": { + "ownerDomain": "channel-owner.example", + "hostDomain": "hoststream.example", + "agentUrl": " ", + "collectionId": "retro_news", + "hostInventoryPartnerDomains": null, + "ownerManifest": { + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails" + } + ], + "collections": [ + { + "collection_id": "retro_news", + "name": "Retro News", + "kind": "channel", + "distribution": [ + { + "publisher_domain": "hoststream.example", + "property_ids": [ + "hoststream_ctv" + ] + } + ] + } + ] + }, + "hostManifest": { + "properties": [ + { + "property_id": "hoststream_ctv", + "name": "HostStream CTV", + "property_type": "ctv_app", + "identifiers": [ + { + "type": "roku_channel_id", + "value": "123" + } + ] + } + ], + "authorized_agents": [ + { + "url": " ", + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "hoststream_ctv" + ], + "collections": [ + { + "publisher_domain": "channel-owner.example", + "collection_ids": [ + "retro_news" + ] + } + ] + } + ] + } + }, + "expected": { + "semantics_version": "1", + "state": "owner_attested", + "legs": { + "owner_collection_declared": { + "ok": true + }, + "owner_distribution_carriage": { + "ok": true + }, + "owner_agent_declared": { + "ok": false, + "failure": "agent_not_declared_by_owner" + }, + "host_authorization": { + "ok": false, + "failure": "no_agent_entry" + }, + "inventory_partner_domain": { + "ok": false, + "failure": "ads_txt_unavailable" + } + }, + "resolved_collection_id": "retro_news" + } + }, + { + "id": "concrete-product-property-mismatch", + "input": { + "ownerDomain": "channel-owner.example", + "hostDomain": "hoststream.example", + "agentUrl": "https://sales.channel-owner.example", + "collectionId": "retro_news", + "hostInventoryPartnerDomains": null, + "ownerManifest": { + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails" + } + ], + "collections": [ + { + "collection_id": "retro_news", + "name": "Retro News", + "kind": "channel", + "distribution": [ + { + "publisher_domain": "hoststream.example", + "property_ids": [ + "hoststream_ctv" + ] + } + ] + } + ] + }, + "hostManifest": { + "properties": [ + { + "property_id": "hoststream_ctv", + "name": "HostStream CTV", + "property_type": "ctv_app", + "identifiers": [ + { + "type": "roku_channel_id", + "value": "123" + } + ] + } + ], + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "hoststream_ctv" + ], + "collections": [ + { + "publisher_domain": "channel-owner.example", + "collection_ids": [ + "retro_news" + ] + } + ] + } + ] + }, + "requiredHostPropertyIds": [ + "other" + ] + }, + "expected": { + "semantics_version": "1", + "state": "owner_attested", + "legs": { + "owner_collection_declared": { + "ok": true + }, + "owner_distribution_carriage": { + "ok": true + }, + "owner_agent_declared": { + "ok": true + }, + "host_authorization": { + "ok": false, + "failure": "property_scope_mismatch" + }, + "inventory_partner_domain": { + "ok": false, + "failure": "ads_txt_unavailable" + } + }, + "resolved_collection_id": "retro_news" + } + }, + { + "id": "concrete-product-property-match", + "input": { + "ownerDomain": "channel-owner.example", + "hostDomain": "hoststream.example", + "agentUrl": "https://sales.channel-owner.example", + "collectionId": "retro_news", + "hostInventoryPartnerDomains": null, + "ownerManifest": { + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails" + } + ], + "collections": [ + { + "collection_id": "retro_news", + "name": "Retro News", + "kind": "channel", + "distribution": [ + { + "publisher_domain": "hoststream.example", + "property_ids": [ + "hoststream_ctv" + ] + } + ] + } + ] + }, + "hostManifest": { + "properties": [ + { + "property_id": "hoststream_ctv", + "name": "HostStream CTV", + "property_type": "ctv_app", + "identifiers": [ + { + "type": "roku_channel_id", + "value": "123" + } + ] + } + ], + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "hoststream_ctv" + ], + "collections": [ + { + "publisher_domain": "channel-owner.example", + "collection_ids": [ + "retro_news" + ] + } + ] + } + ] + }, + "requiredHostPropertyIds": [ + "hoststream_ctv" + ] + }, + "expected": { + "semantics_version": "1", + "state": "verified_owner_sold", + "legs": { + "owner_collection_declared": { + "ok": true + }, + "owner_distribution_carriage": { + "ok": true + }, + "owner_agent_declared": { + "ok": true + }, + "host_authorization": { + "ok": true + }, + "inventory_partner_domain": { + "ok": false, + "failure": "ads_txt_unavailable" + } + }, + "resolved_collection_id": "retro_news" + } + }, + { + "id": "unknown-narrowing-extension", + "input": { + "ownerDomain": "channel-owner.example", + "hostDomain": "hoststream.example", + "agentUrl": "https://sales.channel-owner.example", + "collectionId": "retro_news", + "hostInventoryPartnerDomains": null, + "ownerManifest": { + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails" + } + ], + "collections": [ + { + "collection_id": "retro_news", + "name": "Retro News", + "kind": "channel", + "distribution": [ + { + "publisher_domain": "hoststream.example", + "property_ids": [ + "hoststream_ctv" + ] + } + ] + } + ] + }, + "hostManifest": { + "properties": [ + { + "property_id": "hoststream_ctv", + "name": "HostStream CTV", + "property_type": "ctv_app", + "identifiers": [ + { + "type": "roku_channel_id", + "value": "123" + } + ] + } + ], + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "hoststream_ctv" + ], + "collections": [ + { + "publisher_domain": "channel-owner.example", + "collection_ids": [ + "retro_news" + ] + } + ], + "future_scope": {} + } + ] + } + }, + "expected": { + "semantics_version": "1", + "state": "owner_attested", + "legs": { + "owner_collection_declared": { + "ok": true + }, + "owner_distribution_carriage": { + "ok": true + }, + "owner_agent_declared": { + "ok": true + }, + "host_authorization": { + "ok": false, + "failure": "unsupported_constraints" + }, + "inventory_partner_domain": { + "ok": false, + "failure": "ads_txt_unavailable" + } + }, + "resolved_collection_id": "retro_news" + } + }, + { + "id": "owner-revokes-host", + "input": { + "ownerDomain": "channel-owner.example", + "hostDomain": "hoststream.example", + "agentUrl": "https://sales.channel-owner.example", + "collectionId": "retro_news", + "hostInventoryPartnerDomains": null, + "ownerManifest": { + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails" + } + ], + "collections": [ + { + "collection_id": "retro_news", + "name": "Retro News", + "kind": "channel", + "distribution": [ + { + "publisher_domain": "hoststream.example", + "property_ids": [ + "hoststream_ctv" + ] + } + ] + } + ], + "revoked_publisher_domains": [ + "hoststream.example" + ] + }, + "hostManifest": { + "properties": [ + { + "property_id": "hoststream_ctv", + "name": "HostStream CTV", + "property_type": "ctv_app", + "identifiers": [ + { + "type": "roku_channel_id", + "value": "123" + } + ] + } + ], + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "hoststream_ctv" + ], + "collections": [ + { + "publisher_domain": "channel-owner.example", + "collection_ids": [ + "retro_news" + ] + } + ] + } + ] + } + }, + "expected": { + "semantics_version": "1", + "state": "owner_attested", + "legs": { + "owner_collection_declared": { + "ok": true + }, + "owner_distribution_carriage": { + "ok": true + }, + "owner_agent_declared": { + "ok": true + }, + "host_authorization": { + "ok": false, + "failure": "collection_scope_mismatch" + }, + "inventory_partner_domain": { + "ok": false, + "failure": "ads_txt_unavailable" + } + }, + "resolved_collection_id": "retro_news" + } + }, + { + "id": "owner-revokes-owner", + "input": { + "ownerDomain": "channel-owner.example", + "hostDomain": "hoststream.example", + "agentUrl": "https://sales.channel-owner.example", + "collectionId": "retro_news", + "hostInventoryPartnerDomains": null, + "ownerManifest": { + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails" + } + ], + "collections": [ + { + "collection_id": "retro_news", + "name": "Retro News", + "kind": "channel", + "distribution": [ + { + "publisher_domain": "hoststream.example", + "property_ids": [ + "hoststream_ctv" + ] + } + ] + } + ], + "revoked_publisher_domains": [ + "channel-owner.example" + ] + }, + "hostManifest": { + "properties": [ + { + "property_id": "hoststream_ctv", + "name": "HostStream CTV", + "property_type": "ctv_app", + "identifiers": [ + { + "type": "roku_channel_id", + "value": "123" + } + ] + } + ], + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "hoststream_ctv" + ], + "collections": [ + { + "publisher_domain": "channel-owner.example", + "collection_ids": [ + "retro_news" + ] + } + ] + } + ] + } + }, + "expected": { + "semantics_version": "1", + "state": "unverified", + "legs": { + "owner_collection_declared": { + "ok": false, + "failure": "publisher_revoked" + }, + "owner_distribution_carriage": { + "ok": false, + "failure": "collection_leg_failed" + }, + "owner_agent_declared": { + "ok": true + }, + "host_authorization": { + "ok": false, + "failure": "property_scope_mismatch" + }, + "inventory_partner_domain": { + "ok": false, + "failure": "ads_txt_unavailable" + } + } + } + }, + { + "id": "host-revokes-self", + "input": { + "ownerDomain": "channel-owner.example", + "hostDomain": "hoststream.example", + "agentUrl": "https://sales.channel-owner.example", + "collectionId": "retro_news", + "hostInventoryPartnerDomains": null, + "ownerManifest": { + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails" + } + ], + "collections": [ + { + "collection_id": "retro_news", + "name": "Retro News", + "kind": "channel", + "distribution": [ + { + "publisher_domain": "hoststream.example", + "property_ids": [ + "hoststream_ctv" + ] + } + ] + } + ] + }, + "hostManifest": { + "properties": [ + { + "property_id": "hoststream_ctv", + "name": "HostStream CTV", + "property_type": "ctv_app", + "identifiers": [ + { + "type": "roku_channel_id", + "value": "123" + } + ] + } + ], + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "hoststream_ctv" + ], + "collections": [ + { + "publisher_domain": "channel-owner.example", + "collection_ids": [ + "retro_news" + ] + } + ] + } + ], + "revoked_publisher_domains": [ + "hoststream.example" + ] + } + }, + "expected": { + "semantics_version": "1", + "state": "owner_attested", + "legs": { + "owner_collection_declared": { + "ok": true + }, + "owner_distribution_carriage": { + "ok": true + }, + "owner_agent_declared": { + "ok": true + }, + "host_authorization": { + "ok": false, + "failure": "property_scope_mismatch" + }, + "inventory_partner_domain": { + "ok": false, + "failure": "ads_txt_unavailable" + } + }, + "resolved_collection_id": "retro_news" + } + }, + { + "id": "malformed-revocation", + "input": { + "ownerDomain": "channel-owner.example", + "hostDomain": "hoststream.example", + "agentUrl": "https://sales.channel-owner.example", + "collectionId": "retro_news", + "hostInventoryPartnerDomains": null, + "ownerManifest": { + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails" + } + ], + "collections": [ + { + "collection_id": "retro_news", + "name": "Retro News", + "kind": "channel", + "distribution": [ + { + "publisher_domain": "hoststream.example", + "property_ids": [ + "hoststream_ctv" + ] + } + ] + } + ] + }, + "hostManifest": { + "properties": [ + { + "property_id": "hoststream_ctv", + "name": "HostStream CTV", + "property_type": "ctv_app", + "identifiers": [ + { + "type": "roku_channel_id", + "value": "123" + } + ] + } + ], + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "hoststream_ctv" + ], + "collections": [ + { + "publisher_domain": "channel-owner.example", + "collection_ids": [ + "retro_news" + ] + } + ] + } + ], + "revoked_publisher_domains": [ + {} + ] + } + }, + "expected": { + "semantics_version": "1", + "state": "owner_attested", + "legs": { + "owner_collection_declared": { + "ok": true + }, + "owner_distribution_carriage": { + "ok": true + }, + "owner_agent_declared": { + "ok": true + }, + "host_authorization": { + "ok": false, + "failure": "collection_scope_mismatch" + }, + "inventory_partner_domain": { + "ok": false, + "failure": "ads_txt_unavailable" + } + }, + "resolved_collection_id": "retro_news" + } + }, + { + "id": "iab-evidence-not-evaluated", + "input": { + "ownerDomain": "channel-owner.example", + "hostDomain": "hoststream.example", + "agentUrl": "https://sales.channel-owner.example", + "collectionId": "retro_news", + "hostInventoryPartnerDomains": null, + "ownerManifest": { + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails" + } + ], + "collections": [ + { + "collection_id": "retro_news", + "name": "Retro News", + "kind": "channel", + "distribution": [ + { + "publisher_domain": "hoststream.example", + "property_ids": [ + "hoststream_ctv" + ] + } + ] + } + ] + }, + "hostManifest": { + "properties": [ + { + "property_id": "hoststream_ctv", + "name": "HostStream CTV", + "property_type": "ctv_app", + "identifiers": [ + { + "type": "roku_channel_id", + "value": "123" + } + ] + } + ], + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "hoststream_ctv" + ], + "collections": [ + { + "publisher_domain": "channel-owner.example", + "collection_ids": [ + "retro_news" + ] + } + ] + } + ] + }, + "inventoryPartnerDomainEvaluated": false + }, + "expected": { + "semantics_version": "1", + "state": "verified_owner_sold", + "legs": { + "owner_collection_declared": { + "ok": true + }, + "owner_distribution_carriage": { + "ok": true + }, + "owner_agent_declared": { + "ok": true + }, + "host_authorization": { + "ok": true + }, + "inventory_partner_domain": { + "ok": false, + "failure": "not_evaluated" + } + }, + "resolved_collection_id": "retro_news" + } + }, + { + "id": "bounded-nested-evaluation", + "input": { + "ownerDomain": "channel-owner.example", + "hostDomain": "hoststream.example", + "agentUrl": "https://sales.channel-owner.example", + "collectionId": "retro_news", + "hostInventoryPartnerDomains": null, + "ownerManifest": { + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails" + } + ], + "collections": [ + { + "collection_id": "retro_news", + "name": "Retro News", + "kind": "channel", + "distribution": [ + { + "publisher_domain": "hoststream.example", + "property_ids": [ + "hoststream_ctv" + ] + } + ] + } + ] + }, + "hostManifest": { + "properties": [ + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {}, + {} + ], + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "hoststream_ctv" + ], + "collections": [ + { + "publisher_domain": "channel-owner.example", + "collection_ids": [ + "retro_news" + ] + } + ] + } + ] + } + }, + "expected": { + "semantics_version": "1", + "state": "unverified", + "legs": { + "owner_collection_declared": { + "ok": false, + "failure": "evaluation_limit_exceeded" + }, + "owner_distribution_carriage": { + "ok": false, + "failure": "evaluation_limit_exceeded" + }, + "owner_agent_declared": { + "ok": false, + "failure": "evaluation_limit_exceeded" + }, + "host_authorization": { + "ok": false, + "failure": "evaluation_limit_exceeded" + }, + "inventory_partner_domain": { + "ok": false, + "failure": "evaluation_limit_exceeded" + } + } + } + }, + { + "id": "host-delegated-without-owner-carriage", + "input": { + "ownerDomain": "channel-owner.example", + "hostDomain": "hoststream.example", + "agentUrl": "https://sales.channel-owner.example", + "collectionId": "retro_news", + "hostInventoryPartnerDomains": [ + "channel-owner.example" + ], + "ownerManifest": { + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails" + } + ], + "collections": [ + { + "collection_id": "retro_news", + "name": "Retro News", + "kind": "channel", + "distribution": [] + } + ] + }, + "hostManifest": { + "properties": [ + { + "property_id": "hoststream_ctv", + "name": "HostStream CTV", + "property_type": "ctv_app", + "identifiers": [ + { + "type": "roku_channel_id", + "value": "123" + } + ] + } + ], + "authorized_agents": [] + } + }, + "expected": { + "semantics_version": "1", + "state": "host_delegated", + "legs": { + "owner_collection_declared": { + "ok": true + }, + "owner_distribution_carriage": { + "ok": false, + "failure": "no_distribution_for_host" + }, + "owner_agent_declared": { + "ok": true + }, + "host_authorization": { + "ok": false, + "failure": "no_agent_entry" + }, + "inventory_partner_domain": { + "ok": true + } + }, + "resolved_collection_id": "retro_news" + } + }, + { + "id": "host-self-revocation-blocks-interim-evidence", + "input": { + "ownerDomain": "channel-owner.example", + "hostDomain": "hoststream.example", + "agentUrl": "https://sales.channel-owner.example", + "collectionId": "retro_news", + "hostInventoryPartnerDomains": [ + "channel-owner.example" + ], + "ownerManifest": { + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails" + } + ], + "collections": [ + { + "collection_id": "retro_news", + "name": "Retro News", + "kind": "channel", + "distribution": [ + { + "publisher_domain": "hoststream.example", + "property_ids": [ + "hoststream_ctv" + ] + } + ] + } + ] + }, + "hostManifest": { + "properties": [ + { + "property_id": "hoststream_ctv", + "name": "HostStream CTV", + "property_type": "ctv_app", + "identifiers": [ + { + "type": "roku_channel_id", + "value": "123" + } + ] + } + ], + "authorized_agents": [], + "revoked_publisher_domains": [ + "hoststream.example" + ] + } + }, + "expected": { + "semantics_version": "1", + "state": "owner_attested", + "legs": { + "owner_collection_declared": { + "ok": true + }, + "owner_distribution_carriage": { + "ok": true + }, + "owner_agent_declared": { + "ok": true + }, + "host_authorization": { + "ok": false, + "failure": "no_agent_entry" + }, + "inventory_partner_domain": { + "ok": true + } + }, + "resolved_collection_id": "retro_news" + } + }, + { + "id": "nested-collection-qualifier", + "input": { + "ownerDomain": "channel-owner.example", + "hostDomain": "hoststream.example", + "agentUrl": "https://sales.channel-owner.example", + "collectionId": "retro_news", + "hostInventoryPartnerDomains": null, + "ownerManifest": { + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails" + } + ], + "collections": [ + { + "collection_id": "retro_news", + "name": "Retro News", + "kind": "channel", + "distribution": [ + { + "publisher_domain": "hoststream.example", + "property_ids": [ + "hoststream_ctv" + ] + } + ] + } + ] + }, + "hostManifest": { + "properties": [ + { + "property_id": "hoststream_ctv", + "name": "HostStream CTV", + "property_type": "ctv_app", + "identifiers": [ + { + "type": "roku_channel_id", + "value": "123" + } + ] + } + ], + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "hoststream_ctv" + ], + "collections": [ + { + "publisher_domain": "channel-owner.example", + "collection_ids": [ + "retro_news" + ], + "countries": [ + "US" + ] + } + ] + } + ] + } + }, + "expected": { + "semantics_version": "1", + "state": "owner_attested", + "legs": { + "owner_collection_declared": { + "ok": true + }, + "owner_distribution_carriage": { + "ok": true + }, + "owner_agent_declared": { + "ok": true + }, + "host_authorization": { + "ok": false, + "failure": "unsupported_constraints" + }, + "inventory_partner_domain": { + "ok": false, + "failure": "ads_txt_unavailable" + } + }, + "resolved_collection_id": "retro_news" + } + }, + { + "id": "nested-property-qualifier", + "input": { + "ownerDomain": "channel-owner.example", + "hostDomain": "hoststream.example", + "agentUrl": "https://sales.channel-owner.example", + "collectionId": "retro_news", + "hostInventoryPartnerDomains": null, + "ownerManifest": { + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails" + } + ], + "collections": [ + { + "collection_id": "retro_news", + "name": "Retro News", + "kind": "channel", + "distribution": [ + { + "publisher_domain": "hoststream.example", + "property_ids": [ + "hoststream_ctv" + ] + } + ] + } + ] + }, + "hostManifest": { + "properties": [ + { + "property_id": "hoststream_ctv", + "name": "HostStream CTV", + "property_type": "ctv_app", + "identifiers": [ + { + "type": "roku_channel_id", + "value": "123" + } + ] + } + ], + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails", + "authorization_type": "publisher_properties", + "collections": [ + { + "publisher_domain": "channel-owner.example", + "collection_ids": [ + "retro_news" + ] + } + ], + "publisher_properties": [ + { + "publisher_domain": "hoststream.example", + "selection_type": "all", + "countries": [ + "US" + ] + } + ] + } + ] + } + }, + "expected": { + "semantics_version": "1", + "state": "owner_attested", + "legs": { + "owner_collection_declared": { + "ok": true + }, + "owner_distribution_carriage": { + "ok": true + }, + "owner_agent_declared": { + "ok": true + }, + "host_authorization": { + "ok": false, + "failure": "unsupported_constraints" + }, + "inventory_partner_domain": { + "ok": false, + "failure": "ads_txt_unavailable" + } + }, + "resolved_collection_id": "retro_news" + } + }, + { + "id": "held-revocation-with-host-unavailable", + "input": { + "ownerDomain": "channel-owner.example", + "hostDomain": "hoststream.example", + "agentUrl": "https://sales.channel-owner.example", + "collectionId": "retro_news", + "hostInventoryPartnerDomains": [ + "channel-owner.example" + ], + "ownerManifest": { + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails" + } + ], + "collections": [ + { + "collection_id": "retro_news", + "name": "Retro News", + "kind": "channel", + "distribution": [ + { + "publisher_domain": "hoststream.example", + "property_ids": [ + "hoststream_ctv" + ] + } + ] + } + ] + }, + "hostManifest": null, + "heldRevocations": { + "host": [ + "channel-owner.example" + ] + } + }, + "expected": { + "semantics_version": "1", + "state": "owner_attested", + "legs": { + "owner_collection_declared": { + "ok": true + }, + "owner_distribution_carriage": { + "ok": false, + "failure": "host_manifest_not_found" + }, + "owner_agent_declared": { + "ok": true + }, + "host_authorization": { + "ok": false, + "failure": "manifest_not_found" + }, + "inventory_partner_domain": { + "ok": true + } + }, + "resolved_collection_id": "retro_news" + } + }, + { + "id": "domain-level-iab-per-complete-collection", + "input": { + "ownerDomain": "channel-owner.example", + "hostDomain": "hoststream.example", + "agentUrl": "https://sales.channel-owner.example", + "hostInventoryPartnerDomains": null, + "ownerManifest": { + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails" + } + ], + "collections": [ + { + "collection_id": "retro_news", + "name": "Retro News", + "kind": "channel", + "distribution": [ + { + "publisher_domain": "hoststream.example", + "property_ids": [ + "hoststream_ctv" + ] + } + ] + }, + { + "collection_id": "web_channel", + "name": "Retro News", + "kind": "channel", + "distribution": [ + { + "publisher_domain": "hoststream.example", + "property_ids": [ + "web" + ] + } + ] + } + ] + }, + "hostManifest": { + "properties": [ + { + "property_id": "hoststream_ctv", + "name": "HostStream CTV", + "property_type": "ctv_app", + "identifiers": [ + { + "type": "roku_channel_id", + "value": "123" + } + ] + }, + { + "property_id": "web", + "name": "HostStream CTV", + "property_type": "website", + "identifiers": [ + { + "type": "roku_channel_id", + "value": "123" + } + ] + } + ], + "authorized_agents": [] + }, + "hostInventoryPartnerDomainsByFile": { + "ads.txt": [ + "channel-owner.example" + ], + "app-ads.txt": [] + } + }, + "expected": { + "semantics_version": "1", + "state": "host_delegated", + "legs": { + "owner_collection_declared": { + "ok": true + }, + "owner_distribution_carriage": { + "ok": true + }, + "owner_agent_declared": { + "ok": true + }, + "host_authorization": { + "ok": false, + "failure": "no_agent_entry" + }, + "inventory_partner_domain": { + "ok": true + } + }, + "resolved_collection_id": "web_channel" + } + } + ], + "ads_txt_policy_vectors": [ + { + "id": "ctv-needs-app-ads", + "input": { + "ownerDomain": "channel-owner.example", + "hostDomain": "hoststream.example", + "agentUrl": "https://sales.channel-owner.example", + "collectionId": "retro_news", + "hostInventoryPartnerDomains": null, + "ownerManifest": { + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails" + } + ], + "collections": [ + { + "collection_id": "retro_news", + "name": "Retro News", + "kind": "channel", + "distribution": [ + { + "publisher_domain": "hoststream.example", + "property_ids": [ + "hoststream_ctv" + ] + } + ] + } + ] + }, + "hostManifest": { + "properties": [ + { + "property_id": "hoststream_ctv", + "name": "HostStream CTV", + "property_type": "ctv_app", + "identifiers": [ + { + "type": "roku_channel_id", + "value": "123" + } + ] + } + ], + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "hoststream_ctv" + ], + "collections": [ + { + "publisher_domain": "channel-owner.example", + "collection_ids": [ + "retro_news" + ] + } + ] + } + ] + } + }, + "expected": { + "files": [ + "app-ads.txt" + ], + "requireAll": true + } + }, + { + "id": "website-needs-ads", + "input": { + "ownerDomain": "channel-owner.example", + "hostDomain": "hoststream.example", + "agentUrl": "https://sales.channel-owner.example", + "collectionId": "retro_news", + "hostInventoryPartnerDomains": null, + "ownerManifest": { + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails" + } + ], + "collections": [ + { + "collection_id": "retro_news", + "name": "Retro News", + "kind": "channel", + "distribution": [ + { + "publisher_domain": "hoststream.example", + "property_ids": [ + "hoststream_ctv" + ] + } + ] + } + ] + }, + "hostManifest": { + "properties": [ + { + "property_id": "hoststream_ctv", + "name": "HostStream CTV", + "property_type": "website", + "identifiers": [ + { + "type": "roku_channel_id", + "value": "123" + } + ] + } + ], + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "hoststream_ctv" + ], + "collections": [ + { + "publisher_domain": "channel-owner.example", + "collection_ids": [ + "retro_news" + ] + } + ] + } + ] + } + }, + "expected": { + "files": [ + "ads.txt" + ], + "requireAll": true + } + }, + { + "id": "mixed-surfaces-need-both", + "input": { + "ownerDomain": "channel-owner.example", + "hostDomain": "hoststream.example", + "agentUrl": "https://sales.channel-owner.example", + "collectionId": "retro_news", + "hostInventoryPartnerDomains": null, + "ownerManifest": { + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails" + } + ], + "collections": [ + { + "collection_id": "retro_news", + "name": "Retro News", + "kind": "channel", + "distribution": [ + { + "publisher_domain": "hoststream.example", + "property_ids": [ + "hoststream_ctv", + "web" + ] + } + ] + } + ] + }, + "hostManifest": { + "properties": [ + { + "property_id": "hoststream_ctv", + "name": "HostStream CTV", + "property_type": "ctv_app", + "identifiers": [ + { + "type": "roku_channel_id", + "value": "123" + } + ] + }, + { + "property_id": "web", + "name": "HostStream CTV", + "property_type": "website", + "identifiers": [ + { + "type": "roku_channel_id", + "value": "123" + } + ] + } + ], + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "hoststream_ctv" + ], + "collections": [ + { + "publisher_domain": "channel-owner.example", + "collection_ids": [ + "retro_news" + ] + } + ] + } + ] + } + }, + "expected": { + "files": [ + "ads.txt", + "app-ads.txt" + ], + "requireAll": true + } + }, + { + "id": "missing-host-fallback-files", + "input": { + "ownerDomain": "channel-owner.example", + "hostDomain": "hoststream.example", + "agentUrl": "https://sales.channel-owner.example", + "collectionId": "retro_news", + "hostInventoryPartnerDomains": null, + "ownerManifest": { + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails" + } + ], + "collections": [ + { + "collection_id": "retro_news", + "name": "Retro News", + "kind": "channel", + "distribution": [ + { + "publisher_domain": "hoststream.example", + "property_ids": [ + "hoststream_ctv" + ] + } + ] + } + ] + }, + "hostManifest": null + }, + "expected": { + "files": [ + "app-ads.txt", + "ads.txt" + ], + "requireAll": false + } + }, + { + "id": "dooh-has-no-iab-file", + "input": { + "ownerDomain": "channel-owner.example", + "hostDomain": "hoststream.example", + "agentUrl": "https://sales.channel-owner.example", + "collectionId": "retro_news", + "hostInventoryPartnerDomains": null, + "ownerManifest": { + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails" + } + ], + "collections": [ + { + "collection_id": "retro_news", + "name": "Retro News", + "kind": "channel", + "distribution": [ + { + "publisher_domain": "hoststream.example", + "property_ids": [ + "hoststream_ctv" + ] + } + ] + } + ] + }, + "hostManifest": { + "properties": [ + { + "property_id": "hoststream_ctv", + "name": "HostStream CTV", + "property_type": "dooh", + "identifiers": [ + { + "type": "roku_channel_id", + "value": "123" + } + ] + } + ], + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "hoststream_ctv" + ], + "collections": [ + { + "publisher_domain": "channel-owner.example", + "collection_ids": [ + "retro_news" + ] + } + ] + } + ] + } + }, + "expected": { + "files": [], + "requireAll": true + } + }, + { + "id": "bulk-fetch-includes-untyped-collection-fallback", + "input": { + "ownerDomain": "channel-owner.example", + "hostDomain": "hoststream.example", + "agentUrl": "https://sales.channel-owner.example", + "hostInventoryPartnerDomains": null, + "ownerManifest": { + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails" + } + ], + "collections": [ + { + "collection_id": "retro_news", + "name": "Retro News", + "kind": "channel", + "distribution": [ + { + "publisher_domain": "hoststream.example", + "identifiers": [ + { + "type": "publisher_channel_id", + "value": "retro" + } + ] + } + ] + }, + { + "collection_id": "web_channel", + "name": "Retro News", + "kind": "channel", + "distribution": [ + { + "publisher_domain": "hoststream.example", + "property_ids": [ + "web" + ] + } + ] + } + ] + }, + "hostManifest": { + "properties": [ + { + "property_id": "hoststream_ctv", + "name": "HostStream CTV", + "property_type": "ctv_app", + "identifiers": [ + { + "type": "roku_channel_id", + "value": "123" + } + ] + }, + { + "property_id": "web", + "name": "HostStream CTV", + "property_type": "website", + "identifiers": [ + { + "type": "roku_channel_id", + "value": "123" + } + ] + } + ], + "authorized_agents": [] + }, + "hostInventoryPartnerDomainsByFile": { + "ads.txt": [ + "channel-owner.example" + ], + "app-ads.txt": [] + } + }, + "expected": { + "files": [ + "ads.txt", + "app-ads.txt" + ], + "requireAll": false + } + } + ], + "inventory_partner_combination_vectors": [ + { + "id": "all-applicable-required", + "contents": [ + "inventorypartnerdomain=channel-owner.example", + "" + ], + "requireAll": true, + "expected": [] + }, + { + "id": "all-applicable-unavailable", + "contents": [ + "inventorypartnerdomain=channel-owner.example", + null + ], + "requireAll": true, + "expected": null + }, + { + "id": "unknown-surface-union", + "contents": [ + "inventorypartnerdomain=channel-owner.example", + null + ], + "requireAll": false, + "expected": [ + "channel-owner.example" + ] + }, + { + "id": "all-applicable-agree", + "contents": [ + "inventorypartnerdomain=channel-owner.example", + "INVENTORYPARTNERDOMAIN=channel-owner.example" + ], + "requireAll": true, + "expected": [ + "channel-owner.example" + ] + } + ], + "inventory_partner_domain_vectors": [ + { + "id": "case-whitespace-comments", + "text": "INVENTORYPARTNERDOMAIN = Channel-Owner.example # deal\n# inventorypartnerdomain=commented.example\ninventorypartnerdomain=other.example\ninventorypartnerdomain=not a domain", + "expected": [ + "channel-owner.example", + "other.example" + ] + } + ] +} diff --git a/test/lib/product-property-policy-client.test.js b/test/lib/product-property-policy-client.test.js index 75097379b..9b9ebf96e 100644 --- a/test/lib/product-property-policy-client.test.js +++ b/test/lib/product-property-policy-client.test.js @@ -657,3 +657,80 @@ describe('client product property policy enforcement', () => { assert.strictEqual(policyLog.request_property_list.resolution_error, 'list_agent_url_malformed'); }); }); + +describe('supply-path annotations across discovery completion paths', () => { + for (const taskName of ['get_products', 'list_products']) { + test(`${taskName} annotates immediate, polled, and webhook products before publication`, async () => { + const products = [ + makeProduct('owner-sold', 'host.example', { + collections: [{ publisher_domain: 'owner.example', collection_ids: ['channel'] }], + supply_path_state: 'verified_owner_sold', + }), + ]; + const handlerCalls = []; + const agent = makeClient({ + validation: { + supplyPathVerification: { + source: 'registry', + registry: { + verifySupplyPath: async request => ({ + ...request, + semantics_version: '1', + state: 'owner_attested', + legs: {}, + sources: { cached: true }, + checked_at: new Date().toISOString(), + }), + }, + }, + }, + handlers: { + [taskName === 'get_products' ? 'onGetProductsStatusChange' : 'onTaskStatusChange']: response => + handlerCalls.push(response), + }, + }); + ProtocolClient.callTool = async () => ({ status: 'completed', products, cache_scope: 'public' }); + const immediate = await agent.executeTask(taskName, taskName === 'get_products' ? { brief: 'sports' } : {}); + assert.strictEqual(immediate.success, true, JSON.stringify(immediate)); + assert.strictEqual(immediate.data.products[0].supply_path_state, 'owner_attested'); + ProtocolClient.callTool = async (_agent, tool) => + tool === taskName + ? { status: 'submitted', task_id: 'supply-path-task' } + : { + task_id: 'supply-path-task', + task_type: taskName, + protocol: 'media-buy', + status: 'completed', + created_at: '2026-06-02T12:00:00Z', + updated_at: '2026-06-02T12:00:01Z', + result: { products, cache_scope: 'public' }, + }; + const submitted = await agent.executeTask(taskName, taskName === 'get_products' ? { brief: 'sports' } : {}); + assert.strictEqual(submitted.status, 'submitted'); + const tracked = await submitted.submitted.track(); + assert.strictEqual(tracked.result.products[0].supply_path_state, 'owner_attested'); + const completed = await submitted.submitted.waitForCompletion(1); + assert.strictEqual(completed.data.products[0].supply_path_state, 'owner_attested'); + const next = await agent.executeTask(taskName, taskName === 'get_products' ? { brief: 'sports' } : {}); + await agent.handleWebhook( + { + idempotency_key: `supply_path_${taskName}_completed`, + operation_id: next.metadata.taskId, + task_id: 'supply-path-task', + task_type: taskName, + status: 'completed', + timestamp: new Date().toISOString(), + result: { products, cache_scope: 'public' }, + }, + taskName, + next.metadata.taskId + ); + assert.ok(handlerCalls.some(response => response.products?.[0]?.supply_path_state === 'owner_attested')); + assert.ok( + handlerCalls.every( + response => !response.products || response.products[0].supply_path_state !== 'verified_owner_sold' + ) + ); + }); + } +}); diff --git a/test/lib/supply-path.test.js b/test/lib/supply-path.test.js new file mode 100644 index 000000000..5ce911f7b --- /dev/null +++ b/test/lib/supply-path.test.js @@ -0,0 +1,667 @@ +const { describe, it } = require('node:test'); +const assert = require('node:assert/strict'); +const { readFileSync } = require('node:fs'); +const { createHash } = require('node:crypto'); +const sdk = require('../../dist/lib'); +const { + evaluateSupplyPath, + verifySupplyPath, + parseInventoryPartnerDomains, + annotateProductsSupplyPaths, + RegistryClient, +} = sdk; +const AGENT = 'https://sales.channel-owner.example'; +const OWNER = 'channel-owner.example'; +const HOST = 'hoststream.example'; +function input() { + return { + ownerDomain: OWNER, + hostDomain: HOST, + agentUrl: AGENT, + collectionId: 'retro_news', + hostInventoryPartnerDomains: null, + ownerManifest: { + authorized_agents: [{ url: AGENT, authorized_for: 'Owner avails' }], + collections: [ + { + collection_id: 'retro_news', + name: 'Retro News', + kind: 'channel', + distribution: [{ publisher_domain: HOST, property_ids: ['hoststream_ctv'] }], + }, + ], + }, + hostManifest: { + properties: [ + { + property_id: 'hoststream_ctv', + name: 'HostStream', + property_type: 'ctv_app', + identifiers: [{ type: 'roku_channel_id', value: '123' }], + }, + ], + authorized_agents: [ + { + url: AGENT, + authorized_for: 'Owner avails', + authorization_type: 'property_ids', + property_ids: ['hoststream_ctv'], + collections: [{ publisher_domain: OWNER, collection_ids: ['retro_news'] }], + }, + ], + }, + }; +} +const request = { owner_domain: OWNER, host_domain: HOST, agent_url: AGENT, collection_id: 'retro_news' }; +function transport(changes = {}, requests = []) { + const fixture = input(); + const responses = { + [`https://${OWNER}/.well-known/adagents.json`]: fixture.ownerManifest, + [`https://${HOST}/.well-known/adagents.json`]: fixture.hostManifest, + ...changes, + }; + return async (url, init) => { + requests.push({ url, init }); + assert.equal(init.redirect, 'manual'); + const value = responses[url]; + if (typeof value === 'function') return value(url, init); + if (value instanceof Response) return value.clone(); + if (value === undefined) return new Response('missing', { status: 404 }); + return new Response(JSON.stringify(value), { headers: { 'content-type': 'application/json' } }); + }; +} + +// This corpus is consumed verbatim by the upstream registry and this SDK. +describe('canonical shared supply-path golden vectors', () => { + it('preserves the pinned upstream bytes', () => { + const source = JSON.parse(readFileSync(require.resolve('../fixtures/supply-path/source.json'), 'utf8')); + const bytes = readFileSync(require.resolve('../fixtures/supply-path/vectors.json')); + assert.match(source.commit, /^[a-f0-9]{40}$/); + assert.equal(createHash('sha256').update(bytes).digest('hex'), source.sha256); + }); + const corpus = JSON.parse(readFileSync(require.resolve('../fixtures/supply-path/vectors.json'), 'utf8')); + const { supplyPathAdsTxtPolicy, combineInventoryPartnerDomains } = require('../../dist/lib/supply-path/evaluate'); + for (const vector of corpus.ads_txt_policy_vectors) + it(vector.id, () => assert.deepEqual(supplyPathAdsTxtPolicy(vector.input), vector.expected)); + for (const vector of corpus.inventory_partner_combination_vectors) + it(vector.id, () => + assert.deepEqual(combineInventoryPartnerDomains(vector.contents, vector.requireAll), vector.expected) + ); + for (const vector of corpus.vectors) + it(vector.id, () => { + const result = evaluateSupplyPath(vector.input); + const projection = { + ...(result.resolved_collection_id ? { resolved_collection_id: result.resolved_collection_id } : {}), + semantics_version: result.semantics_version, + state: result.state, + legs: Object.fromEntries( + Object.entries(result.legs).map(([key, leg]) => [ + key, + { ok: leg.ok, ...(leg.failure ? { failure: leg.failure } : {}) }, + ]) + ), + }; + assert.deepEqual(projection, vector.expected); + }); + for (const vector of corpus.inventory_partner_domain_vectors) + it(vector.id, () => assert.deepEqual(parseInventoryPartnerDomains(vector.text), vector.expected)); +}); + +describe('fail-closed authoritative semantics', () => { + for (const collections of [ + null, + {}, + 'all', + [], + [{ publisher_domain: OWNER, collection_ids: null }], + [{ publisher_domain: OWNER, collection_ids: [] }], + [{ publisher_domain: OWNER, collection_ids: ['retro_news', 42] }], + ]) { + it(`rejects malformed collection scope ${JSON.stringify(collections)}`, () => { + const evidence = input(); + evidence.hostManifest.authorized_agents[0].collections = collections; + const result = evaluateSupplyPath(evidence); + assert.equal(result.state, 'owner_attested'); + assert.equal(result.legs.host_authorization.failure, 'collection_scope_mismatch'); + }); + } + for (const field of ['countries', 'placement_ids', 'placement_tags', 'effective_from', 'effective_until']) { + it(`does not widen unevaluated ${field}`, () => { + const evidence = input(); + evidence.hostManifest.authorized_agents[0][field] = 'unparseable'; + assert.equal(evaluateSupplyPath(evidence).state, 'owner_attested'); + }); + } + it('refuses any dangling property ID, even alongside a valid ID', () => { + const evidence = input(); + evidence.ownerManifest.collections[0].distribution[0].property_ids.push('dangling'); + const result = evaluateSupplyPath(evidence); + assert.equal(result.state, 'owner_attested'); + assert.equal(result.legs.owner_distribution_carriage.failure, 'property_ids_unresolved'); + assert.deepEqual(result.legs.owner_distribution_carriage.property_ids_unmatched, ['dangling']); + }); + it('never treats unknown or signal authorization types as publisher-wide', () => { + for (const type of [undefined, 'signal_ids', 'future']) { + const evidence = input(); + evidence.hostManifest.authorized_agents[0].authorization_type = type; + assert.equal(evaluateSupplyPath(evidence).state, 'owner_attested'); + } + }); + it('checks identifier-only carriage against a resolvable host grant', () => { + const evidence = input(); + evidence.ownerManifest.collections[0].distribution[0] = { + publisher_domain: HOST, + identifiers: [{ type: 'publisher_channel_id', value: 'retro' }], + }; + assert.equal(evaluateSupplyPath(evidence).state, 'owner_attested'); + evidence.hostManifest.authorized_agents[0].property_ids = ['missing']; + assert.equal(evaluateSupplyPath(evidence).state, 'owner_attested'); + }); + it('accepts distribution with both property IDs and identifiers', () => { + const evidence = input(); + evidence.ownerManifest.collections[0].distribution[0].identifiers = [ + { type: 'publisher_channel_id', value: 'retro' }, + ]; + assert.equal(evaluateSupplyPath(evidence).state, 'verified_owner_sold'); + }); + it('never conflates URL paths by lowercasing or removing a slash', () => { + for (const url of [AGENT + '/Sales', AGENT + '/sales/']) { + const evidence = input(); + evidence.agentUrl = AGENT + '/sales'; + evidence.hostManifest.authorized_agents[0].url = url; + assert.equal(evaluateSupplyPath(evidence).state, 'owner_attested'); + } + }); + it('does not stitch collection A carriage to collection B authorization', () => { + const evidence = input(); + delete evidence.collectionId; + evidence.ownerManifest.collections.push({ + collection_id: 'other', + name: 'Other', + kind: 'channel', + distribution: [], + }); + evidence.hostManifest.authorized_agents[0].collections[0].collection_ids = ['other']; + assert.equal(evaluateSupplyPath(evidence).state, 'owner_attested'); + }); + it('honors host property revocation', () => { + const evidence = input(); + evidence.hostManifest.revoked_publisher_domains = [HOST]; + assert.equal(evaluateSupplyPath(evidence).state, 'owner_attested'); + }); + it('resolves property tags and rejects malformed publisher selectors', () => { + const evidence = input(); + evidence.hostManifest.properties[0].tags = ['ctv']; + const grant = evidence.hostManifest.authorized_agents[0]; + grant.authorization_type = 'property_tags'; + delete grant.property_ids; + grant.property_tags = ['ctv']; + assert.equal(evaluateSupplyPath(evidence).state, 'verified_owner_sold'); + grant.authorization_type = 'publisher_properties'; + grant.publisher_properties = [{ publisher_domain: HOST, publisher_domains: [HOST], selection_type: 'all' }]; + assert.equal(evaluateSupplyPath(evidence).state, 'owner_attested'); + }); +}); + +describe('live evidence retrieval', () => { + it('fetches authoritative files, returns hashes and replay bytes, and does not call the agent', async () => { + const calls = []; + const result = await verifySupplyPath(request, { + source: 'authoritative', + trustedFetchFn: transport({}, calls), + retainEvidenceBodies: true, + }); + assert.equal(result.state, 'verified_owner_sold'); + assert.equal(result.sources.cached, false); + assert.equal(calls.length, 2); + for (const item of result.sources.evidence) + assert.equal(item.sha256, createHash('sha256').update(Buffer.from(item.body_base64, 'base64')).digest('hex')); + assert.ok(calls.every(c => c.url.endsWith('/.well-known/adagents.json'))); + }); + it('uses app-ads.txt for interim host evidence and distinguishes unavailable from absent', async () => { + for (const [text, expected] of [ + ['INVENTORYPARTNERDOMAIN=channel-owner.example # owner', 'host_delegated'], + ['', 'owner_attested'], + ]) { + const host = input().hostManifest; + host.authorized_agents = []; + const result = await verifySupplyPath(request, { + source: 'authoritative', + trustedFetchFn: transport({ + [`https://${HOST}/.well-known/adagents.json`]: host, + [`https://${HOST}/app-ads.txt`]: new Response(text, { headers: { 'content-type': 'text/plain' } }), + }), + }); + assert.equal(result.state, expected); + assert.equal(result.legs.inventory_partner_domain.failure, text ? undefined : 'not_declared'); + } + }); + it('follows a publisher-origin authoritative_location once and retains the trust chain', async () => { + const target = 'https://cdn.example/owner.json'; + const result = await verifySupplyPath(request, { + source: 'authoritative', + trustedFetchFn: transport({ + [`https://${OWNER}/.well-known/adagents.json`]: { authoritative_location: target }, + [target]: input().ownerManifest, + }), + }); + assert.equal(result.state, 'verified_owner_sold'); + assert.ok(result.sources.evidence.some(e => e.delegated_to === target)); + }); + it('refuses cross-origin HTTP redirects without contacting the target', async () => { + const calls = []; + const result = await verifySupplyPath(request, { + source: 'authoritative', + trustedFetchFn: transport( + { + [`https://${OWNER}/.well-known/adagents.json`]: new Response('', { + status: 302, + headers: { location: 'https://other.example/manifest' }, + }), + }, + calls + ), + }); + assert.equal(result.state, 'unverified'); + assert.ok(!calls.some(c => c.url.includes('other.example'))); + assert.ok(result.sources.evidence.some(e => e.error === 'redirect_refused')); + }); + it('follows bounded same-origin HTTP redirects', async () => { + const result = await verifySupplyPath(request, { + source: 'authoritative', + trustedFetchFn: transport({ + [`https://${OWNER}/.well-known/adagents.json`]: new Response('', { + status: 302, + headers: { location: '/manifest.json' }, + }), + [`https://${OWNER}/manifest.json`]: input().ownerManifest, + }), + }); + assert.equal(result.state, 'verified_owner_sold'); + assert.equal(result.sources.evidence.length, 3); + }); + it('rejects private/metadata targets even with a trusted transport', async () => { + for (const target of ['https://127.0.0.1/manifest', 'https://169.254.169.254/manifest', 'https://[::1]/manifest']) { + await assert.rejects( + verifySupplyPath(request, { + source: 'authoritative', + trustedFetchFn: transport({ + [`https://${OWNER}/.well-known/adagents.json`]: { authoritative_location: target }, + }), + }), + /Refusing/ + ); + } + }); + it('fails closed on oversized, malformed, mislabeled, and chained documents', async () => { + const target = 'https://cdn.example/manifest.json'; + for (const document of [ + new Response('{', { headers: { 'content-type': 'application/json' } }), + new Response(JSON.stringify(input().ownerManifest), { headers: { 'content-type': 'text/html' } }), + { authoritative_location: target, authorized_agents: [] }, + { authorized_agents: 'all' }, + ]) { + const result = await verifySupplyPath(request, { + source: 'authoritative', + trustedFetchFn: transport({ + [`https://${OWNER}/.well-known/adagents.json`]: document, + [target]: { authoritative_location: 'https://next.example/' }, + }), + }); + assert.equal(result.state, 'unverified'); + } + const result = await verifySupplyPath(request, { + source: 'authoritative', + maxBodyBytes: 20, + trustedFetchFn: transport(), + }); + assert.equal(result.state, 'unverified'); + assert.ok(result.sources.evidence.some(e => e.error === 'body_exceeds_limit')); + }); + it('validates domains, IDs, bounds, and caller cancellation before network access', async () => { + const trustedFetchFn = () => { + throw new Error('unexpected fetch'); + }; + for (const owner_domain of [ + 'https://host.example/path', + 'x.example@internal', + 'x.example:444', + '127.0.0.1', + 'a..example', + ]) + await assert.rejects( + verifySupplyPath({ ...request, owner_domain }, { source: 'authoritative', trustedFetchFn }), + TypeError + ); + for (const timeoutMs of [0, -1, NaN, Infinity, 60001]) + await assert.rejects( + verifySupplyPath(request, { source: 'authoritative', timeoutMs, trustedFetchFn }), + TypeError + ); + await assert.rejects( + verifySupplyPath(request, { + source: 'authoritative', + signal: AbortSignal.abort(new Error('cancelled')), + trustedFetchFn, + }), + /cancelled/ + ); + }); +}); + +describe('registry wrapper and product discovery annotations', () => { + it('posts only the canonical request and preserves registry evidence', async () => { + const response = { + ...request, + ...evaluateSupplyPath(input()), + sources: { + owner_adagents_url: 'https://owner.example/', + host_adagents_url: 'https://host.example/', + cached: true, + }, + checked_at: '2026-09-14T00:00:00Z', + extension: 'preserved', + }; + const registry = new RegistryClient({ + apiKey: '', + fetch: async (url, init) => { + assert.equal(url, 'https://agenticadvertising.org/api/registry/verify/supply-path'); + assert.deepEqual(JSON.parse(init.body), request); + return new Response(JSON.stringify(response), { headers: { 'content-type': 'application/json' } }); + }, + }); + assert.deepEqual(await verifySupplyPath(request, { source: 'registry', registry }), response); + }); + it('annotates external selectors, deduplicates calls, and removes forged seller verdicts', async () => { + const product = { + product_id: 'actual-seller-product', + publisher_properties: [{ publisher_domain: HOST, selection_type: 'all' }], + collections: [{ publisher_domain: OWNER, collection_ids: ['retro_news'] }], + supply_path_state: 'unverified', + }; + const calls = []; + const result = await annotateProductsSupplyPaths([product, product], AGENT, { + source: 'authoritative', + trustedFetchFn: transport({}, calls), + }); + assert.equal(result[0].supply_path_state, 'verified_owner_sold'); + assert.equal(result[0].supply_path_verification.scope, 'product_properties'); + assert.equal(calls.length, 2); + assert.equal(product.supply_path_state, 'unverified'); + assert.equal(result.length, 2); + const invalid = await annotateProductsSupplyPaths( + [{ ...product, collections: [{ publisher_domain: OWNER }] }], + AGENT + ); + assert.equal(invalid[0].supply_path_state, 'unverified'); + assert.deepEqual(invalid[0].supply_path_verification.errors, ['invalid_product_selectors']); + assert.deepEqual(await annotateProductsSupplyPaths([], AGENT), []); + }); +}); + +describe('bounded evidence and complete product scope', () => { + it('bounds a stalled transport and a stalled response body even if the egress hook ignores abort', async () => { + for (const trustedFetchFn of [ + () => new Promise(() => {}), + async () => + new Response(new ReadableStream({ pull: () => new Promise(() => {}) }), { + headers: { 'content-type': 'application/json' }, + }), + ]) { + await assert.rejects( + verifySupplyPath(request, { source: 'authoritative', timeoutMs: 30, trustedFetchFn }), + /deadline/ + ); + } + }); + it('keeps concurrent owner and host pointer provenance associated with the correct response', async () => { + const ownerTarget = 'https://cdn.example/owner.json'; + const hostTarget = 'https://cdn.example/host.json'; + const result = await verifySupplyPath(request, { + source: 'authoritative', + trustedFetchFn: transport({ + [`https://${OWNER}/.well-known/adagents.json`]: { authoritative_location: ownerTarget }, + [`https://${HOST}/.well-known/adagents.json`]: { authoritative_location: hostTarget }, + [ownerTarget]: input().ownerManifest, + [hostTarget]: input().hostManifest, + }), + }); + for (const [publisher, target] of [ + [OWNER, ownerTarget], + [HOST, hostTarget], + ]) { + const pointer = result.sources.evidence.find( + e => e.publisher_domain === publisher && e.requested_url.endsWith('/.well-known/adagents.json') + ); + assert.equal(pointer.delegated_to, target); + } + }); + it('honors superseded_by without accepting stale grants or chained delegation', async () => { + const target = 'https://cdn.example/new.json'; + const result = await verifySupplyPath(request, { + source: 'authoritative', + trustedFetchFn: transport({ + [`https://${OWNER}/.well-known/adagents.json`]: { ...input().ownerManifest, superseded_by: target }, + [target]: { authorized_agents: [], collections: [] }, + }), + }); + assert.equal(result.state, 'unverified'); + }); + it('uses only applicable IAB files and reports deliberately skipped evidence', async () => { + const calls = []; + const fixture = input(); + fixture.hostManifest.authorized_agents = []; + const result = await verifySupplyPath(request, { + source: 'authoritative', + trustedFetchFn: transport( + { + [`https://${HOST}/.well-known/adagents.json`]: fixture.hostManifest, + [`https://${HOST}/ads.txt`]: new Response(`inventorypartnerdomain=${OWNER}`, { + headers: { 'content-type': 'text/plain' }, + }), + }, + calls + ), + }); + assert.equal(result.state, 'owner_attested'); + assert.equal(result.legs.inventory_partner_domain.failure, 'not_declared'); + assert.ok(!calls.some(c => c.url.endsWith('/ads.txt'))); + const verified = await verifySupplyPath(request, { source: 'authoritative', trustedFetchFn: transport() }); + assert.equal(verified.legs.inventory_partner_domain.failure, 'not_evaluated'); + }); + it('deduplicates evidence across different paths without reusing a different product property verdict', async () => { + const product = { + product_id: 'seller-product', + publisher_properties: [{ publisher_domain: HOST, selection_type: 'by_id', property_ids: ['hoststream_ctv'] }], + collections: [{ publisher_domain: OWNER, collection_ids: ['retro_news'] }], + }; + const calls = []; + const result = await annotateProductsSupplyPaths( + [ + product, + { + ...product, + publisher_properties: [{ publisher_domain: HOST, selection_type: 'by_id', property_ids: ['missing'] }], + }, + ], + AGENT, + { source: 'authoritative', trustedFetchFn: transport({}, calls) } + ); + assert.equal(result[0].supply_path_state, 'verified_owner_sold'); + assert.equal(result[1].supply_path_state, 'owner_attested'); + assert.equal(calls.filter(c => c.url.endsWith('/.well-known/adagents.json')).length, 2); + }); + it('does not discard an unresolved selector alongside a valid selector', async () => { + const result = await verifySupplyPath(request, { + source: 'authoritative', + trustedFetchFn: transport(), + propertySelectors: [ + { publisher_domain: HOST, selection_type: 'by_id', property_ids: ['hoststream_ctv'] }, + { publisher_domain: HOST, selection_type: 'by_tag', property_tags: ['missing'] }, + ], + }); + assert.equal(result.state, 'owner_attested'); + }); + it('holds revocations across refreshes and scopes them to the publisher authority', async () => { + const revocationStore = new sdk.InMemorySupplyPathRevocationStore(); + const revoked = input().hostManifest; + revoked.revoked_publisher_domains = [{ publisher_domain: OWNER, revoked_at: '2026-09-01T00:00:00Z' }]; + const first = await verifySupplyPath(request, { + source: 'authoritative', + revocationStore, + trustedFetchFn: transport({ [`https://${HOST}/.well-known/adagents.json`]: revoked }), + }); + assert.equal(first.state, 'owner_attested'); + const stale = await verifySupplyPath(request, { + source: 'authoritative', + revocationStore, + trustedFetchFn: transport(), + }); + assert.equal(stale.state, 'owner_attested'); + assert.equal(stale.sources.held_revocations.find(r => r.authority === HOST).entries[0].publisher_domain, OWNER); + assert.deepEqual(await revocationStore.observe('unrelated.example', []), []); + }); + it('propagates revocation storage failures instead of dropping the hold', async () => { + await assert.rejects( + verifySupplyPath(request, { + source: 'authoritative', + trustedFetchFn: transport(), + revocationStore: { + observe: async () => { + throw new Error('storage unavailable'); + }, + }, + }), + /storage unavailable/ + ); + }); + it('rejects older registry semantics and inconsistent verified legs while preserving new diagnostic strings', async () => { + const response = { + ...request, + ...evaluateSupplyPath(input()), + sources: { owner_adagents_url: `https://${OWNER}/`, host_adagents_url: `https://${HOST}/`, cached: true }, + checked_at: new Date().toISOString(), + }; + const registry = value => + new RegistryClient({ + fetch: async () => new Response(JSON.stringify(value), { headers: { 'content-type': 'application/json' } }), + }); + await assert.rejects( + verifySupplyPath(request, { + source: 'registry', + registry: registry({ ...response, semantics_version: undefined }), + }), + /Invalid registry/ + ); + await assert.rejects( + verifySupplyPath(request, { + source: 'registry', + registry: registry({ + ...response, + legs: { ...response.legs, owner_distribution_carriage: { ok: false, failure: 'property_ids_unresolved' } }, + }), + }), + /Invalid registry/ + ); + const extended = { + ...response, + state: 'owner_attested', + legs: { ...response.legs, host_authorization: { ok: false, failure: 'future_diagnostic' } }, + }; + assert.deepEqual(await verifySupplyPath(request, { source: 'registry', registry: registry(extended) }), extended); + }); +}); + +describe('review regressions at state and deadline boundaries', () => { + it('enforces retained revocations when the next host manifest cannot be fetched', async () => { + const revocationStore = new sdk.InMemorySupplyPathRevocationStore(); + await revocationStore.observe(HOST, [{ publisher_domain: OWNER, revoked_at: '2026-09-01T00:00:00Z' }]); + const result = await verifySupplyPath(request, { + source: 'authoritative', + revocationStore, + trustedFetchFn: transport({ + [`https://${HOST}/.well-known/adagents.json`]: new Response('unavailable', { status: 503 }), + [`https://${HOST}/app-ads.txt`]: new Response(`inventorypartnerdomain=${OWNER}`, { + headers: { 'content-type': 'text/plain' }, + }), + }), + }); + assert.equal(result.state, 'owner_attested'); + assert.equal(result.legs.host_authorization.failure, 'manifest_not_found'); + assert.equal(result.sources.held_revocations.find(r => r.authority === HOST).entries.length, 1); + }); + it('bounds durable revocation storage by the same overall deadline', async () => { + await assert.rejects( + verifySupplyPath(request, { + source: 'authoritative', + timeoutMs: 30, + trustedFetchFn: transport(), + revocationStore: { observe: () => new Promise(() => {}) }, + }), + /deadline/ + ); + }); + it('selects the strongest domain-level path using each collection applicable IAB evidence', async () => { + const corpus = JSON.parse(readFileSync(require.resolve('../fixtures/supply-path/vectors.json'), 'utf8')); + const fixture = corpus.vectors.find(v => v.id === 'domain-level-iab-per-complete-collection').input; + const result = await verifySupplyPath( + { owner_domain: OWNER, host_domain: HOST, agent_url: AGENT }, + { + source: 'authoritative', + trustedFetchFn: transport({ + [`https://${OWNER}/.well-known/adagents.json`]: fixture.ownerManifest, + [`https://${HOST}/.well-known/adagents.json`]: fixture.hostManifest, + [`https://${HOST}/ads.txt`]: new Response(`inventorypartnerdomain=${OWNER}`, { + headers: { 'content-type': 'text/plain' }, + }), + }), + } + ); + assert.equal(result.state, 'host_delegated'); + assert.equal(result.resolved_collection_id, 'web_channel'); + }); +}); + +it('bulk fetching preserves untyped collection fallback alongside a typed website collection', async () => { + const corpus = JSON.parse(readFileSync(require.resolve('../fixtures/supply-path/vectors.json'), 'utf8')); + const fixture = corpus.ads_txt_policy_vectors.find( + v => v.id === 'bulk-fetch-includes-untyped-collection-fallback' + ).input; + const calls = []; + const result = await verifySupplyPath( + { owner_domain: OWNER, host_domain: HOST, agent_url: AGENT }, + { + source: 'authoritative', + trustedFetchFn: transport( + { + [`https://${OWNER}/.well-known/adagents.json`]: fixture.ownerManifest, + [`https://${HOST}/.well-known/adagents.json`]: fixture.hostManifest, + [`https://${HOST}/app-ads.txt`]: new Response(`inventorypartnerdomain=${OWNER}`, { + headers: { 'content-type': 'text/plain' }, + }), + }, + calls + ), + } + ); + assert.equal(result.state, 'host_delegated'); + assert.equal(result.resolved_collection_id, 'retro_news'); + assert.ok(calls.some(c => c.url.endsWith('/app-ads.txt'))); +}); + +it('does not turn a malformed revocation list containing a valid denial into host delegation', async () => { + const host = input().hostManifest; + host.revoked_publisher_domains = [{ publisher_domain: OWNER, revoked_at: '2026-09-01T00:00:00Z' }, {}]; + await assert.rejects( + verifySupplyPath(request, { + source: 'authoritative', + trustedFetchFn: transport({ + [`https://${HOST}/.well-known/adagents.json`]: host, + [`https://${HOST}/app-ads.txt`]: new Response(`inventorypartnerdomain=${OWNER}`, { + headers: { 'content-type': 'text/plain' }, + }), + }), + }), + /Invalid publisher revocation evidence/ + ); +}); diff --git a/tsconfig.examples.json b/tsconfig.examples.json index f73789643..01e497075 100644 --- a/tsconfig.examples.json +++ b/tsconfig.examples.json @@ -12,6 +12,7 @@ } }, "include": [ + "examples/supply-path-verification.ts", "examples/comply-controller-seller.ts", "examples/seller-3.2-starter.ts", "examples/seller-test-controller.ts", From 7eb6790fdac6921e75b6fb722d6e6daa8a42ef88 Mon Sep 17 00:00:00 2001 From: Brian O'Kelley Date: Mon, 14 Sep 2026 15:15:07 +0000 Subject: [PATCH 02/21] fix(build): budget the 34 supply-path package artifacts --- scripts/check-package-size.mjs | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/scripts/check-package-size.mjs b/scripts/check-package-size.mjs index a7eefa43d..677528ebc 100644 --- a/scripts/check-package-size.mjs +++ b/scripts/check-package-size.mjs @@ -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; From 06bb53850bb33c143e71e31bcf29348f8061378c Mon Sep 17 00:00:00 2001 From: Brian O'Kelley Date: Mon, 14 Sep 2026 15:43:06 +0000 Subject: [PATCH 03/21] fix(supply-path): retain authority evidence and enforce shared publisher scope --- .../verify-authoritative-supply-paths.md | 2 + docs/guides/SUPPLY-PATH-VERIFICATION.md | 14 +- src/lib/discovery/types.ts | 2 + src/lib/supply-path/evaluate.ts | 44 ++- src/lib/supply-path/fetch-evidence.ts | 95 +++-- src/lib/supply-path/index.ts | 5 + src/lib/supply-path/products.ts | 2 +- src/lib/supply-path/revocations.ts | 72 +++- src/lib/supply-path/types.ts | 21 +- src/lib/supply-path/validation.ts | 62 +++- src/lib/supply-path/verify.ts | 14 +- .../product-property-policy-client.test.js | 19 +- test/lib/supply-path.test.js | 333 +++++++++++++++++- 13 files changed, 611 insertions(+), 74 deletions(-) diff --git a/.changeset/verify-authoritative-supply-paths.md b/.changeset/verify-authoritative-supply-paths.md index dae2798bd..5c3be475d 100644 --- a/.changeset/verify-authoritative-supply-paths.md +++ b/.changeset/verify-authoritative-supply-paths.md @@ -5,3 +5,5 @@ 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. diff --git a/docs/guides/SUPPLY-PATH-VERIFICATION.md b/docs/guides/SUPPLY-PATH-VERIFICATION.md index b0d9944c1..f9cc00227 100644 --- a/docs/guides/SUPPLY-PATH-VERIFICATION.md +++ b/docs/guides/SUPPLY-PATH-VERIFICATION.md @@ -48,7 +48,7 @@ const cached = await registry.verifySupplyPath(request); 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 wrapper does not promote registry provenance into authoritative evidence. +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 @@ -68,7 +68,7 @@ for (const product of annotated) { 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, 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). +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 @@ -78,7 +78,11 @@ Products, ordering and unrelated seller fields are preserved. Computed annotatio 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. 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. +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 on first observation with `InMemorySupplyPathAuthorityStore`. A later pointer change rejects before fetching the new location. Configure a durable shared `SupplyPathAuthorityStore` across restarts or workers; `check` must atomically pin a new publisher and reject a changed location. 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-observation pinning cannot detect an origin already compromised before the first 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. @@ -86,7 +90,9 @@ Evidence contains requested/resolved URLs, HTTP status, fetch time, SHA-256 of e `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`. -Previously observed publisher revocations 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 for each `(publisher_domain, revoked_at)` tuple. 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. +Previously observed publisher revocations 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. ## Contract and conformance diff --git a/src/lib/discovery/types.ts b/src/lib/discovery/types.ts index e966d6435..42920ce5d 100644 --- a/src/lib/discovery/types.ts +++ b/src/lib/discovery/types.ts @@ -125,6 +125,8 @@ export type CollectionDistribution = { publisher_domain: string } & ( } ); export interface DiscoveryCollection { + /** Required when a shared cross-origin document declares this publisher-scoped collection. */ + publisher_domain?: string; collection_id: string; name: string; kind?: string; diff --git a/src/lib/supply-path/evaluate.ts b/src/lib/supply-path/evaluate.ts index e434a7fc4..a9dffbf0c 100644 --- a/src/lib/supply-path/evaluate.ts +++ b/src/lib/supply-path/evaluate.ts @@ -55,12 +55,23 @@ function coversCollection(entry: Record, owner: string, id: str } /** Resolve one entry at a time: separate grants are alternatives, never merged across collection scopes. */ -function propertyScope(entry: Record, host: string, manifest: SupplyPathManifest): Set { +function propertyScope( + entry: Record, + host: string, + manifest: SupplyPathManifest, + requirePublisher = false +): Set { if (revoked(manifest, host)) return new Set(); + if ( + !['property_ids', 'property_tags', 'publisher_properties', 'inline_properties'].includes( + String(entry.authorization_type) + ) + ) + return new Set(); if (entry.authorization_type === 'publisher_properties') { if (!Array.isArray(entry.publisher_properties) || entry.publisher_properties.length === 0) return new Set(); const properties = records(manifest.properties).filter( - p => p.publisher_domain === undefined || domain(p.publisher_domain) === host + p => (p.publisher_domain === undefined && !requirePublisher) || domain(p.publisher_domain) === host ); const ids = new Set(); try { @@ -92,13 +103,20 @@ function propertyScope(entry: Record, host: string, manifest: S if (entry.authorization_type === 'property_ids' && !strings(entry.property_ids)) return new Set(); if (entry.authorization_type === 'property_tags' && !strings(entry.property_tags)) return new Set(); // Reuse discovery's discriminator, missing-selector, and revocation semantics. + if (manifest.properties !== undefined && (!Array.isArray(manifest.properties) || !manifest.properties.every(record))) + return new Set(); + if ( + entry.authorization_type === 'inline_properties' && + (!Array.isArray(entry.properties) || !entry.properties.every(record)) + ) + return new Set(); const result = resolveAgentProperties( { ...manifest, authorized_agents: [entry as unknown as AuthorizedAgent] } as AdAgentsJson, String(entry.url) ); return new Set( result.properties - .filter(p => p.publisher_domain === undefined || domain(p.publisher_domain) === host) + .filter(p => (p.publisher_domain === undefined && !requirePublisher) || domain(p.publisher_domain) === host) .map(p => p.property_id) .filter((id): id is string => typeof id === 'string' && id.length > 0) ); @@ -222,7 +240,11 @@ export function evaluateSupplyPath(input: SupplyPathInput): SupplyPathVerdict { ); }; const collectionLeg: SupplyPathLegs['owner_collection_declared'] = { ok: false }; - const declared = records(ownerManifest?.collections); + const declared = records(ownerManifest?.collections).filter( + c => + (c.publisher_domain === undefined && !input.requireExplicitOwnerPublisherDomain) || + domain(c.publisher_domain) === owner + ); const targets = declared.filter(c => c.collection_id === input.collectionId && typeof c.collection_id === 'string'); if (!ownerManifest) collectionLeg.failure = 'manifest_not_found'; else if (owner && isRevoked('owner', owner)) collectionLeg.failure = 'publisher_revoked'; @@ -272,7 +294,9 @@ export function evaluateSupplyPath(input: SupplyPathInput): SupplyPathVerdict { carriage.property_ids_unmatched = claimed; } else { const properties = records(hostManifest.properties).filter( - p => p.publisher_domain === undefined || domain(p.publisher_domain) === host + p => + (p.publisher_domain === undefined && !input.requireExplicitHostPublisherDomain) || + domain(p.publisher_domain) === host ); const counts = new Map(); for (const property of properties) counts.set(property.property_id, (counts.get(property.property_id) ?? 0) + 1); @@ -290,6 +314,7 @@ export function evaluateSupplyPath(input: SupplyPathInput): SupplyPathVerdict { e => agentIdentity(e.url) === agent && owner && + (!input.requireExplicitOwnerPublisherDomain || e.collections !== undefined) && coversCollection(e, owner, input.collectionId) && !unsupportedConstraints(e).length ) @@ -314,7 +339,7 @@ export function evaluateSupplyPath(input: SupplyPathInput): SupplyPathVerdict { collectionLeg.ok && covered.find(e => { if (unsupportedConstraints(e).length) return false; - const scope = propertyScope(e, host, hostManifest); + const scope = propertyScope(e, host, hostManifest, input.requireExplicitHostPublisherDomain); const required = input.requiredHostPropertyIds ?? claimed; if ( input.requiredHostPropertyIds && @@ -414,7 +439,12 @@ export function supplyPathAdsTxtPolicy(input: SupplyPathInput): { ) ); const requested = input.requiredHostPropertyIds ? new Set(input.requiredHostPropertyIds) : collectionIds; - const properties = records(input.hostManifest?.properties).filter(p => requested.has(String(p.property_id))); + const properties = records(input.hostManifest?.properties).filter( + p => + requested.has(String(p.property_id)) && + ((p.publisher_domain === undefined && !input.requireExplicitHostPublisherDomain) || + domain(p.publisher_domain) === domain(input.hostDomain)) + ); const files = new Set<'ads.txt' | 'app-ads.txt'>(); for (const property of properties) { if (property.property_type === 'website') files.add('ads.txt'); diff --git a/src/lib/supply-path/fetch-evidence.ts b/src/lib/supply-path/fetch-evidence.ts index 0dcff0fb9..a79a8459c 100644 --- a/src/lib/supply-path/fetch-evidence.ts +++ b/src/lib/supply-path/fetch-evidence.ts @@ -1,10 +1,11 @@ +import { defaultSupplyPathAuthorities } from './revocations'; import { withAbortSignal } from '../protocols/abort'; import { createHash } from 'node:crypto'; import { parse } from 'secure-json-parse'; import { SsrfRefusedError, SSRF_TRANSIENT_CODES, type SsrfFetchResult } from '../net/ssrf-fetch'; import { ssrfSafeFetchAdAgents, AdAgentsRedirectRefusedError } from '../discovery/adagents-redirects'; import type { AuthoritativeSupplyPathOptions, SupplyPathEvidence, SupplyPathManifest } from './types'; -import { defaultSupplyPathRevocations, parseRevocations } from './revocations'; +import { defaultSupplyPathRevocations, parseRevocations, type SupplyPathRevocation } from './revocations'; import { record } from './validation'; export function boundedOption(value: number | undefined, fallback: number, maximum: number, name: string): number { @@ -17,6 +18,9 @@ export function boundedOption(value: number | undefined, fallback: number, maxim /** A verification-local evidence session. No cached verdict survives a request. */ export class SupplyPathEvidenceSession { readonly evidence: SupplyPathEvidence[] = []; + readonly crossOriginAuthorities = new Set(); + private readonly checkedAuthorities = new Set(); + private readonly observedRevocations = new Map(); readonly revocations = new Map(); readonly signal: AbortSignal; private readonly maxBodyBytes: number; @@ -150,20 +154,22 @@ export class SupplyPathEvidenceSession { } } private parseManifest(publisher: string, response: SsrfFetchResult): SupplyPathManifest | null { + let document: unknown; try { - const document: unknown = parse(new TextDecoder('utf-8', { fatal: true }).decode(response.body)); + document = parse(new TextDecoder('utf-8', { fatal: true }).decode(response.body)); if (!record(document)) throw new Error('not_object'); - return document; } catch { - this.evidence.push({ - kind: 'adagents', - publisher_domain: publisher, - requested_url: response.url, - fetched_at: new Date().toISOString(), - error: 'invalid_document', - }); + this.documentError(publisher, response, 'invalid_document'); return null; } + const denials = parseRevocations(document.revoked_publisher_domains); + if (denials === null) { + this.documentError(publisher, response, 'invalid_revocations'); + throw new TypeError('Invalid publisher revocation evidence'); + } + // Denials survive invalid affirmative envelopes and failed/chained pointers. + this.observedRevocations.set(publisher, [...(this.observedRevocations.get(publisher) ?? []), ...denials]); + return document; } private documentError(publisher: string, response: SsrfFetchResult, error: string): void { this.evidence.push({ @@ -192,6 +198,25 @@ export class SupplyPathEvidenceSession { } const evidence = this.provenance.get(initial); if (evidence) evidence.delegated_to = target; + let location: URL; + try { + location = new URL(target); + } catch { + this.documentError(publisher, initial, 'invalid_authoritative_location'); + return null; + } + if ( + location.protocol !== 'https:' || + location.username || + location.password || + location.hash || + (location.port && location.port !== '443') + ) { + this.documentError(publisher, initial, 'invalid_authoritative_location'); + return null; + } + await this.checkAuthority(publisher, location.href); + if (location.origin !== new URL(url).origin) this.crossOriginAuthorities.add(publisher); const response = await this.read(publisher, 'adagents', target, true); if (!response) return null; manifest = this.parseManifest(publisher, response); @@ -203,28 +228,46 @@ export class SupplyPathEvidenceSession { } if (!Array.isArray(manifest.authorized_agents)) { this.documentError(publisher, initial, 'missing_authorized_agents'); - return null; + // Preserve denials even when the affirmative authorization list is malformed. + return { revoked_publisher_domains: manifest.revoked_publisher_domains }; } return manifest; } + private async checkAuthority(publisher: string, location: string): Promise { + let accepted: boolean; + try { + accepted = await withAbortSignal([this.signal], undefined, () => + (this.options.authorityStore ?? defaultSupplyPathAuthorities).check(publisher, location) + ); + } catch (cause) { + this.signal.throwIfAborted(); + throw new Error('Supply-path authority storage failed', { cause }); + } + this.signal.throwIfAborted(); + if (!accepted) + throw new TypeError( + `Authoritative location changed for ${publisher} to ${location}; independently confirm the publisher migration before updating its pin` + ); + this.checkedAuthorities.add(publisher); + } private async readAndRemember(publisher: string): Promise { const manifest = await this.readAdagents(publisher); - const observed = parseRevocations(manifest?.revoked_publisher_domains); - if (observed === null) { - this.evidence.push({ - kind: 'adagents', - publisher_domain: publisher, - requested_url: `https://${publisher}/.well-known/adagents.json`, - fetched_at: new Date().toISOString(), - error: 'invalid_revocations', - }); - throw new TypeError('Invalid publisher revocation evidence'); + if (manifest && !this.checkedAuthorities.has(publisher)) + await this.checkAuthority(publisher, `https://${publisher}/.well-known/adagents.json`); + const observed = this.observedRevocations.get(publisher) ?? []; + let held: readonly SupplyPathRevocation[]; + try { + held = await withAbortSignal([this.signal], undefined, () => + (this.options.revocationStore ?? defaultSupplyPathRevocations).observe(publisher, observed) + ); + } catch (cause) { + this.signal.throwIfAborted(); + throw new Error('Supply-path revocation storage failed', { cause }); } - const held = await withAbortSignal([this.signal], undefined, () => - (this.options.revocationStore ?? defaultSupplyPathRevocations).observe(publisher, observed ?? []) - ); this.signal.throwIfAborted(); - this.revocations.set(publisher, held); - return manifest ? { ...manifest, revoked_publisher_domains: [...held] } : null; + // Persistence can add prior denials; it cannot erase current wire evidence. + const effective = [...new Map([...held, ...observed].map(entry => [entry.publisher_domain, entry])).values()]; + this.revocations.set(publisher, effective); + return manifest ? { ...manifest, revoked_publisher_domains: effective } : null; } } diff --git a/src/lib/supply-path/index.ts b/src/lib/supply-path/index.ts index 4bccd3245..46bb09f39 100644 --- a/src/lib/supply-path/index.ts +++ b/src/lib/supply-path/index.ts @@ -11,3 +11,8 @@ export { type SupplyPathRevocationStore, type SupplyPathRevocation, } from './revocations'; +export { + defaultSupplyPathAuthorities, + InMemorySupplyPathAuthorityStore, + type SupplyPathAuthorityStore, +} from './revocations'; diff --git a/src/lib/supply-path/products.ts b/src/lib/supply-path/products.ts index 701b8e4b5..f30c87b9a 100644 --- a/src/lib/supply-path/products.ts +++ b/src/lib/supply-path/products.ts @@ -109,7 +109,7 @@ export async function annotateProductsSupplyPaths( } return { keys, errors }; }); - const outcomes = new Map(); + const outcomes = new Map(); // Bound fan-out without allocating one network operation per product. const pending = [...requests.entries()]; let position = 0; diff --git a/src/lib/supply-path/revocations.ts b/src/lib/supply-path/revocations.ts index acb54a290..30382016e 100644 --- a/src/lib/supply-path/revocations.ts +++ b/src/lib/supply-path/revocations.ts @@ -1,13 +1,30 @@ import { domain, record } from './validation'; +/** Admission limits protect process-local defaults; existing evidence is never evicted to admit another authority. */ +class AuthorityAdmissionBudget { + private windowStart = Date.now(); + private admitted = 0; + consume(): void { + const now = Date.now(); + if (now >= this.windowStart + 60_000) { + this.windowStart = now; + this.admitted = 0; + } + if (this.admitted >= 128) throw new Error('Supply-path new-authority admission rate exceeded'); + this.admitted++; + } +} + export interface SupplyPathRevocation { publisher_domain: string; revoked_at: string; } /** * Atomic, authority-scoped seven-day revocation hold. Durable implementations - * must preserve the first observation of each (publisher_domain, revoked_at) - * tuple, and reject on storage failure instead of returning an empty set. + * must key by authority and publisher_domain, preserving first observation + * across changed publisher timestamps, and reject on storage failure instead of returning an empty set. + * Capture tenant identity from trusted application context in the store instance; + * include that tenant in every key and transaction. Publisher evidence must never select a tenant. */ export interface SupplyPathRevocationStore { observe(authority: string, revoked: readonly SupplyPathRevocation[]): Promise; @@ -15,15 +32,32 @@ export interface SupplyPathRevocationStore { /** Process-local default. Use a durable shared store across workers/restarts. */ export class InMemorySupplyPathRevocationStore implements SupplyPathRevocationStore { + private readonly admission = new AuthorityAdmissionBudget(); private readonly entries = new Map(); async observe(authority: string, revoked: readonly SupplyPathRevocation[]): Promise { const now = Date.now(); for (const [key, value] of this.entries) if (value.expires <= now) this.entries.delete(key); + const scoped = new Set( + [...this.entries.values()] + .filter(value => value.authority === authority) + .map(value => value.entry.publisher_domain) + ); + const existingAuthority = scoped.size > 0; + for (const entry of revoked) scoped.add(entry.publisher_domain); + if (scoped.size > 1024) throw new Error('Supply-path publisher authority revocation capacity exceeded'); + const newEntries = revoked.filter(entry => !this.entries.has(JSON.stringify([authority, entry.publisher_domain]))); + const newCount = new Set(newEntries.map(entry => entry.publisher_domain)).size; + if (this.entries.size + newCount > 10000) throw new Error('Supply-path revocation store capacity exceeded'); + if (!existingAuthority && scoped.size > 0) this.admission.consume(); for (const entry of revoked) { - const key = JSON.stringify([authority, entry.publisher_domain, entry.revoked_at]); - if (this.entries.has(key)) continue; + const key = JSON.stringify([authority, entry.publisher_domain]); + const prior = this.entries.get(key); + if (prior) { + if (Date.parse(entry.revoked_at) < Date.parse(prior.entry.revoked_at)) + prior.entry.revoked_at = entry.revoked_at; + continue; + } // Never evict a live revocation to accommodate counterparty-controlled data. - if (this.entries.size >= 10000) throw new Error('Supply-path revocation store capacity exceeded'); this.entries.set(key, { authority, entry: { ...entry }, expires: now + 7 * 86400000 }); } return [...this.entries.values()].filter(value => value.authority === authority).map(value => ({ ...value.entry })); @@ -50,3 +84,31 @@ export function parseRevocations(value: unknown): SupplyPathRevocation[] | null } return entries; } + +/** Atomic trust-on-first-use storage. Capture the authenticated tenant in the store instance and namespace every pin by that tenant. */ +export interface SupplyPathAuthorityStore { + /** Pin the first location; subsequently return true only for that location. Storage failures must reject. */ + check(publisherDomain: string, location: string): Promise; +} + +/** Process-local pointer integrity. Use durable shared storage across workers/restarts. */ +export class InMemorySupplyPathAuthorityStore implements SupplyPathAuthorityStore { + private readonly admission = new AuthorityAdmissionBudget(); + private readonly locations = new Map(); + async check(publisherDomain: string, location: string): Promise { + const pinned = this.locations.get(publisherDomain); + if (pinned !== undefined) return pinned === location; + if (this.locations.size >= 10000) throw new Error('Supply-path authority store capacity exceeded'); + this.admission.consume(); + this.locations.set(publisherDomain, location); + return true; + } + /** Call only after independently confirming a publisher's migration. Never call from an automatic retry. */ + approveChange(publisherDomain: string, location: string): void { + if (!this.locations.has(publisherDomain) && this.locations.size >= 10000) + throw new Error('Supply-path authority store capacity exceeded'); + if (!this.locations.has(publisherDomain)) this.admission.consume(); + this.locations.set(publisherDomain, location); + } +} +export const defaultSupplyPathAuthorities = new InMemorySupplyPathAuthorityStore(); diff --git a/src/lib/supply-path/types.ts b/src/lib/supply-path/types.ts index 78aea62e9..706fae3e4 100644 --- a/src/lib/supply-path/types.ts +++ b/src/lib/supply-path/types.ts @@ -83,6 +83,10 @@ export interface SupplyPathInput { collectionId?: string; /** Optional concrete product scope, resolved from the host manifest. Empty means unresolved. */ requiredHostPropertyIds?: string[]; + /** Cross-origin authoritative documents must explicitly attribute every host property. */ + requireExplicitHostPublisherDomain?: boolean; + /** Cross-origin owner catalogs must explicitly attribute collections and owner agent grants. */ + requireExplicitOwnerPublisherDomain?: boolean; ownerManifest: SupplyPathManifest | null; hostManifest: SupplyPathManifest | null; /** @@ -109,7 +113,16 @@ export interface SupplyPathRequest { export interface RegistrySupplyPathResult extends SupplyPathRequest, Omit { legs: { [K in keyof SupplyPathLegs]: Omit & { failure?: string } }; - sources: { owner_adagents_url: string; host_adagents_url: string; cached: boolean }; + sources: { + owner_adagents_url: string; + host_adagents_url: string; + cached: boolean; + /** Cache observation times, distinct from the verdict's checked_at. */ + owner_fetched_at: string | null; + host_fetched_at: string | null; + owner_resolved_url: string | null; + host_resolved_url: string | null; + }; checked_at: string; } @@ -131,11 +144,11 @@ export interface SupplyPathEvidence { body_base64?: string; } -export interface AuthoritativeSupplyPathResult extends RegistrySupplyPathResult { +export interface AuthoritativeSupplyPathResult extends Omit { source: 'authoritative'; legs: SupplyPathLegs; property_selectors?: import('../discovery/types').SinglePublisherPropertySelector[]; - sources: RegistrySupplyPathResult['sources'] & { + sources: Pick & { cached: false; evidence: SupplyPathEvidence[]; held_revocations: Array<{ authority: string; entries: readonly import('./revocations').SupplyPathRevocation[] }>; @@ -146,6 +159,8 @@ export interface AuthoritativeSupplyPathOptions { source: 'authoritative'; /** Defaults to a process-local seven-day hold; supply durable storage across workers/restarts. */ revocationStore?: import('./revocations').SupplyPathRevocationStore; + /** Pins authoritative locations. Changed pointers require independently confirmed migration. */ + authorityStore?: import('./revocations').SupplyPathAuthorityStore; /** Optional product property scope. Every selected host property must be proven. */ propertySelectors?: import('../discovery/types').SinglePublisherPropertySelector[]; /** Overall deadline, including all evidence and redirect fetches. Default 15 seconds, max 60 seconds. */ diff --git a/src/lib/supply-path/validation.ts b/src/lib/supply-path/validation.ts index 78d56b144..8ec5ab881 100644 --- a/src/lib/supply-path/validation.ts +++ b/src/lib/supply-path/validation.ts @@ -51,7 +51,10 @@ export function assertRegistrySupplyPathResult( const fail = (): never => { throw new TypeError('Invalid registry supply-path response'); }; - if (!record(value) || value.semantics_version !== '1' || !record(value.legs) || !record(value.sources)) return fail(); + if (!record(value)) return fail(); + if (value.semantics_version !== '1') + throw new TypeError('Invalid registry supply-path response: semantics_version 1 required; upgrade the registry'); + if (!record(value.legs) || !record(value.sources)) return fail(); if (!['verified_owner_sold', 'host_delegated', 'owner_attested', 'unverified'].includes(String(value.state))) return fail(); if ( @@ -76,24 +79,36 @@ export function assertRegistrySupplyPathResult( return fail(); } } - const failures: Record = { - owner_collection_declared: ['manifest_not_found', 'no_collections_declared', 'collection_not_declared'], - owner_distribution_carriage: [ - 'collection_leg_failed', - 'no_distribution_for_host', - 'property_ids_unresolved', - 'host_manifest_not_found', - ], - owner_agent_declared: ['manifest_not_found', 'agent_not_declared_by_owner'], - host_authorization: [ - 'manifest_not_found', - 'no_agent_entry', - 'collection_scope_mismatch', - 'property_scope_mismatch', - ], - inventory_partner_domain: ['not_declared', 'ads_txt_unavailable'], - }; - for (const key of Object.keys(failures)) { + for (const key of ['owner_fetched_at', 'host_fetched_at']) { + const timestamp = value.sources[key]; + if (timestamp !== null && (typeof timestamp !== 'string' || !Number.isFinite(Date.parse(timestamp)))) return fail(); + } + for (const key of ['owner_resolved_url', 'host_resolved_url']) { + const location = value.sources[key]; + if (location === null) continue; + if (typeof location !== 'string' || location.length > 8192) return fail(); + try { + const parsed = new URL(location); + if ( + parsed.protocol !== 'https:' || + parsed.username || + parsed.password || + parsed.hash || + (parsed.port && parsed.port !== '443') + ) + return fail(); + } catch { + return fail(); + } + } + const legNames = [ + 'owner_collection_declared', + 'owner_distribution_carriage', + 'owner_agent_declared', + 'host_authorization', + 'inventory_partner_domain', + ]; + for (const key of legNames) { const leg = value.legs[key]; if (!record(leg) || typeof leg.ok !== 'boolean' || (leg.detail !== undefined && typeof leg.detail !== 'string')) return fail(); @@ -104,6 +119,15 @@ export function assertRegistrySupplyPathResult( } } const ok = (key: string) => (value.legs as Record>)[key]?.ok === true; + if (ok('owner_collection_declared')) { + if ( + typeof value.resolved_collection_id !== 'string' || + !value.resolved_collection_id.trim() || + value.resolved_collection_id.length > 256 || + (request.collection_id !== undefined && value.resolved_collection_id !== request.collection_id) + ) + return fail(); + } else if (value.resolved_collection_id !== undefined) return fail(); // Check the registry's documented ladder; do not silently recompute a remote // verdict using assumptions about evidence that was not returned. if ( diff --git a/src/lib/supply-path/verify.ts b/src/lib/supply-path/verify.ts index 8bacf58fb..9b96ba9c7 100644 --- a/src/lib/supply-path/verify.ts +++ b/src/lib/supply-path/verify.ts @@ -12,7 +12,7 @@ import { supplyPathAdsTxtPolicy, parseInventoryPartnerDomains, } from './evaluate'; -import { validateSupplyPathRequest } from './validation'; +import { assertRegistrySupplyPathResult, validateSupplyPathRequest } from './validation'; import type { SupplyPathRequest, VerifySupplyPathOptions, @@ -40,7 +40,11 @@ export async function verifySupplyPath( options: VerifySupplyPathOptions = { source: 'authoritative' } ): Promise { const normalized = validateSupplyPathRequest(request); - if (options.source === 'registry') return (options.registry ?? new RegistryClient()).verifySupplyPath(normalized); + if (options.source === 'registry') { + const result = await (options.registry ?? new RegistryClient()).verifySupplyPath(normalized); + assertRegistrySupplyPathResult(result, normalized); + return result; + } if (options.source !== 'authoritative') throw new TypeError('source must be registry or authoritative'); const session = new SupplyPathEvidenceSession(options); try { @@ -69,6 +73,8 @@ export async function verifyAuthoritativeSupplyPath( collectionId: normalized.collection_id, ownerManifest, hostManifest, + requireExplicitOwnerPublisherDomain: session.crossOriginAuthorities.has(normalized.owner_domain), + requireExplicitHostPublisherDomain: session.crossOriginAuthorities.has(normalized.host_domain), hostInventoryPartnerDomains: null as string[] | null, hostInventoryPartnerDomainsByFile: undefined as import('./types').SupplyPathInput['hostInventoryPartnerDomainsByFile'], @@ -83,7 +89,9 @@ export async function verifyAuthoritativeSupplyPath( throw new TypeError('propertySelectors must be non-empty'); const ids = new Set(); const properties = records(hostManifest?.properties).filter( - p => p.publisher_domain === undefined || domain(p.publisher_domain) === normalized.host_domain + p => + (p.publisher_domain === undefined && !input.requireExplicitHostPublisherDomain) || + domain(p.publisher_domain) === normalized.host_domain ); let unresolved = false; for (const raw of options.propertySelectors) { diff --git a/test/lib/product-property-policy-client.test.js b/test/lib/product-property-policy-client.test.js index 9b9ebf96e..bc007ae76 100644 --- a/test/lib/product-property-policy-client.test.js +++ b/test/lib/product-property-policy-client.test.js @@ -677,8 +677,23 @@ describe('supply-path annotations across discovery completion paths', () => { ...request, semantics_version: '1', state: 'owner_attested', - legs: {}, - sources: { cached: true }, + resolved_collection_id: request.collection_id, + legs: { + owner_collection_declared: { ok: true }, + owner_distribution_carriage: { ok: true }, + owner_agent_declared: { ok: true }, + host_authorization: { ok: false, failure: 'no_agent_entry' }, + inventory_partner_domain: { ok: false, failure: 'not_declared' }, + }, + sources: { + owner_fetched_at: new Date().toISOString(), + host_fetched_at: new Date().toISOString(), + owner_resolved_url: null, + host_resolved_url: null, + cached: true, + owner_adagents_url: `https://${request.owner_domain}/.well-known/adagents.json`, + host_adagents_url: `https://${request.host_domain}/.well-known/adagents.json`, + }, checked_at: new Date().toISOString(), }), }, diff --git a/test/lib/supply-path.test.js b/test/lib/supply-path.test.js index 5ce911f7b..448cb17e9 100644 --- a/test/lib/supply-path.test.js +++ b/test/lib/supply-path.test.js @@ -5,11 +5,16 @@ const { createHash } = require('node:crypto'); const sdk = require('../../dist/lib'); const { evaluateSupplyPath, - verifySupplyPath, + verifySupplyPath: verifySupplyPathSdk, parseInventoryPartnerDomains, annotateProductsSupplyPaths, RegistryClient, } = sdk; +const verifySupplyPath = (request, options = { source: 'authoritative' }) => + verifySupplyPathSdk( + request, + options.source === 'registry' ? options : { authorityStore: new sdk.InMemorySupplyPathAuthorityStore(), ...options } + ); const AGENT = 'https://sales.channel-owner.example'; const OWNER = 'channel-owner.example'; const HOST = 'hoststream.example'; @@ -21,10 +26,11 @@ function input() { collectionId: 'retro_news', hostInventoryPartnerDomains: null, ownerManifest: { - authorized_agents: [{ url: AGENT, authorized_for: 'Owner avails' }], + authorized_agents: [{ url: AGENT, authorized_for: 'Owner avails', collections: [{ publisher_domain: OWNER }] }], collections: [ { collection_id: 'retro_news', + publisher_domain: OWNER, name: 'Retro News', kind: 'channel', distribution: [{ publisher_domain: HOST, property_ids: ['hoststream_ctv'] }], @@ -71,6 +77,119 @@ function transport(changes = {}, requests = []) { }; } +describe('authority and revocation trust boundaries', () => { + it('never lets a storage adapter erase a freshly observed denial', async () => { + const fixture = input(); + fixture.hostManifest.revoked_publisher_domains = [{ publisher_domain: OWNER, revoked_at: '2026-09-01T00:00:00Z' }]; + const result = await verifySupplyPath(request, { + source: 'authoritative', + revocationStore: { observe: async () => [] }, + trustedFetchFn: transport({ [`https://${HOST}/.well-known/adagents.json`]: fixture.hostManifest }), + }); + assert.equal(result.state, 'owner_attested'); + assert.equal(result.sources.held_revocations.find(r => r.authority === HOST).entries[0].publisher_domain, OWNER); + }); + for (const publisher of [undefined, 'other.example', HOST]) { + it(`requires explicit matching host attribution in a shared authoritative document (${publisher})`, async () => { + const fixture = input(); + fixture.hostManifest.properties[0].publisher_domain = publisher; + const result = await verifySupplyPath(request, { + source: 'authoritative', + trustedFetchFn: transport({ + [`https://${HOST}/.well-known/adagents.json`]: { authoritative_location: 'https://cdn.example/host.json' }, + 'https://cdn.example/host.json': fixture.hostManifest, + }), + }); + assert.equal(result.state, publisher === HOST ? 'verified_owner_sold' : 'owner_attested'); + }); + } + it('refuses changed authority locations before fetching them and supports independently approved migrations', async () => { + const authorityStore = new sdk.InMemorySupplyPathAuthorityStore(); + const fixture = input(); + fixture.hostManifest.properties[0].publisher_domain = HOST; + const verify = (location, requests = []) => + verifySupplyPath(request, { + source: 'authoritative', + authorityStore, + trustedFetchFn: transport( + { + [`https://${HOST}/.well-known/adagents.json`]: { authoritative_location: location }, + [location]: fixture.hostManifest, + }, + requests + ), + }); + assert.equal((await verify('https://cdn.example/host.json')).state, 'verified_owner_sold'); + const requests = []; + await assert.rejects(verify('https://changed.example/host.json', requests), /Authoritative location changed/); + assert.equal( + requests.some(r => r.url === 'https://changed.example/host.json'), + false + ); + authorityStore.approveChange(HOST, 'https://changed.example/host.json'); + assert.equal((await verify('https://changed.example/host.json')).state, 'verified_owner_sold'); + }); + it('bounds authority persistence by the overall deadline', async () => { + await assert.rejects( + verifySupplyPath(request, { + source: 'authoritative', + timeoutMs: 25, + authorityStore: { check: () => new Promise(() => {}) }, + trustedFetchFn: transport(), + }), + /deadline|abort/i + ); + }); + it('validates custom registry adapters and the concrete winning collection', async () => { + const valid = { + ...request, + ...evaluateSupplyPath(input()), + checked_at: new Date().toISOString(), + sources: { + owner_fetched_at: new Date().toISOString(), + host_fetched_at: new Date().toISOString(), + owner_resolved_url: null, + host_resolved_url: null, + cached: true, + owner_adagents_url: `https://${OWNER}/.well-known/adagents.json`, + host_adagents_url: `https://${HOST}/.well-known/adagents.json`, + }, + }; + for (const patch of [ + { legs: {} }, + { resolved_collection_id: undefined }, + { resolved_collection_id: 42 }, + { resolved_collection_id: 'other' }, + ]) { + await assert.rejects( + verifySupplyPath(request, { + source: 'registry', + registry: { verifySupplyPath: async () => ({ ...valid, ...patch }) }, + }), + /Invalid registry/ + ); + } + for (const malformed of [ + { owner_fetched_at: undefined }, + { host_fetched_at: 12345 }, + { owner_resolved_url: 'http://owner.example/' }, + { host_resolved_url: {} }, + ]) { + await assert.rejects( + verifySupplyPath(request, { + source: 'registry', + registry: { verifySupplyPath: async () => ({ ...valid, sources: { ...valid.sources, ...malformed } }) }, + }), + /Invalid registry/ + ); + } + assert.deepEqual( + await verifySupplyPath(request, { source: 'registry', registry: { verifySupplyPath: async () => valid } }), + valid + ); + }); +}); + // This corpus is consumed verbatim by the upstream registry and this SDK. describe('canonical shared supply-path golden vectors', () => { it('preserves the pinned upstream bytes', () => { @@ -355,6 +474,10 @@ describe('registry wrapper and product discovery annotations', () => { ...request, ...evaluateSupplyPath(input()), sources: { + owner_fetched_at: new Date().toISOString(), + host_fetched_at: new Date().toISOString(), + owner_resolved_url: null, + host_resolved_url: null, owner_adagents_url: 'https://owner.example/', host_adagents_url: 'https://host.example/', cached: true, @@ -532,14 +655,22 @@ describe('bounded evidence and complete product scope', () => { }, }, }), - /storage unavailable/ + /revocation storage failed/ ); }); it('rejects older registry semantics and inconsistent verified legs while preserving new diagnostic strings', async () => { const response = { ...request, ...evaluateSupplyPath(input()), - sources: { owner_adagents_url: `https://${OWNER}/`, host_adagents_url: `https://${HOST}/`, cached: true }, + sources: { + owner_fetched_at: new Date().toISOString(), + host_fetched_at: new Date().toISOString(), + owner_resolved_url: null, + host_resolved_url: null, + owner_adagents_url: `https://${OWNER}/`, + host_adagents_url: `https://${HOST}/`, + cached: true, + }, checked_at: new Date().toISOString(), }; const registry = value => @@ -665,3 +796,197 @@ it('does not turn a malformed revocation list containing a valid denial into hos /Invalid publisher revocation evidence/ ); }); + +// An invalid affirmative list must not discard independently meaningful denials. +it('retains fresh revocations from a host document missing authorized_agents', async () => { + const result = await verifySupplyPath(request, { + source: 'authoritative', + revocationStore: new sdk.InMemorySupplyPathRevocationStore(), + trustedFetchFn: transport({ + [`https://${HOST}/.well-known/adagents.json`]: { revoked_publisher_domains: [OWNER] }, + [`https://${HOST}/ads.txt`]: new Response(`inventorypartnerdomain=${OWNER}`, { + headers: { 'content-type': 'text/plain' }, + }), + [`https://${HOST}/app-ads.txt`]: new Response(`inventorypartnerdomain=${OWNER}`, { + headers: { 'content-type': 'text/plain' }, + }), + }), + }); + assert.equal(result.state, 'owner_attested'); + assert.equal(result.sources.held_revocations.find(r => r.authority === HOST).entries[0].publisher_domain, OWNER); +}); + +it('isolates a single publisher authority from consuming the global revocation capacity', async () => { + const store = new sdk.InMemorySupplyPathRevocationStore(); + const revoked = Array.from({ length: 1024 }, (_, i) => ({ + publisher_domain: `publisher-${i}.example`, + revoked_at: '2026-09-01T00:00:00Z', + })); + await store.observe('attacker.example', revoked); + await assert.rejects( + store.observe('attacker.example', [{ publisher_domain: 'next.example', revoked_at: '2026-09-02T00:00:00Z' }]), + /authority revocation capacity/ + ); + assert.equal((await store.observe('attacker.example', [])).length, 1024); + assert.deepEqual( + await store.observe('innocent.example', [{ publisher_domain: OWNER, revoked_at: '2026-09-02T00:00:00Z' }]), + [{ publisher_domain: OWNER, revoked_at: '2026-09-02T00:00:00Z' }] + ); +}); + +it('rate-bounds many-authority admission and retains all live default-store evidence at capacity', () => { + // A separate process exercises the actual module defaults without poisoning + // the other verification tests' process-wide stores. + const { execFileSync } = require('node:child_process'); + execFileSync( + process.execPath, + [ + '-e', + ` + const assert = require('node:assert/strict'); + let now = Date.parse('2026-09-01T00:00:00Z'); + Date.now = () => now; + const { defaultSupplyPathRevocations: revocations, defaultSupplyPathAuthorities: pins } = require(${JSON.stringify(require.resolve('../../dist/lib/supply-path/revocations'))}); + const denial = [{ publisher_domain: 'owner.example', revoked_at: '2026-09-01T00:00:00Z' }]; + (async () => { + for (let i = 0; i < 10000; i++) { + if (i > 0 && i % 128 === 0) { + await assert.rejects(revocations.observe('rate-blocked.attacker.example', denial), /admission rate/); + await assert.rejects(pins.check('rate-blocked.attacker.example', 'https://cdn.example/blocked.json'), /admission rate/); + // Existing evidence remains readable during an admission-rate refusal. + assert.deepEqual(await revocations.observe('host-0.attacker.example', []), denial); + assert.equal(await pins.check('host-0.attacker.example', 'https://cdn.example/0.json'), true); + now += 60001; + } + const authority = 'host-' + i + '.attacker.example'; + await revocations.observe(authority, denial); + await pins.check(authority, 'https://cdn.example/' + i + '.json'); + } + now += 60001; + await assert.rejects(revocations.observe('innocent.example', denial), /capacity exceeded/); + await assert.rejects(pins.check('innocent.example', 'https://innocent.example/adagents.json'), /capacity exceeded/); + // Scan every retained authority: neither rate limiting nor total exhaustion + // may evict a live denial or adopt a different pinned location. + for (let i = 0; i < 10000; i++) { + const authority = 'host-' + i + '.attacker.example'; + assert.deepEqual(await revocations.observe(authority, []), denial); + assert.equal(await pins.check(authority, 'https://cdn.example/' + i + '.json'), true); + assert.equal(await pins.check(authority, 'https://attacker.example/replacement'), false); + } + })().catch(error => { console.error(error); process.exitCode = 1; }); + `, + ], + { timeout: 60000, stdio: 'pipe' } + ); +}); + +it('retains denials in an ambiguous pointer envelope before considering IAB evidence', async () => { + const result = await verifySupplyPath(request, { + source: 'authoritative', + revocationStore: new sdk.InMemorySupplyPathRevocationStore(), + trustedFetchFn: transport({ + [`https://${HOST}/.well-known/adagents.json`]: { + authoritative_location: 'https://cdn.example/host.json', + authorized_agents: [], + revoked_publisher_domains: [OWNER], + }, + [`https://${HOST}/ads.txt`]: new Response(`inventorypartnerdomain=${OWNER}`, { + headers: { 'content-type': 'text/plain' }, + }), + [`https://${HOST}/app-ads.txt`]: new Response(`inventorypartnerdomain=${OWNER}`, { + headers: { 'content-type': 'text/plain' }, + }), + }), + }); + assert.equal(result.state, 'owner_attested'); + assert.equal(result.sources.held_revocations.find(r => r.authority === HOST).entries[0].publisher_domain, OWNER); +}); + +it('holds from first observation across changed timestamps and expires at the exact boundary', async t => { + t.mock.timers.enable({ apis: ['Date'], now: Date.parse('2026-09-01T00:00:00Z') }); + const store = new sdk.InMemorySupplyPathRevocationStore(); + await store.observe(HOST, [{ publisher_domain: OWNER, revoked_at: '2026-09-01T00:00:00Z' }]); + t.mock.timers.tick(6 * 86400000); + await store.observe(HOST, [ + { publisher_domain: OWNER, revoked_at: '2026-09-07T00:00:00Z' }, + { publisher_domain: 'new.example', revoked_at: '2026-09-07T00:00:00Z' }, + ]); + t.mock.timers.tick(86400000 - 1); + assert.equal((await store.observe(HOST, [])).length, 2); + t.mock.timers.tick(1); + assert.deepEqual( + (await store.observe(HOST, [])).map(r => r.publisher_domain), + ['new.example'] + ); +}); + +it('requires explicit owner attribution before a shared document can declare a collection', async () => { + for (const publisher of [undefined, 'other-owner.example', OWNER]) { + const fixture = input(); + fixture.ownerManifest.collections[0].publisher_domain = publisher; + const result = await verifySupplyPath(request, { + source: 'authoritative', + revocationStore: new sdk.InMemorySupplyPathRevocationStore(), + trustedFetchFn: transport({ + [`https://${OWNER}/.well-known/adagents.json`]: { + authoritative_location: 'https://cdn.example/shared-owner.json', + }, + 'https://cdn.example/shared-owner.json': fixture.ownerManifest, + [`https://${HOST}/app-ads.txt`]: new Response(`inventorypartnerdomain=${OWNER}`, { + headers: { 'content-type': 'text/plain' }, + }), + }), + }); + assert.equal(result.state, publisher === OWNER ? 'verified_owner_sold' : 'unverified'); + } +}); + +it('does not borrow an unscoped owner agent grant from a shared catalog through inventory-partner evidence', async () => { + const fixture = input(); + delete fixture.ownerManifest.authorized_agents[0].collections; + fixture.hostManifest.authorized_agents = []; + const result = await verifySupplyPath(request, { + source: 'authoritative', + revocationStore: new sdk.InMemorySupplyPathRevocationStore(), + trustedFetchFn: transport({ + [`https://${OWNER}/.well-known/adagents.json`]: { + authoritative_location: 'https://cdn.example/shared-owner.json', + }, + 'https://cdn.example/shared-owner.json': fixture.ownerManifest, + [`https://${HOST}/.well-known/adagents.json`]: fixture.hostManifest, + [`https://${HOST}/app-ads.txt`]: new Response(`inventorypartnerdomain=${OWNER}`, { + headers: { 'content-type': 'text/plain' }, + }), + }), + }); + assert.equal(result.state, 'owner_attested'); + assert.equal(result.legs.owner_agent_declared.failure, 'agent_not_declared_by_owner'); +}); + +it('records malformed pointers as unavailable evidence while retaining their denials', async () => { + for (const location of ['not a URL', 'http://example.com/host.json', 'https://user:password@example.com/host.json']) { + const store = new sdk.InMemorySupplyPathRevocationStore(); + const result = await verifySupplyPath(request, { + source: 'authoritative', + revocationStore: store, + trustedFetchFn: transport({ + [`https://${HOST}/.well-known/adagents.json`]: { + authoritative_location: location, + revoked_publisher_domains: [OWNER], + }, + [`https://${HOST}/ads.txt`]: new Response(`inventorypartnerdomain=${OWNER}`, { + headers: { 'content-type': 'text/plain' }, + }), + [`https://${HOST}/app-ads.txt`]: new Response(`inventorypartnerdomain=${OWNER}`, { + headers: { 'content-type': 'text/plain' }, + }), + }), + }); + assert.equal(result.state, 'owner_attested'); + assert.ok(result.sources.evidence.some(item => item.error === 'invalid_authoritative_location')); + assert.deepEqual( + (await store.observe(HOST, [])).map(item => item.publisher_domain), + [OWNER] + ); + } +}); From 03e5cf5c37cc3c977c86700dbbfd6a9e2200c943 Mon Sep 17 00:00:00 2001 From: Brian O'Kelley Date: Mon, 14 Sep 2026 15:44:21 +0000 Subject: [PATCH 04/21] test(supply-path): consume corrected upstream authority vectors --- test/fixtures/supply-path/source.json | 4 +- test/fixtures/supply-path/vectors.json | 1946 ++++++++++++++++++++++++ 2 files changed, 1948 insertions(+), 2 deletions(-) diff --git a/test/fixtures/supply-path/source.json b/test/fixtures/supply-path/source.json index 88e1528d1..d36b1a4b1 100644 --- a/test/fixtures/supply-path/source.json +++ b/test/fixtures/supply-path/source.json @@ -1,7 +1,7 @@ { "repository": "adcontextprotocol/adcp", - "commit": "87b09d10cea7ee93e5badc4ce702a7d2aff02254", + "commit": "f701ede564fe55909f5ace51b48575f586c4f890", "path": "static/compliance/source/test-vectors/supply-path/vectors.json", - "sha256": "c70298c8cf3db46c3d9c685f2efb790198a35ec1f9eaf8b113d23dc983106226", + "sha256": "c81122ed89d041660c5568471002cb6d21d21b55917699ddff209a5838668337", "semantics_version": "1" } diff --git a/test/fixtures/supply-path/vectors.json b/test/fixtures/supply-path/vectors.json index 02122e974..381f04480 100644 --- a/test/fixtures/supply-path/vectors.json +++ b/test/fixtures/supply-path/vectors.json @@ -5615,6 +5615,1952 @@ }, "resolved_collection_id": "web_channel" } + }, + { + "id": "inline-property-grant", + "input": { + "ownerDomain": "channel-owner.example", + "hostDomain": "hoststream.example", + "agentUrl": "https://sales.channel-owner.example", + "collectionId": "retro_news", + "hostInventoryPartnerDomains": null, + "ownerManifest": { + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails" + } + ], + "collections": [ + { + "collection_id": "retro_news", + "name": "Retro News", + "kind": "channel", + "distribution": [ + { + "publisher_domain": "hoststream.example", + "property_ids": [ + "hoststream_ctv" + ] + } + ] + } + ] + }, + "hostManifest": { + "properties": [ + { + "property_id": "hoststream_ctv", + "name": "HostStream CTV", + "property_type": "ctv_app", + "identifiers": [ + { + "type": "roku_channel_id", + "value": "123" + } + ] + } + ], + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails", + "authorization_type": "inline_properties", + "collections": [ + { + "publisher_domain": "channel-owner.example", + "collection_ids": [ + "retro_news" + ] + } + ], + "properties": [ + { + "property_id": "hoststream_ctv", + "name": "HostStream CTV", + "property_type": "ctv_app", + "identifiers": [ + { + "type": "roku_channel_id", + "value": "123" + } + ] + } + ] + } + ] + } + }, + "expected": { + "semantics_version": "1", + "state": "verified_owner_sold", + "legs": { + "owner_collection_declared": { + "ok": true + }, + "owner_distribution_carriage": { + "ok": true + }, + "owner_agent_declared": { + "ok": true + }, + "host_authorization": { + "ok": true + }, + "inventory_partner_domain": { + "ok": false, + "failure": "ads_txt_unavailable" + } + }, + "resolved_collection_id": "retro_news" + } + }, + { + "id": "legacy-inline-without-discriminator-is-not-a-grant", + "input": { + "ownerDomain": "channel-owner.example", + "hostDomain": "hoststream.example", + "agentUrl": "https://sales.channel-owner.example", + "collectionId": "retro_news", + "hostInventoryPartnerDomains": null, + "ownerManifest": { + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails" + } + ], + "collections": [ + { + "collection_id": "retro_news", + "name": "Retro News", + "kind": "channel", + "distribution": [ + { + "publisher_domain": "hoststream.example", + "property_ids": [ + "hoststream_ctv" + ] + } + ] + } + ] + }, + "hostManifest": { + "properties": [ + { + "property_id": "hoststream_ctv", + "name": "HostStream CTV", + "property_type": "ctv_app", + "identifiers": [ + { + "type": "roku_channel_id", + "value": "123" + } + ] + } + ], + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails", + "collections": [ + { + "publisher_domain": "channel-owner.example", + "collection_ids": [ + "retro_news" + ] + } + ], + "properties": [ + { + "property_id": "hoststream_ctv", + "name": "HostStream CTV", + "property_type": "ctv_app", + "identifiers": [ + { + "type": "roku_channel_id", + "value": "123" + } + ] + } + ] + } + ] + } + }, + "expected": { + "semantics_version": "1", + "state": "owner_attested", + "legs": { + "owner_collection_declared": { + "ok": true + }, + "owner_distribution_carriage": { + "ok": true + }, + "owner_agent_declared": { + "ok": true + }, + "host_authorization": { + "ok": false, + "failure": "property_scope_mismatch" + }, + "inventory_partner_domain": { + "ok": false, + "failure": "ads_txt_unavailable" + } + }, + "resolved_collection_id": "retro_news" + } + }, + { + "id": "property-tag-grant", + "input": { + "ownerDomain": "channel-owner.example", + "hostDomain": "hoststream.example", + "agentUrl": "https://sales.channel-owner.example", + "collectionId": "retro_news", + "hostInventoryPartnerDomains": null, + "ownerManifest": { + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails" + } + ], + "collections": [ + { + "collection_id": "retro_news", + "name": "Retro News", + "kind": "channel", + "distribution": [ + { + "publisher_domain": "hoststream.example", + "property_ids": [ + "hoststream_ctv" + ] + } + ] + } + ] + }, + "hostManifest": { + "properties": [ + { + "property_id": "hoststream_ctv", + "name": "HostStream CTV", + "property_type": "ctv_app", + "identifiers": [ + { + "type": "roku_channel_id", + "value": "123" + } + ], + "tags": [ + "ctv" + ] + } + ], + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails", + "authorization_type": "property_tags", + "collections": [ + { + "publisher_domain": "channel-owner.example", + "collection_ids": [ + "retro_news" + ] + } + ], + "property_tags": [ + "ctv" + ] + } + ] + } + }, + "expected": { + "semantics_version": "1", + "state": "verified_owner_sold", + "legs": { + "owner_collection_declared": { + "ok": true + }, + "owner_distribution_carriage": { + "ok": true + }, + "owner_agent_declared": { + "ok": true + }, + "host_authorization": { + "ok": true + }, + "inventory_partner_domain": { + "ok": false, + "failure": "ads_txt_unavailable" + } + }, + "resolved_collection_id": "retro_news" + } + }, + { + "id": "publisher-property-selector-all", + "input": { + "ownerDomain": "channel-owner.example", + "hostDomain": "hoststream.example", + "agentUrl": "https://sales.channel-owner.example", + "collectionId": "retro_news", + "hostInventoryPartnerDomains": null, + "ownerManifest": { + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails" + } + ], + "collections": [ + { + "collection_id": "retro_news", + "name": "Retro News", + "kind": "channel", + "distribution": [ + { + "publisher_domain": "hoststream.example", + "property_ids": [ + "hoststream_ctv" + ] + } + ] + } + ] + }, + "hostManifest": { + "properties": [ + { + "property_id": "hoststream_ctv", + "name": "HostStream CTV", + "property_type": "ctv_app", + "identifiers": [ + { + "type": "roku_channel_id", + "value": "123" + } + ] + } + ], + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails", + "authorization_type": "publisher_properties", + "collections": [ + { + "publisher_domain": "channel-owner.example", + "collection_ids": [ + "retro_news" + ] + } + ], + "publisher_properties": [ + { + "publisher_domain": "hoststream.example", + "selection_type": "all" + } + ] + } + ] + } + }, + "expected": { + "semantics_version": "1", + "state": "verified_owner_sold", + "legs": { + "owner_collection_declared": { + "ok": true + }, + "owner_distribution_carriage": { + "ok": true + }, + "owner_agent_declared": { + "ok": true + }, + "host_authorization": { + "ok": true + }, + "inventory_partner_domain": { + "ok": false, + "failure": "ads_txt_unavailable" + } + }, + "resolved_collection_id": "retro_news" + } + }, + { + "id": "publisher-property-selector-all-compact", + "input": { + "ownerDomain": "channel-owner.example", + "hostDomain": "hoststream.example", + "agentUrl": "https://sales.channel-owner.example", + "collectionId": "retro_news", + "hostInventoryPartnerDomains": null, + "ownerManifest": { + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails" + } + ], + "collections": [ + { + "collection_id": "retro_news", + "name": "Retro News", + "kind": "channel", + "distribution": [ + { + "publisher_domain": "hoststream.example", + "property_ids": [ + "hoststream_ctv" + ] + } + ] + } + ] + }, + "hostManifest": { + "properties": [ + { + "property_id": "hoststream_ctv", + "name": "HostStream CTV", + "property_type": "ctv_app", + "identifiers": [ + { + "type": "roku_channel_id", + "value": "123" + } + ] + } + ], + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails", + "authorization_type": "publisher_properties", + "collections": [ + { + "publisher_domain": "channel-owner.example", + "collection_ids": [ + "retro_news" + ] + } + ], + "publisher_properties": [ + { + "publisher_domains": [ + "hoststream.example", + "other.example" + ], + "selection_type": "all" + } + ] + } + ] + } + }, + "expected": { + "semantics_version": "1", + "state": "verified_owner_sold", + "legs": { + "owner_collection_declared": { + "ok": true + }, + "owner_distribution_carriage": { + "ok": true + }, + "owner_agent_declared": { + "ok": true + }, + "host_authorization": { + "ok": true + }, + "inventory_partner_domain": { + "ok": false, + "failure": "ads_txt_unavailable" + } + }, + "resolved_collection_id": "retro_news" + } + }, + { + "id": "publisher-property-selector-by_id", + "input": { + "ownerDomain": "channel-owner.example", + "hostDomain": "hoststream.example", + "agentUrl": "https://sales.channel-owner.example", + "collectionId": "retro_news", + "hostInventoryPartnerDomains": null, + "ownerManifest": { + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails" + } + ], + "collections": [ + { + "collection_id": "retro_news", + "name": "Retro News", + "kind": "channel", + "distribution": [ + { + "publisher_domain": "hoststream.example", + "property_ids": [ + "hoststream_ctv" + ] + } + ] + } + ] + }, + "hostManifest": { + "properties": [ + { + "property_id": "hoststream_ctv", + "name": "HostStream CTV", + "property_type": "ctv_app", + "identifiers": [ + { + "type": "roku_channel_id", + "value": "123" + } + ] + } + ], + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails", + "authorization_type": "publisher_properties", + "collections": [ + { + "publisher_domain": "channel-owner.example", + "collection_ids": [ + "retro_news" + ] + } + ], + "publisher_properties": [ + { + "publisher_domain": "hoststream.example", + "selection_type": "by_id", + "property_ids": [ + "hoststream_ctv" + ] + } + ] + } + ] + } + }, + "expected": { + "semantics_version": "1", + "state": "verified_owner_sold", + "legs": { + "owner_collection_declared": { + "ok": true + }, + "owner_distribution_carriage": { + "ok": true + }, + "owner_agent_declared": { + "ok": true + }, + "host_authorization": { + "ok": true + }, + "inventory_partner_domain": { + "ok": false, + "failure": "ads_txt_unavailable" + } + }, + "resolved_collection_id": "retro_news" + } + }, + { + "id": "publisher-property-selector-by_id-compact", + "input": { + "ownerDomain": "channel-owner.example", + "hostDomain": "hoststream.example", + "agentUrl": "https://sales.channel-owner.example", + "collectionId": "retro_news", + "hostInventoryPartnerDomains": null, + "ownerManifest": { + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails" + } + ], + "collections": [ + { + "collection_id": "retro_news", + "name": "Retro News", + "kind": "channel", + "distribution": [ + { + "publisher_domain": "hoststream.example", + "property_ids": [ + "hoststream_ctv" + ] + } + ] + } + ] + }, + "hostManifest": { + "properties": [ + { + "property_id": "hoststream_ctv", + "name": "HostStream CTV", + "property_type": "ctv_app", + "identifiers": [ + { + "type": "roku_channel_id", + "value": "123" + } + ] + } + ], + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails", + "authorization_type": "publisher_properties", + "collections": [ + { + "publisher_domain": "channel-owner.example", + "collection_ids": [ + "retro_news" + ] + } + ], + "publisher_properties": [ + { + "publisher_domains": [ + "hoststream.example", + "other.example" + ], + "selection_type": "by_id", + "property_ids": [ + "hoststream_ctv" + ] + } + ] + } + ] + } + }, + "expected": { + "semantics_version": "1", + "state": "owner_attested", + "legs": { + "owner_collection_declared": { + "ok": true + }, + "owner_distribution_carriage": { + "ok": true + }, + "owner_agent_declared": { + "ok": true + }, + "host_authorization": { + "ok": false, + "failure": "property_scope_mismatch" + }, + "inventory_partner_domain": { + "ok": false, + "failure": "ads_txt_unavailable" + } + }, + "resolved_collection_id": "retro_news" + } + }, + { + "id": "publisher-property-selector-by_tag", + "input": { + "ownerDomain": "channel-owner.example", + "hostDomain": "hoststream.example", + "agentUrl": "https://sales.channel-owner.example", + "collectionId": "retro_news", + "hostInventoryPartnerDomains": null, + "ownerManifest": { + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails" + } + ], + "collections": [ + { + "collection_id": "retro_news", + "name": "Retro News", + "kind": "channel", + "distribution": [ + { + "publisher_domain": "hoststream.example", + "property_ids": [ + "hoststream_ctv" + ] + } + ] + } + ] + }, + "hostManifest": { + "properties": [ + { + "property_id": "hoststream_ctv", + "name": "HostStream CTV", + "property_type": "ctv_app", + "identifiers": [ + { + "type": "roku_channel_id", + "value": "123" + } + ], + "tags": [ + "ctv" + ] + } + ], + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails", + "authorization_type": "publisher_properties", + "collections": [ + { + "publisher_domain": "channel-owner.example", + "collection_ids": [ + "retro_news" + ] + } + ], + "publisher_properties": [ + { + "publisher_domain": "hoststream.example", + "selection_type": "by_tag", + "property_tags": [ + "ctv" + ] + } + ] + } + ] + } + }, + "expected": { + "semantics_version": "1", + "state": "verified_owner_sold", + "legs": { + "owner_collection_declared": { + "ok": true + }, + "owner_distribution_carriage": { + "ok": true + }, + "owner_agent_declared": { + "ok": true + }, + "host_authorization": { + "ok": true + }, + "inventory_partner_domain": { + "ok": false, + "failure": "ads_txt_unavailable" + } + }, + "resolved_collection_id": "retro_news" + } + }, + { + "id": "publisher-property-selector-by_tag-compact", + "input": { + "ownerDomain": "channel-owner.example", + "hostDomain": "hoststream.example", + "agentUrl": "https://sales.channel-owner.example", + "collectionId": "retro_news", + "hostInventoryPartnerDomains": null, + "ownerManifest": { + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails" + } + ], + "collections": [ + { + "collection_id": "retro_news", + "name": "Retro News", + "kind": "channel", + "distribution": [ + { + "publisher_domain": "hoststream.example", + "property_ids": [ + "hoststream_ctv" + ] + } + ] + } + ] + }, + "hostManifest": { + "properties": [ + { + "property_id": "hoststream_ctv", + "name": "HostStream CTV", + "property_type": "ctv_app", + "identifiers": [ + { + "type": "roku_channel_id", + "value": "123" + } + ], + "tags": [ + "ctv" + ] + } + ], + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails", + "authorization_type": "publisher_properties", + "collections": [ + { + "publisher_domain": "channel-owner.example", + "collection_ids": [ + "retro_news" + ] + } + ], + "publisher_properties": [ + { + "publisher_domains": [ + "hoststream.example", + "other.example" + ], + "selection_type": "by_tag", + "property_tags": [ + "ctv" + ] + } + ] + } + ] + } + }, + "expected": { + "semantics_version": "1", + "state": "verified_owner_sold", + "legs": { + "owner_collection_declared": { + "ok": true + }, + "owner_distribution_carriage": { + "ok": true + }, + "owner_agent_declared": { + "ok": true + }, + "host_authorization": { + "ok": true + }, + "inventory_partner_domain": { + "ok": false, + "failure": "ads_txt_unavailable" + } + }, + "resolved_collection_id": "retro_news" + } + }, + { + "id": "shared-pointer-requires-explicit-property-publisher", + "input": { + "ownerDomain": "channel-owner.example", + "hostDomain": "hoststream.example", + "agentUrl": "https://sales.channel-owner.example", + "collectionId": "retro_news", + "hostInventoryPartnerDomains": null, + "ownerManifest": { + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails" + } + ], + "collections": [ + { + "collection_id": "retro_news", + "name": "Retro News", + "kind": "channel", + "distribution": [ + { + "publisher_domain": "hoststream.example", + "property_ids": [ + "hoststream_ctv" + ] + } + ] + } + ] + }, + "hostManifest": { + "properties": [ + { + "property_id": "hoststream_ctv", + "name": "HostStream CTV", + "property_type": "ctv_app", + "identifiers": [ + { + "type": "roku_channel_id", + "value": "123" + } + ] + } + ], + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "hoststream_ctv" + ], + "collections": [ + { + "publisher_domain": "channel-owner.example", + "collection_ids": [ + "retro_news" + ] + } + ] + } + ] + }, + "requireExplicitHostPublisherDomain": true + }, + "expected": { + "semantics_version": "1", + "state": "owner_attested", + "legs": { + "owner_collection_declared": { + "ok": true + }, + "owner_distribution_carriage": { + "ok": false, + "failure": "property_ids_unresolved" + }, + "owner_agent_declared": { + "ok": true + }, + "host_authorization": { + "ok": false, + "failure": "property_scope_mismatch" + }, + "inventory_partner_domain": { + "ok": false, + "failure": "ads_txt_unavailable" + } + }, + "resolved_collection_id": "retro_news" + } + }, + { + "id": "shared-pointer-explicit-property-publisher", + "input": { + "ownerDomain": "channel-owner.example", + "hostDomain": "hoststream.example", + "agentUrl": "https://sales.channel-owner.example", + "collectionId": "retro_news", + "hostInventoryPartnerDomains": null, + "ownerManifest": { + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails" + } + ], + "collections": [ + { + "collection_id": "retro_news", + "name": "Retro News", + "kind": "channel", + "distribution": [ + { + "publisher_domain": "hoststream.example", + "property_ids": [ + "hoststream_ctv" + ] + } + ] + } + ] + }, + "hostManifest": { + "properties": [ + { + "property_id": "hoststream_ctv", + "name": "HostStream CTV", + "property_type": "ctv_app", + "identifiers": [ + { + "type": "roku_channel_id", + "value": "123" + } + ], + "publisher_domain": "hoststream.example" + } + ], + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "hoststream_ctv" + ], + "collections": [ + { + "publisher_domain": "channel-owner.example", + "collection_ids": [ + "retro_news" + ] + } + ] + } + ] + }, + "requireExplicitHostPublisherDomain": true + }, + "expected": { + "semantics_version": "1", + "state": "verified_owner_sold", + "legs": { + "owner_collection_declared": { + "ok": true + }, + "owner_distribution_carriage": { + "ok": true + }, + "owner_agent_declared": { + "ok": true + }, + "host_authorization": { + "ok": true + }, + "inventory_partner_domain": { + "ok": false, + "failure": "ads_txt_unavailable" + } + }, + "resolved_collection_id": "retro_news" + } + }, + { + "id": "canonical-agent-origin-default-port", + "input": { + "ownerDomain": "channel-owner.example", + "hostDomain": "hoststream.example", + "agentUrl": "HTTPS://SALES.CHANNEL-OWNER.EXAMPLE:443/", + "collectionId": "retro_news", + "hostInventoryPartnerDomains": null, + "ownerManifest": { + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails" + } + ], + "collections": [ + { + "collection_id": "retro_news", + "name": "Retro News", + "kind": "channel", + "distribution": [ + { + "publisher_domain": "hoststream.example", + "property_ids": [ + "hoststream_ctv" + ] + } + ] + } + ] + }, + "hostManifest": { + "properties": [ + { + "property_id": "hoststream_ctv", + "name": "HostStream CTV", + "property_type": "ctv_app", + "identifiers": [ + { + "type": "roku_channel_id", + "value": "123" + } + ] + } + ], + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "hoststream_ctv" + ], + "collections": [ + { + "publisher_domain": "channel-owner.example", + "collection_ids": [ + "retro_news" + ] + } + ] + } + ] + } + }, + "expected": { + "semantics_version": "1", + "state": "verified_owner_sold", + "legs": { + "owner_collection_declared": { + "ok": true + }, + "owner_distribution_carriage": { + "ok": true + }, + "owner_agent_declared": { + "ok": true + }, + "host_authorization": { + "ok": true + }, + "inventory_partner_domain": { + "ok": false, + "failure": "ads_txt_unavailable" + } + }, + "resolved_collection_id": "retro_news" + } + }, + { + "id": "malformed-top-level-property-record", + "input": { + "ownerDomain": "channel-owner.example", + "hostDomain": "hoststream.example", + "agentUrl": "https://sales.channel-owner.example", + "collectionId": "retro_news", + "hostInventoryPartnerDomains": null, + "ownerManifest": { + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails" + } + ], + "collections": [ + { + "collection_id": "retro_news", + "name": "Retro News", + "kind": "channel", + "distribution": [ + { + "publisher_domain": "hoststream.example", + "property_ids": [ + "hoststream_ctv" + ] + } + ] + } + ] + }, + "hostManifest": { + "properties": [ + { + "property_id": "hoststream_ctv", + "name": "HostStream CTV", + "property_type": "ctv_app", + "identifiers": [ + { + "type": "roku_channel_id", + "value": "123" + } + ] + }, + null + ], + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "hoststream_ctv" + ], + "collections": [ + { + "publisher_domain": "channel-owner.example", + "collection_ids": [ + "retro_news" + ] + } + ] + } + ] + } + }, + "expected": { + "semantics_version": "1", + "state": "owner_attested", + "legs": { + "owner_collection_declared": { + "ok": true + }, + "owner_distribution_carriage": { + "ok": true + }, + "owner_agent_declared": { + "ok": true + }, + "host_authorization": { + "ok": false, + "failure": "property_scope_mismatch" + }, + "inventory_partner_domain": { + "ok": false, + "failure": "ads_txt_unavailable" + } + }, + "resolved_collection_id": "retro_news" + } + }, + { + "id": "malformed-inline-property-record", + "input": { + "ownerDomain": "channel-owner.example", + "hostDomain": "hoststream.example", + "agentUrl": "https://sales.channel-owner.example", + "collectionId": "retro_news", + "hostInventoryPartnerDomains": null, + "ownerManifest": { + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails" + } + ], + "collections": [ + { + "collection_id": "retro_news", + "name": "Retro News", + "kind": "channel", + "distribution": [ + { + "publisher_domain": "hoststream.example", + "property_ids": [ + "hoststream_ctv" + ] + } + ] + } + ] + }, + "hostManifest": { + "properties": [ + { + "property_id": "hoststream_ctv", + "name": "HostStream CTV", + "property_type": "ctv_app", + "identifiers": [ + { + "type": "roku_channel_id", + "value": "123" + } + ] + } + ], + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails", + "authorization_type": "inline_properties", + "collections": [ + { + "publisher_domain": "channel-owner.example", + "collection_ids": [ + "retro_news" + ] + } + ], + "properties": [ + { + "property_id": "hoststream_ctv", + "name": "HostStream CTV", + "property_type": "ctv_app", + "identifiers": [ + { + "type": "roku_channel_id", + "value": "123" + } + ] + }, + null + ] + } + ] + } + }, + "expected": { + "semantics_version": "1", + "state": "owner_attested", + "legs": { + "owner_collection_declared": { + "ok": true + }, + "owner_distribution_carriage": { + "ok": true + }, + "owner_agent_declared": { + "ok": true + }, + "host_authorization": { + "ok": false, + "failure": "property_scope_mismatch" + }, + "inventory_partner_domain": { + "ok": false, + "failure": "ads_txt_unavailable" + } + }, + "resolved_collection_id": "retro_news" + } + }, + { + "id": "shared-owner-catalog-unattributed-collection", + "input": { + "ownerDomain": "channel-owner.example", + "hostDomain": "hoststream.example", + "agentUrl": "https://sales.channel-owner.example", + "collectionId": "retro_news", + "hostInventoryPartnerDomains": null, + "ownerManifest": { + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails" + } + ], + "collections": [ + { + "collection_id": "retro_news", + "name": "Retro News", + "kind": "channel", + "distribution": [ + { + "publisher_domain": "hoststream.example", + "property_ids": [ + "hoststream_ctv" + ] + } + ] + } + ] + }, + "hostManifest": { + "properties": [ + { + "property_id": "hoststream_ctv", + "name": "HostStream CTV", + "property_type": "ctv_app", + "identifiers": [ + { + "type": "roku_channel_id", + "value": "123" + } + ] + } + ], + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "hoststream_ctv" + ], + "collections": [ + { + "publisher_domain": "channel-owner.example", + "collection_ids": [ + "retro_news" + ] + } + ] + } + ] + }, + "requireExplicitOwnerPublisherDomain": true + }, + "expected": { + "semantics_version": "1", + "state": "unverified", + "legs": { + "owner_collection_declared": { + "ok": false, + "failure": "collection_not_declared" + }, + "owner_distribution_carriage": { + "ok": false, + "failure": "collection_leg_failed" + }, + "owner_agent_declared": { + "ok": false, + "failure": "agent_not_declared_by_owner" + }, + "host_authorization": { + "ok": false, + "failure": "property_scope_mismatch" + }, + "inventory_partner_domain": { + "ok": false, + "failure": "ads_txt_unavailable" + } + } + } + }, + { + "id": "shared-owner-catalog-explicit-namespace", + "input": { + "ownerDomain": "channel-owner.example", + "hostDomain": "hoststream.example", + "agentUrl": "https://sales.channel-owner.example", + "collectionId": "retro_news", + "hostInventoryPartnerDomains": null, + "ownerManifest": { + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails", + "collections": [ + { + "publisher_domain": "channel-owner.example", + "collection_ids": [ + "retro_news" + ] + } + ] + } + ], + "collections": [ + { + "collection_id": "retro_news", + "name": "Retro News", + "kind": "channel", + "distribution": [ + { + "publisher_domain": "hoststream.example", + "property_ids": [ + "hoststream_ctv" + ] + } + ], + "publisher_domain": "channel-owner.example" + } + ] + }, + "hostManifest": { + "properties": [ + { + "property_id": "hoststream_ctv", + "name": "HostStream CTV", + "property_type": "ctv_app", + "identifiers": [ + { + "type": "roku_channel_id", + "value": "123" + } + ] + } + ], + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "hoststream_ctv" + ], + "collections": [ + { + "publisher_domain": "channel-owner.example", + "collection_ids": [ + "retro_news" + ] + } + ] + } + ] + }, + "requireExplicitOwnerPublisherDomain": true + }, + "expected": { + "semantics_version": "1", + "state": "verified_owner_sold", + "legs": { + "owner_collection_declared": { + "ok": true + }, + "owner_distribution_carriage": { + "ok": true + }, + "owner_agent_declared": { + "ok": true + }, + "host_authorization": { + "ok": true + }, + "inventory_partner_domain": { + "ok": false, + "failure": "ads_txt_unavailable" + } + }, + "resolved_collection_id": "retro_news" + } + }, + { + "id": "shared-owner-catalog-cannot-borrow-collection-via-ipd", + "input": { + "ownerDomain": "channel-owner.example", + "hostDomain": "hoststream.example", + "agentUrl": "https://sales.channel-owner.example", + "collectionId": "retro_news", + "hostInventoryPartnerDomains": [ + "channel-owner.example" + ], + "ownerManifest": { + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails", + "collections": [ + { + "publisher_domain": "channel-owner.example", + "collection_ids": [ + "retro_news" + ] + } + ] + } + ], + "collections": [ + { + "collection_id": "retro_news", + "name": "Retro News", + "kind": "channel", + "distribution": [ + { + "publisher_domain": "hoststream.example", + "property_ids": [ + "hoststream_ctv" + ] + } + ], + "publisher_domain": "other-owner.example" + } + ] + }, + "hostManifest": { + "properties": [ + { + "property_id": "hoststream_ctv", + "name": "HostStream CTV", + "property_type": "ctv_app", + "identifiers": [ + { + "type": "roku_channel_id", + "value": "123" + } + ] + } + ], + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "hoststream_ctv" + ], + "collections": [ + { + "publisher_domain": "channel-owner.example", + "collection_ids": [ + "retro_news" + ] + } + ] + } + ] + }, + "requireExplicitOwnerPublisherDomain": true + }, + "expected": { + "semantics_version": "1", + "state": "unverified", + "legs": { + "owner_collection_declared": { + "ok": false, + "failure": "collection_not_declared" + }, + "owner_distribution_carriage": { + "ok": false, + "failure": "collection_leg_failed" + }, + "owner_agent_declared": { + "ok": true + }, + "host_authorization": { + "ok": false, + "failure": "property_scope_mismatch" + }, + "inventory_partner_domain": { + "ok": true + } + } + } + }, + { + "id": "shared-owner-unscoped-agent-cannot-borrow-ipd", + "input": { + "ownerDomain": "channel-owner.example", + "hostDomain": "hoststream.example", + "agentUrl": "https://sales.channel-owner.example", + "collectionId": "retro_news", + "hostInventoryPartnerDomains": [ + "channel-owner.example" + ], + "ownerManifest": { + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails" + } + ], + "collections": [ + { + "collection_id": "retro_news", + "name": "Retro News", + "kind": "channel", + "distribution": [ + { + "publisher_domain": "hoststream.example", + "property_ids": [ + "hoststream_ctv" + ] + } + ], + "publisher_domain": "channel-owner.example" + } + ] + }, + "hostManifest": { + "properties": [ + { + "property_id": "hoststream_ctv", + "name": "HostStream CTV", + "property_type": "ctv_app", + "identifiers": [ + { + "type": "roku_channel_id", + "value": "123" + } + ] + } + ], + "authorized_agents": [] + }, + "requireExplicitOwnerPublisherDomain": true + }, + "expected": { + "semantics_version": "1", + "state": "owner_attested", + "legs": { + "owner_collection_declared": { + "ok": true + }, + "owner_distribution_carriage": { + "ok": true + }, + "owner_agent_declared": { + "ok": false, + "failure": "agent_not_declared_by_owner" + }, + "host_authorization": { + "ok": false, + "failure": "no_agent_entry" + }, + "inventory_partner_domain": { + "ok": true + } + }, + "resolved_collection_id": "retro_news" + } + }, + { + "id": "shared-owner-wrong-agent-namespace", + "input": { + "ownerDomain": "channel-owner.example", + "hostDomain": "hoststream.example", + "agentUrl": "https://sales.channel-owner.example", + "collectionId": "retro_news", + "hostInventoryPartnerDomains": [ + "channel-owner.example" + ], + "ownerManifest": { + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails", + "collections": [ + { + "publisher_domain": "other-owner.example" + } + ] + } + ], + "collections": [ + { + "collection_id": "retro_news", + "name": "Retro News", + "kind": "channel", + "distribution": [ + { + "publisher_domain": "hoststream.example", + "property_ids": [ + "hoststream_ctv" + ] + } + ], + "publisher_domain": "channel-owner.example" + } + ] + }, + "hostManifest": { + "properties": [ + { + "property_id": "hoststream_ctv", + "name": "HostStream CTV", + "property_type": "ctv_app", + "identifiers": [ + { + "type": "roku_channel_id", + "value": "123" + } + ] + } + ], + "authorized_agents": [] + }, + "requireExplicitOwnerPublisherDomain": true + }, + "expected": { + "semantics_version": "1", + "state": "owner_attested", + "legs": { + "owner_collection_declared": { + "ok": true + }, + "owner_distribution_carriage": { + "ok": true + }, + "owner_agent_declared": { + "ok": false, + "failure": "agent_not_declared_by_owner" + }, + "host_authorization": { + "ok": false, + "failure": "no_agent_entry" + }, + "inventory_partner_domain": { + "ok": true + } + }, + "resolved_collection_id": "retro_news" + } + }, + { + "id": "shared-owner-bulk-agent-grant", + "input": { + "ownerDomain": "channel-owner.example", + "hostDomain": "hoststream.example", + "agentUrl": "https://sales.channel-owner.example", + "collectionId": "retro_news", + "hostInventoryPartnerDomains": [ + "channel-owner.example" + ], + "ownerManifest": { + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails", + "collections": [ + { + "publisher_domain": "channel-owner.example" + } + ] + } + ], + "collections": [ + { + "collection_id": "retro_news", + "name": "Retro News", + "kind": "channel", + "distribution": [ + { + "publisher_domain": "hoststream.example", + "property_ids": [ + "hoststream_ctv" + ] + } + ], + "publisher_domain": "channel-owner.example" + } + ] + }, + "hostManifest": { + "properties": [ + { + "property_id": "hoststream_ctv", + "name": "HostStream CTV", + "property_type": "ctv_app", + "identifiers": [ + { + "type": "roku_channel_id", + "value": "123" + } + ] + } + ], + "authorized_agents": [] + }, + "requireExplicitOwnerPublisherDomain": true + }, + "expected": { + "semantics_version": "1", + "state": "host_delegated", + "legs": { + "owner_collection_declared": { + "ok": true + }, + "owner_distribution_carriage": { + "ok": true + }, + "owner_agent_declared": { + "ok": true + }, + "host_authorization": { + "ok": false, + "failure": "no_agent_entry" + }, + "inventory_partner_domain": { + "ok": true + } + }, + "resolved_collection_id": "retro_news" + } + }, + { + "id": "shared-owner-empty-agent-selector", + "input": { + "ownerDomain": "channel-owner.example", + "hostDomain": "hoststream.example", + "agentUrl": "https://sales.channel-owner.example", + "collectionId": "retro_news", + "hostInventoryPartnerDomains": [ + "channel-owner.example" + ], + "ownerManifest": { + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails", + "collections": [] + } + ], + "collections": [ + { + "collection_id": "retro_news", + "name": "Retro News", + "kind": "channel", + "distribution": [ + { + "publisher_domain": "hoststream.example", + "property_ids": [ + "hoststream_ctv" + ] + } + ], + "publisher_domain": "channel-owner.example" + } + ] + }, + "hostManifest": { + "properties": [ + { + "property_id": "hoststream_ctv", + "name": "HostStream CTV", + "property_type": "ctv_app", + "identifiers": [ + { + "type": "roku_channel_id", + "value": "123" + } + ] + } + ], + "authorized_agents": [] + }, + "requireExplicitOwnerPublisherDomain": true + }, + "expected": { + "semantics_version": "1", + "state": "owner_attested", + "legs": { + "owner_collection_declared": { + "ok": true + }, + "owner_distribution_carriage": { + "ok": true + }, + "owner_agent_declared": { + "ok": false, + "failure": "agent_not_declared_by_owner" + }, + "host_authorization": { + "ok": false, + "failure": "no_agent_entry" + }, + "inventory_partner_domain": { + "ok": true + } + }, + "resolved_collection_id": "retro_news" + } } ], "ads_txt_policy_vectors": [ From a552b65677302ce3bd63472641e0dc67705f6b0d Mon Sep 17 00:00:00 2001 From: Brian O'Kelley Date: Mon, 14 Sep 2026 16:06:27 +0000 Subject: [PATCH 05/21] fix(supply-path): pin authority only after successful manifest validation --- .../verify-authoritative-supply-paths.md | 2 +- docs/guides/SUPPLY-PATH-VERIFICATION.md | 2 +- src/lib/supply-path/fetch-evidence.ts | 25 ++-- src/lib/supply-path/revocations.ts | 18 ++- .../supply-path/supply-path.type-checks.ts | 16 ++- test/lib/supply-path.test.js | 109 +++++++++++++++++- 6 files changed, 152 insertions(+), 20 deletions(-) diff --git a/.changeset/verify-authoritative-supply-paths.md b/.changeset/verify-authoritative-supply-paths.md index 5c3be475d..30fa33748 100644 --- a/.changeset/verify-authoritative-supply-paths.md +++ b/.changeset/verify-authoritative-supply-paths.md @@ -6,4 +6,4 @@ Add supply-path verification with a typed canonical registry wrapper and a live 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. +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. diff --git a/docs/guides/SUPPLY-PATH-VERIFICATION.md b/docs/guides/SUPPLY-PATH-VERIFICATION.md index f9cc00227..6516c89f1 100644 --- a/docs/guides/SUPPLY-PATH-VERIFICATION.md +++ b/docs/guides/SUPPLY-PATH-VERIFICATION.md @@ -82,7 +82,7 @@ HTTP redirects are limited to three within the exact HTTPS origin. A publisher-o 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 on first observation with `InMemorySupplyPathAuthorityStore`. A later pointer change rejects before fetching the new location. Configure a durable shared `SupplyPathAuthorityStore` across restarts or workers; `check` must atomically pin a new publisher and reject a changed location. 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-observation pinning cannot detect an origin already compromised before the first observation. +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. diff --git a/src/lib/supply-path/fetch-evidence.ts b/src/lib/supply-path/fetch-evidence.ts index a79a8459c..a41ed4274 100644 --- a/src/lib/supply-path/fetch-evidence.ts +++ b/src/lib/supply-path/fetch-evidence.ts @@ -19,7 +19,6 @@ export function boundedOption(value: number | undefined, fallback: number, maxim export class SupplyPathEvidenceSession { readonly evidence: SupplyPathEvidence[] = []; readonly crossOriginAuthorities = new Set(); - private readonly checkedAuthorities = new Set(); private readonly observedRevocations = new Map(); readonly revocations = new Map(); readonly signal: AbortSignal; @@ -184,6 +183,8 @@ export class SupplyPathEvidenceSession { const url = `https://${publisher}/.well-known/adagents.json`; const initial = await this.read(publisher, 'adagents', url); if (!initial) return null; + let authorityLocation = url; + let documentResponse = initial; let manifest = this.parseManifest(publisher, initial); if (!manifest) return null; if (manifest.authoritative_location !== undefined || manifest.superseded_by !== undefined) { @@ -215,29 +216,34 @@ export class SupplyPathEvidenceSession { this.documentError(publisher, initial, 'invalid_authoritative_location'); return null; } - await this.checkAuthority(publisher, location.href); - if (location.origin !== new URL(url).origin) this.crossOriginAuthorities.add(publisher); + authorityLocation = location.href; + await this.checkAuthority(publisher, authorityLocation, 'check'); const response = await this.read(publisher, 'adagents', target, true); if (!response) return null; + documentResponse = response; manifest = this.parseManifest(publisher, response); if (!manifest) return null; if (manifest.authoritative_location !== undefined || manifest.superseded_by !== undefined) { this.documentError(publisher, response, 'chained_authoritative_pointer'); return null; } + } else { + await this.checkAuthority(publisher, authorityLocation, 'check'); } if (!Array.isArray(manifest.authorized_agents)) { - this.documentError(publisher, initial, 'missing_authorized_agents'); - // Preserve denials even when the affirmative authorization list is malformed. - return { revoked_publisher_domains: manifest.revoked_publisher_domains }; + this.documentError(publisher, documentResponse, 'missing_authorized_agents'); + // parseManifest already captured denials; invalid envelopes cannot establish a pin. + return null; } + await this.checkAuthority(publisher, authorityLocation, 'observe'); + if (new URL(authorityLocation).origin !== new URL(url).origin) this.crossOriginAuthorities.add(publisher); return manifest; } - private async checkAuthority(publisher: string, location: string): Promise { + private async checkAuthority(publisher: string, location: string, operation: 'check' | 'observe'): Promise { let accepted: boolean; try { accepted = await withAbortSignal([this.signal], undefined, () => - (this.options.authorityStore ?? defaultSupplyPathAuthorities).check(publisher, location) + (this.options.authorityStore ?? defaultSupplyPathAuthorities)[operation](publisher, location) ); } catch (cause) { this.signal.throwIfAborted(); @@ -248,12 +254,9 @@ export class SupplyPathEvidenceSession { throw new TypeError( `Authoritative location changed for ${publisher} to ${location}; independently confirm the publisher migration before updating its pin` ); - this.checkedAuthorities.add(publisher); } private async readAndRemember(publisher: string): Promise { const manifest = await this.readAdagents(publisher); - if (manifest && !this.checkedAuthorities.has(publisher)) - await this.checkAuthority(publisher, `https://${publisher}/.well-known/adagents.json`); const observed = this.observedRevocations.get(publisher) ?? []; let held: readonly SupplyPathRevocation[]; try { diff --git a/src/lib/supply-path/revocations.ts b/src/lib/supply-path/revocations.ts index 30382016e..2b7675dc2 100644 --- a/src/lib/supply-path/revocations.ts +++ b/src/lib/supply-path/revocations.ts @@ -85,10 +85,20 @@ export function parseRevocations(value: unknown): SupplyPathRevocation[] | null return entries; } -/** Atomic trust-on-first-use storage. Capture the authenticated tenant in the store instance and namespace every pin by that tenant. */ +/** + * Trust-on-first-successful-use storage. Capture the authenticated tenant in the + * store instance and namespace every pin by that tenant. Neither a read nor a + * failed fetch may create a pin. Storage failures must reject. + */ export interface SupplyPathAuthorityStore { - /** Pin the first location; subsequently return true only for that location. Storage failures must reject. */ + /** Read-only precheck: true if absent or equal; false for a different existing pin. */ check(publisherDomain: string, location: string): Promise; + /** + * After successful manifest validation, atomically insert if absent or compare + * with the existing pin. Return false on mismatch, including a concurrent change + * since check(). A successful precheck is never a reservation or authorization. + */ + observe(publisherDomain: string, location: string): Promise; } /** Process-local pointer integrity. Use durable shared storage across workers/restarts. */ @@ -96,6 +106,10 @@ export class InMemorySupplyPathAuthorityStore implements SupplyPathAuthorityStor private readonly admission = new AuthorityAdmissionBudget(); private readonly locations = new Map(); async check(publisherDomain: string, location: string): Promise { + const pinned = this.locations.get(publisherDomain); + return pinned === undefined || pinned === location; + } + async observe(publisherDomain: string, location: string): Promise { const pinned = this.locations.get(publisherDomain); if (pinned !== undefined) return pinned === location; if (this.locations.size >= 10000) throw new Error('Supply-path authority store capacity exceeded'); diff --git a/src/lib/supply-path/supply-path.type-checks.ts b/src/lib/supply-path/supply-path.type-checks.ts index 9d95d3b21..e59fe535c 100644 --- a/src/lib/supply-path/supply-path.type-checks.ts +++ b/src/lib/supply-path/supply-path.type-checks.ts @@ -6,9 +6,12 @@ import { type CollectionDistribution, type AuthorizedAgent, type AdagentsAuthorizedAgent, + type SupplyPathAuthorityStore, } from '../index'; const bulk: AuthorizationCollectionSelector = { publisher_domain: 'owner.example' }; +// @ts-expect-error Durable authority stores must separate precheck from atomic successful observation. +const incompleteAuthorityStore: SupplyPathAuthorityStore = { check: async () => true }; const product: ProductCollectionSelector = { publisher_domain: 'owner.example', collection_ids: ['channel'] }; // @ts-expect-error Product selectors cannot use authorization bulk grants. const invalidProduct: ProductCollectionSelector = bulk; @@ -56,4 +59,15 @@ async function check(): Promise { const forged: typeof live = cached; void forged; } -void [invalidProduct, emptyProduct, byId, byIdentifier, both, emptyDistribution, discoveryGrant, registryGrant, check]; +void [ + incompleteAuthorityStore, + invalidProduct, + emptyProduct, + byId, + byIdentifier, + both, + emptyDistribution, + discoveryGrant, + registryGrant, + check, +]; diff --git a/test/lib/supply-path.test.js b/test/lib/supply-path.test.js index 448cb17e9..d4423645a 100644 --- a/test/lib/supply-path.test.js +++ b/test/lib/supply-path.test.js @@ -134,7 +134,7 @@ describe('authority and revocation trust boundaries', () => { verifySupplyPath(request, { source: 'authoritative', timeoutMs: 25, - authorityStore: { check: () => new Promise(() => {}) }, + authorityStore: { check: () => new Promise(() => {}), observe: async () => true }, trustedFetchFn: transport(), }), /deadline|abort/i @@ -852,7 +852,7 @@ it('rate-bounds many-authority admission and retains all live default-store evid for (let i = 0; i < 10000; i++) { if (i > 0 && i % 128 === 0) { await assert.rejects(revocations.observe('rate-blocked.attacker.example', denial), /admission rate/); - await assert.rejects(pins.check('rate-blocked.attacker.example', 'https://cdn.example/blocked.json'), /admission rate/); + await assert.rejects(pins.observe('rate-blocked.attacker.example', 'https://cdn.example/blocked.json'), /admission rate/); // Existing evidence remains readable during an admission-rate refusal. assert.deepEqual(await revocations.observe('host-0.attacker.example', []), denial); assert.equal(await pins.check('host-0.attacker.example', 'https://cdn.example/0.json'), true); @@ -860,11 +860,11 @@ it('rate-bounds many-authority admission and retains all live default-store evid } const authority = 'host-' + i + '.attacker.example'; await revocations.observe(authority, denial); - await pins.check(authority, 'https://cdn.example/' + i + '.json'); + await pins.observe(authority, 'https://cdn.example/' + i + '.json'); } now += 60001; await assert.rejects(revocations.observe('innocent.example', denial), /capacity exceeded/); - await assert.rejects(pins.check('innocent.example', 'https://innocent.example/adagents.json'), /capacity exceeded/); + await assert.rejects(pins.observe('innocent.example', 'https://innocent.example/adagents.json'), /capacity exceeded/); // Scan every retained authority: neither rate limiting nor total exhaustion // may evict a live denial or adopt a different pinned location. for (let i = 0; i < 10000; i++) { @@ -990,3 +990,104 @@ it('records malformed pointers as unavailable evidence while retaining their den ); } }); + +describe('authority pins require a successfully validated manifest', () => { + const failures = { + unavailable: new Response('unavailable', { status: 503 }), + malformed: new Response('{invalid JSON', { headers: { 'content-type': 'application/json' } }), + missing_envelope: {}, + malformed_envelope: { authorized_agents: null }, + chained: { authoritative_location: 'https://chained.example/another.json' }, + }; + for (const [name, failedTarget] of Object.entries(failures)) { + it(`does not poison the process default with a ${name} target`, async () => { + const host = `${name.replaceAll('_', '-')}.first-pin.example`; + const failed = `https://cdn.example/${name}-failed.json`; + const valid = `https://cdn.example/${name}-valid.json`; + const replacement = `https://cdn.example/${name}-replacement.json`; + const fixture = input(); + fixture.ownerManifest.collections[0].distribution[0].publisher_domain = host; + fixture.hostManifest.properties[0].publisher_domain = host; + const verify = (location, contents, requests = []) => + verifySupplyPathSdk( + { ...request, host_domain: host }, + { + source: 'authoritative', // Exercise the actual default authority store. + revocationStore: new sdk.InMemorySupplyPathRevocationStore(), + trustedFetchFn: transport( + { + [`https://${OWNER}/.well-known/adagents.json`]: fixture.ownerManifest, + [`https://${host}/.well-known/adagents.json`]: { authoritative_location: location }, + [location]: contents, + }, + requests + ), + } + ); + assert.equal((await verify(failed, failedTarget)).state, 'owner_attested'); + assert.equal(await sdk.defaultSupplyPathAuthorities.check(host, valid), true); + assert.equal((await verify(valid, fixture.hostManifest)).state, 'verified_owner_sold'); + assert.equal(await sdk.defaultSupplyPathAuthorities.check(host, valid), true); + assert.equal(await sdk.defaultSupplyPathAuthorities.check(host, replacement), false); + const requests = []; + await assert.rejects( + verify(replacement, { revoked_publisher_domains: [OWNER] }, requests), + /Authoritative location changed/ + ); + assert.equal( + requests.some(item => item.url === replacement), + false + ); + // A failed refresh of the accepted location preserves its pin as well. + assert.equal((await verify(valid, failedTarget)).state, 'owner_attested'); + assert.equal(await sdk.defaultSupplyPathAuthorities.check(host, replacement), false); + }); + } + it('does not pin a malformed publisher-origin envelope before a later valid pointer', async () => { + const pins = new sdk.InMemorySupplyPathAuthorityStore(); + await verifySupplyPath(request, { + source: 'authoritative', + authorityStore: pins, + trustedFetchFn: transport({ [`https://${HOST}/.well-known/adagents.json`]: {} }), + }); + assert.equal(await pins.check(HOST, 'https://cdn.example/later.json'), true); + assert.equal(await pins.observe(HOST, 'https://cdn.example/later.json'), true); + assert.equal(await pins.check(HOST, `https://${HOST}/.well-known/adagents.json`), false); + }); + it('atomically rejects a pin changed between precheck and successful observation', async () => { + const pins = new sdk.InMemorySupplyPathAuthorityStore(); + const fixture = input(); + fixture.hostManifest.properties[0].publisher_domain = HOST; + const target = 'https://cdn.example/racing.json'; + const confirmed = 'https://operator-confirmed.example/host.json'; + await assert.rejects( + verifySupplyPath(request, { + source: 'authoritative', + authorityStore: pins, + trustedFetchFn: transport({ + [`https://${HOST}/.well-known/adagents.json`]: { authoritative_location: target }, + [target]: () => { + pins.approveChange(HOST, confirmed); + return new Response(JSON.stringify(fixture.hostManifest), { + headers: { 'content-type': 'application/json' }, + }); + }, + }), + }), + /Authoritative location changed/ + ); + assert.equal(await pins.check(HOST, confirmed), true); + assert.equal(await pins.check(HOST, target), false); + }); + it('bounds the successful-observation commit by the same overall deadline', async () => { + await assert.rejects( + verifySupplyPath(request, { + source: 'authoritative', + timeoutMs: 25, + authorityStore: { check: async () => true, observe: () => new Promise(() => {}) }, + trustedFetchFn: transport(), + }), + /deadline|abort/i + ); + }); +}); From af39c4b81ecf7eca56be5f5697c3ec6c95b10b9d Mon Sep 17 00:00:00 2001 From: Brian O'Kelley Date: Mon, 14 Sep 2026 16:15:03 +0000 Subject: [PATCH 06/21] fix(supply-path): retain denials before later authority failures --- docs/guides/SUPPLY-PATH-VERIFICATION.md | 2 +- src/lib/supply-path/fetch-evidence.ts | 15 ++++-- test/lib/supply-path.test.js | 63 ++++++++++++++++++++++++- 3 files changed, 74 insertions(+), 6 deletions(-) diff --git a/docs/guides/SUPPLY-PATH-VERIFICATION.md b/docs/guides/SUPPLY-PATH-VERIFICATION.md index 6516c89f1..0e21bfb2a 100644 --- a/docs/guides/SUPPLY-PATH-VERIFICATION.md +++ b/docs/guides/SUPPLY-PATH-VERIFICATION.md @@ -90,7 +90,7 @@ Evidence contains requested/resolved URLs, HTTP status, fetch time, SHA-256 of e `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`. -Previously observed publisher revocations 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. +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. diff --git a/src/lib/supply-path/fetch-evidence.ts b/src/lib/supply-path/fetch-evidence.ts index a41ed4274..ae3c5266e 100644 --- a/src/lib/supply-path/fetch-evidence.ts +++ b/src/lib/supply-path/fetch-evidence.ts @@ -152,7 +152,7 @@ export class SupplyPathEvidenceSession { return null; } } - private parseManifest(publisher: string, response: SsrfFetchResult): SupplyPathManifest | null { + private async parseManifest(publisher: string, response: SsrfFetchResult): Promise { let document: unknown; try { document = parse(new TextDecoder('utf-8', { fatal: true }).decode(response.body)); @@ -168,6 +168,9 @@ export class SupplyPathEvidenceSession { } // Denials survive invalid affirmative envelopes and failed/chained pointers. this.observedRevocations.set(publisher, [...(this.observedRevocations.get(publisher) ?? []), ...denials]); + // Persist before any later fetch or authority operation can fail or exhaust + // the deadline. A failed affirmative verification must not erase a denial. + if (denials.length) await this.rememberRevocations(publisher); return document; } private documentError(publisher: string, response: SsrfFetchResult, error: string): void { @@ -185,7 +188,7 @@ export class SupplyPathEvidenceSession { if (!initial) return null; let authorityLocation = url; let documentResponse = initial; - let manifest = this.parseManifest(publisher, initial); + let manifest = await this.parseManifest(publisher, initial); if (!manifest) return null; if (manifest.authoritative_location !== undefined || manifest.superseded_by !== undefined) { const target = manifest.authoritative_location ?? manifest.superseded_by; @@ -221,7 +224,7 @@ export class SupplyPathEvidenceSession { const response = await this.read(publisher, 'adagents', target, true); if (!response) return null; documentResponse = response; - manifest = this.parseManifest(publisher, response); + manifest = await this.parseManifest(publisher, response); if (!manifest) return null; if (manifest.authoritative_location !== undefined || manifest.superseded_by !== undefined) { this.documentError(publisher, response, 'chained_authoritative_pointer'); @@ -257,6 +260,10 @@ export class SupplyPathEvidenceSession { } private async readAndRemember(publisher: string): Promise { const manifest = await this.readAdagents(publisher); + const effective = await this.rememberRevocations(publisher); + return manifest ? { ...manifest, revoked_publisher_domains: effective } : null; + } + private async rememberRevocations(publisher: string): Promise { const observed = this.observedRevocations.get(publisher) ?? []; let held: readonly SupplyPathRevocation[]; try { @@ -271,6 +278,6 @@ export class SupplyPathEvidenceSession { // Persistence can add prior denials; it cannot erase current wire evidence. const effective = [...new Map([...held, ...observed].map(entry => [entry.publisher_domain, entry])).values()]; this.revocations.set(publisher, effective); - return manifest ? { ...manifest, revoked_publisher_domains: effective } : null; + return effective; } } diff --git a/test/lib/supply-path.test.js b/test/lib/supply-path.test.js index d4423645a..f3a702e33 100644 --- a/test/lib/supply-path.test.js +++ b/test/lib/supply-path.test.js @@ -1056,6 +1056,7 @@ describe('authority pins require a successfully validated manifest', () => { }); it('atomically rejects a pin changed between precheck and successful observation', async () => { const pins = new sdk.InMemorySupplyPathAuthorityStore(); + const revocationStore = new sdk.InMemorySupplyPathRevocationStore(); const fixture = input(); fixture.hostManifest.properties[0].publisher_domain = HOST; const target = 'https://cdn.example/racing.json'; @@ -1064,8 +1065,12 @@ describe('authority pins require a successfully validated manifest', () => { verifySupplyPath(request, { source: 'authoritative', authorityStore: pins, + revocationStore, trustedFetchFn: transport({ - [`https://${HOST}/.well-known/adagents.json`]: { authoritative_location: target }, + [`https://${HOST}/.well-known/adagents.json`]: { + authoritative_location: target, + revoked_publisher_domains: [OWNER], + }, [target]: () => { pins.approveChange(HOST, confirmed); return new Response(JSON.stringify(fixture.hostManifest), { @@ -1078,7 +1083,63 @@ describe('authority pins require a successfully validated manifest', () => { ); assert.equal(await pins.check(HOST, confirmed), true); assert.equal(await pins.check(HOST, target), false); + const recovered = await verifySupplyPath(request, { + source: 'authoritative', + authorityStore: pins, + revocationStore, + trustedFetchFn: transport({ + [`https://${HOST}/.well-known/adagents.json`]: { authoritative_location: confirmed }, + [confirmed]: fixture.hostManifest, + }), + }); + assert.equal(recovered.state, 'owner_attested'); + assert.deepEqual( + (await revocationStore.observe(HOST, [])).map(entry => entry.publisher_domain), + [OWNER] + ); }); + for (const failure of ['throw', 'timeout']) { + it(`retains a validated target denial when final authority observation fails by ${failure}`, async () => { + const pins = new sdk.InMemorySupplyPathAuthorityStore(); + const revocationStore = new sdk.InMemorySupplyPathRevocationStore(); + const target = `https://cdn.example/observation-${failure}.json`; + await pins.observe(HOST, target); + let failing = true; + const authorityStore = { + check: (publisher, location) => pins.check(publisher, location), + observe: (publisher, location) => { + if (publisher === HOST && failing) { + if (failure === 'timeout') return new Promise(() => {}); + throw new Error('authority backend unavailable'); + } + return pins.observe(publisher, location); + }, + }; + const fixture = input(); + fixture.hostManifest.properties[0].publisher_domain = HOST; + const verify = manifest => + verifySupplyPath(request, { + source: 'authoritative', + authorityStore, + revocationStore, + timeoutMs: failing && failure === 'timeout' ? 25 : 1000, + trustedFetchFn: transport({ + [`https://${HOST}/.well-known/adagents.json`]: { authoritative_location: target }, + [target]: manifest, + }), + }); + await assert.rejects( + verify({ ...fixture.hostManifest, revoked_publisher_domains: [OWNER] }), + /storage failed|deadline|abort/i + ); + failing = false; + assert.equal((await verify(fixture.hostManifest)).state, 'owner_attested'); + assert.deepEqual( + (await revocationStore.observe(HOST, [])).map(entry => entry.publisher_domain), + [OWNER] + ); + }); + } it('bounds the successful-observation commit by the same overall deadline', async () => { await assert.rejects( verifySupplyPath(request, { From 638dd3be436732d25b8a067097066fee35c40610 Mon Sep 17 00:00:00 2001 From: Brian O'Kelley Date: Mon, 14 Sep 2026 16:20:47 +0000 Subject: [PATCH 07/21] docs(supply-path): clarify authority store admission contract --- src/lib/supply-path/types.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/lib/supply-path/types.ts b/src/lib/supply-path/types.ts index 706fae3e4..fda77e8ad 100644 --- a/src/lib/supply-path/types.ts +++ b/src/lib/supply-path/types.ts @@ -159,7 +159,7 @@ export interface AuthoritativeSupplyPathOptions { source: 'authoritative'; /** Defaults to a process-local seven-day hold; supply durable storage across workers/restarts. */ revocationStore?: import('./revocations').SupplyPathRevocationStore; - /** Pins authoritative locations. Changed pointers require independently confirmed migration. */ + /** Read-only check plus atomic observe pins only validated manifests; changed locations require confirmed migration. */ authorityStore?: import('./revocations').SupplyPathAuthorityStore; /** Optional product property scope. Every selected host property must be proven. */ propertySelectors?: import('../discovery/types').SinglePublisherPropertySelector[]; From 1938495373aba6a424209363616e9b920242a8d2 Mon Sep 17 00:00:00 2001 From: Brian O'Kelley Date: Mon, 14 Sep 2026 16:27:06 +0000 Subject: [PATCH 08/21] fix(supply-path): reject fragment aliases without consuming pin admission --- .../verify-authoritative-supply-paths.md | 2 + docs/guides/SUPPLY-PATH-VERIFICATION.md | 2 + src/lib/supply-path/fetch-evidence.ts | 2 +- src/lib/supply-path/revocations.ts | 4 ++ test/lib/supply-path.test.js | 71 ++++++++++++++++++- 5 files changed, 79 insertions(+), 2 deletions(-) diff --git a/.changeset/verify-authoritative-supply-paths.md b/.changeset/verify-authoritative-supply-paths.md index 30fa33748..a57e54540 100644 --- a/.changeset/verify-authoritative-supply-paths.md +++ b/.changeset/verify-authoritative-supply-paths.md @@ -7,3 +7,5 @@ Add supply-path verification with a typed canonical registry wrapper and a live 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. diff --git a/docs/guides/SUPPLY-PATH-VERIFICATION.md b/docs/guides/SUPPLY-PATH-VERIFICATION.md index 0e21bfb2a..9d687a4d3 100644 --- a/docs/guides/SUPPLY-PATH-VERIFICATION.md +++ b/docs/guides/SUPPLY-PATH-VERIFICATION.md @@ -94,6 +94,8 @@ Validated publisher revocations are persisted immediately after parsing, before 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. diff --git a/src/lib/supply-path/fetch-evidence.ts b/src/lib/supply-path/fetch-evidence.ts index ae3c5266e..9dd86442f 100644 --- a/src/lib/supply-path/fetch-evidence.ts +++ b/src/lib/supply-path/fetch-evidence.ts @@ -213,7 +213,7 @@ export class SupplyPathEvidenceSession { location.protocol !== 'https:' || location.username || location.password || - location.hash || + location.href.includes('#') || (location.port && location.port !== '443') ) { this.documentError(publisher, initial, 'invalid_authoritative_location'); diff --git a/src/lib/supply-path/revocations.ts b/src/lib/supply-path/revocations.ts index 2b7675dc2..a1f0185ae 100644 --- a/src/lib/supply-path/revocations.ts +++ b/src/lib/supply-path/revocations.ts @@ -89,6 +89,10 @@ export function parseRevocations(value: unknown): SupplyPathRevocation[] | null * Trust-on-first-successful-use storage. Capture the authenticated tenant in the * store instance and namespace every pin by that tenant. Neither a read nor a * failed fetch may create a pin. Storage failures must reject. + * Keys are the exact serialized HTTPS URL supplied by the verifier, with no + * fragment delimiter. Preserve query/path spelling; do not merge distinct URLs. + * A deadline may abandon an observe promise while its transaction completes. + * Such a commit still represents a validated manifest; retries must be idempotent. */ export interface SupplyPathAuthorityStore { /** Read-only precheck: true if absent or equal; false for a different existing pin. */ diff --git a/test/lib/supply-path.test.js b/test/lib/supply-path.test.js index f3a702e33..e1d05a897 100644 --- a/test/lib/supply-path.test.js +++ b/test/lib/supply-path.test.js @@ -964,7 +964,12 @@ it('does not borrow an unscoped owner agent grant from a shared catalog through }); it('records malformed pointers as unavailable evidence while retaining their denials', async () => { - for (const location of ['not a URL', 'http://example.com/host.json', 'https://user:password@example.com/host.json']) { + for (const location of [ + 'not a URL', + 'http://example.com/host.json', + 'https://user:password@example.com/host.json', + 'https://cdn.example/host.json#', + ]) { const store = new sdk.InMemorySupplyPathRevocationStore(); const result = await verifySupplyPath(request, { source: 'authoritative', @@ -992,6 +997,70 @@ it('records malformed pointers as unavailable evidence while retaining their den }); describe('authority pins require a successfully validated manifest', () => { + it('does not charge authority admission for more than 128 failed target fetches', async () => { + const pins = new sdk.InMemorySupplyPathAuthorityStore(); + for (let i = 0; i < 129; i++) { + const host = `failed-${i}.admission.example`; + const target = `https://cdn.example/failed-${i}.json`; + await verifySupplyPath( + { ...request, host_domain: host }, + { + source: 'authoritative', + authorityStore: pins, + revocationStore: new sdk.InMemorySupplyPathRevocationStore(), + trustedFetchFn: transport({ + [`https://${host}/.well-known/adagents.json`]: { authoritative_location: target }, + [target]: {}, + }), + } + ); + assert.equal(await pins.check(host, 'https://cdn.example/recovery.json'), true); + } + assert.equal( + ( + await verifySupplyPath(request, { + source: 'authoritative', + authorityStore: pins, + trustedFetchFn: transport(), + revocationStore: new sdk.InMemorySupplyPathRevocationStore(), + }) + ).state, + 'verified_owner_sold' + ); + }); + it('refuses an empty fragment without fetching or pinning its target', async () => { + const pins = new sdk.InMemorySupplyPathAuthorityStore(); + const requests = []; + const target = 'https://cdn.example/host.json#'; + await verifySupplyPath(request, { + source: 'authoritative', + authorityStore: pins, + revocationStore: new sdk.InMemorySupplyPathRevocationStore(), + trustedFetchFn: transport( + { + [`https://${HOST}/.well-known/adagents.json`]: { authoritative_location: target }, + [target]: input().hostManifest, + }, + requests + ), + }); + assert.equal( + requests.some(item => item.url === target), + false + ); + assert.equal(await pins.check(HOST, 'https://cdn.example/recovery.json'), true); + assert.equal( + ( + await verifySupplyPath(request, { + source: 'authoritative', + authorityStore: pins, + trustedFetchFn: transport(), + revocationStore: new sdk.InMemorySupplyPathRevocationStore(), + }) + ).state, + 'verified_owner_sold' + ); + }); const failures = { unavailable: new Response('unavailable', { status: 503 }), malformed: new Response('{invalid JSON', { headers: { 'content-type': 'application/json' } }), From d7e884bd2d0f871baa89b6037a4e3d74689c8b9b Mon Sep 17 00:00:00 2001 From: Brian O'Kelley Date: Mon, 14 Sep 2026 16:34:25 +0000 Subject: [PATCH 09/21] test(cli): keep tunnel lifecycle checks independent of public agents --- test/lib/cli-webhook-receiver-flag.test.js | 33 +++++++++++++--------- 1 file changed, 20 insertions(+), 13 deletions(-) diff --git a/test/lib/cli-webhook-receiver-flag.test.js b/test/lib/cli-webhook-receiver-flag.test.js index 5f8788ff1..90a014d66 100644 --- a/test/lib/cli-webhook-receiver-flag.test.js +++ b/test/lib/cli-webhook-receiver-flag.test.js @@ -494,14 +494,17 @@ describe('storyboard run --webhook-receiver-auto-tunnel', () => { test('ADCP_WEBHOOK_TUNNEL override substitutes {port} and captures marker URL', () => { // End-to-end of the override path: the stub prints the URL behind the // `ADCP_TUNNEL_URL=` marker and stays alive. The CLI must capture that URL, - // proceed to runStoryboard, fail at network dispatch (test-mcp isn't real - // here), and kill the tunnel on exit. The `runCli` timeout is the - // regression guard — if capture succeeds but the run hangs, the test fails - // loudly instead of stalling CI. - const result = runCli(['storyboard', 'run', 'test-mcp', '--file', scenarioPath, '--webhook-receiver-auto-tunnel'], { - ADCP_WEBHOOK_TUNNEL: `${stubTunnelPath} {port}`, - ADCP_WEBHOOK_TUNNEL_TIMEOUT_MS: '5000', - }); + // proceed to runStoryboard, fail at network dispatch, and kill the tunnel + // on exit. Use a refused loopback endpoint: test-mcp is a live public service + // whose network timing must not determine this local tunnel lifecycle test. + // The runCli timeout catches a hang after capture instead of stalling CI. + const result = runCli( + ['storyboard', 'run', 'http://127.0.0.1:1/mcp', '--file', scenarioPath, '--webhook-receiver-auto-tunnel'], + { + ADCP_WEBHOOK_TUNNEL: `${stubTunnelPath} {port}`, + ADCP_WEBHOOK_TUNNEL_TIMEOUT_MS: '5000', + } + ); assert.notStrictEqual(result.signal, 'SIGKILL', 'CLI hung past timeout — regression'); assert.match(result.stderr, /Auto-tunnel \(.+\): https:\/\/stub-\d+\.tunnel\.test → http:\/\/localhost:\d+/); }); @@ -511,11 +514,15 @@ describe('storyboard run --webhook-receiver-auto-tunnel', () => { // forwarding URL, the scanner must not latch onto that bystander. The stub // prints the noise URL first, then the marker; success proves the scanner // kept reading past the noise instead of wiring the wrong destination. - const result = runCli(['storyboard', 'run', 'test-mcp', '--file', scenarioPath, '--webhook-receiver-auto-tunnel'], { - ADCP_WEBHOOK_TUNNEL: `${stubTunnelPath} {port}`, - FAKE_TUNNEL_NOISE_URL: 'https://docs.example.com/getting-started', - ADCP_WEBHOOK_TUNNEL_TIMEOUT_MS: '5000', - }); + const result = runCli( + ['storyboard', 'run', 'http://127.0.0.1:1/mcp', '--file', scenarioPath, '--webhook-receiver-auto-tunnel'], + { + ADCP_WEBHOOK_TUNNEL: `${stubTunnelPath} {port}`, + FAKE_TUNNEL_NOISE_URL: 'https://docs.example.com/getting-started', + ADCP_WEBHOOK_TUNNEL_TIMEOUT_MS: '5000', + } + ); + assert.notStrictEqual(result.signal, 'SIGKILL', 'CLI hung past timeout after marker capture'); assert.match(result.stderr, /Auto-tunnel \(.+\): https:\/\/stub-\d+\.tunnel\.test/); assert.doesNotMatch(result.stderr, /Auto-tunnel \(.+\): https:\/\/docs\.example\.com/); }); From 6de659a24c01cbd9cdeafe346f5f1938d27f5a2c Mon Sep 17 00:00:00 2001 From: Brian O'Kelley Date: Sat, 19 Sep 2026 10:15:07 +0000 Subject: [PATCH 10/21] fix(supply-path): consume merged canonical vectors --- src/lib/supply-path/evaluate.ts | 66 +++ test/fixtures/supply-path/source.json | 4 +- test/fixtures/supply-path/vectors.json | 738 ++++++++++++++++++++++--- test/lib/supply-path.test.js | 15 +- 4 files changed, 751 insertions(+), 72 deletions(-) diff --git a/src/lib/supply-path/evaluate.ts b/src/lib/supply-path/evaluate.ts index a9dffbf0c..cde056f89 100644 --- a/src/lib/supply-path/evaluate.ts +++ b/src/lib/supply-path/evaluate.ts @@ -9,6 +9,7 @@ import { expandPublisherPropertySelector, } from '../discovery/publisher-property-selector'; import type { AdAgentsJson, AuthorizedAgent } from '../discovery/types'; +import { MediaChannelValues, PropertyIdentifierTypesValues, PropertyTypeValues } from '../types/enums.generated'; import type { SupplyPathInput, SupplyPathLegs, SupplyPathManifest, SupplyPathVerdict } from './types'; import { agentIdentity, domain, record, records, strings } from './validation'; @@ -54,6 +55,70 @@ function coversCollection(entry: Record, owner: string, id: str ); } +const PROPERTY_TYPES = new Set(PropertyTypeValues); +const PROPERTY_IDENTIFIER_TYPES = new Set(PropertyIdentifierTypesValues); +const PROPERTY_CHANNELS = new Set(MediaChannelValues); + +/** A declaration is not evidence unless its property grant is complete and schema-shaped. */ +function hasPropertyAuthorizationEnvelope(entry: Record): boolean { + const propertyToken = (value: unknown): value is string => typeof value === 'string' && /^[a-z0-9_]+$/.test(value); + const propertyTokens = (value: unknown): value is string[] => + Array.isArray(value) && value.length > 0 && value.every(propertyToken); + const optionalUniqueList = (value: unknown, valid: (item: unknown) => boolean): boolean => + value === undefined || (Array.isArray(value) && value.every(valid) && new Set(value).size === value.length); + const validInlineProperty = (value: unknown): boolean => { + if ( + !record(value) || + typeof value.property_type !== 'string' || + !PROPERTY_TYPES.has(value.property_type) || + typeof value.name !== 'string' || + !Array.isArray(value.identifiers) || + value.identifiers.length === 0 + ) { + return false; + } + if (value.property_id !== undefined && !propertyToken(value.property_id)) return false; + if (value.publisher_domain !== undefined && typeof value.publisher_domain !== 'string') return false; + if ( + !optionalUniqueList(value.tags, propertyToken) || + !optionalUniqueList(value.supported_channels, item => typeof item === 'string' && PROPERTY_CHANNELS.has(item)) + ) { + return false; + } + return value.identifiers.every( + identifier => + record(identifier) && + typeof identifier.type === 'string' && + PROPERTY_IDENTIFIER_TYPES.has(identifier.type) && + typeof identifier.value === 'string' + ); + }; + + if (entry.authorization_type === 'property_ids') return propertyTokens(entry.property_ids); + if (entry.authorization_type === 'property_tags') return propertyTokens(entry.property_tags); + if (entry.authorization_type === 'inline_properties') { + return ( + Array.isArray(entry.properties) && entry.properties.length > 0 && entry.properties.every(validInlineProperty) + ); + } + if (entry.authorization_type === 'publisher_properties') { + if ( + !Array.isArray(entry.publisher_properties) || + entry.publisher_properties.length === 0 || + !entry.publisher_properties.every(record) + ) { + return false; + } + try { + entry.publisher_properties.forEach(selector => parsePublisherPropertySelector(selector)); + return true; + } catch { + return false; + } + } + return false; +} + /** Resolve one entry at a time: separate grants are alternatives, never merged across collection scopes. */ function propertyScope( entry: Record, @@ -314,6 +379,7 @@ export function evaluateSupplyPath(input: SupplyPathInput): SupplyPathVerdict { e => agentIdentity(e.url) === agent && owner && + hasPropertyAuthorizationEnvelope(e) && (!input.requireExplicitOwnerPublisherDomain || e.collections !== undefined) && coversCollection(e, owner, input.collectionId) && !unsupportedConstraints(e).length diff --git a/test/fixtures/supply-path/source.json b/test/fixtures/supply-path/source.json index d36b1a4b1..a5a448126 100644 --- a/test/fixtures/supply-path/source.json +++ b/test/fixtures/supply-path/source.json @@ -1,7 +1,7 @@ { "repository": "adcontextprotocol/adcp", - "commit": "f701ede564fe55909f5ace51b48575f586c4f890", + "commit": "dc69e0b2264b4c563f2175a48c515b7108dbb4f6", "path": "static/compliance/source/test-vectors/supply-path/vectors.json", - "sha256": "c81122ed89d041660c5568471002cb6d21d21b55917699ddff209a5838668337", + "sha256": "1a239d61209896aad843375d307650fb22dbfe7a8c73ebb900d8aec6d58abd31", "semantics_version": "1" } diff --git a/test/fixtures/supply-path/vectors.json b/test/fixtures/supply-path/vectors.json index 381f04480..955f5633a 100644 --- a/test/fixtures/supply-path/vectors.json +++ b/test/fixtures/supply-path/vectors.json @@ -14,7 +14,11 @@ "authorized_agents": [ { "url": "https://sales.channel-owner.example", - "authorized_for": "Owner-sold avails" + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "owner_inventory" + ] } ], "collections": [ @@ -103,7 +107,11 @@ "authorized_agents": [ { "url": "https://sales.channel-owner.example", - "authorized_for": "Owner-sold avails" + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "owner_inventory" + ] } ], "collections": [ @@ -189,7 +197,11 @@ "authorized_agents": [ { "url": "https://sales.channel-owner.example", - "authorized_for": "Owner-sold avails" + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "owner_inventory" + ] } ], "collections": [ @@ -271,7 +283,11 @@ "authorized_agents": [ { "url": "https://sales.channel-owner.example", - "authorized_for": "Owner-sold avails" + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "owner_inventory" + ] } ], "collections": [ @@ -354,7 +370,11 @@ "authorized_agents": [ { "url": "https://sales.channel-owner.example", - "authorized_for": "Owner-sold avails" + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "owner_inventory" + ] } ], "collections": [ @@ -437,7 +457,11 @@ "authorized_agents": [ { "url": "https://sales.channel-owner.example", - "authorized_for": "Owner-sold avails" + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "owner_inventory" + ] } ], "collections": [ @@ -520,7 +544,11 @@ "authorized_agents": [ { "url": "https://sales.channel-owner.example", - "authorized_for": "Owner-sold avails" + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "owner_inventory" + ] } ], "collections": [ @@ -603,7 +631,11 @@ "authorized_agents": [ { "url": "https://sales.channel-owner.example", - "authorized_for": "Owner-sold avails" + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "owner_inventory" + ] } ], "collections": [ @@ -691,7 +723,11 @@ "authorized_agents": [ { "url": "https://sales.channel-owner.example", - "authorized_for": "Owner-sold avails" + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "owner_inventory" + ] } ], "collections": [ @@ -779,7 +815,11 @@ "authorized_agents": [ { "url": "https://sales.channel-owner.example", - "authorized_for": "Owner-sold avails" + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "owner_inventory" + ] } ], "collections": [ @@ -870,7 +910,11 @@ "authorized_agents": [ { "url": "https://sales.channel-owner.example", - "authorized_for": "Owner-sold avails" + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "owner_inventory" + ] } ], "collections": [ @@ -960,7 +1004,11 @@ "authorized_agents": [ { "url": "https://sales.channel-owner.example", - "authorized_for": "Owner-sold avails" + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "owner_inventory" + ] } ], "collections": [ @@ -1050,7 +1098,11 @@ "authorized_agents": [ { "url": "https://sales.channel-owner.example", - "authorized_for": "Owner-sold avails" + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "owner_inventory" + ] } ], "collections": [ @@ -1140,7 +1192,11 @@ "authorized_agents": [ { "url": "https://sales.channel-owner.example", - "authorized_for": "Owner-sold avails" + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "owner_inventory" + ] } ], "collections": [ @@ -1232,7 +1288,11 @@ "authorized_agents": [ { "url": "https://sales.channel-owner.example", - "authorized_for": "Owner-sold avails" + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "owner_inventory" + ] } ], "collections": [ @@ -1311,7 +1371,11 @@ "authorized_agents": [ { "url": "https://sales.channel-owner.example", - "authorized_for": "Owner-sold avails" + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "owner_inventory" + ] } ], "collections": [ @@ -1404,7 +1468,11 @@ "authorized_agents": [ { "url": "https://sales.channel-owner.example", - "authorized_for": "Owner-sold avails" + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "owner_inventory" + ] } ], "collections": [ @@ -1499,7 +1567,11 @@ "authorized_agents": [ { "url": "https://sales.channel-owner.example", - "authorized_for": "Owner-sold avails" + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "owner_inventory" + ] } ], "collections": [ @@ -1587,7 +1659,11 @@ "authorized_agents": [ { "url": "https://sales.channel-owner.example", - "authorized_for": "Owner-sold avails" + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "owner_inventory" + ] } ], "collections": [ @@ -1678,7 +1754,11 @@ "authorized_agents": [ { "url": "https://sales.channel-owner.example", - "authorized_for": "Owner-sold avails" + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "owner_inventory" + ] } ], "collections": [ @@ -1769,7 +1849,11 @@ "authorized_agents": [ { "url": "https://sales.channel-owner.example", - "authorized_for": "Owner-sold avails" + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "owner_inventory" + ] } ], "collections": [ @@ -1860,7 +1944,11 @@ "authorized_agents": [ { "url": "https://sales.channel-owner.example", - "authorized_for": "Owner-sold avails" + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "owner_inventory" + ] } ], "collections": [ @@ -1951,7 +2039,11 @@ "authorized_agents": [ { "url": "https://sales.channel-owner.example", - "authorized_for": "Owner-sold avails" + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "owner_inventory" + ] } ], "collections": [ @@ -2042,7 +2134,11 @@ "authorized_agents": [ { "url": "https://sales.channel-owner.example", - "authorized_for": "Owner-sold avails" + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "owner_inventory" + ] } ], "collections": [ @@ -2132,7 +2228,11 @@ "authorized_agents": [ { "url": "https://sales.channel-owner.example", - "authorized_for": "Owner-sold avails" + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "owner_inventory" + ] } ], "collections": [ @@ -2222,7 +2322,11 @@ "authorized_agents": [ { "url": "https://sales.channel-owner.example", - "authorized_for": "Owner-sold avails" + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "owner_inventory" + ] } ], "collections": [ @@ -2312,7 +2416,11 @@ "authorized_agents": [ { "url": "https://sales.channel-owner.example", - "authorized_for": "Owner-sold avails" + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "owner_inventory" + ] } ], "collections": [ @@ -2405,7 +2513,11 @@ "authorized_agents": [ { "url": "https://sales.channel-owner.example", - "authorized_for": "Owner-sold avails" + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "owner_inventory" + ] } ], "collections": [ @@ -2534,7 +2646,11 @@ "authorized_agents": [ { "url": "https://sales.channel-owner.example", - "authorized_for": "Owner-sold avails" + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "owner_inventory" + ] } ], "collections": [ @@ -2624,7 +2740,11 @@ "authorized_agents": [ { "url": "https://sales.channel-owner.example", - "authorized_for": "Owner-sold avails" + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "owner_inventory" + ] } ], "collections": [ @@ -2712,7 +2832,11 @@ "authorized_agents": [ { "url": "https://sales.channel-owner.example", - "authorized_for": "Owner-sold avails" + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "owner_inventory" + ] } ], "collections": [ @@ -2810,7 +2934,11 @@ "authorized_agents": [ { "url": "https://sales.channel-owner.example", - "authorized_for": "Owner-sold avails" + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "owner_inventory" + ] } ], "collections": [ @@ -2871,7 +2999,7 @@ } }, { - "id": "host-delegated-without-host-adagents", + "id": "owner-agent-missing-discriminator", "input": { "ownerDomain": "channel-owner.example", "hostDomain": "hoststream.example", @@ -2903,6 +3031,85 @@ } ] }, + "hostManifest": { + "properties": [ + { + "property_id": "hoststream_ctv", + "name": "HostStream CTV", + "property_type": "ctv_app", + "identifiers": [ + { + "type": "roku_channel_id", + "value": "123" + } + ] + } + ], + "authorized_agents": [] + } + }, + "expected": { + "semantics_version": "1", + "state": "owner_attested", + "legs": { + "owner_collection_declared": { + "ok": true + }, + "owner_distribution_carriage": { + "ok": true + }, + "owner_agent_declared": { + "ok": false, + "failure": "agent_not_declared_by_owner" + }, + "host_authorization": { + "ok": false, + "failure": "no_agent_entry" + }, + "inventory_partner_domain": { + "ok": true + } + }, + "resolved_collection_id": "retro_news" + } + }, + { + "id": "host-delegated-without-host-adagents", + "input": { + "ownerDomain": "channel-owner.example", + "hostDomain": "hoststream.example", + "agentUrl": "https://sales.channel-owner.example", + "collectionId": "retro_news", + "hostInventoryPartnerDomains": [ + "channel-owner.example" + ], + "ownerManifest": { + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "owner_inventory" + ] + } + ], + "collections": [ + { + "collection_id": "retro_news", + "name": "Retro News", + "kind": "channel", + "distribution": [ + { + "publisher_domain": "hoststream.example", + "property_ids": [ + "hoststream_ctv" + ] + } + ] + } + ] + }, "hostManifest": null }, "expected": { @@ -3012,7 +3219,11 @@ "authorized_agents": [ { "url": "https://sales.channel-owner.example", - "authorized_for": "Owner-sold avails" + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "owner_inventory" + ] } ], "collections": [ @@ -3101,7 +3312,11 @@ "authorized_agents": [ { "url": "https://sales.channel-owner.example", - "authorized_for": "Owner-sold avails" + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "owner_inventory" + ] } ], "collections": [ @@ -3192,7 +3407,11 @@ "authorized_agents": [ { "url": "https://sales.channel-owner.example", - "authorized_for": "Owner-sold avails" + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "owner_inventory" + ] } ], "collections": [ @@ -3283,8 +3502,12 @@ "authorized_agents": [ { "url": "https://sales.channel-owner.example", - "authorized_for": "Owner-sold avails" - } + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "owner_inventory" + ] + } ], "collections": [ { @@ -3376,7 +3599,11 @@ "authorized_agents": [ { "url": "https://sales.channel-owner.example", - "authorized_for": "Owner-sold avails" + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "owner_inventory" + ] } ], "collections": [ @@ -3468,7 +3695,11 @@ "authorized_agents": [ { "url": "https://sales.channel-owner.example", - "authorized_for": "Owner-sold avails" + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "owner_inventory" + ] } ], "collections": [ @@ -3559,7 +3790,11 @@ "authorized_agents": [ { "url": "https://sales.channel-owner.example", - "authorized_for": "Owner-sold avails" + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "owner_inventory" + ] } ], "collections": [ @@ -3652,7 +3887,11 @@ "authorized_agents": [ { "url": "https://sales.channel-owner.example", - "authorized_for": "Owner-sold avails" + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "owner_inventory" + ] } ], "collections": [ @@ -3746,7 +3985,11 @@ "authorized_agents": [ { "url": "https://sales.channel-owner.example", - "authorized_for": "Owner-sold avails" + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "owner_inventory" + ] } ], "collections": [ @@ -3839,7 +4082,11 @@ "authorized_agents": [ { "url": "https://sales.channel-owner.example", - "authorized_for": "Owner-sold avails" + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "owner_inventory" + ] } ], "collections": [ @@ -3932,7 +4179,11 @@ "authorized_agents": [ { "url": "https://sales.channel-owner.example", - "authorized_for": "Owner-sold avails" + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "owner_inventory" + ] } ], "collections": [ @@ -4022,7 +4273,11 @@ "authorized_agents": [ { "url": "https://sales.channel-owner.example", - "authorized_for": "Owner-sold avails" + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "owner_inventory" + ] } ], "collections": [ @@ -5130,7 +5385,11 @@ "authorized_agents": [ { "url": "https://sales.channel-owner.example", - "authorized_for": "Owner-sold avails" + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "owner_inventory" + ] } ], "collections": [ @@ -5198,7 +5457,11 @@ "authorized_agents": [ { "url": "https://sales.channel-owner.example", - "authorized_for": "Owner-sold avails" + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "owner_inventory" + ] } ], "collections": [ @@ -5273,7 +5536,11 @@ "authorized_agents": [ { "url": "https://sales.channel-owner.example", - "authorized_for": "Owner-sold avails" + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "owner_inventory" + ] } ], "collections": [ @@ -5366,7 +5633,11 @@ "authorized_agents": [ { "url": "https://sales.channel-owner.example", - "authorized_for": "Owner-sold avails" + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "owner_inventory" + ] } ], "collections": [ @@ -5464,7 +5735,11 @@ "authorized_agents": [ { "url": "https://sales.channel-owner.example", - "authorized_for": "Owner-sold avails" + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "owner_inventory" + ] } ], "collections": [ @@ -5526,7 +5801,11 @@ "authorized_agents": [ { "url": "https://sales.channel-owner.example", - "authorized_for": "Owner-sold avails" + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "owner_inventory" + ] } ], "collections": [ @@ -5628,7 +5907,11 @@ "authorized_agents": [ { "url": "https://sales.channel-owner.example", - "authorized_for": "Owner-sold avails" + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "owner_inventory" + ] } ], "collections": [ @@ -5727,7 +6010,11 @@ "authorized_agents": [ { "url": "https://sales.channel-owner.example", - "authorized_for": "Owner-sold avails" + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "owner_inventory" + ] } ], "collections": [ @@ -5826,7 +6113,11 @@ "authorized_agents": [ { "url": "https://sales.channel-owner.example", - "authorized_for": "Owner-sold avails" + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "owner_inventory" + ] } ], "collections": [ @@ -5918,7 +6209,11 @@ "authorized_agents": [ { "url": "https://sales.channel-owner.example", - "authorized_for": "Owner-sold avails" + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "owner_inventory" + ] } ], "collections": [ @@ -6010,7 +6305,11 @@ "authorized_agents": [ { "url": "https://sales.channel-owner.example", - "authorized_for": "Owner-sold avails" + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "owner_inventory" + ] } ], "collections": [ @@ -6105,7 +6404,11 @@ "authorized_agents": [ { "url": "https://sales.channel-owner.example", - "authorized_for": "Owner-sold avails" + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "owner_inventory" + ] } ], "collections": [ @@ -6200,7 +6503,11 @@ "authorized_agents": [ { "url": "https://sales.channel-owner.example", - "authorized_for": "Owner-sold avails" + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "owner_inventory" + ] } ], "collections": [ @@ -6299,7 +6606,11 @@ "authorized_agents": [ { "url": "https://sales.channel-owner.example", - "authorized_for": "Owner-sold avails" + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "owner_inventory" + ] } ], "collections": [ @@ -6397,7 +6708,11 @@ "authorized_agents": [ { "url": "https://sales.channel-owner.example", - "authorized_for": "Owner-sold avails" + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "owner_inventory" + ] } ], "collections": [ @@ -6498,7 +6813,11 @@ "authorized_agents": [ { "url": "https://sales.channel-owner.example", - "authorized_for": "Owner-sold avails" + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "owner_inventory" + ] } ], "collections": [ @@ -6590,7 +6909,11 @@ "authorized_agents": [ { "url": "https://sales.channel-owner.example", - "authorized_for": "Owner-sold avails" + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "owner_inventory" + ] } ], "collections": [ @@ -6681,7 +7004,11 @@ "authorized_agents": [ { "url": "https://sales.channel-owner.example", - "authorized_for": "Owner-sold avails" + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "owner_inventory" + ] } ], "collections": [ @@ -6770,7 +7097,11 @@ "authorized_agents": [ { "url": "https://sales.channel-owner.example", - "authorized_for": "Owner-sold avails" + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "owner_inventory" + ] } ], "collections": [ @@ -6861,7 +7192,11 @@ "authorized_agents": [ { "url": "https://sales.channel-owner.example", - "authorized_for": "Owner-sold avails" + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "owner_inventory" + ] } ], "collections": [ @@ -6962,7 +7297,11 @@ "authorized_agents": [ { "url": "https://sales.channel-owner.example", - "authorized_for": "Owner-sold avails" + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "owner_inventory" + ] } ], "collections": [ @@ -7063,6 +7402,10 @@ "retro_news" ] } + ], + "authorization_type": "property_ids", + "property_ids": [ + "owner_inventory" ] } ], @@ -7164,6 +7507,10 @@ "retro_news" ] } + ], + "authorization_type": "property_ids", + "property_ids": [ + "owner_inventory" ] } ], @@ -7258,7 +7605,11 @@ "authorized_agents": [ { "url": "https://sales.channel-owner.example", - "authorized_for": "Owner-sold avails" + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "owner_inventory" + ] } ], "collections": [ @@ -7340,6 +7691,10 @@ { "publisher_domain": "other-owner.example" } + ], + "authorization_type": "property_ids", + "property_ids": [ + "owner_inventory" ] } ], @@ -7422,6 +7777,10 @@ { "publisher_domain": "channel-owner.example" } + ], + "authorization_type": "property_ids", + "property_ids": [ + "owner_inventory" ] } ], @@ -7499,7 +7858,11 @@ { "url": "https://sales.channel-owner.example", "authorized_for": "Owner-sold avails", - "collections": [] + "collections": [], + "authorization_type": "property_ids", + "property_ids": [ + "owner_inventory" + ] } ], "collections": [ @@ -7561,6 +7924,243 @@ }, "resolved_collection_id": "retro_news" } + }, + { + "id": "owner-agent-invalid-property-id", + "input": { + "ownerDomain": "channel-owner.example", + "hostDomain": "hoststream.example", + "agentUrl": "https://sales.channel-owner.example", + "collectionId": "retro_news", + "hostInventoryPartnerDomains": [ + "channel-owner.example" + ], + "ownerManifest": { + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails", + "authorization_type": "property_ids", + "property_ids": [ + "INVALID ID" + ] + } + ], + "collections": [ + { + "collection_id": "retro_news", + "name": "Retro News", + "kind": "channel", + "distribution": [ + { + "publisher_domain": "hoststream.example", + "property_ids": [ + "hoststream_ctv" + ] + } + ] + } + ] + }, + "hostManifest": { + "properties": [ + { + "property_id": "hoststream_ctv", + "name": "HostStream CTV", + "property_type": "ctv_app", + "identifiers": [ + { + "type": "roku_channel_id", + "value": "123" + } + ] + } + ], + "authorized_agents": [] + } + }, + "expected": { + "semantics_version": "1", + "state": "owner_attested", + "legs": { + "owner_collection_declared": { + "ok": true + }, + "owner_distribution_carriage": { + "ok": true + }, + "owner_agent_declared": { + "ok": false, + "failure": "agent_not_declared_by_owner" + }, + "host_authorization": { + "ok": false, + "failure": "no_agent_entry" + }, + "inventory_partner_domain": { + "ok": true + } + }, + "resolved_collection_id": "retro_news" + } + }, + { + "id": "owner-agent-invalid-property-tag", + "input": { + "ownerDomain": "channel-owner.example", + "hostDomain": "hoststream.example", + "agentUrl": "https://sales.channel-owner.example", + "collectionId": "retro_news", + "hostInventoryPartnerDomains": [ + "channel-owner.example" + ], + "ownerManifest": { + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails", + "authorization_type": "property_tags", + "property_tags": [ + "INVALID TAG" + ] + } + ], + "collections": [ + { + "collection_id": "retro_news", + "name": "Retro News", + "kind": "channel", + "distribution": [ + { + "publisher_domain": "hoststream.example", + "property_ids": [ + "hoststream_ctv" + ] + } + ] + } + ] + }, + "hostManifest": { + "properties": [ + { + "property_id": "hoststream_ctv", + "name": "HostStream CTV", + "property_type": "ctv_app", + "identifiers": [ + { + "type": "roku_channel_id", + "value": "123" + } + ] + } + ], + "authorized_agents": [] + } + }, + "expected": { + "semantics_version": "1", + "state": "owner_attested", + "legs": { + "owner_collection_declared": { + "ok": true + }, + "owner_distribution_carriage": { + "ok": true + }, + "owner_agent_declared": { + "ok": false, + "failure": "agent_not_declared_by_owner" + }, + "host_authorization": { + "ok": false, + "failure": "no_agent_entry" + }, + "inventory_partner_domain": { + "ok": true + } + }, + "resolved_collection_id": "retro_news" + } + }, + { + "id": "owner-agent-malformed-inline-property", + "input": { + "ownerDomain": "channel-owner.example", + "hostDomain": "hoststream.example", + "agentUrl": "https://sales.channel-owner.example", + "collectionId": "retro_news", + "hostInventoryPartnerDomains": [ + "channel-owner.example" + ], + "ownerManifest": { + "authorized_agents": [ + { + "url": "https://sales.channel-owner.example", + "authorized_for": "Owner-sold avails", + "authorization_type": "inline_properties", + "properties": [ + {} + ] + } + ], + "collections": [ + { + "collection_id": "retro_news", + "name": "Retro News", + "kind": "channel", + "distribution": [ + { + "publisher_domain": "hoststream.example", + "property_ids": [ + "hoststream_ctv" + ] + } + ] + } + ] + }, + "hostManifest": { + "properties": [ + { + "property_id": "hoststream_ctv", + "name": "HostStream CTV", + "property_type": "ctv_app", + "identifiers": [ + { + "type": "roku_channel_id", + "value": "123" + } + ] + } + ], + "authorized_agents": [] + } + }, + "expected": { + "semantics_version": "1", + "state": "owner_attested", + "legs": { + "owner_collection_declared": { + "ok": true + }, + "owner_distribution_carriage": { + "ok": true + }, + "owner_agent_declared": { + "ok": false, + "failure": "agent_not_declared_by_owner" + }, + "host_authorization": { + "ok": false, + "failure": "no_agent_entry" + }, + "inventory_partner_domain": { + "ok": true + } + }, + "resolved_collection_id": "retro_news" + } } ], "ads_txt_policy_vectors": [ diff --git a/test/lib/supply-path.test.js b/test/lib/supply-path.test.js index e1d05a897..af85ffb82 100644 --- a/test/lib/supply-path.test.js +++ b/test/lib/supply-path.test.js @@ -26,7 +26,15 @@ function input() { collectionId: 'retro_news', hostInventoryPartnerDomains: null, ownerManifest: { - authorized_agents: [{ url: AGENT, authorized_for: 'Owner avails', collections: [{ publisher_domain: OWNER }] }], + authorized_agents: [ + { + url: AGENT, + authorized_for: 'Owner avails', + authorization_type: 'property_ids', + property_ids: ['owner_property'], + collections: [{ publisher_domain: OWNER }], + }, + ], collections: [ { collection_id: 'retro_news', @@ -758,6 +766,11 @@ it('bulk fetching preserves untyped collection fallback alongside a typed websit const fixture = corpus.ads_txt_policy_vectors.find( v => v.id === 'bulk-fetch-includes-untyped-collection-fallback' ).input; + // The policy vector isolates file selection and intentionally omits a complete + // owner grant. Supply one here so this integration assertion measures the + // fetched inventory-partner fallback rather than owner-grant validation. + fixture.ownerManifest.authorized_agents[0].authorization_type = 'property_ids'; + fixture.ownerManifest.authorized_agents[0].property_ids = ['owner_property']; const calls = []; const result = await verifySupplyPath( { owner_domain: OWNER, host_domain: HOST, agent_url: AGENT }, From c4ca2ded445440fd936f0e0a30df7a3f914630b0 Mon Sep 17 00:00:00 2001 From: Brian O'Kelley Date: Sat, 19 Sep 2026 10:22:27 +0000 Subject: [PATCH 11/21] fix(supply-path): reject malformed property grants --- src/lib/supply-path/evaluate.ts | 32 +++++++++++++++++++++++++++++--- test/lib/supply-path.test.js | 27 +++++++++++++++++++++++++++ 2 files changed, 56 insertions(+), 3 deletions(-) diff --git a/src/lib/supply-path/evaluate.ts b/src/lib/supply-path/evaluate.ts index cde056f89..d87899e09 100644 --- a/src/lib/supply-path/evaluate.ts +++ b/src/lib/supply-path/evaluate.ts @@ -56,7 +56,21 @@ function coversCollection(entry: Record, owner: string, id: str } const PROPERTY_TYPES = new Set(PropertyTypeValues); -const PROPERTY_IDENTIFIER_TYPES = new Set(PropertyIdentifierTypesValues); +const PROPERTY_IDENTIFIER_TYPES = new Set([ + ...PropertyIdentifierTypesValues, + // The SDK still accepts the published pre-3.2 discovery aliases represented + // by discovery/types.ts and by the canonical supply-path corpus. + 'amazon_app_store_id', + 'roku_channel_id', + 'lg_channel_id', + 'vizio_app_id', + 'fire_tv_app_id', + 'dooh_venue_id', + 'podcast_rss_feed', + 'spotify_show_id', + 'iab_tech_lab_domain_id', + 'custom', +]); const PROPERTY_CHANNELS = new Set(MediaChannelValues); /** A declaration is not evidence unless its property grant is complete and schema-shaped. */ @@ -110,7 +124,19 @@ function hasPropertyAuthorizationEnvelope(entry: Record): boole return false; } try { - entry.publisher_properties.forEach(selector => parsePublisherPropertySelector(selector)); + for (const raw of entry.publisher_properties) { + const selector = parsePublisherPropertySelector(raw); + const value = raw as Record; + if ( + (selector.selection_type === 'by_id' && + (!propertyTokens(value.property_ids) || value.property_tags !== undefined)) || + (selector.selection_type === 'by_tag' && + (!propertyTokens(value.property_tags) || value.property_ids !== undefined)) || + (selector.selection_type === 'all' && (value.property_ids !== undefined || value.property_tags !== undefined)) + ) { + return false; + } + } return true; } catch { return false; @@ -404,7 +430,7 @@ export function evaluateSupplyPath(input: SupplyPathInput): SupplyPathVerdict { carriage.ok && collectionLeg.ok && covered.find(e => { - if (unsupportedConstraints(e).length) return false; + if (!hasPropertyAuthorizationEnvelope(e) || unsupportedConstraints(e).length) return false; const scope = propertyScope(e, host, hostManifest, input.requireExplicitHostPublisherDomain); const required = input.requiredHostPropertyIds ?? claimed; if ( diff --git a/test/lib/supply-path.test.js b/test/lib/supply-path.test.js index af85ffb82..40bd6031b 100644 --- a/test/lib/supply-path.test.js +++ b/test/lib/supply-path.test.js @@ -274,6 +274,33 @@ describe('fail-closed authoritative semantics', () => { assert.equal(evaluateSupplyPath(evidence).state, 'owner_attested'); } }); + it('rejects malformed host inline property grants', () => { + const evidence = input(); + const grant = evidence.hostManifest.authorized_agents[0]; + grant.authorization_type = 'inline_properties'; + delete grant.property_ids; + grant.properties = [{ property_id: 'hoststream_ctv' }]; + const result = evaluateSupplyPath(evidence); + assert.equal(result.state, 'owner_attested'); + assert.equal(result.legs.host_authorization.failure, 'property_scope_mismatch'); + }); + for (const [selection_type, field] of [ + ['by_id', 'property_ids'], + ['by_tag', 'property_tags'], + ]) { + it(`rejects malformed owner publisher_properties ${selection_type} elements`, () => { + const evidence = input(); + evidence.hostManifest.authorized_agents = []; + evidence.hostInventoryPartnerDomains = [OWNER]; + const grant = evidence.ownerManifest.authorized_agents[0]; + grant.authorization_type = 'publisher_properties'; + delete grant.property_ids; + grant.publisher_properties = [{ publisher_domain: OWNER, selection_type, [field]: [null] }]; + const result = evaluateSupplyPath(evidence); + assert.equal(result.state, 'owner_attested'); + assert.equal(result.legs.owner_agent_declared.failure, 'agent_not_declared_by_owner'); + }); + } it('checks identifier-only carriage against a resolvable host grant', () => { const evidence = input(); evidence.ownerManifest.collections[0].distribution[0] = { From da59d98a90ccab1a3f379ab45cc3e3fb8a52e0b7 Mon Sep 17 00:00:00 2001 From: Brian O'Kelley Date: Sat, 19 Sep 2026 10:32:30 +0000 Subject: [PATCH 12/21] fix(supply-path): close exact-head review gaps --- src/lib/core/AgentClient.ts | 13 +--- src/lib/core/AsyncHandler.ts | 11 +++ src/lib/core/SingleAgentClient.ts | 24 +++++- src/lib/index.ts | 1 + src/lib/supply-path/evaluate.ts | 101 +++++++++++++++----------- src/lib/supply-path/fetch-evidence.ts | 10 ++- src/lib/supply-path/index.ts | 1 + src/lib/supply-path/products.ts | 68 +++++++++++++---- test/lib/supply-path-types.test.js | 63 ++++++++++++++++ test/lib/supply-path.test.js | 48 ++++++++++++ 10 files changed, 273 insertions(+), 67 deletions(-) create mode 100644 test/lib/supply-path-types.test.js diff --git a/src/lib/core/AgentClient.ts b/src/lib/core/AgentClient.ts index e1eed2031..fceda914a 100644 --- a/src/lib/core/AgentClient.ts +++ b/src/lib/core/AgentClient.ts @@ -44,11 +44,11 @@ import type { import { assertNativeRequestProposalsTask, guardNativeRequestProposalsCompletion } from './request-proposals-guard'; import type { AdcpCapabilities } from '../utils/capabilities'; import type { WebhookHeaderValue } from '../webhooks'; +import type { ListProductsResponseWithSupplyPath } from '../supply-path'; import type { GetProductsRequest, GetProductsResponse, ListProductsRequest, - ListProductsResponse, RequestProposalsRequest, RequestProposalsResponse, DeclineProposalsRequest, @@ -212,7 +212,7 @@ export type V2AugmentedGetProductsResponse = CanonicalGetProductsResponse; */ export type TaskResponseTypeMap = { get_products: CanonicalGetProductsResponse; - list_products: ListProductsResponse; + list_products: ListProductsResponseWithSupplyPath; request_proposals: RequestProposalsResponse; refine_proposals: RefineProposalsResponse; decline_proposals: DeclineProposalsResponse; @@ -820,13 +820,8 @@ export class AgentClient { params: ListProductsRequest, inputHandler?: InputHandler, options?: TaskOptions - ): Promise> { - const result = await this.client.executeTask( - 'list_products', - params, - inputHandler, - this.withSession('list_products', options) - ); + ): Promise> { + const result = await this.client.listProducts(params, inputHandler, this.withSession('list_products', options)); this.retainSession(result); return result; } diff --git a/src/lib/core/AsyncHandler.ts b/src/lib/core/AsyncHandler.ts index bfc6d9d9f..1554007d1 100644 --- a/src/lib/core/AsyncHandler.ts +++ b/src/lib/core/AsyncHandler.ts @@ -69,6 +69,7 @@ import type { CanonicalGetProductsResponse, CanonicalListCreativesResponse, } from '../v2/projection/creative-delivery'; +import type { ListProductsResponseWithSupplyPath } from '../supply-path/products'; /** * Metadata provided with webhook responses @@ -166,6 +167,11 @@ export type GetProductsStatusChangeHandler = ( metadata: WebhookMetadata ) => void | Promise; +export type ListProductsStatusChangeHandler = ( + response: ListProductsResponseWithSupplyPath, + metadata: WebhookMetadata +) => void | Promise; + export type CreateMediaBuyStatusChangeHandler = ( response: CanonicalCreativeResponse< | CreateMediaBuyResponse @@ -263,6 +269,7 @@ export interface Activity { export interface AsyncHandlerConfig { // AdCP tool status change handlers - called for ALL status changes (completed, failed, working, input-required, submitted) onGetProductsStatusChange?: GetProductsStatusChangeHandler; + onListProductsStatusChange?: ListProductsStatusChangeHandler; onListCreativeFormatsLegacyStatusChange?: ( data: ListCreativeFormatsResponse, metadata: WebhookMetadata @@ -763,6 +770,10 @@ export class AsyncHandler { handler = this.config.onGetProductsStatusChange; break; + case 'list_products': + handler = this.config.onListProductsStatusChange; + break; + case 'list_creative_formats': handler = this.config.onListCreativeFormatsLegacyStatusChange; break; diff --git a/src/lib/core/SingleAgentClient.ts b/src/lib/core/SingleAgentClient.ts index 5e0f742aa..943782577 100644 --- a/src/lib/core/SingleAgentClient.ts +++ b/src/lib/core/SingleAgentClient.ts @@ -1,4 +1,8 @@ -import { annotateProductsSupplyPaths, type ProductSupplyPathOptions } from '../supply-path/products'; +import { + annotateProductsSupplyPaths, + type ListProductsResponseWithSupplyPath, + type ProductSupplyPathOptions, +} from '../supply-path/products'; // Main ADCP Client - Type-safe conversation-aware client for AdCP agents import { z } from 'zod'; @@ -20,6 +24,7 @@ import { isExternalSchemaRootActive, schemaAllowsTopLevelField } from '../valida import type { GetProductsRequest, GetProductsResponse, + ListProductsRequest, PropertyListReference, ListCreativeFormatsRequest, ListCreativeFormatsResponse, @@ -6149,6 +6154,21 @@ export class SingleAgentClient { ); } + /** Discover products through the compact AdCP 3.2 catalog task. */ + async listProducts( + params: ListProductsRequest, + inputHandler?: InputHandler, + options?: TaskOptions + ): Promise> { + return this.executeAndHandle( + 'list_products', + 'onListProductsStatusChange', + params, + inputHandler, + options + ); + } + /** @deprecated Explicit raw-wire escape hatch for migration tooling. */ async getProductsLegacy( params: GetProductsRequest, @@ -7337,6 +7357,8 @@ export class SingleAgentClient { switch (taskName) { case 'get_products': return this.getProducts(params as CanonicalGetProductsRequest, inputHandler, options); + case 'list_products': + return this.listProducts(params as ListProductsRequest, inputHandler, options); case 'create_media_buy': return (await this.createMediaBuy( params as MutatingRequestInput, diff --git a/src/lib/index.ts b/src/lib/index.ts index 3025aa90c..c16fd848e 100644 --- a/src/lib/index.ts +++ b/src/lib/index.ts @@ -622,6 +622,7 @@ export type { UpdateMediaBuyStatusChangeHandler, SyncCreativesStatusChangeHandler, GetProductsStatusChangeHandler, + ListProductsStatusChangeHandler, } from './core/AsyncHandler'; export { AsyncHandler, diff --git a/src/lib/supply-path/evaluate.ts b/src/lib/supply-path/evaluate.ts index d87899e09..0678f9475 100644 --- a/src/lib/supply-path/evaluate.ts +++ b/src/lib/supply-path/evaluate.ts @@ -73,46 +73,56 @@ const PROPERTY_IDENTIFIER_TYPES = new Set([ ]); const PROPERTY_CHANNELS = new Set(MediaChannelValues); +function isPropertyToken(value: unknown): value is string { + return typeof value === 'string' && /^[a-z0-9_]+$/.test(value); +} + +function isPropertyTokenList(value: unknown): value is string[] { + return Array.isArray(value) && value.length > 0 && value.every(isPropertyToken); +} + +function isOptionalUniqueList(value: unknown, valid: (item: unknown) => boolean): boolean { + return value === undefined || (Array.isArray(value) && value.every(valid) && new Set(value).size === value.length); +} + +/** A manifest property cannot authorize inventory unless its complete record is schema-shaped. */ +function isValidPropertyRecord(value: unknown): value is Record { + if ( + !record(value) || + typeof value.property_type !== 'string' || + !PROPERTY_TYPES.has(value.property_type) || + typeof value.name !== 'string' || + value.name.length === 0 || + !Array.isArray(value.identifiers) || + value.identifiers.length === 0 + ) { + return false; + } + if (value.property_id !== undefined && !isPropertyToken(value.property_id)) return false; + if (value.publisher_domain !== undefined && !domain(value.publisher_domain)) return false; + if ( + !isOptionalUniqueList(value.tags, isPropertyToken) || + !isOptionalUniqueList(value.supported_channels, item => typeof item === 'string' && PROPERTY_CHANNELS.has(item)) + ) { + return false; + } + return value.identifiers.every( + identifier => + record(identifier) && + typeof identifier.type === 'string' && + PROPERTY_IDENTIFIER_TYPES.has(identifier.type) && + typeof identifier.value === 'string' && + identifier.value.length > 0 + ); +} + /** A declaration is not evidence unless its property grant is complete and schema-shaped. */ function hasPropertyAuthorizationEnvelope(entry: Record): boolean { - const propertyToken = (value: unknown): value is string => typeof value === 'string' && /^[a-z0-9_]+$/.test(value); - const propertyTokens = (value: unknown): value is string[] => - Array.isArray(value) && value.length > 0 && value.every(propertyToken); - const optionalUniqueList = (value: unknown, valid: (item: unknown) => boolean): boolean => - value === undefined || (Array.isArray(value) && value.every(valid) && new Set(value).size === value.length); - const validInlineProperty = (value: unknown): boolean => { - if ( - !record(value) || - typeof value.property_type !== 'string' || - !PROPERTY_TYPES.has(value.property_type) || - typeof value.name !== 'string' || - !Array.isArray(value.identifiers) || - value.identifiers.length === 0 - ) { - return false; - } - if (value.property_id !== undefined && !propertyToken(value.property_id)) return false; - if (value.publisher_domain !== undefined && typeof value.publisher_domain !== 'string') return false; - if ( - !optionalUniqueList(value.tags, propertyToken) || - !optionalUniqueList(value.supported_channels, item => typeof item === 'string' && PROPERTY_CHANNELS.has(item)) - ) { - return false; - } - return value.identifiers.every( - identifier => - record(identifier) && - typeof identifier.type === 'string' && - PROPERTY_IDENTIFIER_TYPES.has(identifier.type) && - typeof identifier.value === 'string' - ); - }; - - if (entry.authorization_type === 'property_ids') return propertyTokens(entry.property_ids); - if (entry.authorization_type === 'property_tags') return propertyTokens(entry.property_tags); + if (entry.authorization_type === 'property_ids') return isPropertyTokenList(entry.property_ids); + if (entry.authorization_type === 'property_tags') return isPropertyTokenList(entry.property_tags); if (entry.authorization_type === 'inline_properties') { return ( - Array.isArray(entry.properties) && entry.properties.length > 0 && entry.properties.every(validInlineProperty) + Array.isArray(entry.properties) && entry.properties.length > 0 && entry.properties.every(isValidPropertyRecord) ); } if (entry.authorization_type === 'publisher_properties') { @@ -129,9 +139,9 @@ function hasPropertyAuthorizationEnvelope(entry: Record): boole const value = raw as Record; if ( (selector.selection_type === 'by_id' && - (!propertyTokens(value.property_ids) || value.property_tags !== undefined)) || + (!isPropertyTokenList(value.property_ids) || value.property_tags !== undefined)) || (selector.selection_type === 'by_tag' && - (!propertyTokens(value.property_tags) || value.property_ids !== undefined)) || + (!isPropertyTokenList(value.property_tags) || value.property_ids !== undefined)) || (selector.selection_type === 'all' && (value.property_ids !== undefined || value.property_tags !== undefined)) ) { return false; @@ -162,7 +172,9 @@ function propertyScope( if (entry.authorization_type === 'publisher_properties') { if (!Array.isArray(entry.publisher_properties) || entry.publisher_properties.length === 0) return new Set(); const properties = records(manifest.properties).filter( - p => (p.publisher_domain === undefined && !requirePublisher) || domain(p.publisher_domain) === host + p => + isValidPropertyRecord(p) && + ((p.publisher_domain === undefined && !requirePublisher) || domain(p.publisher_domain) === host) ); const ids = new Set(); try { @@ -207,7 +219,11 @@ function propertyScope( ); return new Set( result.properties - .filter(p => (p.publisher_domain === undefined && !requirePublisher) || domain(p.publisher_domain) === host) + .filter( + p => + isValidPropertyRecord(p) && + ((p.publisher_domain === undefined && !requirePublisher) || domain(p.publisher_domain) === host) + ) .map(p => p.property_id) .filter((id): id is string => typeof id === 'string' && id.length > 0) ); @@ -386,8 +402,9 @@ export function evaluateSupplyPath(input: SupplyPathInput): SupplyPathVerdict { } else { const properties = records(hostManifest.properties).filter( p => - (p.publisher_domain === undefined && !input.requireExplicitHostPublisherDomain) || - domain(p.publisher_domain) === host + isValidPropertyRecord(p) && + ((p.publisher_domain === undefined && !input.requireExplicitHostPublisherDomain) || + domain(p.publisher_domain) === host) ); const counts = new Map(); for (const property of properties) counts.set(property.property_id, (counts.get(property.property_id) ?? 0) + 1); diff --git a/src/lib/supply-path/fetch-evidence.ts b/src/lib/supply-path/fetch-evidence.ts index 9dd86442f..3b8291cb7 100644 --- a/src/lib/supply-path/fetch-evidence.ts +++ b/src/lib/supply-path/fetch-evidence.ts @@ -250,7 +250,10 @@ export class SupplyPathEvidenceSession { ); } catch (cause) { this.signal.throwIfAborted(); - throw new Error('Supply-path authority storage failed', { cause }); + throw new Error( + `Supply-path authority storage failed for ${publisher}; inspect error.cause and restore store availability or capacity without discarding existing pins`, + { cause } + ); } this.signal.throwIfAborted(); if (!accepted) @@ -272,7 +275,10 @@ export class SupplyPathEvidenceSession { ); } catch (cause) { this.signal.throwIfAborted(); - throw new Error('Supply-path revocation storage failed', { cause }); + throw new Error( + `Supply-path revocation storage failed for ${publisher}; inspect error.cause and restore store availability or capacity without discarding held revocations`, + { cause } + ); } this.signal.throwIfAborted(); // Persistence can add prior denials; it cannot erase current wire evidence. diff --git a/src/lib/supply-path/index.ts b/src/lib/supply-path/index.ts index 46bb09f39..05e38a07c 100644 --- a/src/lib/supply-path/index.ts +++ b/src/lib/supply-path/index.ts @@ -3,6 +3,7 @@ export { verifySupplyPath } from './verify'; export { evaluateSupplyPath, parseInventoryPartnerDomains, SUPPLY_PATH_STATES } from './evaluate'; export { annotateProductsSupplyPaths, + type ListProductsResponseWithSupplyPath, type ProductSupplyPathAnnotation, type ProductSupplyPathOptions, } from './products'; diff --git a/src/lib/supply-path/products.ts b/src/lib/supply-path/products.ts index f30c87b9a..71bd72468 100644 --- a/src/lib/supply-path/products.ts +++ b/src/lib/supply-path/products.ts @@ -1,4 +1,5 @@ import type { SinglePublisherPropertySelector } from '../discovery/types'; +import type { ListProductsResponse } from '../types'; import { verifySupplyPath, verifyAuthoritativeSupplyPath } from './verify'; import { SUPPLY_PATH_STATES, isUnqualifiedPropertySelector } from './evaluate'; import { boundedOption, SupplyPathEvidenceSession } from './fetch-evidence'; @@ -23,6 +24,9 @@ export interface ProductSupplyPathAnnotation { | { source: 'authoritative'; scope: 'product_properties'; paths: AuthoritativeSupplyPathResult[] } ) & { errors: string[] }; } +export type ListProductsResponseWithSupplyPath = Omit & { + products?: Array[number] & ProductSupplyPathAnnotation>; +}; export type ProductSupplyPathOptions = VerifySupplyPathOptions & { /** Maximum distinct paths in one discovery response. Default 64, max 256. */ maxPaths?: number; @@ -46,8 +50,17 @@ export async function annotateProductsSupplyPaths( options: ProductSupplyPathOptions = { source: 'authoritative' } ): Promise> { const maxPaths = boundedOption(options.maxPaths, 64, 256, 'maxPaths'); + const timeoutMs = boundedOption(options.timeoutMs, 15_000, 60_000, 'timeoutMs'); + if (options.source === 'authoritative') + boundedOption(options.maxBodyBytes, 256 * 1024, 20 * 1024 * 1024, 'maxBodyBytes'); + const deadlineAt = Date.now() + timeoutMs; + const checkPreprocessingBudget = (): void => { + options.signal?.throwIfAborted(); + if (Date.now() >= deadlineAt) throw new Error('Supply-path discovery deadline exceeded'); + }; const requests = new Map(); const selections = products.map(product => { + checkPreprocessingBudget(); const value = product as Record; const keys: string[] = []; const errors: string[] = []; @@ -71,11 +84,28 @@ export async function annotateProductsSupplyPaths( try { if (!value.publisher_properties.every(isUnqualifiedPropertySelector)) throw new Error('unsupported_product_selector_fields'); - const propertySelectors = value.publisher_properties.flatMap(raw => - expandPublisherPropertySelector(parsePublisherPropertySelector(raw)) - ); - const hosts = [...new Set(propertySelectors.map(s => s.publisher_domain))]; + const propertySelectorsByKey = new Map(); + let selectorExpansions = 0; + for (const raw of value.publisher_properties) { + checkPreprocessingBudget(); + selectorExpansions += Array.isArray(raw.publisher_domains) ? raw.publisher_domains.length : 1; + if (selectorExpansions > 4096) throw new Error('selector_work_limit_exceeded'); + for (const selector of expandPublisherPropertySelector(parsePublisherPropertySelector(raw))) { + propertySelectorsByKey.set(JSON.stringify(selector), selector); + } + } + const propertySelectors = [...propertySelectorsByKey.entries()] + .sort(([left], [right]) => left.localeCompare(right)) + .map(([, selector]) => selector); + const selectorsByHost = new Map(); + for (const selector of propertySelectors) { + const existing = selectorsByHost.get(selector.publisher_domain); + if (existing) existing.push(selector); + else selectorsByHost.set(selector.publisher_domain, [selector]); + } + const collectionIdsByOwner = new Map>(); for (const selector of value.collections) { + checkPreprocessingBudget(); if ( !record(selector) || !Object.keys(selector).every(key => ['publisher_domain', 'collection_ids'].includes(key)) || @@ -84,16 +114,24 @@ export async function annotateProductsSupplyPaths( ) throw new Error('invalid_collection_selector'); const owner = domain(selector.publisher_domain)!; - for (const host of hosts) { + let ids = collectionIdsByOwner.get(owner); + if (!ids) { + ids = new Set(); + collectionIdsByOwner.set(owner, ids); + } + for (const id of selector.collection_ids) ids.add(id); + } + for (const [owner, collectionIds] of collectionIdsByOwner) { + for (const [host, selectors] of selectorsByHost) { if (domain(host) === owner) continue; - for (const id of selector.collection_ids) { + for (const id of collectionIds) { + checkPreprocessingBudget(); const request = validateSupplyPathRequest({ owner_domain: owner, host_domain: host, agent_url: agentUrl, collection_id: id, }); - const selectors = propertySelectors.filter(s => s.publisher_domain === host); const key = JSON.stringify({ request, selectors }); if (!requests.has(key) && requests.size >= maxPaths) { if (!errors.includes('path_limit_exceeded')) errors.push('path_limit_exceeded'); @@ -113,18 +151,22 @@ export async function annotateProductsSupplyPaths( // Bound fan-out without allocating one network operation per product. const pending = [...requests.entries()]; let position = 0; - const timeoutMs = boundedOption(options.timeoutMs, 15_000, 60_000, 'timeoutMs'); + checkPreprocessingBudget(); const controller = new AbortController(); const onAbort = () => controller.abort(options.signal?.reason); options.signal?.addEventListener('abort', onAbort, { once: true }); if (options.signal?.aborted) onAbort(); - const timer = setTimeout(() => controller.abort(new Error('Supply-path discovery deadline exceeded')), timeoutMs); - const session = - options.source === 'authoritative' - ? new SupplyPathEvidenceSession({ ...options, signal: controller.signal }) - : undefined; + const timer = setTimeout( + () => controller.abort(new Error('Supply-path discovery deadline exceeded')), + Math.max(1, deadlineAt - Date.now()) + ); + let session: SupplyPathEvidenceSession | undefined; let onDeadline: () => void = () => {}; try { + session = + options.source === 'authoritative' + ? new SupplyPathEvidenceSession({ ...options, signal: controller.signal }) + : undefined; controller.signal.throwIfAborted(); const aborted = new Promise((_, reject) => { onDeadline = () => reject(controller.signal.reason); diff --git a/test/lib/supply-path-types.test.js b/test/lib/supply-path-types.test.js new file mode 100644 index 000000000..c3d2f5410 --- /dev/null +++ b/test/lib/supply-path-types.test.js @@ -0,0 +1,63 @@ +const { test } = require('node:test'); +const assert = require('node:assert/strict'); +const { spawnSync } = require('node:child_process'); +const fs = require('node:fs'); +const os = require('node:os'); +const path = require('node:path'); + +const repoRoot = path.join(__dirname, '..', '..'); + +test('listProducts and its status handler expose supply-path annotations', () => { + const fixtureDir = fs.mkdtempSync(path.join(os.tmpdir(), 'supply-path-types-')); + const fixturePath = path.join(fixtureDir, 'typecheck.ts'); + const importPath = path.relative(fixtureDir, path.join(repoRoot, 'dist/lib')).replace(/\\/g, '/'); + const modulePath = importPath.startsWith('.') ? importPath : `./${importPath}`; + + fs.writeFileSync( + fixturePath, + ` +import type { + AgentClient, + ListProductsResponseWithSupplyPath, + ListProductsStatusChangeHandler, +} from '${modulePath}'; + +type ListResult = Awaited>; +declare const result: ListResult; +declare const response: ListProductsResponseWithSupplyPath; + +if (result.success && result.status === 'completed') { + result.data.products?.[0]?.supply_path_verification?.paths; +} +response.products?.[0]?.supply_path_state; + +const handler: ListProductsStatusChangeHandler = async completed => { + completed.products?.[0]?.supply_path_verification?.errors; +}; +void handler; +` + ); + + try { + const compiled = spawnSync( + 'npx', + [ + 'tsc', + '--noEmit', + '--strict', + '--target', + 'ES2022', + '--module', + 'NodeNext', + '--moduleResolution', + 'NodeNext', + '--skipLibCheck', + fixturePath, + ], + { cwd: repoRoot, encoding: 'utf8', timeout: 30000 } + ); + assert.equal(compiled.status, 0, compiled.stderr || compiled.stdout); + } finally { + fs.rmSync(fixtureDir, { recursive: true, force: true }); + } +}); diff --git a/test/lib/supply-path.test.js b/test/lib/supply-path.test.js index 40bd6031b..3f842f1a7 100644 --- a/test/lib/supply-path.test.js +++ b/test/lib/supply-path.test.js @@ -284,6 +284,26 @@ describe('fail-closed authoritative semantics', () => { assert.equal(result.state, 'owner_attested'); assert.equal(result.legs.host_authorization.failure, 'property_scope_mismatch'); }); + for (const authorizationType of ['property_ids', 'property_tags', 'publisher_properties']) { + it(`rejects malformed top-level properties for ${authorizationType} grants`, () => { + const evidence = input(); + evidence.hostManifest.properties[0] = { + property_id: 'hoststream_ctv', + tags: ['ctv'], + }; + const grant = evidence.hostManifest.authorized_agents[0]; + grant.authorization_type = authorizationType; + delete grant.property_ids; + if (authorizationType === 'property_ids') grant.property_ids = ['hoststream_ctv']; + if (authorizationType === 'property_tags') grant.property_tags = ['ctv']; + if (authorizationType === 'publisher_properties') { + grant.publisher_properties = [{ publisher_domain: HOST, selection_type: 'all' }]; + } + const result = evaluateSupplyPath(evidence); + assert.equal(result.state, 'owner_attested'); + assert.equal(result.legs.owner_distribution_carriage.failure, 'property_ids_unresolved'); + }); + } for (const [selection_type, field] of [ ['by_id', 'property_ids'], ['by_tag', 'property_tags'], @@ -555,6 +575,34 @@ describe('registry wrapper and product discovery annotations', () => { assert.deepEqual(invalid[0].supply_path_verification.errors, ['invalid_product_selectors']); assert.deepEqual(await annotateProductsSupplyPaths([], AGENT), []); }); + it('deduplicates repeated selectors before path expansion', async () => { + const propertySelector = { publisher_domain: HOST, selection_type: 'all' }; + const collectionSelector = { publisher_domain: OWNER, collection_ids: ['retro_news', 'retro_news'] }; + const calls = []; + const [result] = await annotateProductsSupplyPaths( + [ + { + product_id: 'duplicate-selectors', + publisher_properties: Array.from({ length: 128 }, () => ({ ...propertySelector })), + collections: Array.from({ length: 128 }, () => ({ ...collectionSelector })), + }, + ], + AGENT, + { source: 'authoritative', trustedFetchFn: transport({}, calls) } + ); + assert.equal(result.supply_path_state, 'verified_owner_sold'); + assert.equal(result.supply_path_verification.paths.length, 1); + assert.equal(calls.length, 2); + }); + it('validates evidence-session options before allocating batch timers', async () => { + const before = process.getActiveResourcesInfo().filter(resource => resource === 'Timeout').length; + await assert.rejects( + annotateProductsSupplyPaths([], AGENT, { source: 'authoritative', maxBodyBytes: 0 }), + /maxBodyBytes/ + ); + const after = process.getActiveResourcesInfo().filter(resource => resource === 'Timeout').length; + assert.equal(after, before); + }); }); describe('bounded evidence and complete product scope', () => { From 41c969518fabc87274770a38207af0b0b3ab20d7 Mon Sep 17 00:00:00 2001 From: Brian O'Kelley Date: Sat, 19 Sep 2026 10:38:39 +0000 Subject: [PATCH 13/21] fix(supply-path): fail closed on unresolved scope --- src/lib/supply-path/fetch-evidence.ts | 2 +- src/lib/supply-path/index.ts | 1 + src/lib/supply-path/products.ts | 10 +++--- src/lib/supply-path/validation.ts | 52 +++++++++++++++------------ src/lib/supply-path/verify.ts | 32 ++++++++++++----- test/lib/supply-path-types.test.js | 10 ++++++ test/lib/supply-path.test.js | 24 +++++++++++++ 7 files changed, 96 insertions(+), 35 deletions(-) diff --git a/src/lib/supply-path/fetch-evidence.ts b/src/lib/supply-path/fetch-evidence.ts index 3b8291cb7..da5728ba2 100644 --- a/src/lib/supply-path/fetch-evidence.ts +++ b/src/lib/supply-path/fetch-evidence.ts @@ -258,7 +258,7 @@ export class SupplyPathEvidenceSession { this.signal.throwIfAborted(); if (!accepted) throw new TypeError( - `Authoritative location changed for ${publisher} to ${location}; independently confirm the publisher migration before updating its pin` + `Authoritative location changed for ${publisher}; independently confirm the publisher migration before updating its pin` ); } private async readAndRemember(publisher: string): Promise { diff --git a/src/lib/supply-path/index.ts b/src/lib/supply-path/index.ts index 05e38a07c..23289e34b 100644 --- a/src/lib/supply-path/index.ts +++ b/src/lib/supply-path/index.ts @@ -3,6 +3,7 @@ export { verifySupplyPath } from './verify'; export { evaluateSupplyPath, parseInventoryPartnerDomains, SUPPLY_PATH_STATES } from './evaluate'; export { annotateProductsSupplyPaths, + type AnnotatedSupplyPathProduct, type ListProductsResponseWithSupplyPath, type ProductSupplyPathAnnotation, type ProductSupplyPathOptions, diff --git a/src/lib/supply-path/products.ts b/src/lib/supply-path/products.ts index 71bd72468..f489df0d1 100644 --- a/src/lib/supply-path/products.ts +++ b/src/lib/supply-path/products.ts @@ -24,8 +24,10 @@ export interface ProductSupplyPathAnnotation { | { source: 'authoritative'; scope: 'product_properties'; paths: AuthoritativeSupplyPathResult[] } ) & { errors: string[] }; } +export type AnnotatedSupplyPathProduct = Omit & + ProductSupplyPathAnnotation; export type ListProductsResponseWithSupplyPath = Omit & { - products?: Array[number] & ProductSupplyPathAnnotation>; + products?: Array[number]>>; }; export type ProductSupplyPathOptions = VerifySupplyPathOptions & { /** Maximum distinct paths in one discovery response. Default 64, max 256. */ @@ -48,7 +50,7 @@ export async function annotateProductsSupplyPaths( products: readonly T[], agentUrl: string, options: ProductSupplyPathOptions = { source: 'authoritative' } -): Promise> { +): Promise>> { const maxPaths = boundedOption(options.maxPaths, 64, 256, 'maxPaths'); const timeoutMs = boundedOption(options.timeoutMs, 15_000, 60_000, 'timeoutMs'); if (options.source === 'authoritative') @@ -205,7 +207,7 @@ export async function annotateProductsSupplyPaths( void _state; void _verification; const { keys, errors } = selections[index]!; - if (!keys.length && !errors.length) return rest as T & ProductSupplyPathAnnotation; + if (!keys.length && !errors.length) return rest as AnnotatedSupplyPathProduct; const paths = keys.map(key => outcomes.get(key)!); const state = errors.length ? 'unverified' @@ -223,6 +225,6 @@ export async function annotateProductsSupplyPaths( paths, errors, }, - } as T & ProductSupplyPathAnnotation; + } as AnnotatedSupplyPathProduct; }); } diff --git a/src/lib/supply-path/validation.ts b/src/lib/supply-path/validation.ts index 8ec5ab881..2a1ef7feb 100644 --- a/src/lib/supply-path/validation.ts +++ b/src/lib/supply-path/validation.ts @@ -48,45 +48,50 @@ export function assertRegistrySupplyPathResult( value: unknown, request: SupplyPathRequest ): asserts value is import('./types').RegistrySupplyPathResult { - const fail = (): never => { - throw new TypeError('Invalid registry supply-path response'); + const fail = (invariant: string): never => { + throw new TypeError( + `Invalid registry supply-path response: ${invariant}; verification cannot be accepted, check the registry response contract` + ); }; - if (!record(value)) return fail(); + if (!record(value)) return fail('response must be an object'); if (value.semantics_version !== '1') throw new TypeError('Invalid registry supply-path response: semantics_version 1 required; upgrade the registry'); - if (!record(value.legs) || !record(value.sources)) return fail(); + if (!record(value.legs) || !record(value.sources)) return fail('legs and sources must be objects'); if (!['verified_owner_sold', 'host_delegated', 'owner_attested', 'unverified'].includes(String(value.state))) - return fail(); + return fail('state is not recognized'); if ( domain(value.owner_domain) !== request.owner_domain || domain(value.host_domain) !== request.host_domain || agentIdentity(value.agent_url) !== agentIdentity(request.agent_url) || value.collection_id !== request.collection_id ) - return fail(); + return fail('request identity does not match the submitted owner, host, agent, and collection'); if ( typeof value.checked_at !== 'string' || !Number.isFinite(Date.parse(value.checked_at)) || typeof value.sources.cached !== 'boolean' ) - return fail(); + return fail('checked_at or sources.cached provenance is malformed'); for (const key of ['owner_adagents_url', 'host_adagents_url']) { - if (typeof value.sources[key] !== 'string') return fail(); + if (typeof value.sources[key] !== 'string') return fail(`sources.${key} must be an HTTPS URL`); try { const url = new URL(value.sources[key]); - if (url.protocol !== 'https:' || url.username || url.password) return fail(); + if (url.protocol !== 'https:' || url.username || url.password) + return fail(`sources.${key} must be an HTTPS URL without credentials`); } catch { - return fail(); + return fail(`sources.${key} must be a valid URL`); } } for (const key of ['owner_fetched_at', 'host_fetched_at']) { const timestamp = value.sources[key]; - if (timestamp !== null && (typeof timestamp !== 'string' || !Number.isFinite(Date.parse(timestamp)))) return fail(); + if (timestamp !== null && (typeof timestamp !== 'string' || !Number.isFinite(Date.parse(timestamp)))) + return fail(`sources.${key} must be null or a valid timestamp`); } for (const key of ['owner_resolved_url', 'host_resolved_url']) { const location = value.sources[key]; if (location === null) continue; - if (typeof location !== 'string' || location.length > 8192) return fail(); + if (typeof location !== 'string' || location.length > 8192) + return fail(`sources.${key} must be null or a bounded HTTPS URL`); try { const parsed = new URL(location); if ( @@ -96,9 +101,9 @@ export function assertRegistrySupplyPathResult( parsed.hash || (parsed.port && parsed.port !== '443') ) - return fail(); + return fail(`sources.${key} must be an HTTPS URL without credentials, fragments, or nonstandard ports`); } catch { - return fail(); + return fail(`sources.${key} must be a valid URL`); } } const legNames = [ @@ -111,11 +116,12 @@ export function assertRegistrySupplyPathResult( for (const key of legNames) { const leg = value.legs[key]; if (!record(leg) || typeof leg.ok !== 'boolean' || (leg.detail !== undefined && typeof leg.detail !== 'string')) - return fail(); - if (leg.ok ? leg.failure !== undefined : typeof leg.failure !== 'string' || !leg.failure.length) return fail(); + return fail(`legs.${key} is malformed`); + if (leg.ok ? leg.failure !== undefined : typeof leg.failure !== 'string' || !leg.failure.length) + return fail(`legs.${key} has an inconsistent ok/failure pair`); for (const ids of ['property_ids_matched', 'property_ids_unmatched']) { if (leg[ids] !== undefined && (!Array.isArray(leg[ids]) || !leg[ids].every(id => typeof id === 'string'))) - return fail(); + return fail(`legs.${key}.${ids} must contain only string property IDs`); } } const ok = (key: string) => (value.legs as Record>)[key]?.ok === true; @@ -126,19 +132,21 @@ export function assertRegistrySupplyPathResult( value.resolved_collection_id.length > 256 || (request.collection_id !== undefined && value.resolved_collection_id !== request.collection_id) ) - return fail(); - } else if (value.resolved_collection_id !== undefined) return fail(); + return fail('resolved_collection_id is missing, malformed, or inconsistent with the request'); + } else if (value.resolved_collection_id !== undefined) + return fail('resolved_collection_id requires a successful owner collection leg'); // Check the registry's documented ladder; do not silently recompute a remote // verdict using assumptions about evidence that was not returned. if ( value.state === 'verified_owner_sold' && !(ok('owner_collection_declared') && ok('owner_distribution_carriage') && ok('host_authorization')) ) - return fail(); + return fail('verified_owner_sold is inconsistent with its required successful legs'); if ( value.state === 'host_delegated' && !(ok('owner_collection_declared') && ok('owner_agent_declared') && ok('inventory_partner_domain')) ) - return fail(); - if (value.state === 'owner_attested' && !ok('owner_collection_declared')) return fail(); + return fail('host_delegated is inconsistent with its required successful legs'); + if (value.state === 'owner_attested' && !ok('owner_collection_declared')) + return fail('owner_attested requires a successful owner collection leg'); } diff --git a/src/lib/supply-path/verify.ts b/src/lib/supply-path/verify.ts index 9b96ba9c7..03a2815ae 100644 --- a/src/lib/supply-path/verify.ts +++ b/src/lib/supply-path/verify.ts @@ -22,6 +22,24 @@ import type { AuthoritativeSupplyPathResult, } from './types'; +/** + * Verify one owner/host/agent path. Authoritative mode (the default) fetches + * live publisher evidence; registry mode validates a remote cached verdict. + * Invalid evidence rejects or returns a fail-closed verdict—it is never + * converted into synthetic authorization. + * + * @example + * ```ts + * const verdict = await verifySupplyPath({ + * owner_domain: 'owner.example', + * host_domain: 'host.example', + * agent_url: 'https://sales.example', + * collection_id: 'news', + * }); + * ``` + * + * @see docs/guides/SUPPLY-PATH-VERIFICATION.md + */ export function verifySupplyPath( request: SupplyPathRequest, options: RegistrySupplyPathOptions @@ -34,7 +52,6 @@ export function verifySupplyPath( request: SupplyPathRequest, options: VerifySupplyPathOptions ): Promise; -/** Verify a single owner/host/agent path. Defaults to live authoritative evidence. */ export async function verifySupplyPath( request: SupplyPathRequest, options: VerifySupplyPathOptions = { source: 'authoritative' } @@ -108,14 +125,13 @@ export async function verifyAuthoritativeSupplyPath( throw new TypeError('Invalid product property tags'); let matched = false; for (const property of properties) { - if (typeof property.property_id !== 'string') continue; - if ( + const selected = single.selection_type === 'all' || - (strings(property.tags) && property.tags.some(tag => single.property_tags.includes(tag))) - ) { - ids.add(property.property_id); - matched = true; - } + (strings(property.tags) && property.tags.some(tag => single.property_tags.includes(tag))); + if (!selected) continue; + matched = true; + if (typeof property.property_id !== 'string' || !property.property_id.length) unresolved = true; + else ids.add(property.property_id); } if (!matched) unresolved = true; } diff --git a/test/lib/supply-path-types.test.js b/test/lib/supply-path-types.test.js index c3d2f5410..3fc84bb8c 100644 --- a/test/lib/supply-path-types.test.js +++ b/test/lib/supply-path-types.test.js @@ -20,7 +20,9 @@ import type { AgentClient, ListProductsResponseWithSupplyPath, ListProductsStatusChangeHandler, + SupplyPathState, } from '${modulePath}'; +import { annotateProductsSupplyPaths } from '${modulePath}'; type ListResult = Awaited>; declare const result: ListResult; @@ -34,6 +36,14 @@ response.products?.[0]?.supply_path_state; const handler: ListProductsStatusChangeHandler = async completed => { completed.products?.[0]?.supply_path_verification?.errors; }; +const replaced = annotateProductsSupplyPaths( + [{ product_id: 'seller-authored', supply_path_state: 'verified_owner_sold' as const }], + 'https://sales.example' +); +replaced.then(products => { + const state: SupplyPathState | undefined = products[0]?.supply_path_state; + void state; +}); void handler; ` ); diff --git a/test/lib/supply-path.test.js b/test/lib/supply-path.test.js index 3f842f1a7..4ed61e98e 100644 --- a/test/lib/supply-path.test.js +++ b/test/lib/supply-path.test.js @@ -708,6 +708,30 @@ describe('bounded evidence and complete product scope', () => { }); assert.equal(result.state, 'owner_attested'); }); + for (const selectionType of ['all', 'by_tag']) { + it(`fails closed when a ${selectionType} selector includes a property without property_id`, async () => { + const fixture = input(); + fixture.hostManifest.properties[0].tags = ['selected']; + fixture.hostManifest.properties.push({ + property_type: 'website', + name: 'Unaddressable property', + identifiers: [{ type: 'domain', value: 'extra.example' }], + tags: ['selected'], + }); + const selector = { + publisher_domain: HOST, + selection_type: selectionType, + ...(selectionType === 'by_tag' ? { property_tags: ['selected'] } : {}), + }; + const result = await verifySupplyPath(request, { + source: 'authoritative', + trustedFetchFn: transport({ [`https://${HOST}/.well-known/adagents.json`]: fixture.hostManifest }), + propertySelectors: [selector], + }); + assert.equal(result.state, 'owner_attested'); + assert.equal(result.legs.host_authorization.failure, 'property_scope_mismatch'); + }); + } it('holds revocations across refreshes and scopes them to the publisher authority', async () => { const revocationStore = new sdk.InMemorySupplyPathRevocationStore(); const revoked = input().hostManifest; From e3131bbdc3c38c7a7b3517003cfa039775086b22 Mon Sep 17 00:00:00 2001 From: Brian O'Kelley Date: Sat, 19 Sep 2026 10:49:09 +0000 Subject: [PATCH 14/21] fix(supply-path): validate selector predicates --- src/lib/core/SingleAgentClient.ts | 29 ++++++++------ src/lib/supply-path/evaluate.ts | 16 ++++++++ src/lib/supply-path/fetch-evidence.ts | 4 +- src/lib/supply-path/products.ts | 20 +++++++--- src/lib/supply-path/verify.ts | 13 +++++-- .../product-property-policy-client.test.js | 35 +++++++++++++++++ test/lib/supply-path.test.js | 38 ++++++++++++++++++- 7 files changed, 132 insertions(+), 23 deletions(-) diff --git a/src/lib/core/SingleAgentClient.ts b/src/lib/core/SingleAgentClient.ts index 943782577..95c8de761 100644 --- a/src/lib/core/SingleAgentClient.ts +++ b/src/lib/core/SingleAgentClient.ts @@ -4779,7 +4779,7 @@ export class SingleAgentClient { this.rememberProductPolicyRequestParams(taskType, context.productPolicyRequest, result, resumedOptions); } this.rememberLegacyFormatConverter(taskType, finalizerLegacyFormatConverter, result, resumedOptions); - result = await this.applyProductPropertyPolicy(result, taskType, context.productPolicyRequest); + result = await this.applyProductPropertyPolicy(result, taskType, context.productPolicyRequest, options?.signal); throwIfAborted(options?.signal); if (context.canonical) { @@ -5332,7 +5332,8 @@ export class SingleAgentClient { private async applyProductPropertyPolicy( result: TaskResult, taskType: string, - requestParams: Record + requestParams: Record, + taskSignal?: AbortSignal ): Promise> { // Reject non-transactable products (no pricing_options) before any // property-policy evaluation, regardless of whether a property policy is @@ -5348,11 +5349,13 @@ export class SingleAgentClient { ) { const data = result.data as { products?: object[] }; if (Array.isArray(data.products)) { - const products = await annotateProductsSupplyPaths( - data.products, - this.agent.agent_uri, - this.config.validation.supplyPathVerification - ); + const configured = this.config.validation.supplyPathVerification; + const signals = [configured.signal, taskSignal].filter((signal): signal is AbortSignal => signal !== undefined); + const signal = signals.length > 1 ? AbortSignal.any(signals) : signals[0]; + const products = await annotateProductsSupplyPaths(data.products, this.agent.agent_uri, { + ...configured, + ...(signal ? { signal } : {}), + }); result = { ...result, data: { ...result.data, products } }; } } @@ -5668,7 +5671,8 @@ export class SingleAgentClient { return await this.applyProductPropertyPolicyToTaskInfo( taskInfo, taskType, - (policyState.request ?? {}) as Record + (policyState.request ?? {}) as Record, + options?.signal ); } finally { if (terminal) { @@ -5687,7 +5691,8 @@ export class SingleAgentClient { return await this.applyProductPropertyPolicy( completed, taskType, - (policyState.request ?? {}) as Record + (policyState.request ?? {}) as Record, + signal ?? options?.signal ); } finally { if (terminal) { @@ -5708,7 +5713,8 @@ export class SingleAgentClient { private async applyProductPropertyPolicyToTaskInfo( taskInfo: TaskInfo, taskType: string, - requestParams: Record + requestParams: Record, + taskSignal?: AbortSignal ): Promise { if ( (taskType !== 'get_products' && @@ -5735,7 +5741,8 @@ export class SingleAgentClient { debug_logs: [], }), taskType, - requestParams + requestParams, + taskSignal ); if (policyResult.success) { diff --git a/src/lib/supply-path/evaluate.ts b/src/lib/supply-path/evaluate.ts index 0678f9475..6e2ed42b7 100644 --- a/src/lib/supply-path/evaluate.ts +++ b/src/lib/supply-path/evaluate.ts @@ -238,6 +238,22 @@ export function isUnqualifiedPropertySelector(value: unknown): boolean { ); } +/** Reject predicates that conflict with the selector discriminator. */ +export function hasValidPropertySelectorPredicate(value: unknown): boolean { + if (!isUnqualifiedPropertySelector(value)) return false; + try { + const selector = parsePublisherPropertySelector(value); + const raw = value as Record; + if (selector.selection_type === 'by_id') + return isPropertyTokenList(raw.property_ids) && raw.property_tags === undefined; + if (selector.selection_type === 'by_tag') + return isPropertyTokenList(raw.property_tags) && raw.property_ids === undefined; + return raw.property_ids === undefined && raw.property_tags === undefined; + } catch { + return false; + } +} + const UNDERSTOOD_GRANT_FIELDS = new Set([ 'url', 'authorized_for', diff --git a/src/lib/supply-path/fetch-evidence.ts b/src/lib/supply-path/fetch-evidence.ts index da5728ba2..e667bade9 100644 --- a/src/lib/supply-path/fetch-evidence.ts +++ b/src/lib/supply-path/fetch-evidence.ts @@ -164,7 +164,9 @@ export class SupplyPathEvidenceSession { const denials = parseRevocations(document.revoked_publisher_domains); if (denials === null) { this.documentError(publisher, response, 'invalid_revocations'); - throw new TypeError('Invalid publisher revocation evidence'); + throw new TypeError( + `Invalid revoked_publisher_domains in adagents.json for ${publisher}; verification refused, correct the publisher's revocation declaration` + ); } // Denials survive invalid affirmative envelopes and failed/chained pointers. this.observedRevocations.set(publisher, [...(this.observedRevocations.get(publisher) ?? []), ...denials]); diff --git a/src/lib/supply-path/products.ts b/src/lib/supply-path/products.ts index f489df0d1..5db3c6263 100644 --- a/src/lib/supply-path/products.ts +++ b/src/lib/supply-path/products.ts @@ -1,9 +1,9 @@ import type { SinglePublisherPropertySelector } from '../discovery/types'; import type { ListProductsResponse } from '../types'; import { verifySupplyPath, verifyAuthoritativeSupplyPath } from './verify'; -import { SUPPLY_PATH_STATES, isUnqualifiedPropertySelector } from './evaluate'; +import { SUPPLY_PATH_STATES, hasValidPropertySelectorPredicate } from './evaluate'; import { boundedOption, SupplyPathEvidenceSession } from './fetch-evidence'; -import { domain, record, strings, validateSupplyPathRequest } from './validation'; +import { agentIdentity, domain, record, strings, validateSupplyPathRequest } from './validation'; import { parsePublisherPropertySelector, expandPublisherPropertySelector, @@ -51,6 +51,7 @@ export async function annotateProductsSupplyPaths( agentUrl: string, options: ProductSupplyPathOptions = { source: 'authoritative' } ): Promise>> { + if (!agentIdentity(agentUrl)) throw new TypeError('agentUrl must be an HTTPS URL without credentials'); const maxPaths = boundedOption(options.maxPaths, 64, 256, 'maxPaths'); const timeoutMs = boundedOption(options.timeoutMs, 15_000, 60_000, 'timeoutMs'); if (options.source === 'authoritative') @@ -84,8 +85,8 @@ export async function annotateProductsSupplyPaths( return { keys, errors: ['invalid_product_selectors'] }; } try { - if (!value.publisher_properties.every(isUnqualifiedPropertySelector)) - throw new Error('unsupported_product_selector_fields'); + if (!value.publisher_properties.every(hasValidPropertySelectorPredicate)) + throw new Error('invalid_product_selector_predicate'); const propertySelectorsByKey = new Map(); let selectorExpansions = 0; for (const raw of value.publisher_properties) { @@ -144,8 +145,15 @@ export async function annotateProductsSupplyPaths( } } } - } catch { - errors.push('invalid_product_selectors'); + } catch (cause) { + const code = cause instanceof Error ? cause.message : ''; + errors.push( + ['invalid_product_selector_predicate', 'selector_work_limit_exceeded', 'invalid_collection_selector'].includes( + code + ) + ? code + : 'invalid_product_selectors' + ); } return { keys, errors }; }); diff --git a/src/lib/supply-path/verify.ts b/src/lib/supply-path/verify.ts index 03a2815ae..72e6fa658 100644 --- a/src/lib/supply-path/verify.ts +++ b/src/lib/supply-path/verify.ts @@ -8,6 +8,7 @@ import { RegistryClient } from '../registry'; import { SupplyPathEvidenceSession } from './fetch-evidence'; import { isUnqualifiedPropertySelector, + hasValidPropertySelectorPredicate, evaluateSupplyPath, supplyPathAdsTxtPolicy, parseInventoryPartnerDomains, @@ -79,6 +80,15 @@ export async function verifyAuthoritativeSupplyPath( options: AuthoritativeSupplyPathOptions, session: SupplyPathEvidenceSession ): Promise { + if (options.propertySelectors !== undefined) { + if (!Array.isArray(options.propertySelectors) || !options.propertySelectors.length) + throw new TypeError('propertySelectors must be non-empty'); + for (const raw of options.propertySelectors) { + if (!isUnqualifiedPropertySelector(raw)) throw new TypeError('Unsupported product property selector fields'); + if (!hasValidPropertySelectorPredicate(raw)) + throw new TypeError('Product property selector predicate conflicts with selection_type'); + } + } const [ownerManifest, hostManifest] = await Promise.all([ session.adagents(normalized.owner_domain), session.adagents(normalized.host_domain), @@ -102,8 +112,6 @@ export async function verifyAuthoritativeSupplyPath( }; const scopedInput: typeof input & { requiredHostPropertyIds?: string[] } = input; if (options.propertySelectors !== undefined) { - if (!Array.isArray(options.propertySelectors) || !options.propertySelectors.length) - throw new TypeError('propertySelectors must be non-empty'); const ids = new Set(); const properties = records(hostManifest?.properties).filter( p => @@ -112,7 +120,6 @@ export async function verifyAuthoritativeSupplyPath( ); let unresolved = false; for (const raw of options.propertySelectors) { - if (!isUnqualifiedPropertySelector(raw)) throw new TypeError('Unsupported product property selector fields'); const selector = parsePublisherPropertySelector(raw); for (const single of expandPublisherPropertySelector(selector)) { if (domain(single.publisher_domain) !== normalized.host_domain) diff --git a/test/lib/product-property-policy-client.test.js b/test/lib/product-property-policy-client.test.js index bc007ae76..8000db47e 100644 --- a/test/lib/product-property-policy-client.test.js +++ b/test/lib/product-property-policy-client.test.js @@ -659,6 +659,41 @@ describe('client product property policy enforcement', () => { }); describe('supply-path annotations across discovery completion paths', () => { + test('caller cancellation aborts authoritative evidence retrieval', async () => { + const product = makeProduct('owner-sold', 'host.example', { + collections: [{ publisher_domain: 'owner.example', collection_ids: ['channel'] }], + }); + let started; + const evidenceStarted = new Promise(resolve => { + started = resolve; + }); + let evidenceSignal; + const agent = makeClient({ + validation: { + supplyPathVerification: { + source: 'authoritative', + trustedFetchFn: async (_url, init) => { + evidenceSignal = init.signal; + started(); + return await new Promise((_resolve, reject) => { + init.signal.addEventListener('abort', () => reject(init.signal.reason), { once: true }); + }); + }, + }, + }, + }); + ProtocolClient.callTool = async () => ({ status: 'completed', products: [product], cache_scope: 'public' }); + const controller = new AbortController(); + const pending = agent.getProducts({ brief: 'sports' }, undefined, { + project: false, + signal: controller.signal, + }); + await evidenceStarted; + controller.abort(new Error('caller cancelled')); + await assert.rejects(pending, /caller cancelled/); + assert.strictEqual(evidenceSignal.aborted, true); + }); + for (const taskName of ['get_products', 'list_products']) { test(`${taskName} annotates immediate, polled, and webhook products before publication`, async () => { const products = [ diff --git a/test/lib/supply-path.test.js b/test/lib/supply-path.test.js index 4ed61e98e..c9100b6f3 100644 --- a/test/lib/supply-path.test.js +++ b/test/lib/supply-path.test.js @@ -572,9 +572,43 @@ describe('registry wrapper and product discovery annotations', () => { AGENT ); assert.equal(invalid[0].supply_path_state, 'unverified'); - assert.deepEqual(invalid[0].supply_path_verification.errors, ['invalid_product_selectors']); + assert.deepEqual(invalid[0].supply_path_verification.errors, ['invalid_collection_selector']); assert.deepEqual(await annotateProductsSupplyPaths([], AGENT), []); }); + it('rejects predicates that conflict with selection_type before evidence retrieval', async () => { + const conflicting = { + publisher_domain: HOST, + selection_type: 'all', + property_ids: ['unapproved_property'], + }; + await assert.rejects( + verifySupplyPath(request, { + source: 'authoritative', + propertySelectors: [conflicting], + trustedFetchFn: () => { + throw new Error('unexpected fetch'); + }, + }), + /conflicts with selection_type/ + ); + const calls = []; + const [annotated] = await annotateProductsSupplyPaths( + [ + { + product_id: 'conflicting-selector', + publisher_properties: [conflicting], + collections: [{ publisher_domain: OWNER, collection_ids: ['retro_news'] }], + }, + ], + AGENT, + { source: 'authoritative', trustedFetchFn: transport({}, calls) } + ); + assert.deepEqual(annotated.supply_path_verification.errors, ['invalid_product_selector_predicate']); + assert.equal(calls.length, 0); + }); + it('reports an invalid agent URL independently of product selectors', async () => { + await assert.rejects(annotateProductsSupplyPaths([], 'not-a-url'), /agentUrl must be an HTTPS URL/); + }); it('deduplicates repeated selectors before path expansion', async () => { const propertySelector = { publisher_domain: HOST, selection_type: 'all' }; const collectionSelector = { publisher_domain: OWNER, collection_ids: ['retro_news', 'retro_news'] }; @@ -905,7 +939,7 @@ it('does not turn a malformed revocation list containing a valid denial into hos }), }), }), - /Invalid publisher revocation evidence/ + /Invalid revoked_publisher_domains in adagents\.json for hoststream\.example/ ); }); From d877a794c7912b2f4ebb1440e36f1fe2530982c5 Mon Sep 17 00:00:00 2001 From: Brian O'Kelley Date: Sat, 19 Sep 2026 10:56:05 +0000 Subject: [PATCH 15/21] fix(supply-path): bound retained authority state --- src/lib/core/SingleAgentClient.ts | 14 ++++-- src/lib/supply-path/fetch-evidence.ts | 1 + src/lib/supply-path/products.ts | 8 +++- src/lib/supply-path/revocations.ts | 7 +++ .../product-property-policy-client.test.js | 44 +++++++++++++++++++ test/lib/supply-path-types.test.js | 5 +++ test/lib/supply-path.test.js | 20 +++++++++ 7 files changed, 93 insertions(+), 6 deletions(-) diff --git a/src/lib/core/SingleAgentClient.ts b/src/lib/core/SingleAgentClient.ts index 95c8de761..4e89f4a70 100644 --- a/src/lib/core/SingleAgentClient.ts +++ b/src/lib/core/SingleAgentClient.ts @@ -4836,14 +4836,20 @@ export class SingleAgentClient { if (result.submitted && rawSubmittedWaitForCompletion) { result.submitted = { ...result.submitted, - waitForCompletion: async (pollInterval, signal) => - this.finalizeTaskResult( + waitForCompletion: async (pollInterval, signal) => { + const signals = [options?.signal, signal].filter( + (candidate): candidate is AbortSignal => candidate !== undefined + ); + const completionSignal = signals.length > 1 ? AbortSignal.any(signals) : signals[0]; + const completionOptions = { ...(options ?? {}), ...(completionSignal ? { signal: completionSignal } : {}) }; + return this.finalizeTaskResult( await rawSubmittedWaitForCompletion(pollInterval, signal), context, - options, + completionOptions, transformCompletedResponse, finalizerLegacyFormatConverter - ), + ); + }, }; } diff --git a/src/lib/supply-path/fetch-evidence.ts b/src/lib/supply-path/fetch-evidence.ts index e667bade9..e623f7362 100644 --- a/src/lib/supply-path/fetch-evidence.ts +++ b/src/lib/supply-path/fetch-evidence.ts @@ -196,6 +196,7 @@ export class SupplyPathEvidenceSession { const target = manifest.authoritative_location ?? manifest.superseded_by; if ( typeof target !== 'string' || + target.length > 8192 || (manifest.authoritative_location !== undefined && (manifest.authorized_agents !== undefined || manifest.superseded_by !== undefined)) ) { diff --git a/src/lib/supply-path/products.ts b/src/lib/supply-path/products.ts index 5db3c6263..2e56c5cf2 100644 --- a/src/lib/supply-path/products.ts +++ b/src/lib/supply-path/products.ts @@ -13,7 +13,8 @@ import type { SupplyPathState, RegistrySupplyPathResult, AuthoritativeSupplyPathResult, - VerifySupplyPathOptions, + RegistrySupplyPathOptions, + AuthoritativeSupplyPathOptions, } from './types'; export interface ProductSupplyPathAnnotation { @@ -29,7 +30,10 @@ export type AnnotatedSupplyPathProduct = Omit & { products?: Array[number]>>; }; -export type ProductSupplyPathOptions = VerifySupplyPathOptions & { +type ProductSupplyPathVerificationOptions = + | RegistrySupplyPathOptions + | Omit; +export type ProductSupplyPathOptions = ProductSupplyPathVerificationOptions & { /** Maximum distinct paths in one discovery response. Default 64, max 256. */ maxPaths?: number; /** Overall batch deadline, including all paths. Default 15 seconds, max 60 seconds. */ diff --git a/src/lib/supply-path/revocations.ts b/src/lib/supply-path/revocations.ts index a1f0185ae..9e006e898 100644 --- a/src/lib/supply-path/revocations.ts +++ b/src/lib/supply-path/revocations.ts @@ -110,10 +110,12 @@ export class InMemorySupplyPathAuthorityStore implements SupplyPathAuthorityStor private readonly admission = new AuthorityAdmissionBudget(); private readonly locations = new Map(); async check(publisherDomain: string, location: string): Promise { + this.assertBoundedLocation(location); const pinned = this.locations.get(publisherDomain); return pinned === undefined || pinned === location; } async observe(publisherDomain: string, location: string): Promise { + this.assertBoundedLocation(location); const pinned = this.locations.get(publisherDomain); if (pinned !== undefined) return pinned === location; if (this.locations.size >= 10000) throw new Error('Supply-path authority store capacity exceeded'); @@ -123,10 +125,15 @@ export class InMemorySupplyPathAuthorityStore implements SupplyPathAuthorityStor } /** Call only after independently confirming a publisher's migration. Never call from an automatic retry. */ approveChange(publisherDomain: string, location: string): void { + this.assertBoundedLocation(location); if (!this.locations.has(publisherDomain) && this.locations.size >= 10000) throw new Error('Supply-path authority store capacity exceeded'); if (!this.locations.has(publisherDomain)) this.admission.consume(); this.locations.set(publisherDomain, location); } + private assertBoundedLocation(location: string): void { + if (typeof location !== 'string' || location.length === 0 || location.length > 8192) + throw new TypeError('Supply-path authority location must contain 1 to 8192 characters'); + } } export const defaultSupplyPathAuthorities = new InMemorySupplyPathAuthorityStore(); diff --git a/test/lib/product-property-policy-client.test.js b/test/lib/product-property-policy-client.test.js index 8000db47e..334aead20 100644 --- a/test/lib/product-property-policy-client.test.js +++ b/test/lib/product-property-policy-client.test.js @@ -694,6 +694,50 @@ describe('supply-path annotations across discovery completion paths', () => { assert.strictEqual(evidenceSignal.aborted, true); }); + test('waitForCompletion cancellation aborts authoritative evidence retrieval', async () => { + const product = makeProduct('owner-sold', 'host.example', { + collections: [{ publisher_domain: 'owner.example', collection_ids: ['channel'] }], + }); + let started; + const evidenceStarted = new Promise(resolve => { + started = resolve; + }); + let evidenceSignal; + const agent = makeClient({ + validation: { + supplyPathVerification: { + source: 'authoritative', + trustedFetchFn: async (_url, init) => { + evidenceSignal = init.signal; + started(); + return await new Promise((_resolve, reject) => { + init.signal.addEventListener('abort', () => reject(init.signal.reason), { once: true }); + }); + }, + }, + }, + }); + ProtocolClient.callTool = async (_agent, tool) => + tool === 'get_products' + ? { status: 'submitted', task_id: 'cancel-completion' } + : { + task_id: 'cancel-completion', + task_type: 'get_products', + protocol: 'media-buy', + status: 'completed', + created_at: '2026-09-19T00:00:00Z', + updated_at: '2026-09-19T00:00:01Z', + result: { products: [product], cache_scope: 'public' }, + }; + const submitted = await agent.getProducts({ brief: 'sports' }, undefined, { project: false }); + const controller = new AbortController(); + const pending = submitted.submitted.waitForCompletion(1, controller.signal); + await evidenceStarted; + controller.abort(new Error('completion cancelled')); + await assert.rejects(pending, /completion cancelled/); + assert.strictEqual(evidenceSignal.aborted, true); + }); + for (const taskName of ['get_products', 'list_products']) { test(`${taskName} annotates immediate, polled, and webhook products before publication`, async () => { const products = [ diff --git a/test/lib/supply-path-types.test.js b/test/lib/supply-path-types.test.js index 3fc84bb8c..8ab1ada90 100644 --- a/test/lib/supply-path-types.test.js +++ b/test/lib/supply-path-types.test.js @@ -44,6 +44,11 @@ replaced.then(products => { const state: SupplyPathState | undefined = products[0]?.supply_path_state; void state; }); +annotateProductsSupplyPaths([], 'https://sales.example', { + source: 'authoritative', + // @ts-expect-error Annotation property scope is always derived from each product. + propertySelectors: [], +}); void handler; ` ); diff --git a/test/lib/supply-path.test.js b/test/lib/supply-path.test.js index c9100b6f3..566c8eb1b 100644 --- a/test/lib/supply-path.test.js +++ b/test/lib/supply-path.test.js @@ -521,6 +521,26 @@ describe('live evidence retrieval', () => { /cancelled/ ); }); + it('rejects oversized authority pointers before fetching or retaining them', async () => { + const oversized = `https://cdn.example/${'x'.repeat(8192)}`; + const calls = []; + const result = await verifySupplyPath(request, { + source: 'authoritative', + trustedFetchFn: transport( + { [`https://${OWNER}/.well-known/adagents.json`]: { authoritative_location: oversized } }, + calls + ), + }); + assert.equal(result.state, 'unverified'); + assert.equal( + calls.some(call => call.url === oversized), + false + ); + const store = new sdk.InMemorySupplyPathAuthorityStore(); + await assert.rejects(store.check(OWNER, oversized), /1 to 8192 characters/); + await assert.rejects(store.observe(OWNER, oversized), /1 to 8192 characters/); + assert.throws(() => store.approveChange(OWNER, oversized), /1 to 8192 characters/); + }); }); describe('registry wrapper and product discovery annotations', () => { From 6ff6d2e9a123328f28223204d3123b1dc292df6d Mon Sep 17 00:00:00 2001 From: Brian O'Kelley Date: Sat, 19 Sep 2026 11:03:53 +0000 Subject: [PATCH 16/21] fix(supply-path): validate manifests before pinning --- src/lib/supply-path/fetch-evidence.ts | 13 ++++++++++--- src/lib/supply-path/revocations.ts | 3 +++ src/lib/supply-path/types.ts | 2 ++ test/lib/supply-path.test.js | 16 ++++++++++++++++ 4 files changed, 31 insertions(+), 3 deletions(-) diff --git a/src/lib/supply-path/fetch-evidence.ts b/src/lib/supply-path/fetch-evidence.ts index e623f7362..8a0db8d1c 100644 --- a/src/lib/supply-path/fetch-evidence.ts +++ b/src/lib/supply-path/fetch-evidence.ts @@ -6,7 +6,7 @@ import { SsrfRefusedError, SSRF_TRANSIENT_CODES, type SsrfFetchResult } from '.. import { ssrfSafeFetchAdAgents, AdAgentsRedirectRefusedError } from '../discovery/adagents-redirects'; import type { AuthoritativeSupplyPathOptions, SupplyPathEvidence, SupplyPathManifest } from './types'; import { defaultSupplyPathRevocations, parseRevocations, type SupplyPathRevocation } from './revocations'; -import { record } from './validation'; +import { agentIdentity, record } from './validation'; export function boundedOption(value: number | undefined, fallback: number, maximum: number, name: string): number { if (value === undefined) return fallback; @@ -133,6 +133,9 @@ export class SupplyPathEvidenceSession { return response; } catch (error) { this.signal.throwIfAborted(); + const rawCauseCode = record(error) && typeof error.code === 'string' ? error.code.toUpperCase() : undefined; + const causeCode = + rawCauseCode && /^(?:E[A-Z0-9_]{2,40}|CERT_[A-Z0-9_]{2,40})$/.test(rawCauseCode) ? rawCauseCode : undefined; const code = error instanceof SsrfRefusedError || error instanceof AdAgentsRedirectRefusedError ? error.code @@ -146,6 +149,7 @@ export class SupplyPathEvidenceSession { requested_url: url, fetched_at: new Date().toISOString(), error: code, + ...(causeCode ? { cause_code: causeCode } : {}), }); // Preserve the repository's explicit network-policy refusal boundary. if (error instanceof SsrfRefusedError && !SSRF_TRANSIENT_CODES.has(error.code)) throw error; @@ -236,8 +240,11 @@ export class SupplyPathEvidenceSession { } else { await this.checkAuthority(publisher, authorityLocation, 'check'); } - if (!Array.isArray(manifest.authorized_agents)) { - this.documentError(publisher, documentResponse, 'missing_authorized_agents'); + if ( + !Array.isArray(manifest.authorized_agents) || + !manifest.authorized_agents.every(entry => record(entry) && agentIdentity(entry.url)) + ) { + this.documentError(publisher, documentResponse, 'malformed_authorized_agents'); // parseManifest already captured denials; invalid envelopes cannot establish a pin. return null; } diff --git a/src/lib/supply-path/revocations.ts b/src/lib/supply-path/revocations.ts index 9e006e898..59a4aeb36 100644 --- a/src/lib/supply-path/revocations.ts +++ b/src/lib/supply-path/revocations.ts @@ -17,6 +17,7 @@ class AuthorityAdmissionBudget { export interface SupplyPathRevocation { publisher_domain: string; + /** Publisher timestamp, or `unspecified` for a legacy domain-only declaration. Never use this as the hold expiry. */ revoked_at: string; } /** @@ -25,6 +26,8 @@ export interface SupplyPathRevocation { * across changed publisher timestamps, and reject on storage failure instead of returning an empty set. * Capture tenant identity from trusted application context in the store instance; * include that tenant in every key and transaction. Publisher evidence must never select a tenant. + * Persist `revoked_at` as publisher metadata that may be the `unspecified` sentinel; + * maintain the seven-day first-observation expiry in a separate timestamp column. */ export interface SupplyPathRevocationStore { observe(authority: string, revoked: readonly SupplyPathRevocation[]): Promise; diff --git a/src/lib/supply-path/types.ts b/src/lib/supply-path/types.ts index fda77e8ad..f2401418c 100644 --- a/src/lib/supply-path/types.ts +++ b/src/lib/supply-path/types.ts @@ -138,6 +138,8 @@ export interface SupplyPathEvidence { byte_length?: number; connection_pinned?: boolean; error?: string; + /** Sanitized transport code such as ECONNREFUSED; never contains the underlying error message. */ + cause_code?: string; /** Present for HTTP redirects and authoritative_location delegation. */ delegated_to?: string; /** Exact bytes for audit/replay when retainEvidenceBodies is enabled. */ diff --git a/test/lib/supply-path.test.js b/test/lib/supply-path.test.js index 566c8eb1b..bc4be48f2 100644 --- a/test/lib/supply-path.test.js +++ b/test/lib/supply-path.test.js @@ -521,6 +521,21 @@ describe('live evidence retrieval', () => { /cancelled/ ); }); + it('preserves a sanitized transport cause code in unavailable evidence', async () => { + const failure = new Error('internal address and TLS details'); + failure.code = 'ECONNREFUSED'; + const result = await verifySupplyPath(request, { + source: 'authoritative', + trustedFetchFn: async () => { + throw failure; + }, + }); + assert.equal(result.state, 'unverified'); + assert.ok(result.sources.evidence.length > 0); + assert.ok(result.sources.evidence.every(item => item.error === 'fetch_failed')); + assert.ok(result.sources.evidence.every(item => item.cause_code === 'ECONNREFUSED')); + assert.ok(result.sources.evidence.every(item => !JSON.stringify(item).includes('internal address'))); + }); it('rejects oversized authority pointers before fetching or retaining them', async () => { const oversized = `https://cdn.example/${'x'.repeat(8192)}`; const calls = []; @@ -1232,6 +1247,7 @@ describe('authority pins require a successfully validated manifest', () => { malformed: new Response('{invalid JSON', { headers: { 'content-type': 'application/json' } }), missing_envelope: {}, malformed_envelope: { authorized_agents: null }, + malformed_agent_entry: { authorized_agents: [null] }, chained: { authoritative_location: 'https://chained.example/another.json' }, }; for (const [name, failedTarget] of Object.entries(failures)) { From 967e64069229337836ff0772979d98fe153cb273 Mon Sep 17 00:00:00 2001 From: Brian O'Kelley Date: Sat, 19 Sep 2026 11:15:11 +0000 Subject: [PATCH 17/21] fix(supply-path): bound selector evaluation work --- src/lib/supply-path/evaluate.ts | 7 +- src/lib/supply-path/fetch-evidence.ts | 14 +++- src/lib/supply-path/products.ts | 6 +- src/lib/supply-path/verify.ts | 107 +++++++++++++++++++++----- test/lib/supply-path.test.js | 27 +++++++ 5 files changed, 137 insertions(+), 24 deletions(-) diff --git a/src/lib/supply-path/evaluate.ts b/src/lib/supply-path/evaluate.ts index 6e2ed42b7..04e0b10d6 100644 --- a/src/lib/supply-path/evaluate.ts +++ b/src/lib/supply-path/evaluate.ts @@ -313,7 +313,8 @@ function nodeCost(value: unknown): number { return cost; } -function limitVerdict(): SupplyPathVerdict { +/** Internal fail-closed result used when preprocessing reaches the same evaluation budget. */ +export function evaluationLimitVerdict(): SupplyPathVerdict { const failure = { ok: false, failure: 'evaluation_limit_exceeded' as const }; return { semantics_version: '1', @@ -330,12 +331,12 @@ function limitVerdict(): SupplyPathVerdict { export function evaluateSupplyPath(input: SupplyPathInput): SupplyPathVerdict { const total = nodeCost(input); - if (!Number.isFinite(total)) return limitVerdict(); + if (!Number.isFinite(total)) return evaluationLimitVerdict(); const grants = nodeCost(input.hostManifest?.authorized_agents); const properties = nodeCost(input.hostManifest?.properties); const collections = records(input.ownerManifest?.collections).length; if (!Number.isFinite(total) || grants * properties + Math.max(1, collections) * total * 4 > 4_000_000) { - return limitVerdict(); + return evaluationLimitVerdict(); } // Bulk inquiry is existential over complete individual paths, not a union // of owner collection A's carriage and collection B's host authorization. diff --git a/src/lib/supply-path/fetch-evidence.ts b/src/lib/supply-path/fetch-evidence.ts index 8a0db8d1c..c41c7ce2f 100644 --- a/src/lib/supply-path/fetch-evidence.ts +++ b/src/lib/supply-path/fetch-evidence.ts @@ -24,6 +24,7 @@ export class SupplyPathEvidenceSession { readonly signal: AbortSignal; private readonly maxBodyBytes: number; private readonly timeoutMs: number; + private readonly deadlineAt: number; private readonly timer: ReturnType; private readonly controller = new AbortController(); private readonly abort: () => void; @@ -34,6 +35,7 @@ export class SupplyPathEvidenceSession { constructor(private readonly options: AuthoritativeSupplyPathOptions) { this.timeoutMs = boundedOption(options.timeoutMs, 15_000, 60_000, 'timeoutMs'); + this.deadlineAt = Date.now() + this.timeoutMs; this.maxBodyBytes = boundedOption(options.maxBodyBytes, 256 * 1024, 20 * 1024 * 1024, 'maxBodyBytes'); this.signal = this.controller.signal; this.abort = () => this.controller.abort(options.signal?.reason); @@ -49,6 +51,14 @@ export class SupplyPathEvidenceSession { this.controller.abort(new Error('Supply-path evidence session closed')); this.options.signal?.removeEventListener('abort', this.abort); } + /** Enforce the absolute deadline even while synchronous evidence evaluation blocks timer delivery. */ + assertActive(): void { + this.signal.throwIfAborted(); + if (Date.now() >= this.deadlineAt) { + this.controller.abort(new Error('Supply-path verification deadline exceeded')); + this.signal.throwIfAborted(); + } + } adagents(publisher: string): Promise { let pending = this.documents.get(publisher); if (!pending) { @@ -77,7 +87,7 @@ export class SupplyPathEvidenceSession { url: string, pointer = false ): Promise { - this.signal.throwIfAborted(); + this.assertActive(); try { if (this.observedBytes >= 64 * 1024 * 1024) throw new Error('evidence_budget_exceeded'); const parsed = new URL(url); @@ -157,6 +167,7 @@ export class SupplyPathEvidenceSession { } } private async parseManifest(publisher: string, response: SsrfFetchResult): Promise { + this.assertActive(); let document: unknown; try { document = parse(new TextDecoder('utf-8', { fatal: true }).decode(response.body)); @@ -165,6 +176,7 @@ export class SupplyPathEvidenceSession { this.documentError(publisher, response, 'invalid_document'); return null; } + this.assertActive(); const denials = parseRevocations(document.revoked_publisher_domains); if (denials === null) { this.documentError(publisher, response, 'invalid_revocations'); diff --git a/src/lib/supply-path/products.ts b/src/lib/supply-path/products.ts index 2e56c5cf2..e71d19c4b 100644 --- a/src/lib/supply-path/products.ts +++ b/src/lib/supply-path/products.ts @@ -179,7 +179,11 @@ export async function annotateProductsSupplyPaths( try { session = options.source === 'authoritative' - ? new SupplyPathEvidenceSession({ ...options, signal: controller.signal }) + ? new SupplyPathEvidenceSession({ + ...options, + signal: controller.signal, + timeoutMs: Math.max(1, deadlineAt - Date.now()), + }) : undefined; controller.signal.throwIfAborted(); const aborted = new Promise((_, reject) => { diff --git a/src/lib/supply-path/verify.ts b/src/lib/supply-path/verify.ts index 72e6fa658..937169ead 100644 --- a/src/lib/supply-path/verify.ts +++ b/src/lib/supply-path/verify.ts @@ -10,6 +10,7 @@ import { isUnqualifiedPropertySelector, hasValidPropertySelectorPredicate, evaluateSupplyPath, + evaluationLimitVerdict, supplyPathAdsTxtPolicy, parseInventoryPartnerDomains, } from './evaluate'; @@ -23,6 +24,9 @@ import type { AuthoritativeSupplyPathResult, } from './types'; +const MAX_PROPERTY_SCOPE_VALUES = 32_768; +const MAX_PROPERTY_SELECTOR_EXPANSIONS = 4_096; + /** * Verify one owner/host/agent path. Authoritative mode (the default) fetches * live publisher evidence; registry mode validates a remote cached verdict. @@ -83,6 +87,8 @@ export async function verifyAuthoritativeSupplyPath( if (options.propertySelectors !== undefined) { if (!Array.isArray(options.propertySelectors) || !options.propertySelectors.length) throw new TypeError('propertySelectors must be non-empty'); + if (options.propertySelectors.length > 1024) + throw new TypeError('propertySelectors exceed the evaluation work limit'); for (const raw of options.propertySelectors) { if (!isUnqualifiedPropertySelector(raw)) throw new TypeError('Unsupported product property selector fields'); if (!hasValidPropertySelectorPredicate(raw)) @@ -111,42 +117,102 @@ export async function verifyAuthoritativeSupplyPath( }, }; const scopedInput: typeof input & { requiredHostPropertyIds?: string[] } = input; + let selectorLimitExceeded = false; if (options.propertySelectors !== undefined) { const ids = new Set(); - const properties = records(hostManifest?.properties).filter( - p => - (p.publisher_domain === undefined && !input.requireExplicitHostPublisherDomain) || - domain(p.publisher_domain) === normalized.host_domain - ); + const rawProperties = hostManifest?.properties; + if (Array.isArray(rawProperties) && rawProperties.length > 1024) selectorLimitExceeded = true; + const properties = selectorLimitExceeded + ? [] + : records(rawProperties).filter( + p => + (p.publisher_domain === undefined && !input.requireExplicitHostPublisherDomain) || + domain(p.publisher_domain) === normalized.host_domain + ); let unresolved = false; + let scopeValues = properties.length; + const availableTags = new Set(); + for (const property of properties) { + session.assertActive(); + if (property.tags === undefined) continue; + if (!strings(property.tags) || property.tags.length > 1024) { + selectorLimitExceeded = true; + continue; + } + scopeValues += property.tags.length; + if (scopeValues > MAX_PROPERTY_SCOPE_VALUES) { + selectorLimitExceeded = true; + break; + } + for (const tag of property.tags) { + if (tag.length > 8192) selectorLimitExceeded = true; + availableTags.add(tag); + } + } + const selectors = [] as ReturnType; for (const raw of options.propertySelectors) { + session.assertActive(); + if (selectorLimitExceeded) continue; const selector = parsePublisherPropertySelector(raw); - for (const single of expandPublisherPropertySelector(selector)) { + const expansionCount = 'publisher_domains' in selector ? selector.publisher_domains.length : 1; + if (selectors.length + expansionCount > MAX_PROPERTY_SELECTOR_EXPANSIONS) { + selectorLimitExceeded = true; + continue; + } + const expanded = expandPublisherPropertySelector(selector); + selectors.push(...expanded); + } + const selectedTags = new Set(); + let selectAll = false; + for (const single of selectors) { + session.assertActive(); + scopeValues += 1; + if (scopeValues > MAX_PROPERTY_SCOPE_VALUES) selectorLimitExceeded = true; + if (!selectorLimitExceeded) { if (domain(single.publisher_domain) !== normalized.host_domain) throw new TypeError('propertySelectors must name host_domain'); if (single.selection_type === 'by_id') { if (!strings(single.property_ids)) throw new TypeError('Invalid product property IDs'); + scopeValues += single.property_ids.length; + if (single.property_ids.length > 1024 || single.property_ids.some(id => id.length > 8192)) + selectorLimitExceeded = true; for (const id of single.property_ids) ids.add(id); } else { if (single.selection_type === 'by_tag' && !strings(single.property_tags)) throw new TypeError('Invalid product property tags'); - let matched = false; - for (const property of properties) { - const selected = - single.selection_type === 'all' || - (strings(property.tags) && property.tags.some(tag => single.property_tags.includes(tag))); - if (!selected) continue; - matched = true; - if (typeof property.property_id !== 'string' || !property.property_id.length) unresolved = true; - else ids.add(property.property_id); + if (single.selection_type === 'all') { + selectAll = true; + if (!properties.length) unresolved = true; + } else { + scopeValues += single.property_tags.length; + if (single.property_tags.length > 1024 || single.property_tags.some(tag => tag.length > 8192)) + selectorLimitExceeded = true; + let matched = false; + for (const tag of single.property_tags) { + if (!availableTags.has(tag)) continue; + matched = true; + selectedTags.add(tag); + } + if (!matched) unresolved = true; } - if (!matched) unresolved = true; } } } - scopedInput.requiredHostPropertyIds = unresolved ? [] : [...ids]; + if (scopeValues > MAX_PROPERTY_SCOPE_VALUES) selectorLimitExceeded = true; + if (!selectorLimitExceeded && (selectAll || selectedTags.size)) { + for (const property of properties) { + session.assertActive(); + const selected = selectAll || (strings(property.tags) && property.tags.some(tag => selectedTags.has(tag))); + if (!selected) continue; + if (typeof property.property_id !== 'string' || !property.property_id.length) unresolved = true; + else ids.add(property.property_id); + } + } + scopedInput.requiredHostPropertyIds = selectorLimitExceeded || unresolved ? [] : [...ids]; } - let verdict = evaluateSupplyPath(scopedInput); + session.assertActive(); + let verdict = selectorLimitExceeded ? evaluationLimitVerdict() : evaluateSupplyPath(scopedInput); + session.assertActive(); if (!verdict.legs.host_authorization.ok && verdict.legs.host_authorization.failure !== 'evaluation_limit_exceeded') { const policy = supplyPathAdsTxtPolicy(scopedInput); const responses = await Promise.all( @@ -158,11 +224,14 @@ export async function verifyAuthoritativeSupplyPath( responses[index] ? parseInventoryPartnerDomains(new TextDecoder().decode(responses[index]!.body)) : null, ]) ); + session.assertActive(); verdict = evaluateSupplyPath(scopedInput); + session.assertActive(); } else if (verdict.legs.host_authorization.ok) { verdict = evaluateSupplyPath({ ...scopedInput, inventoryPartnerDomainEvaluated: false }); + session.assertActive(); } - session.signal.throwIfAborted(); + session.assertActive(); return { ...verdict, ...normalized, diff --git a/test/lib/supply-path.test.js b/test/lib/supply-path.test.js index bc4be48f2..8e27e7683 100644 --- a/test/lib/supply-path.test.js +++ b/test/lib/supply-path.test.js @@ -777,6 +777,33 @@ describe('bounded evidence and complete product scope', () => { }); assert.equal(result.state, 'owner_attested'); }); + it('fails closed before selector and property tags can multiply synchronous work', async () => { + const fixture = input(); + fixture.hostManifest.properties[0].tags = Array.from({ length: 1024 }, (_, index) => `host_${index}`); + const propertySelectors = Array.from({ length: 40 }, (_, selector) => ({ + publisher_domain: HOST, + selection_type: 'by_tag', + property_tags: Array.from({ length: 1024 }, (_, tag) => `selector_${selector}_${tag}`), + })); + const result = await verifySupplyPath(request, { + source: 'authoritative', + timeoutMs: 200, + trustedFetchFn: transport({ [`https://${HOST}/.well-known/adagents.json`]: fixture.hostManifest }), + propertySelectors, + }); + assert.equal(result.state, 'unverified'); + assert.equal(result.legs.host_authorization.failure, 'evaluation_limit_exceeded'); + }); + it('enforces its absolute deadline even before the timer callback can run', () => { + const { SupplyPathEvidenceSession } = require('../../dist/lib/supply-path/fetch-evidence'); + const session = new SupplyPathEvidenceSession({ source: 'authoritative', timeoutMs: 1 }); + const until = Date.now() + 5; + while (Date.now() < until) { + // Deliberately occupy the event loop so only the absolute check can observe expiry. + } + assert.throws(() => session.assertActive(), /deadline/i); + session.close(); + }); for (const selectionType of ['all', 'by_tag']) { it(`fails closed when a ${selectionType} selector includes a property without property_id`, async () => { const fixture = input(); From a32ad568780d28074ac1dbddec234fa042c43bcd Mon Sep 17 00:00:00 2001 From: Brian O'Kelley Date: Sat, 19 Sep 2026 11:22:37 +0000 Subject: [PATCH 18/21] fix(supply-path): cap compact selector preprocessing --- src/lib/supply-path/products.ts | 85 +++++++++++++++++++++++++-------- src/lib/supply-path/verify.ts | 9 +++- test/lib/supply-path.test.js | 38 +++++++++++++++ 3 files changed, 111 insertions(+), 21 deletions(-) diff --git a/src/lib/supply-path/products.ts b/src/lib/supply-path/products.ts index e71d19c4b..b9bcfc0f2 100644 --- a/src/lib/supply-path/products.ts +++ b/src/lib/supply-path/products.ts @@ -1,13 +1,11 @@ +import { createHash } from 'node:crypto'; import type { SinglePublisherPropertySelector } from '../discovery/types'; import type { ListProductsResponse } from '../types'; import { verifySupplyPath, verifyAuthoritativeSupplyPath } from './verify'; import { SUPPLY_PATH_STATES, hasValidPropertySelectorPredicate } from './evaluate'; import { boundedOption, SupplyPathEvidenceSession } from './fetch-evidence'; import { agentIdentity, domain, record, strings, validateSupplyPathRequest } from './validation'; -import { - parsePublisherPropertySelector, - expandPublisherPropertySelector, -} from '../discovery/publisher-property-selector'; +import { parsePublisherPropertySelector } from '../discovery/publisher-property-selector'; import type { SupplyPathRequest, SupplyPathState, @@ -41,6 +39,30 @@ export type ProductSupplyPathOptions = ProductSupplyPathVerificationOptions & { signal?: AbortSignal; }; +const MAX_SELECTOR_PREPROCESS_VALUES = 32_768; +const MAX_SELECTOR_PREPROCESS_BYTES = 4 * 1024 * 1024; + +function selectorPredicateFingerprint(selector: SinglePublisherPropertySelector): { + key: string; + values: number; + bytes: number; +} { + const predicate = + selector.selection_type === 'by_id' + ? selector.property_ids + : selector.selection_type === 'by_tag' + ? selector.property_tags + : []; + const hash = createHash('sha256').update(selector.selection_type); + let bytes = selector.selection_type.length; + for (const value of predicate) { + if (value.length > 8192) throw new Error('selector_work_limit_exceeded'); + hash.update('\0').update(value); + bytes += value.length; + } + return { key: hash.digest('hex'), values: predicate.length, bytes }; +} + /** * Annotate products with external-domain collection paths. Preserves actual * seller products, order, and all unrelated fields. Seller-authored verification @@ -91,25 +113,47 @@ export async function annotateProductsSupplyPaths( try { if (!value.publisher_properties.every(hasValidPropertySelectorPredicate)) throw new Error('invalid_product_selector_predicate'); - const propertySelectorsByKey = new Map(); + const selectorsByHost = new Map>(); let selectorExpansions = 0; + let selectorValues = 0; + let selectorBytes = 0; for (const raw of value.publisher_properties) { checkPreprocessingBudget(); - selectorExpansions += Array.isArray(raw.publisher_domains) ? raw.publisher_domains.length : 1; + const parsed = parsePublisherPropertySelector(raw); + const domains = 'publisher_domains' in parsed ? parsed.publisher_domains : [parsed.publisher_domain]; + const single: SinglePublisherPropertySelector = + parsed.selection_type === 'all' + ? { selection_type: 'all', publisher_domain: domains[0]! } + : parsed.selection_type === 'by_id' + ? { + selection_type: 'by_id', + publisher_domain: domains[0]!, + property_ids: parsed.property_ids, + } + : { + selection_type: 'by_tag', + publisher_domain: domains[0]!, + property_tags: parsed.property_tags, + }; + const predicate = selectorPredicateFingerprint(single); + selectorExpansions += domains.length; + selectorValues += domains.length + predicate.values * Math.min(domains.length, maxPaths); + selectorBytes += + domains.reduce((total, publisher) => total + publisher.length, 0) + + predicate.bytes * Math.min(domains.length, maxPaths); if (selectorExpansions > 4096) throw new Error('selector_work_limit_exceeded'); - for (const selector of expandPublisherPropertySelector(parsePublisherPropertySelector(raw))) { - propertySelectorsByKey.set(JSON.stringify(selector), selector); + if (selectorValues > MAX_SELECTOR_PREPROCESS_VALUES || selectorBytes > MAX_SELECTOR_PREPROCESS_BYTES) + throw new Error('selector_work_limit_exceeded'); + for (const publisher_domain of domains) { + checkPreprocessingBudget(); + let selectors = selectorsByHost.get(publisher_domain); + if (!selectors) { + selectors = new Map(); + selectorsByHost.set(publisher_domain, selectors); + } + selectors.set(predicate.key, { ...single, publisher_domain }); } } - const propertySelectors = [...propertySelectorsByKey.entries()] - .sort(([left], [right]) => left.localeCompare(right)) - .map(([, selector]) => selector); - const selectorsByHost = new Map(); - for (const selector of propertySelectors) { - const existing = selectorsByHost.get(selector.publisher_domain); - if (existing) existing.push(selector); - else selectorsByHost.set(selector.publisher_domain, [selector]); - } const collectionIdsByOwner = new Map>(); for (const selector of value.collections) { checkPreprocessingBudget(); @@ -129,8 +173,11 @@ export async function annotateProductsSupplyPaths( for (const id of selector.collection_ids) ids.add(id); } for (const [owner, collectionIds] of collectionIdsByOwner) { - for (const [host, selectors] of selectorsByHost) { + for (const [host, selectorsByKey] of selectorsByHost) { if (domain(host) === owner) continue; + const selectorEntries = [...selectorsByKey.entries()].sort(([left], [right]) => left.localeCompare(right)); + const selectors = selectorEntries.map(([, selector]) => selector); + const selectorKey = selectorEntries.map(([key]) => key).join(':'); for (const id of collectionIds) { checkPreprocessingBudget(); const request = validateSupplyPathRequest({ @@ -139,7 +186,7 @@ export async function annotateProductsSupplyPaths( agent_url: agentUrl, collection_id: id, }); - const key = JSON.stringify({ request, selectors }); + const key = `${JSON.stringify(request)}\0${selectorKey}`; if (!requests.has(key) && requests.size >= maxPaths) { if (!errors.includes('path_limit_exceeded')) errors.push('path_limit_exceeded'); return { keys, errors }; diff --git a/src/lib/supply-path/verify.ts b/src/lib/supply-path/verify.ts index 937169ead..3365a3bb7 100644 --- a/src/lib/supply-path/verify.ts +++ b/src/lib/supply-path/verify.ts @@ -135,7 +135,11 @@ export async function verifyAuthoritativeSupplyPath( for (const property of properties) { session.assertActive(); if (property.tags === undefined) continue; - if (!strings(property.tags) || property.tags.length > 1024) { + if ( + !Array.isArray(property.tags) || + property.tags.length > 1024 || + property.tags.some(tag => typeof tag !== 'string' || !tag.trim()) + ) { selectorLimitExceeded = true; continue; } @@ -202,7 +206,8 @@ export async function verifyAuthoritativeSupplyPath( if (!selectorLimitExceeded && (selectAll || selectedTags.size)) { for (const property of properties) { session.assertActive(); - const selected = selectAll || (strings(property.tags) && property.tags.some(tag => selectedTags.has(tag))); + const selected = + selectAll || (Array.isArray(property.tags) && property.tags.some(tag => selectedTags.has(tag))); if (!selected) continue; if (typeof property.property_id !== 'string' || !property.property_id.length) unresolved = true; else ids.add(property.property_id); diff --git a/test/lib/supply-path.test.js b/test/lib/supply-path.test.js index 8e27e7683..05f7319dc 100644 --- a/test/lib/supply-path.test.js +++ b/test/lib/supply-path.test.js @@ -663,6 +663,34 @@ describe('registry wrapper and product discovery annotations', () => { assert.equal(result.supply_path_verification.paths.length, 1); assert.equal(calls.length, 2); }); + it('rejects compact selector byte amplification before allocating path keys', async () => { + const startedAt = Date.now(); + const [result] = await annotateProductsSupplyPaths( + [ + { + product_id: 'compact-amplification', + publisher_properties: [ + { + publisher_domains: Array.from({ length: 1024 }, (_, index) => `host${index}.example`), + selection_type: 'by_tag', + property_tags: Array.from({ length: 128 }, (_, index) => `tag_${index}_${'a'.repeat(1000)}`), + }, + ], + collections: [{ publisher_domain: OWNER, collection_ids: ['retro_news'] }], + }, + ], + AGENT, + { + source: 'authoritative', + timeoutMs: 50, + trustedFetchFn: () => { + throw new Error('unexpected fetch'); + }, + } + ); + assert.deepEqual(result.supply_path_verification.errors, ['selector_work_limit_exceeded']); + assert.ok(Date.now() - startedAt < 500, 'preprocessing should reject without predicate duplication'); + }); it('validates evidence-session options before allocating batch timers', async () => { const before = process.getActiveResourcesInfo().filter(resource => resource === 'Timeout').length; await assert.rejects( @@ -777,6 +805,16 @@ describe('bounded evidence and complete product scope', () => { }); assert.equal(result.state, 'owner_attested'); }); + it('accepts a schema-valid empty property tag list for an unrelated by-id scope', async () => { + const fixture = input(); + fixture.hostManifest.properties[0].tags = []; + const result = await verifySupplyPath(request, { + source: 'authoritative', + trustedFetchFn: transport({ [`https://${HOST}/.well-known/adagents.json`]: fixture.hostManifest }), + propertySelectors: [{ publisher_domain: HOST, selection_type: 'by_id', property_ids: ['hoststream_ctv'] }], + }); + assert.equal(result.state, 'verified_owner_sold'); + }); it('fails closed before selector and property tags can multiply synchronous work', async () => { const fixture = input(); fixture.hostManifest.properties[0].tags = Array.from({ length: 1024 }, (_, index) => `host_${index}`); From 51efa1cd4708a369cd6bb77b1f0cac152c1d823f Mon Sep 17 00:00:00 2001 From: Brian O'Kelley Date: Sat, 19 Sep 2026 11:32:11 +0000 Subject: [PATCH 19/21] fix(supply-path): preserve client compatibility --- src/lib/core/AgentClient.ts | 7 ++++++- src/lib/supply-path/evaluate.ts | 13 ++----------- src/lib/supply-path/products.ts | 9 ++++++--- test/lib/supply-path-types.test.js | 5 +++++ test/lib/supply-path.test.js | 31 ++++++++++++++++++++++++++++++ 5 files changed, 50 insertions(+), 15 deletions(-) diff --git a/src/lib/core/AgentClient.ts b/src/lib/core/AgentClient.ts index fceda914a..cdaeee2cd 100644 --- a/src/lib/core/AgentClient.ts +++ b/src/lib/core/AgentClient.ts @@ -821,7 +821,12 @@ export class AgentClient { inputHandler?: InputHandler, options?: TaskOptions ): Promise> { - const result = await this.client.listProducts(params, inputHandler, this.withSession('list_products', options)); + const result = await this.client.executeTask( + 'list_products', + params, + inputHandler, + this.withSession('list_products', options) + ); this.retainSession(result); return result; } diff --git a/src/lib/supply-path/evaluate.ts b/src/lib/supply-path/evaluate.ts index 04e0b10d6..e00512199 100644 --- a/src/lib/supply-path/evaluate.ts +++ b/src/lib/supply-path/evaluate.ts @@ -58,18 +58,9 @@ function coversCollection(entry: Record, owner: string, id: str const PROPERTY_TYPES = new Set(PropertyTypeValues); const PROPERTY_IDENTIFIER_TYPES = new Set([ ...PropertyIdentifierTypesValues, - // The SDK still accepts the published pre-3.2 discovery aliases represented - // by discovery/types.ts and by the canonical supply-path corpus. - 'amazon_app_store_id', + // Retained only for the pinned canonical corpus, whose CTV properties use + // this distribution identifier in property records. 'roku_channel_id', - 'lg_channel_id', - 'vizio_app_id', - 'fire_tv_app_id', - 'dooh_venue_id', - 'podcast_rss_feed', - 'spotify_show_id', - 'iab_tech_lab_domain_id', - 'custom', ]); const PROPERTY_CHANNELS = new Set(MediaChannelValues); diff --git a/src/lib/supply-path/products.ts b/src/lib/supply-path/products.ts index b9bcfc0f2..a20aea673 100644 --- a/src/lib/supply-path/products.ts +++ b/src/lib/supply-path/products.ts @@ -25,9 +25,12 @@ export interface ProductSupplyPathAnnotation { } export type AnnotatedSupplyPathProduct = Omit & ProductSupplyPathAnnotation; -export type ListProductsResponseWithSupplyPath = Omit & { - products?: Array[number]>>; -}; +type AnnotatedListProductsResponse = T extends unknown + ? Omit & { + products: Array[number]>>; + } + : never; +export type ListProductsResponseWithSupplyPath = AnnotatedListProductsResponse; type ProductSupplyPathVerificationOptions = | RegistrySupplyPathOptions | Omit; diff --git a/test/lib/supply-path-types.test.js b/test/lib/supply-path-types.test.js index 8ab1ada90..cd5dafa00 100644 --- a/test/lib/supply-path-types.test.js +++ b/test/lib/supply-path-types.test.js @@ -18,20 +18,24 @@ test('listProducts and its status handler expose supply-path annotations', () => ` import type { AgentClient, + ListProductsResponse, ListProductsResponseWithSupplyPath, ListProductsStatusChangeHandler, SupplyPathState, + TaskResult, } from '${modulePath}'; import { annotateProductsSupplyPaths } from '${modulePath}'; type ListResult = Awaited>; declare const result: ListResult; declare const response: ListProductsResponseWithSupplyPath; +const backwardsCompatible: TaskResult = result; if (result.success && result.status === 'completed') { result.data.products?.[0]?.supply_path_verification?.paths; } response.products?.[0]?.supply_path_state; +response.products.map(product => product.product_id); const handler: ListProductsStatusChangeHandler = async completed => { completed.products?.[0]?.supply_path_verification?.errors; @@ -50,6 +54,7 @@ annotateProductsSupplyPaths([], 'https://sales.example', { propertySelectors: [], }); void handler; +void backwardsCompatible; ` ); diff --git a/test/lib/supply-path.test.js b/test/lib/supply-path.test.js index 05f7319dc..6bd26c1b4 100644 --- a/test/lib/supply-path.test.js +++ b/test/lib/supply-path.test.js @@ -284,6 +284,37 @@ describe('fail-closed authoritative semantics', () => { assert.equal(result.state, 'owner_attested'); assert.equal(result.legs.host_authorization.failure, 'property_scope_mismatch'); }); + it('does not accept legacy discovery-only identifier aliases as property authorization', () => { + for (const identifierType of [ + 'amazon_app_store_id', + 'lg_channel_id', + 'vizio_app_id', + 'fire_tv_app_id', + 'dooh_venue_id', + 'podcast_rss_feed', + 'spotify_show_id', + 'iab_tech_lab_domain_id', + 'custom', + ]) { + const evidence = input(); + evidence.hostManifest.authorized_agents = []; + evidence.hostInventoryPartnerDomains = [OWNER]; + const grant = evidence.ownerManifest.authorized_agents[0]; + grant.authorization_type = 'inline_properties'; + delete grant.property_ids; + grant.properties = [ + { + property_id: 'legacy_alias', + property_type: 'ctv_app', + name: 'Legacy alias', + identifiers: [{ type: identifierType, value: 'anything' }], + }, + ]; + const result = evaluateSupplyPath(evidence); + assert.equal(result.state, 'owner_attested'); + assert.equal(result.legs.owner_agent_declared.failure, 'agent_not_declared_by_owner'); + } + }); for (const authorizationType of ['property_ids', 'property_tags', 'publisher_properties']) { it(`rejects malformed top-level properties for ${authorizationType} grants`, () => { const evidence = input(); From 1a16bc66deb17ed17f5a37d6aa0cb2f0192ddc62 Mon Sep 17 00:00:00 2001 From: Brian O'Kelley Date: Sat, 19 Sep 2026 11:40:52 +0000 Subject: [PATCH 20/21] fix(supply-path): preserve unchanged response shape --- src/lib/supply-path/products.ts | 6 ++++-- test/lib/supply-path-types.test.js | 13 ++++++++++++- 2 files changed, 16 insertions(+), 3 deletions(-) diff --git a/src/lib/supply-path/products.ts b/src/lib/supply-path/products.ts index a20aea673..09e7c63dc 100644 --- a/src/lib/supply-path/products.ts +++ b/src/lib/supply-path/products.ts @@ -26,8 +26,10 @@ export interface ProductSupplyPathAnnotation { export type AnnotatedSupplyPathProduct = Omit & ProductSupplyPathAnnotation; type AnnotatedListProductsResponse = T extends unknown - ? Omit & { - products: Array[number]>>; + ? { + [K in keyof T]: K extends 'products' + ? Array[number]>> + : T[K]; } : never; export type ListProductsResponseWithSupplyPath = AnnotatedListProductsResponse; diff --git a/test/lib/supply-path-types.test.js b/test/lib/supply-path-types.test.js index cd5dafa00..6e25bf9d3 100644 --- a/test/lib/supply-path-types.test.js +++ b/test/lib/supply-path-types.test.js @@ -29,13 +29,23 @@ import { annotateProductsSupplyPaths } from '${modulePath}'; type ListResult = Awaited>; declare const result: ListResult; declare const response: ListProductsResponseWithSupplyPath; +declare const listed: Extract; +declare const unchanged: Extract; const backwardsCompatible: TaskResult = result; if (result.success && result.status === 'completed') { result.data.products?.[0]?.supply_path_verification?.paths; } response.products?.[0]?.supply_path_state; -response.products.map(product => product.product_id); +listed.products.map(product => product.product_id); +unchanged.products?.map(product => product.product_id); +// @ts-expect-error An unchanged feed legitimately omits products. +unchanged.products.map(product => product.product_id); +const unchangedResponse: ListProductsResponseWithSupplyPath = { + outcome: 'unchanged', + feed_version: 'v1', + cache_scope: 'public', +}; const handler: ListProductsStatusChangeHandler = async completed => { completed.products?.[0]?.supply_path_verification?.errors; @@ -55,6 +65,7 @@ annotateProductsSupplyPaths([], 'https://sales.example', { }); void handler; void backwardsCompatible; +void unchangedResponse; ` ); From 8c3330cb647926fe140aabce0f72af19f9563639 Mon Sep 17 00:00:00 2001 From: Brian O'Kelley Date: Sat, 19 Sep 2026 11:53:04 +0000 Subject: [PATCH 21/21] fix(supply-path): preserve failed poll results --- src/lib/core/SingleAgentClient.ts | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/src/lib/core/SingleAgentClient.ts b/src/lib/core/SingleAgentClient.ts index 4e89f4a70..1eda14d19 100644 --- a/src/lib/core/SingleAgentClient.ts +++ b/src/lib/core/SingleAgentClient.ts @@ -4842,10 +4842,11 @@ export class SingleAgentClient { ); const completionSignal = signals.length > 1 ? AbortSignal.any(signals) : signals[0]; const completionOptions = { ...(options ?? {}), ...(completionSignal ? { signal: completionSignal } : {}) }; + const completed = await rawSubmittedWaitForCompletion(pollInterval, signal); return this.finalizeTaskResult( - await rawSubmittedWaitForCompletion(pollInterval, signal), + completed, context, - completionOptions, + completed.success && completed.status === 'completed' ? completionOptions : options, transformCompletedResponse, finalizerLegacyFormatConverter );