diff --git a/.changeset/verify-authoritative-supply-paths.md b/.changeset/verify-authoritative-supply-paths.md new file mode 100644 index 000000000..a57e54540 --- /dev/null +++ b/.changeset/verify-authoritative-supply-paths.md @@ -0,0 +1,11 @@ +--- +'@adcp/sdk': minor +--- + +Add supply-path verification with a typed canonical registry wrapper and a live authoritative mode that checks owner/host adagents.json declarations and ads.txt/app-ads.txt evidence. Return per-leg diagnostics and auditable fetch provenance, with DNS-pinned SSRF protection, bounded fetching and fail-closed handling of malformed or unresolved authorization constraints. + +Add opt-in external collection path annotations for product discovery, public selector/distribution types, and an explicit distinction between authorization bulk grants and product selectors that require concrete collection IDs. + +Support explicit publisher attribution on shared collection declarations, bounded process-local authority admission, durable tenant-scoped stores, and independent authority migration confirmation. Establish first-use pins only after successful manifest validation, with a read-only precheck and atomic successful-observation commit. + +Persist parsed revocations before later fetch or authority-store failures, preserving their seven-day hold through failed affirmative verification. 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..9d687a4d3 --- /dev/null +++ b/docs/guides/SUPPLY-PATH-VERIFICATION.md @@ -0,0 +1,101 @@ +# Supply-path verification + +Use `verifySupplyPath` to check an owner-sold collection on a host publisher. It returns a state and five independently diagnosed legs: owner collection declaration, owner distribution/carriage, owner agent declaration, host authorization, and `INVENTORYPARTNERDOMAIN` evidence. + +```typescript +import { verifySupplyPath } from '@adcp/sdk'; + +const result = await verifySupplyPath({ + owner_domain: 'channel-owner.example', + host_domain: 'hoststream.example', + agent_url: 'https://sales.channel-owner.example', + collection_id: 'retro_news', +}, { source: 'authoritative', timeoutMs: 15_000, retainEvidenceBodies: true }); + +if (result.state !== 'verified_owner_sold') { + // Apply your buying policy. Never treat owner_attested as authorization. + console.log(result.legs); +} +// Store this evidence with the decision, including exact bytes when enabled. +console.log(result.sources.evidence); +``` + +| State | Meaning | +| --- | --- | +| `verified_owner_sold` | The owner's collection and carriage references resolve, and a host grant covers the complete carried property scope for this agent and collection without unevaluated constraints. | +| `host_delegated` | The host's ads.txt/app-ads.txt names the owner, and the owner declares the agent and collection. This weaker evidence does not bind the host to this agent or collection. Accept only under an explicit buyer policy. | +| `owner_attested` | The owner asserts carriage. This is discovery information, never host sales authorization. | +| `unverified` | The evidence cannot establish a path. | + +The state is a supply-path decision, not a purchase guarantee, exclusivity claim, proof of delivery, or blanket product authorization. Country, effective-time and placement restrictions require an applicable context; this API fails closed on owner or host entries carrying those restrictions, including unknown authorization fields. Independent unrestricted entries can still establish a path. Collection distribution identifiers identify channels in a catalog; they are not host property IDs and are never silently converted into property IDs. + +`collection_id` is optional for a domain-level inquiry. The evaluator considers complete individual collection paths and returns the strongest one as `resolved_collection_id`; it never combines carriage from one collection with authorization for another. For a particular product, always check its explicit collection IDs. + +## Registry mode + +```typescript +import { RegistryClient, verifySupplyPath } from '@adcp/sdk'; + +const request = { + owner_domain: 'channel-owner.example', + host_domain: 'hoststream.example', + agent_url: 'https://sales.channel-owner.example', + collection_id: 'retro_news', +}; +const registry = new RegistryClient(); +const cached = await registry.verifySupplyPath(request); +// Equivalent: +await verifySupplyPath(request, { source: 'registry', registry }); +``` + +This is a typed wrapper over `POST /api/registry/verify/supply-path`. It preserves the registry's verdict, diagnostics, URLs, `cached` flag, timestamp and additional response fields. HTTP failures and malformed/inconsistent response shapes reject the promise. The wrapper requires `semantics_version: "1"`; an older registry must upgrade before it can serve this API. Registry responses describe cached evidence; `checked_at` is the decision time, not proof that the origin files were fetched then. The registry includes `owner_fetched_at`, `host_fetched_at` and resolved URLs so cache provenance can be assessed separately. The wrapper does not promote registry provenance into authoritative evidence. + +## Discovery annotations + +```typescript +import { annotateProductsSupplyPaths } from '@adcp/sdk'; + +// products must be the actual products returned by your seller. +const annotated = await annotateProductsSupplyPaths(products, sellerAgentUrl, { + source: 'authoritative', + maxPaths: 64, +}); +for (const product of annotated) { + console.log(product.supply_path_state, product.supply_path_verification); +} +``` + +Alternatively, configure a client with `validation.supplyPathVerification: { source: 'authoritative' }`. Completed `get_products` and `list_products` responses are annotated before completion handlers receive them, including resumed completion paths. Annotation is opt-in because it performs additional network requests. + +Products combining `publisher_properties` with a collection selector in a different publisher namespace receive `supply_path_state`, the weakest state across their distinct external paths. Details live in `supply_path_verification.paths`. Authoritative mode uses `scope: 'product_properties'` and resolves every product selector against the host manifest; a verified path must cover all selected properties. Registry mode uses `scope: 'owner_host_collection'` because the endpoint accepts no product property context. Its annotation cannot certify the product's selected properties. Neither mode certifies placements, countries, effective dates, or other product restrictions. The weaker `host_delegated` state never establishes concrete product property coverage. +Products, ordering and unrelated seller fields are preserved. Computed annotation replaces any seller-authored verification fields. Local-only products have no external-path annotation. Invalid or omitted product `collection_ids` and path-limit overflow produce `unverified` with errors. Network policy refusal, unconfirmed authoritative-location changes, cancellation and registry failures reject the operation instead of returning a seller-authored or stale success. Batches deduplicate both paths and evidence fetches within the operation, run at most four paths concurrently, and default to 64 distinct paths (maximum 256). + +## Selector types + +`AuthorizationCollectionSelector.collection_ids` is optional: omission grants all collections declared by that exact publisher. Present `[]`, `null`, non-array values and mixed-type ID arrays are invalid, not bulk grants. `ProductCollectionSelector` requires a non-empty explicit ID tuple. `CollectionDistribution` accepts `property_ids`, `identifiers`, or both. Public discovery and registry authorization types preserve these distinctions. + +## Network and evidence policy + +Authoritative mode starts at each publisher's HTTPS `/.well-known/adagents.json`. It uses the SDK's existing SSRF-safe fetcher: every DNS address is checked, the connection is pinned to a validated address, TLS verification remains enabled, and private/link-local/metadata addresses are refused. It does not contact the agent endpoint. No authorization credentials are sent to publisher evidence URLs. + +HTTP redirects are limited to three within the exact HTTPS origin. A publisher-origin `authoritative_location` pointer or `superseded_by` migration may explicitly delegate to another HTTPS origin once; that target cannot redirect again. Properties from a cross-origin document must explicitly name their `publisher_domain`; unscoped shared-network properties cannot authorize another publisher. Credentials, nonstandard ports, mixed pointer/catalog files and chained pointers fail closed. This stricter authoritative API does not use community catalogs, cached fallback documents or MANAGERDOMAIN discovery. Those discovery routes need additional publisher scope proofs before they can serve as enforcement evidence. + +Collections in a cross-origin authoritative document must explicitly name their owning `publisher_domain`, just as shared host properties must identify their publisher. A domain pointing at an unrelated public catalog cannot borrow that catalog's collections, including through weaker inventory-partner evidence. Publisher-origin collection declarations may omit the field. Owner agent grants in shared cross-origin documents must also explicitly select that owner through `collections[].publisher_domain`; an absent `collections` constraint cannot authorize every member. Within that owner namespace, omitted `collection_ids` still grants all collections. + +Authoritative locations are pinned only after the first successfully fetched, parsed, non-chained manifest with the required authorization envelope. Unavailable or malformed targets do not establish a pin. `SupplyPathAuthorityStore.check` is a non-mutating precheck that rejects a different existing pin before fetching its target. After validation, `observe` must atomically insert an absent pin or compare against the existing pin, rejecting a mismatch even when another request or operator changed it after the precheck. A successful `check` is neither a reservation nor authorization; verification requires a successful `observe`. Configure a durable shared store across restarts or workers, and perform the final comparison and insert in one transaction scoped to the trusted tenant and publisher. After independently confirming a publisher migration, update the durable pin or call `approveChange` on your in-memory instance. For the process default, import `defaultSupplyPathAuthorities` from `@adcp/sdk` and call `defaultSupplyPathAuthorities.approveChange(publisherDomain, confirmedHttpsLocation)`. Never approve changes from an automatic retry. First-successful-use pinning cannot detect an origin already compromised before that observation. + +The default deadline is 15 seconds for the whole path (or whole annotation batch), configurable up to 60 seconds. Each decompressed response is capped at 256 KiB, configurable up to 20 MiB, with a 64 MiB aggregate evidence budget per operation. The evaluator rejects arrays above 1,024 entries, strings above 8,192 characters, total input above 32,768 values, or a conservative selector-work estimate above four million operations with `evaluation_limit_exceeded`. Cancellation is supported through `signal`. `trustedFetchFn` is an explicit advanced egress hook: it assumes responsibility for DNS resolution, address policy and DNS rebinding protection; its evidence reports `connection_pinned: false`. It must honor request cancellation and manual redirect handling. + +Evidence contains requested/resolved URLs, HTTP status, fetch time, SHA-256 of exact decompressed bytes, byte count, connection-pinning status and structured failure codes. `retainEvidenceBodies` also retains those bytes as JSON-safe `body_base64`, including pointer and HTTP redirect documents. Retain the entire chain alongside an enforcement decision. Bodies are untrusted publisher content; store them as opaque evidence, not instructions or trusted log fields. A live fetch is an observation at `fetched_at`, not a permanent authorization grant; reverify before subsequent decisions when freshness matters. + +`inventory_partner_domain.failure: 'not_evaluated'` means the IAB fetch was skipped because host authorization already established the strongest state. A 404 is fetched-and-absent (`not_declared`); transport failures remain `ads_txt_unavailable`, with the cause in evidence. Websites use ads.txt, apps use app-ads.txt, and mixed surfaces require the owner in every applicable file. `unsupported_constraints` identifies unevaluated grant fields in `detail`. + +Validated publisher revocations are persisted immediately after parsing, before later fetches or authority-store operations can fail. They are held for seven days per publisher authority, including after the next manifest omits them. The default `InMemorySupplyPathRevocationStore` holds them for the process lifetime. For enforcement across restarts or multiple workers, configure a durable shared `SupplyPathRevocationStore`; its `observe` operation must be atomic and retain first-observation expiry by publisher domain within each authority, retaining the first-observation clock when `revoked_at` changes. Store failures and malformed revocation evidence reject verification. `sources.held_revocations` records the hold used in the decision. Keep observations from different publisher authorities isolated. The process-local store admits at most 1,024 live revocations per authority and 10,000 overall. Both process-local stores limit admission to 128 new authorities per 60-second window; the revocation store counts authorities with a new nonempty hold, and the pointer store counts first pins. Existing holds and pins remain readable during admission refusals. Pointer storage is capped at 10,000 authorities for the process lifetime. Overflow rejects verification without evicting live evidence or silently adopting a replacement pin. + +These defaults are shared by callers in the process. A sustained many-domain attack can still exhaust their finite capacity, including domains controlled under a wildcard. Rate-limit verification requests by authenticated caller or tenant before invoking the API; publisher domain alone is not an abuse-control identity. For multi-tenant enforcement, pass tenant-scoped durable `revocationStore` and `authorityStore` instances. Capture the tenant from trusted application context in each instance, then key revocations by `(tenant, authority, publisher_domain)` and pins by `(tenant, publisher_domain)`. Make capacity/admission limits and transactions tenant-scoped, and reject exhausted writes instead of deleting live evidence. Neither store interface derives a tenant from counterparty evidence. Do not recover from capacity errors by silently replacing a store with an empty one. + +Authority-store keys use the exact serialized HTTPS URL supplied by the verifier. URLs containing a fragment delimiter, including an empty trailing `#`, are refused. Preserve query and path spelling rather than merging potentially distinct server resources. The request deadline bounds the caller's wait; a durable `observe` transaction may complete after the caller times out. It still represents a successfully validated manifest, so retries must be idempotent and must not undo that pin or any retained denial. + +## Contract and conformance + +The state/leg contract originates in [adcp#6897](https://github.com/adcontextprotocol/adcp/pull/6897) and its fail-closed companion. Both implementations execute the same [canonical supply-path vectors](https://github.com/adcontextprotocol/adcp/tree/main/static/compliance/source/test-vectors/supply-path), including each verdict, resolved collection, leg failure, parser result, and applicable IAB-file policy. The SDK vendors the JSON byte-for-byte from a reviewed upstream commit; provenance and checksums are recorded in `test/fixtures/supply-path/source.json`. Updating it requires selecting a reviewed upstream commit and rerunning both implementations. The runtime `semantics_version` prevents silent acceptance of registries running the older fail-open evaluator. 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/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; 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/AgentClient.ts b/src/lib/core/AgentClient.ts index e1eed2031..cdaeee2cd 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,7 +820,7 @@ export class AgentClient { params: ListProductsRequest, inputHandler?: InputHandler, options?: TaskOptions - ): Promise> { + ): Promise> { const result = await this.client.executeTask( 'list_products', params, 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 6966f7393..1eda14d19 100644 --- a/src/lib/core/SingleAgentClient.ts +++ b/src/lib/core/SingleAgentClient.ts @@ -1,3 +1,8 @@ +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'; @@ -19,6 +24,7 @@ import { isExternalSchemaRootActive, schemaAllowsTopLevelField } from '../valida import type { GetProductsRequest, GetProductsResponse, + ListProductsRequest, PropertyListReference, ListCreativeFormatsRequest, ListCreativeFormatsResponse, @@ -1499,6 +1505,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; @@ -4771,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) { @@ -4828,14 +4836,21 @@ export class SingleAgentClient { if (result.submitted && rawSubmittedWaitForCompletion) { result.submitted = { ...result.submitted, - waitForCompletion: async (pollInterval, signal) => - this.finalizeTaskResult( - await rawSubmittedWaitForCompletion(pollInterval, signal), + 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 } : {}) }; + const completed = await rawSubmittedWaitForCompletion(pollInterval, signal); + return this.finalizeTaskResult( + completed, context, - options, + completed.success && completed.status === 'completed' ? completionOptions : options, transformCompletedResponse, finalizerLegacyFormatConverter - ), + ); + }, }; } @@ -5324,13 +5339,33 @@ 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 // 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 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 } }; + } + } const policyConfig = this.config.validation?.productPropertyPolicy; if (policyConfig === false || taskType !== 'get_products') return result; @@ -5525,7 +5560,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 +5648,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> } = { @@ -5633,7 +5678,8 @@ export class SingleAgentClient { return await this.applyProductPropertyPolicyToTaskInfo( taskInfo, taskType, - (policyState.request ?? {}) as Record + (policyState.request ?? {}) as Record, + options?.signal ); } finally { if (terminal) { @@ -5652,7 +5698,8 @@ export class SingleAgentClient { return await this.applyProductPropertyPolicy( completed, taskType, - (policyState.request ?? {}) as Record + (policyState.request ?? {}) as Record, + signal ?? options?.signal ); } finally { if (terminal) { @@ -5673,9 +5720,16 @@ export class SingleAgentClient { private async applyProductPropertyPolicyToTaskInfo( taskInfo: TaskInfo, taskType: string, - requestParams: Record + requestParams: Record, + taskSignal?: AbortSignal ): 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({ @@ -5694,7 +5748,8 @@ export class SingleAgentClient { debug_logs: [], }), taskType, - requestParams + requestParams, + taskSignal ); if (policyResult.success) { @@ -5734,7 +5789,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 }; } @@ -6108,6 +6168,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, @@ -7296,6 +7371,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/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..42920ce5d 100644 --- a/src/lib/discovery/types.ts +++ b/src/lib/discovery/types.ts @@ -104,6 +104,35 @@ 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 { + /** Required when a shared cross-origin document declares this publisher-scoped collection. */ + publisher_domain?: string; + 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 +146,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 +225,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..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, @@ -2318,3 +2319,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..e00512199 --- /dev/null +++ b/src/lib/supply-path/evaluate.ts @@ -0,0 +1,595 @@ +/** + * 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 { MediaChannelValues, PropertyIdentifierTypesValues, PropertyTypeValues } from '../types/enums.generated'; +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))) + ); +} + +const PROPERTY_TYPES = new Set(PropertyTypeValues); +const PROPERTY_IDENTIFIER_TYPES = new Set([ + ...PropertyIdentifierTypesValues, + // Retained only for the pinned canonical corpus, whose CTV properties use + // this distribution identifier in property records. + 'roku_channel_id', +]); +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 { + 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(isValidPropertyRecord) + ); + } + 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 { + for (const raw of entry.publisher_properties) { + const selector = parsePublisherPropertySelector(raw); + const value = raw as Record; + if ( + (selector.selection_type === 'by_id' && + (!isPropertyTokenList(value.property_ids) || value.property_tags !== undefined)) || + (selector.selection_type === 'by_tag' && + (!isPropertyTokenList(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; + } + } + return false; +} + +/** Resolve one entry at a time: separate grants are alternatives, never merged across collection scopes. */ +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 => + isValidPropertyRecord(p) && + ((p.publisher_domain === undefined && !requirePublisher) || 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. + 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 => + 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) + ); +} + +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) + ) + ); +} + +/** 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', + '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; +} + +/** 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', + 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 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 evaluationLimitVerdict(); + } + // 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).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'; + 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 => + 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); + 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 && + hasPropertyAuthorizationEnvelope(e) && + (!input.requireExplicitOwnerPublisherDomain || e.collections !== undefined) && + 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 (!hasPropertyAuthorizationEnvelope(e) || unsupportedConstraints(e).length) return false; + const scope = propertyScope(e, host, hostManifest, input.requireExplicitHostPublisherDomain); + 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)) && + ((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'); + 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..c41c7ce2f --- /dev/null +++ b/src/lib/supply-path/fetch-evidence.ts @@ -0,0 +1,311 @@ +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, type SupplyPathRevocation } from './revocations'; +import { agentIdentity, 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 crossOriginAuthorities = new Set(); + private readonly observedRevocations = new Map(); + readonly revocations = new Map(); + 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; + 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.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); + 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); + } + /** 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) { + 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.assertActive(); + 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 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 + : 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, + ...(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; + return null; + } + } + 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)); + if (!record(document)) throw new Error('not_object'); + } catch { + 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'); + 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]); + // 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 { + 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 authorityLocation = url; + let documentResponse = 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; + if ( + typeof target !== 'string' || + target.length > 8192 || + (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; + 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.href.includes('#') || + (location.port && location.port !== '443') + ) { + this.documentError(publisher, initial, 'invalid_authoritative_location'); + return null; + } + 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 = 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'); + return null; + } + } else { + await this.checkAuthority(publisher, authorityLocation, 'check'); + } + 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; + } + 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, operation: 'check' | 'observe'): Promise { + let accepted: boolean; + try { + accepted = await withAbortSignal([this.signal], undefined, () => + (this.options.authorityStore ?? defaultSupplyPathAuthorities)[operation](publisher, location) + ); + } catch (cause) { + this.signal.throwIfAborted(); + 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) + throw new TypeError( + `Authoritative location changed for ${publisher}; independently confirm the publisher migration before updating its pin` + ); + } + 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 { + 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 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. + const effective = [...new Map([...held, ...observed].map(entry => [entry.publisher_domain, entry])).values()]; + this.revocations.set(publisher, effective); + return effective; + } +} diff --git a/src/lib/supply-path/index.ts b/src/lib/supply-path/index.ts new file mode 100644 index 000000000..23289e34b --- /dev/null +++ b/src/lib/supply-path/index.ts @@ -0,0 +1,20 @@ +export * from './types'; +export { verifySupplyPath } from './verify'; +export { evaluateSupplyPath, parseInventoryPartnerDomains, SUPPLY_PATH_STATES } from './evaluate'; +export { + annotateProductsSupplyPaths, + type AnnotatedSupplyPathProduct, + type ListProductsResponseWithSupplyPath, + type ProductSupplyPathAnnotation, + type ProductSupplyPathOptions, +} from './products'; +export { + InMemorySupplyPathRevocationStore, + 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 new file mode 100644 index 000000000..09e7c63dc --- /dev/null +++ b/src/lib/supply-path/products.ts @@ -0,0 +1,298 @@ +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 } from '../discovery/publisher-property-selector'; +import type { + SupplyPathRequest, + SupplyPathState, + RegistrySupplyPathResult, + AuthoritativeSupplyPathResult, + RegistrySupplyPathOptions, + AuthoritativeSupplyPathOptions, +} 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 AnnotatedSupplyPathProduct = Omit & + ProductSupplyPathAnnotation; +type AnnotatedListProductsResponse = T extends unknown + ? { + [K in keyof T]: K extends 'products' + ? Array[number]>> + : T[K]; + } + : never; +export type ListProductsResponseWithSupplyPath = AnnotatedListProductsResponse; +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. */ + timeoutMs?: number; + 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 + * 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>> { + 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') + 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[] = []; + 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(hasValidPropertySelectorPredicate)) + throw new Error('invalid_product_selector_predicate'); + const selectorsByHost = new Map>(); + let selectorExpansions = 0; + let selectorValues = 0; + let selectorBytes = 0; + for (const raw of value.publisher_properties) { + checkPreprocessingBudget(); + 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'); + 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 collectionIdsByOwner = new Map>(); + for (const selector of value.collections) { + checkPreprocessingBudget(); + 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)!; + 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, 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({ + owner_domain: owner, + host_domain: host, + agent_url: agentUrl, + collection_id: id, + }); + 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 }; + } + requests.set(key, { request, selectors }); + if (!keys.includes(key)) keys.push(key); + } + } + } + } 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 }; + }); + const outcomes = new Map(); + // Bound fan-out without allocating one network operation per product. + const pending = [...requests.entries()]; + let position = 0; + 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')), + Math.max(1, deadlineAt - Date.now()) + ); + let session: SupplyPathEvidenceSession | undefined; + let onDeadline: () => void = () => {}; + try { + session = + options.source === 'authoritative' + ? new SupplyPathEvidenceSession({ + ...options, + signal: controller.signal, + timeoutMs: Math.max(1, deadlineAt - Date.now()), + }) + : undefined; + 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 AnnotatedSupplyPathProduct; + 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 AnnotatedSupplyPathProduct; + }); +} diff --git a/src/lib/supply-path/revocations.ts b/src/lib/supply-path/revocations.ts new file mode 100644 index 000000000..59a4aeb36 --- /dev/null +++ b/src/lib/supply-path/revocations.ts @@ -0,0 +1,142 @@ +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; + /** Publisher timestamp, or `unspecified` for a legacy domain-only declaration. Never use this as the hold expiry. */ + revoked_at: string; +} +/** + * Atomic, authority-scoped seven-day revocation hold. Durable implementations + * 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. + * 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; +} + +/** 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]); + 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. + 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; +} + +/** + * 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. */ + 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. */ +export class InMemorySupplyPathAuthorityStore implements SupplyPathAuthorityStore { + 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'); + 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 { + 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/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..e59fe535c --- /dev/null +++ b/src/lib/supply-path/supply-path.type-checks.ts @@ -0,0 +1,73 @@ +import { + verifySupplyPath, + annotateProductsSupplyPaths, + type AuthorizationCollectionSelector, + type ProductCollectionSelector, + 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; +// @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 [ + incompleteAuthorityStore, + 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..f2401418c --- /dev/null +++ b/src/lib/supply-path/types.ts @@ -0,0 +1,184 @@ +/** 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[]; + /** 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; + /** + * 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; + /** 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; +} + +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; + /** 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. */ + body_base64?: string; +} + +export interface AuthoritativeSupplyPathResult extends Omit { + source: 'authoritative'; + legs: SupplyPathLegs; + property_selectors?: import('../discovery/types').SinglePublisherPropertySelector[]; + sources: Pick & { + 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; + /** 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[]; + /** 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..2a1ef7feb --- /dev/null +++ b/src/lib/supply-path/validation.ts @@ -0,0 +1,152 @@ +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 = (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('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('legs and sources must be objects'); + if (!['verified_owner_sold', 'host_delegated', 'owner_attested', 'unverified'].includes(String(value.state))) + 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('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('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(`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(`sources.${key} must be an HTTPS URL without credentials`); + } catch { + 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(`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(`sources.${key} must be null or a bounded HTTPS URL`); + try { + const parsed = new URL(location); + if ( + parsed.protocol !== 'https:' || + parsed.username || + parsed.password || + parsed.hash || + (parsed.port && parsed.port !== '443') + ) + return fail(`sources.${key} must be an HTTPS URL without credentials, fragments, or nonstandard ports`); + } catch { + return fail(`sources.${key} must be a valid URL`); + } + } + 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(`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(`legs.${key}.${ids} must contain only string property IDs`); + } + } + 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('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('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('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 new file mode 100644 index 000000000..3365a3bb7 --- /dev/null +++ b/src/lib/supply-path/verify.ts @@ -0,0 +1,258 @@ +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, + hasValidPropertySelectorPredicate, + evaluateSupplyPath, + evaluationLimitVerdict, + supplyPathAdsTxtPolicy, + parseInventoryPartnerDomains, +} from './evaluate'; +import { assertRegistrySupplyPathResult, validateSupplyPathRequest } from './validation'; +import type { + SupplyPathRequest, + VerifySupplyPathOptions, + RegistrySupplyPathOptions, + AuthoritativeSupplyPathOptions, + RegistrySupplyPathResult, + 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. + * 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 +): Promise; +export function verifySupplyPath( + request: SupplyPathRequest, + options?: AuthoritativeSupplyPathOptions +): Promise; +export function verifySupplyPath( + request: SupplyPathRequest, + options: VerifySupplyPathOptions +): Promise; +export async function verifySupplyPath( + request: SupplyPathRequest, + options: VerifySupplyPathOptions = { source: 'authoritative' } +): Promise { + const normalized = validateSupplyPathRequest(request); + 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 { + 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 { + 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)) + 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), + ]); + const input = { + ownerDomain: normalized.owner_domain, + hostDomain: normalized.host_domain, + agentUrl: normalized.agent_url, + 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'], + 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; + let selectorLimitExceeded = false; + if (options.propertySelectors !== undefined) { + const ids = new Set(); + 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 ( + !Array.isArray(property.tags) || + property.tags.length > 1024 || + property.tags.some(tag => typeof tag !== 'string' || !tag.trim()) + ) { + 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); + 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'); + 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 (scopeValues > MAX_PROPERTY_SCOPE_VALUES) selectorLimitExceeded = true; + if (!selectorLimitExceeded && (selectAll || selectedTags.size)) { + for (const property of properties) { + session.assertActive(); + 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); + } + } + scopedInput.requiredHostPropertyIds = selectorLimitExceeded || unresolved ? [] : [...ids]; + } + 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( + 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, + ]) + ); + session.assertActive(); + verdict = evaluateSupplyPath(scopedInput); + session.assertActive(); + } else if (verdict.legs.host_authorization.ok) { + verdict = evaluateSupplyPath({ ...scopedInput, inventoryPartnerDomainEvaluated: false }); + session.assertActive(); + } + session.assertActive(); + 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..a5a448126 --- /dev/null +++ b/test/fixtures/supply-path/source.json @@ -0,0 +1,7 @@ +{ + "repository": "adcontextprotocol/adcp", + "commit": "dc69e0b2264b4c563f2175a48c515b7108dbb4f6", + "path": "static/compliance/source/test-vectors/supply-path/vectors.json", + "sha256": "1a239d61209896aad843375d307650fb22dbfe7a8c73ebb900d8aec6d58abd31", + "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..955f5633a --- /dev/null +++ b/test/fixtures/supply-path/vectors.json @@ -0,0 +1,8648 @@ +{ + "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", + "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": { + "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", + "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": { + "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", + "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": { + "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", + "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": { + "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", + "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": { + "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", + "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": { + "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", + "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": { + "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", + "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": { + "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", + "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": { + "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", + "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": { + "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", + "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": { + "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", + "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": { + "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", + "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": { + "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", + "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", + "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", + "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": { + "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", + "authorization_type": "property_ids", + "property_ids": [ + "owner_inventory" + ] + } + ], + "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", + "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" + ], + "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", + "authorization_type": "property_ids", + "property_ids": [ + "owner_inventory" + ] + } + ], + "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", + "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": { + "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", + "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": { + "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", + "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": { + "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", + "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": { + "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", + "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": { + "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", + "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": { + "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", + "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": { + "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", + "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": { + "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", + "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": { + "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", + "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": { + "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", + "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": { + "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", + "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": { + "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", + "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" + ] + } + ] + }, + { + "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", + "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": { + "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": "owner-agent-missing-discriminator", + "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": "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": { + "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", + "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": { + "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", + "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": { + "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", + "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": { + "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", + "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": { + "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", + "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": { + "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", + "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": { + "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", + "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" + ] + } + ] + } + ], + "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", + "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" + ] + } + ] + } + ], + "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", + "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": { + "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", + "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": { + "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", + "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": { + "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", + "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": { + "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", + "authorization_type": "property_ids", + "property_ids": [ + "owner_inventory" + ] + } + ], + "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", + "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": { + "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", + "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": { + "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", + "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": { + "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", + "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, + "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", + "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" + ] + } + ] + }, + { + "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" + } + }, + { + "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", + "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": { + "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", + "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": { + "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", + "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": { + "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", + "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": { + "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", + "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": { + "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", + "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": { + "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", + "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": { + "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", + "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": { + "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", + "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": { + "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", + "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": { + "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", + "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": { + "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", + "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": { + "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", + "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": { + "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", + "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": { + "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", + "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": { + "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" + ] + } + ], + "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" + ] + } + ], + "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" + ] + } + ], + "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" + ] + } + ], + "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", + "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" + ] + } + ], + "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" + } + ], + "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" + ] + } + ], + "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" + } + ], + "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" + ] + } + ], + "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": [], + "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" + ] + } + ], + "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": "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": [ + { + "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/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/); }); diff --git a/test/lib/product-property-policy-client.test.js b/test/lib/product-property-policy-client.test.js index 75097379b..334aead20 100644 --- a/test/lib/product-property-policy-client.test.js +++ b/test/lib/product-property-policy-client.test.js @@ -657,3 +657,174 @@ 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', () => { + 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); + }); + + 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 = [ + 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', + 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(), + }), + }, + }, + }, + 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-types.test.js b/test/lib/supply-path-types.test.js new file mode 100644 index 000000000..6e25bf9d3 --- /dev/null +++ b/test/lib/supply-path-types.test.js @@ -0,0 +1,94 @@ +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, + ListProductsResponse, + ListProductsResponseWithSupplyPath, + ListProductsStatusChangeHandler, + SupplyPathState, + TaskResult, +} from '${modulePath}'; +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; +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; +}; +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; +}); +annotateProductsSupplyPaths([], 'https://sales.example', { + source: 'authoritative', + // @ts-expect-error Annotation property scope is always derived from each product. + propertySelectors: [], +}); +void handler; +void backwardsCompatible; +void unchangedResponse; +` + ); + + 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 new file mode 100644 index 000000000..6bd26c1b4 --- /dev/null +++ b/test/lib/supply-path.test.js @@ -0,0 +1,1501 @@ +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: 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'; +function input() { + return { + ownerDomain: OWNER, + hostDomain: HOST, + agentUrl: AGENT, + collectionId: 'retro_news', + hostInventoryPartnerDomains: null, + ownerManifest: { + 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', + publisher_domain: OWNER, + 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' } }); + }; +} + +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(() => {}), observe: async () => true }, + 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', () => { + 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('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'); + }); + 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(); + 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'], + ]) { + 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] = { + 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/ + ); + }); + 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 = []; + 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', () => { + it('posts only the canonical request and preserves registry evidence', async () => { + const response = { + ...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, + }, + 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_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'] }; + 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('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( + 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', () => { + 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('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}`); + 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(); + 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; + 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'); + }, + }, + }), + /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_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 => + 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; + // 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 }, + { + 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 revoked_publisher_domains in adagents\.json for hoststream\.example/ + ); +}); + +// 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.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); + now += 60001; + } + const authority = 'host-' + i + '.attacker.example'; + await revocations.observe(authority, denial); + 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.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++) { + 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', + 'https://cdn.example/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] + ); + } +}); + +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' } }), + 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)) { + 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 revocationStore = new sdk.InMemorySupplyPathRevocationStore(); + 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, + revocationStore, + trustedFetchFn: transport({ + [`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), { + headers: { 'content-type': 'application/json' }, + }); + }, + }), + }), + /Authoritative location changed/ + ); + 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, { + source: 'authoritative', + timeoutMs: 25, + authorityStore: { check: async () => true, observe: () => new Promise(() => {}) }, + trustedFetchFn: transport(), + }), + /deadline|abort/i + ); + }); +}); 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",