@adcp/sdk 14.0.0-rc.39 → 14.0.0-rc.40

package/dist/lib/supply-path/revocations.js

@@ -0,0 +1,127 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var revocations_exports = {};
+__export(revocations_exports, {
+  InMemorySupplyPathAuthorityStore: () => InMemorySupplyPathAuthorityStore,
+  InMemorySupplyPathRevocationStore: () => InMemorySupplyPathRevocationStore,
+  defaultSupplyPathAuthorities: () => defaultSupplyPathAuthorities,
+  defaultSupplyPathRevocations: () => defaultSupplyPathRevocations,
+  parseRevocations: () => parseRevocations
+});
+module.exports = __toCommonJS(revocations_exports);
+var import_validation = require('./validation.js');
+class AuthorityAdmissionBudget {
+  windowStart = Date.now();
+  admitted = 0;
+  consume() {
+    const now = Date.now();
+    if (now >= this.windowStart + 6e4) {
+      this.windowStart = now;
+      this.admitted = 0;
+    }
+    if (this.admitted >= 128) throw new Error("Supply-path new-authority admission rate exceeded");
+    this.admitted++;
+  }
+}
+class InMemorySupplyPathRevocationStore {
+  admission = new AuthorityAdmissionBudget();
+  entries = /* @__PURE__ */ new Map();
+  async observe(authority, revoked) {
+    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 > 1e4) 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;
+      }
+      this.entries.set(key, { authority, entry: { ...entry }, expires: now + 7 * 864e5 });
+    }
+    return [...this.entries.values()].filter((value) => value.authority === authority).map((value) => ({ ...value.entry }));
+  }
+}
+const defaultSupplyPathRevocations = new InMemorySupplyPathRevocationStore();
+function parseRevocations(value) {
+  if (value === void 0) return [];
+  if (!Array.isArray(value) || value.length > 1024) return null;
+  const entries = [];
+  for (const raw of value) {
+    const publisher = (0, import_validation.domain)((0, import_validation.record)(raw) ? raw.publisher_domain : raw);
+    if (!publisher) return null;
+    const timestamp = (0, import_validation.record)(raw) ? raw.revoked_at : void 0;
+    if (timestamp !== void 0 && (typeof timestamp !== "string" || !Number.isFinite(Date.parse(timestamp))))
+      return null;
+    entries.push({
+      publisher_domain: publisher,
+      revoked_at: typeof timestamp === "string" ? timestamp : "unspecified"
+    });
+  }
+  return entries;
+}
+class InMemorySupplyPathAuthorityStore {
+  admission = new AuthorityAdmissionBudget();
+  locations = /* @__PURE__ */ new Map();
+  async check(publisherDomain, location) {
+    this.assertBoundedLocation(location);
+    const pinned = this.locations.get(publisherDomain);
+    return pinned === void 0 || pinned === location;
+  }
+  async observe(publisherDomain, location) {
+    this.assertBoundedLocation(location);
+    const pinned = this.locations.get(publisherDomain);
+    if (pinned !== void 0) return pinned === location;
+    if (this.locations.size >= 1e4) 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, location) {
+    this.assertBoundedLocation(location);
+    if (!this.locations.has(publisherDomain) && this.locations.size >= 1e4)
+      throw new Error("Supply-path authority store capacity exceeded");
+    if (!this.locations.has(publisherDomain)) this.admission.consume();
+    this.locations.set(publisherDomain, location);
+  }
+  assertBoundedLocation(location) {
+    if (typeof location !== "string" || location.length === 0 || location.length > 8192)
+      throw new TypeError("Supply-path authority location must contain 1 to 8192 characters");
+  }
+}
+const defaultSupplyPathAuthorities = new InMemorySupplyPathAuthorityStore();
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  InMemorySupplyPathAuthorityStore,
+  InMemorySupplyPathRevocationStore,
+  defaultSupplyPathAuthorities,
+  defaultSupplyPathRevocations,
+  parseRevocations
+});

package/dist/lib/supply-path/revocations.mjs

@@ -0,0 +1,99 @@
+import { domain, record } from "./validation.mjs";
+class AuthorityAdmissionBudget {
+  windowStart = Date.now();
+  admitted = 0;
+  consume() {
+    const now = Date.now();
+    if (now >= this.windowStart + 6e4) {
+      this.windowStart = now;
+      this.admitted = 0;
+    }
+    if (this.admitted >= 128) throw new Error("Supply-path new-authority admission rate exceeded");
+    this.admitted++;
+  }
+}
+class InMemorySupplyPathRevocationStore {
+  admission = new AuthorityAdmissionBudget();
+  entries = /* @__PURE__ */ new Map();
+  async observe(authority, revoked) {
+    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 > 1e4) 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;
+      }
+      this.entries.set(key, { authority, entry: { ...entry }, expires: now + 7 * 864e5 });
+    }
+    return [...this.entries.values()].filter((value) => value.authority === authority).map((value) => ({ ...value.entry }));
+  }
+}
+const defaultSupplyPathRevocations = new InMemorySupplyPathRevocationStore();
+function parseRevocations(value) {
+  if (value === void 0) return [];
+  if (!Array.isArray(value) || value.length > 1024) return null;
+  const entries = [];
+  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 : void 0;
+    if (timestamp !== void 0 && (typeof timestamp !== "string" || !Number.isFinite(Date.parse(timestamp))))
+      return null;
+    entries.push({
+      publisher_domain: publisher,
+      revoked_at: typeof timestamp === "string" ? timestamp : "unspecified"
+    });
+  }
+  return entries;
+}
+class InMemorySupplyPathAuthorityStore {
+  admission = new AuthorityAdmissionBudget();
+  locations = /* @__PURE__ */ new Map();
+  async check(publisherDomain, location) {
+    this.assertBoundedLocation(location);
+    const pinned = this.locations.get(publisherDomain);
+    return pinned === void 0 || pinned === location;
+  }
+  async observe(publisherDomain, location) {
+    this.assertBoundedLocation(location);
+    const pinned = this.locations.get(publisherDomain);
+    if (pinned !== void 0) return pinned === location;
+    if (this.locations.size >= 1e4) 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, location) {
+    this.assertBoundedLocation(location);
+    if (!this.locations.has(publisherDomain) && this.locations.size >= 1e4)
+      throw new Error("Supply-path authority store capacity exceeded");
+    if (!this.locations.has(publisherDomain)) this.admission.consume();
+    this.locations.set(publisherDomain, location);
+  }
+  assertBoundedLocation(location) {
+    if (typeof location !== "string" || location.length === 0 || location.length > 8192)
+      throw new TypeError("Supply-path authority location must contain 1 to 8192 characters");
+  }
+}
+const defaultSupplyPathAuthorities = new InMemorySupplyPathAuthorityStore();
+export {
+  InMemorySupplyPathAuthorityStore,
+  InMemorySupplyPathRevocationStore,
+  defaultSupplyPathAuthorities,
+  defaultSupplyPathRevocations,
+  parseRevocations
+};

package/dist/lib/supply-path/types.d.mts

@@ -0,0 +1,168 @@
+/** Supply-path contract from adcontextprotocol/adcp#6897. */
+import type { SsrfFetchOptions } from '../net/ssrf-fetch.mjs';
+import type { RegistryClient } from '../registry/index.mjs';
+/** 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<F extends string> {
+    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<OwnerCollectionFailure>;
+    /** The collection's distribution[] names the host, and any property_ids resolve in the host manifest. */
+    owner_distribution_carriage: Leg<OwnerCarriageFailure> & {
+        property_ids_matched?: string[];
+        property_ids_unmatched?: string[];
+    };
+    /** Owner's own adagents.json lists the sales agent. */
+    owner_agent_declared: Leg<OwnerAgentFailure>;
+    /** Host adagents.json authorizes the agent for the property, collection-scoped. */
+    host_authorization: Leg<HostAuthorizationFailure> & {
+        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<Record<'ads.txt' | 'app-ads.txt', string[] | null>>;
+    /** 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<SupplyPathVerdict, 'legs'> {
+    legs: {
+        [K in keyof SupplyPathLegs]: Omit<SupplyPathLegs[K], 'failure'> & {
+            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<RegistrySupplyPathResult, 'sources'> {
+    source: 'authoritative';
+    legs: SupplyPathLegs;
+    property_selectors?: import('../discovery/types.mjs').SinglePublisherPropertySelector[];
+    sources: Pick<RegistrySupplyPathResult['sources'], 'owner_adagents_url' | 'host_adagents_url'> & {
+        cached: false;
+        evidence: SupplyPathEvidence[];
+        held_revocations: Array<{
+            authority: string;
+            entries: readonly import('./revocations.mjs').SupplyPathRevocation[];
+        }>;
+    };
+}
+export interface AuthoritativeSupplyPathOptions {
+    source: 'authoritative';
+    /** Defaults to a process-local seven-day hold; supply durable storage across workers/restarts. */
+    revocationStore?: import('./revocations.mjs').SupplyPathRevocationStore;
+    /** Read-only check plus atomic observe pins only validated manifests; changed locations require confirmed migration. */
+    authorityStore?: import('./revocations.mjs').SupplyPathAuthorityStore;
+    /** Optional product property scope. Every selected host property must be proven. */
+    propertySelectors?: import('../discovery/types.mjs').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<RegistryClient, 'verifySupplyPath'>;
+}
+export type VerifySupplyPathOptions = AuthoritativeSupplyPathOptions | RegistrySupplyPathOptions;

package/dist/lib/supply-path/types.d.ts

@@ -0,0 +1,168 @@
+/** 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<F extends string> {
+    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<OwnerCollectionFailure>;
+    /** The collection's distribution[] names the host, and any property_ids resolve in the host manifest. */
+    owner_distribution_carriage: Leg<OwnerCarriageFailure> & {
+        property_ids_matched?: string[];
+        property_ids_unmatched?: string[];
+    };
+    /** Owner's own adagents.json lists the sales agent. */
+    owner_agent_declared: Leg<OwnerAgentFailure>;
+    /** Host adagents.json authorizes the agent for the property, collection-scoped. */
+    host_authorization: Leg<HostAuthorizationFailure> & {
+        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<Record<'ads.txt' | 'app-ads.txt', string[] | null>>;
+    /** 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<SupplyPathVerdict, 'legs'> {
+    legs: {
+        [K in keyof SupplyPathLegs]: Omit<SupplyPathLegs[K], 'failure'> & {
+            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<RegistrySupplyPathResult, 'sources'> {
+    source: 'authoritative';
+    legs: SupplyPathLegs;
+    property_selectors?: import('../discovery/types').SinglePublisherPropertySelector[];
+    sources: Pick<RegistrySupplyPathResult['sources'], 'owner_adagents_url' | 'host_adagents_url'> & {
+        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<RegistryClient, 'verifySupplyPath'>;
+}
+export type VerifySupplyPathOptions = AuthoritativeSupplyPathOptions | RegistrySupplyPathOptions;

package/dist/lib/supply-path/types.js

@@ -0,0 +1,16 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var types_exports = {};
+module.exports = __toCommonJS(types_exports);

package/dist/lib/supply-path/validation.d.mts

@@ -0,0 +1,10 @@
+import type { SupplyPathRequest } from './types.mjs';
+export declare function record(value: unknown): value is Record<string, unknown>;
+export declare function records(value: unknown): Record<string, unknown>[];
+export declare function strings(value: unknown): value is string[];
+/** Domain identity never strips www or conflates sibling publisher namespaces. */
+export declare function domain(value: unknown): string | null;
+export declare function agentIdentity(value: unknown): string | null;
+export declare function validateSupplyPathRequest(input: SupplyPathRequest): SupplyPathRequest;
+/** Runtime boundary for cached remote verdicts. Unknown extensions are preserved. */
+export declare function assertRegistrySupplyPathResult(value: unknown, request: SupplyPathRequest): asserts value is import('./types.mjs').RegistrySupplyPathResult;

package/dist/lib/supply-path/validation.d.ts

@@ -0,0 +1,10 @@
+import type { SupplyPathRequest } from './types';
+export declare function record(value: unknown): value is Record<string, unknown>;
+export declare function records(value: unknown): Record<string, unknown>[];
+export declare function strings(value: unknown): value is string[];
+/** Domain identity never strips www or conflates sibling publisher namespaces. */
+export declare function domain(value: unknown): string | null;
+export declare function agentIdentity(value: unknown): string | null;
+export declare function validateSupplyPathRequest(input: SupplyPathRequest): SupplyPathRequest;
+/** Runtime boundary for cached remote verdicts. Unknown extensions are preserved. */
+export declare function assertRegistrySupplyPathResult(value: unknown, request: SupplyPathRequest): asserts value is import('./types').RegistrySupplyPathResult;