@adcp/sdk 14.0.0 → 14.2.0

package/dist/lib/signing/agent-resolver/legacy-brand.js

@@ -0,0 +1,60 @@
+"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 legacy_brand_exports = {};
+__export(legacy_brand_exports, {
+  fetchLegacyBrandJson: () => fetchLegacyBrandJson
+});
+module.exports = __toCommonJS(legacy_brand_exports);
+var import_brand_jwks = require('../brand-jwks.js');
+var import_etld = require('./etld.js');
+var import_fetch_helpers = require('./fetch-helpers.js');
+async function fetchLegacyBrandJson(agentUrl, options) {
+  const agent = new URL(agentUrl);
+  let startUrl = `${agent.origin}/.well-known/brand.json`;
+  const fetch = (url) => (0, import_brand_jwks.fetchBrandJson)({ ...options, startUrl: url, domainDerived: true, maxRedirects: 1 });
+  let result;
+  try {
+    try {
+      result = await fetch(startUrl);
+    } catch (err) {
+      if (!(err instanceof import_brand_jwks.BrandJsonResolverError) || err.httpStatus !== 404 && err.httpStatus !== 410) throw err;
+      const domain = (0, import_etld.eTldPlusOne)(agentUrl);
+      if (domain === agent.hostname) throw err;
+      startUrl = `https://${domain}/.well-known/brand.json`;
+      result = await fetch(startUrl);
+    }
+  } catch (err) {
+    throw new import_fetch_helpers.SafeFetchError(
+      "brand.json",
+      (0, import_fetch_helpers.classifyDiscoveryFailure)(err).dns_error,
+      err instanceof import_brand_jwks.BrandJsonResolverError && err.code === "invalid_body" ? "brand.json body failed strict-JSON parse" : "Legacy brand.json discovery failed",
+      err instanceof import_brand_jwks.BrandJsonResolverError ? err.httpStatus : void 0
+    );
+  }
+  return {
+    body: result.data,
+    url: result.finalUrl,
+    fetchedAt: Math.floor(Date.now() / 1e3),
+    headers: { "cache-control": result.cacheControl }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  fetchLegacyBrandJson
+});

package/dist/lib/signing/agent-resolver/legacy-brand.mjs

@@ -0,0 +1,36 @@
+import { fetchBrandJson, BrandJsonResolverError } from "../brand-jwks.mjs";
+import { eTldPlusOne } from "./etld.mjs";
+import { SafeFetchError, classifyDiscoveryFailure } from "./fetch-helpers.mjs";
+async function fetchLegacyBrandJson(agentUrl, options) {
+  const agent = new URL(agentUrl);
+  let startUrl = `${agent.origin}/.well-known/brand.json`;
+  const fetch = (url) => fetchBrandJson({ ...options, startUrl: url, domainDerived: true, maxRedirects: 1 });
+  let result;
+  try {
+    try {
+      result = await fetch(startUrl);
+    } catch (err) {
+      if (!(err instanceof BrandJsonResolverError) || err.httpStatus !== 404 && err.httpStatus !== 410) throw err;
+      const domain = eTldPlusOne(agentUrl);
+      if (domain === agent.hostname) throw err;
+      startUrl = `https://${domain}/.well-known/brand.json`;
+      result = await fetch(startUrl);
+    }
+  } catch (err) {
+    throw new SafeFetchError(
+      "brand.json",
+      classifyDiscoveryFailure(err).dns_error,
+      err instanceof BrandJsonResolverError && err.code === "invalid_body" ? "brand.json body failed strict-JSON parse" : "Legacy brand.json discovery failed",
+      err instanceof BrandJsonResolverError ? err.httpStatus : void 0
+    );
+  }
+  return {
+    body: result.data,
+    url: result.finalUrl,
+    fetchedAt: Math.floor(Date.now() / 1e3),
+    headers: { "cache-control": result.cacheControl }
+  };
+}
+export {
+  fetchLegacyBrandJson
+};

package/dist/lib/signing/agent-resolver/operator-authorization.d.mts

@@ -0,0 +1,13 @@
+/** Optional receiver account authorization, separate from agent origin binding. */
+import type { ResolveAgentOptions } from './resolve-agent.mjs';
+interface ActiveOperatorDelegation {
+    validUntil?: number;
+}
+/**
+ * Evaluate the complete cross-origin delegation tuple. Domain matching is
+ * against the exact agent eTLD+1 to match step 3 of the
+ * discovery algorithm; brand, activity, country, and time remain independent
+ * authorization dimensions and must all match the same entry.
+ */
+export declare function checkDelegatedOperatorAuthorization(brandJson: unknown, agentEtld1: string, now: number, options: Pick<ResolveAgentOptions, 'requiredOperatorBrand' | 'requiredOperatorScope' | 'requiredOperatorCountry' | 'allowPrivateIp'>): ActiveOperatorDelegation | undefined;
+export {};

package/dist/lib/signing/agent-resolver/operator-authorization.d.ts

@@ -0,0 +1,13 @@
+/** Optional receiver account authorization, separate from agent origin binding. */
+import type { ResolveAgentOptions } from './resolve-agent';
+interface ActiveOperatorDelegation {
+    validUntil?: number;
+}
+/**
+ * Evaluate the complete cross-origin delegation tuple. Domain matching is
+ * against the exact agent eTLD+1 to match step 3 of the
+ * discovery algorithm; brand, activity, country, and time remain independent
+ * authorization dimensions and must all match the same entry.
+ */
+export declare function checkDelegatedOperatorAuthorization(brandJson: unknown, agentEtld1: string, now: number, options: Pick<ResolveAgentOptions, 'requiredOperatorBrand' | 'requiredOperatorScope' | 'requiredOperatorCountry' | 'allowPrivateIp'>): ActiveOperatorDelegation | undefined;
+export {};

package/dist/lib/signing/agent-resolver/operator-authorization.js

@@ -0,0 +1,108 @@
+"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 operator_authorization_exports = {};
+__export(operator_authorization_exports, {
+  checkDelegatedOperatorAuthorization: () => checkDelegatedOperatorAuthorization
+});
+module.exports = __toCommonJS(operator_authorization_exports);
+const AUTHORIZED_OPERATOR_SCOPES = /* @__PURE__ */ new Set([
+  "all",
+  "media_buying",
+  "creative_generation",
+  "rights_clearance",
+  "governance",
+  "measurement",
+  "agent_operations"
+]);
+const AUTHORIZED_OPERATOR_DOMAIN = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$/;
+function checkDelegatedOperatorAuthorization(brandJson, agentEtld1, now, options) {
+  if (!brandJson || typeof brandJson !== "object") return void 0;
+  const operators = brandJson.authorized_operators;
+  if (!Array.isArray(operators)) return void 0;
+  let latestValidUntil;
+  let matched = false;
+  for (const op of operators) {
+    if (!op || typeof op !== "object" || Array.isArray(op)) continue;
+    const candidate = op;
+    const domain = candidate.domain;
+    const brands = candidate.brands;
+    if (typeof domain !== "string" || !AUTHORIZED_OPERATOR_DOMAIN.test(domain) || !isValidBrandGrant(brands)) {
+      continue;
+    }
+    if (domain !== agentEtld1) continue;
+    const scopes = candidate.scopes;
+    if (scopes !== void 0 && !isValidScopeGrant(scopes)) continue;
+    const countries = candidate.countries;
+    if (countries !== void 0 && !isValidCountryGrant(countries)) continue;
+    const validFrom = parseOptionalRfc3339(candidate.valid_from);
+    const validUntil = parseOptionalRfc3339(candidate.valid_until);
+    if (validFrom === null || validUntil === null) continue;
+    if (validFrom !== void 0 && validUntil !== void 0 && validFrom >= validUntil) continue;
+    if (validFrom !== void 0 && now < validFrom) continue;
+    if (validUntil !== void 0 && now >= validUntil) continue;
+    if (!matchesGrant(brands, options.requiredOperatorBrand, "*")) continue;
+    if (scopes !== void 0 && !matchesGrant(scopes, options.requiredOperatorScope, "all")) continue;
+    if (countries !== void 0 && !matchesGrant(countries, options.requiredOperatorCountry)) continue;
+    matched = true;
+    if (validUntil === void 0) return {};
+    latestValidUntil = Math.max(latestValidUntil ?? Number.NEGATIVE_INFINITY, validUntil);
+  }
+  return matched ? { validUntil: latestValidUntil } : void 0;
+}
+function isValidBrandGrant(value) {
+  return Array.isArray(value) && value.length > 0 && value.every((item) => typeof item === "string" && (item === "*" || /^[a-z0-9_]+$/.test(item)));
+}
+function isValidScopeGrant(value) {
+  return Array.isArray(value) && value.length > 0 && new Set(value).size === value.length && value.every((item) => typeof item === "string" && AUTHORIZED_OPERATOR_SCOPES.has(item));
+}
+function isValidCountryGrant(value) {
+  return Array.isArray(value) && value.every((item) => typeof item === "string" && /^[A-Z]{2}$/.test(item));
+}
+function matchesGrant(grants, required, wildcard) {
+  if (wildcard !== void 0 && grants.includes(wildcard)) return true;
+  return required !== void 0 && grants.includes(required);
+}
+function parseOptionalRfc3339(value) {
+  if (value === void 0) return void 0;
+  if (typeof value !== "string") return null;
+  const match = /^(\d{4})-(\d{2})-(\d{2})[Tt](\d{2}):(\d{2}):(\d{2})(?:\.(\d+))?([Zz]|([+-])(\d{2}):(\d{2}))$/.exec(
+    value
+  );
+  if (!match) return null;
+  const year = Number(match[1]);
+  const month = Number(match[2]);
+  const day = Number(match[3]);
+  const hour = Number(match[4]);
+  const minute = Number(match[5]);
+  const second = Number(match[6]);
+  const offsetHour = match[10] === void 0 ? 0 : Number(match[10]);
+  const offsetMinute = match[11] === void 0 ? 0 : Number(match[11]);
+  if (month < 1 || month > 12 || day < 1 || day > daysInMonth(year, month) || hour > 23 || minute > 59 || second > 59 || offsetHour > 23 || offsetMinute > 59) {
+    return null;
+  }
+  const parsed = Date.parse(value) / 1e3;
+  return Number.isFinite(parsed) ? parsed : null;
+}
+function daysInMonth(year, month) {
+  return new Date(Date.UTC(year, month, 0)).getUTCDate();
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  checkDelegatedOperatorAuthorization
+});

package/dist/lib/signing/agent-resolver/operator-authorization.mjs

@@ -0,0 +1,84 @@
+const AUTHORIZED_OPERATOR_SCOPES = /* @__PURE__ */ new Set([
+  "all",
+  "media_buying",
+  "creative_generation",
+  "rights_clearance",
+  "governance",
+  "measurement",
+  "agent_operations"
+]);
+const AUTHORIZED_OPERATOR_DOMAIN = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$/;
+function checkDelegatedOperatorAuthorization(brandJson, agentEtld1, now, options) {
+  if (!brandJson || typeof brandJson !== "object") return void 0;
+  const operators = brandJson.authorized_operators;
+  if (!Array.isArray(operators)) return void 0;
+  let latestValidUntil;
+  let matched = false;
+  for (const op of operators) {
+    if (!op || typeof op !== "object" || Array.isArray(op)) continue;
+    const candidate = op;
+    const domain = candidate.domain;
+    const brands = candidate.brands;
+    if (typeof domain !== "string" || !AUTHORIZED_OPERATOR_DOMAIN.test(domain) || !isValidBrandGrant(brands)) {
+      continue;
+    }
+    if (domain !== agentEtld1) continue;
+    const scopes = candidate.scopes;
+    if (scopes !== void 0 && !isValidScopeGrant(scopes)) continue;
+    const countries = candidate.countries;
+    if (countries !== void 0 && !isValidCountryGrant(countries)) continue;
+    const validFrom = parseOptionalRfc3339(candidate.valid_from);
+    const validUntil = parseOptionalRfc3339(candidate.valid_until);
+    if (validFrom === null || validUntil === null) continue;
+    if (validFrom !== void 0 && validUntil !== void 0 && validFrom >= validUntil) continue;
+    if (validFrom !== void 0 && now < validFrom) continue;
+    if (validUntil !== void 0 && now >= validUntil) continue;
+    if (!matchesGrant(brands, options.requiredOperatorBrand, "*")) continue;
+    if (scopes !== void 0 && !matchesGrant(scopes, options.requiredOperatorScope, "all")) continue;
+    if (countries !== void 0 && !matchesGrant(countries, options.requiredOperatorCountry)) continue;
+    matched = true;
+    if (validUntil === void 0) return {};
+    latestValidUntil = Math.max(latestValidUntil ?? Number.NEGATIVE_INFINITY, validUntil);
+  }
+  return matched ? { validUntil: latestValidUntil } : void 0;
+}
+function isValidBrandGrant(value) {
+  return Array.isArray(value) && value.length > 0 && value.every((item) => typeof item === "string" && (item === "*" || /^[a-z0-9_]+$/.test(item)));
+}
+function isValidScopeGrant(value) {
+  return Array.isArray(value) && value.length > 0 && new Set(value).size === value.length && value.every((item) => typeof item === "string" && AUTHORIZED_OPERATOR_SCOPES.has(item));
+}
+function isValidCountryGrant(value) {
+  return Array.isArray(value) && value.every((item) => typeof item === "string" && /^[A-Z]{2}$/.test(item));
+}
+function matchesGrant(grants, required, wildcard) {
+  if (wildcard !== void 0 && grants.includes(wildcard)) return true;
+  return required !== void 0 && grants.includes(required);
+}
+function parseOptionalRfc3339(value) {
+  if (value === void 0) return void 0;
+  if (typeof value !== "string") return null;
+  const match = /^(\d{4})-(\d{2})-(\d{2})[Tt](\d{2}):(\d{2}):(\d{2})(?:\.(\d+))?([Zz]|([+-])(\d{2}):(\d{2}))$/.exec(
+    value
+  );
+  if (!match) return null;
+  const year = Number(match[1]);
+  const month = Number(match[2]);
+  const day = Number(match[3]);
+  const hour = Number(match[4]);
+  const minute = Number(match[5]);
+  const second = Number(match[6]);
+  const offsetHour = match[10] === void 0 ? 0 : Number(match[10]);
+  const offsetMinute = match[11] === void 0 ? 0 : Number(match[11]);
+  if (month < 1 || month > 12 || day < 1 || day > daysInMonth(year, month) || hour > 23 || minute > 59 || second > 59 || offsetHour > 23 || offsetMinute > 59) {
+    return null;
+  }
+  const parsed = Date.parse(value) / 1e3;
+  return Number.isFinite(parsed) ? parsed : null;
+}
+function daysInMonth(year, month) {
+  return new Date(Date.UTC(year, month, 0)).getUTCDate();
+}
+export {
+  checkDelegatedOperatorAuthorization
+};

package/dist/lib/signing/agent-resolver/resolve-agent.d.mts

@@ -28,6 +28,7 @@
  *     `SsrfRefusedError` carries.
  */
 import type { IdentityKeyOriginPurpose, IdentityPosture } from './capabilities-types.mjs';
+import { type SsrfDnsLookup } from '../../net/index.mjs';
 import { type ConsistencyResult } from './consistency.mjs';
 import { type AgentResolverErrorDetail } from './errors.mjs';
 import { type AgentEntry } from './select-agent.mjs';
@@ -48,6 +49,13 @@ export interface FetchCapabilitiesFn {
 export interface ResolveAgentOptions {
     /** Default `'mcp'`. Ignored when `fetchCapabilities` is supplied. */
     protocol?: AgentProtocol;
+    /** URL matching is mandatory; these filters may only narrow it. */
+    expectedBrandJsonUrl?: string;
+    agentType?: string;
+    agentId?: string;
+    /** Enable the 3.x webhook-only fallback when brand_json_url is absent. */
+    legacyWebhookFallback?: boolean;
+    lookup?: SsrfDnsLookup;
     /**
      * Override the capabilities-fetch step entirely. Tests pass a fake; production
      * callers who already hold a configured protocol client can wire it through
@@ -85,10 +93,7 @@ export interface ResolveAgentOptions {
      */
     declaredPurposes?: readonly IdentityKeyOriginPurpose[];
     /**
-     * Sell-side webhook publisher pin marker — when `webhook_signing` is
-     * `true`, the step-7 origin-consistency check is skipped for the
-     * webhook-signing purpose only (operator-side webhook-signing remains
-     * checked). Buyer-side / receive-side verifiers MUST leave this unset.
+     * @deprecated Publisher pins never skip origin consistency. Ignored.
      */
     publisherPinned?: {
         webhook_signing?: boolean;
@@ -126,6 +131,11 @@ export interface TraceStep {
 export interface AgentResolution {
     agentUrl: string;
     brandJsonUrl: string;
+    /** Exact selected operator record; use it for signed-buyer governance. */
+    brandJson?: unknown;
+    brandJsonCacheControl?: string;
+    /** True only on the explicitly enabled 3.x webhook compatibility path. */
+    legacyWebhookFallback?: boolean;
     agentEntry: AgentEntry;
     jwksUri: string;
     jwks: {

package/dist/lib/signing/agent-resolver/resolve-agent.d.ts

@@ -28,6 +28,7 @@
  *     `SsrfRefusedError` carries.
  */
 import type { IdentityKeyOriginPurpose, IdentityPosture } from './capabilities-types';
+import { type SsrfDnsLookup } from '../../net';
 import { type ConsistencyResult } from './consistency';
 import { type AgentResolverErrorDetail } from './errors';
 import { type AgentEntry } from './select-agent';
@@ -48,6 +49,13 @@ export interface FetchCapabilitiesFn {
 export interface ResolveAgentOptions {
     /** Default `'mcp'`. Ignored when `fetchCapabilities` is supplied. */
     protocol?: AgentProtocol;
+    /** URL matching is mandatory; these filters may only narrow it. */
+    expectedBrandJsonUrl?: string;
+    agentType?: string;
+    agentId?: string;
+    /** Enable the 3.x webhook-only fallback when brand_json_url is absent. */
+    legacyWebhookFallback?: boolean;
+    lookup?: SsrfDnsLookup;
     /**
      * Override the capabilities-fetch step entirely. Tests pass a fake; production
      * callers who already hold a configured protocol client can wire it through
@@ -85,10 +93,7 @@ export interface ResolveAgentOptions {
      */
     declaredPurposes?: readonly IdentityKeyOriginPurpose[];
     /**
-     * Sell-side webhook publisher pin marker — when `webhook_signing` is
-     * `true`, the step-7 origin-consistency check is skipped for the
-     * webhook-signing purpose only (operator-side webhook-signing remains
-     * checked). Buyer-side / receive-side verifiers MUST leave this unset.
+     * @deprecated Publisher pins never skip origin consistency. Ignored.
      */
     publisherPinned?: {
         webhook_signing?: boolean;
@@ -126,6 +131,11 @@ export interface TraceStep {
 export interface AgentResolution {
     agentUrl: string;
     brandJsonUrl: string;
+    /** Exact selected operator record; use it for signed-buyer governance. */
+    brandJson?: unknown;
+    brandJsonCacheControl?: string;
+    /** True only on the explicitly enabled 3.x webhook compatibility path. */
+    legacyWebhookFallback?: boolean;
     agentEntry: AgentEntry;
     jwksUri: string;
     jwks: {