@adcp/sdk 14.0.0 → 14.2.0

package/dist/lib/signing/webhook-verifier.d.ts

@@ -14,8 +14,8 @@
  *     `content-type`, and `content-digest` — `content-digest` is unconditional
  *     for webhooks (vs policy-driven on requests) because every webhook
  *     carries a JSON body.
- *   - JWKS resolved via the publisher's `brand.json` `agents[]` `jwks_uri`,
- *     not the request-path capability document.
+ *   - JWKS resolved via the capabilities-selected operator brand.json;
+ *     publisher pins narrow its keys for applicable inventory.
  *
  * Checklist steps below mirror the 14-step shape in
  * `docs/building/implementation/security.mdx#verifier-checklist-for-webhooks`
@@ -23,6 +23,7 @@
  * match the security doc.
  */
 import type { JwksResolver } from './jwks';
+import { type PublisherSigningKeyPin } from './publisher-pins';
 import { type ReplayStore } from './replay';
 import { type RevocationStore } from './revocation';
 export declare const WEBHOOK_SIGNING_TAG = "adcp/webhook-signing/v1";
@@ -42,6 +43,10 @@ export interface WebhookRequestLike {
 export declare const WEBHOOK_MANDATORY_COMPONENTS: ReadonlyArray<string>;
 export interface VerifyWebhookOptions {
     jwks: JwksResolver;
+    /** Applicable publishers from the verifier's own media-buy record. */
+    publisherPins?: readonly PublisherSigningKeyPin[];
+    /** Log the underlying request_signature_* discovery cause locally. */
+    onKeyResolutionError?: (error: unknown) => void;
     replayStore: ReplayStore;
     revocationStore: RevocationStore;
     /** Now in seconds since epoch. Defaults to `Date.now() / 1000`. */

package/dist/lib/signing/webhook-verifier.js

@@ -28,11 +28,19 @@ module.exports = __toCommonJS(webhook_verifier_exports);
 var import_canonicalize = require('./canonicalize.js');
 var import_content_digest = require('./content-digest.js');
 var import_errors = require('./errors.js');
+var import_errors2 = require('./agent-resolver/errors.js');
+var import_brand_jwks = require('./brand-jwks.js');
 var import_parser = require('./parser.js');
 var import_crypto = require('./crypto.js');
+var import_publisher_pins = require('./publisher-pins.js');
 var import_replay = require('./replay.js');
 var import_revocation = require('./revocation.js');
 var import_types = require('./types.js');
+function keyDiscoveryRetryable(error) {
+  if (error instanceof import_errors2.AgentResolverError) return error.recovery === "transient";
+  if (error instanceof import_brand_jwks.BrandJsonResolverError) return error.recovery === "transient";
+  return true;
+}
 const WEBHOOK_SIGNING_TAG = "adcp/webhook-signing/v1";
 const WEBHOOK_MANDATORY_COMPONENTS = [
   "@method",
@@ -84,7 +92,22 @@ async function verifyWebhookSignature(request, options) {
   validateWindow(parsedInput.params.created, parsedInput.params.expires, now);
   validateCoveredComponents(parsedInput.components);
   const canonicalWebhookTarget = validateTargetUri(request.url);
-  const keyResolution = options.jwks.resolveWithMetadata ? await options.jwks.resolveWithMetadata(parsedInput.params.keyid) : { jwk: await options.jwks.resolve(parsedInput.params.keyid) };
+  let keyResolution;
+  try {
+    keyResolution = options.jwks.resolveWithMetadata ? await options.jwks.resolveWithMetadata(parsedInput.params.keyid) : { jwk: await options.jwks.resolve(parsedInput.params.keyid) };
+  } catch (error) {
+    try {
+      options.onKeyResolutionError?.(error);
+    } catch {
+    }
+    throw new import_errors.WebhookSignatureError(
+      "webhook_signature_key_unknown",
+      7,
+      "Signing key discovery or publisher pin check failed.",
+      void 0,
+      keyDiscoveryRetryable(error)
+    );
+  }
   const jwk = keyResolution.jwk;
   if (!jwk) {
     throw new import_errors.WebhookSignatureError(
@@ -166,6 +189,23 @@ async function verifyWebhookSignature(request, options) {
       "Content-Digest header does not match recomputed body hash."
     );
   }
+  if (options.publisherPins) {
+    try {
+      await (0, import_publisher_pins.assertPublisherPins)(jwk, options.publisherPins, currentTime);
+    } catch (error) {
+      try {
+        options.onKeyResolutionError?.(error);
+      } catch {
+      }
+      throw new import_errors.WebhookSignatureError(
+        "webhook_signature_key_unknown",
+        7,
+        "Signing key is outside the applicable publisher pins.",
+        void 0,
+        keyDiscoveryRetryable(error)
+      );
+    }
+  }
   if (keyResolution.operatorAuthorizationValidUntil !== void 0) {
     assertDelegatedOperatorAuthorizationActive(keyResolution.operatorAuthorizationValidUntil, currentTime());
   }
@@ -189,7 +229,7 @@ async function verifyWebhookSignature(request, options) {
   if (keyResolution.operatorAuthorizationValidUntil !== void 0) {
     assertDelegatedOperatorAuthorizationActive(keyResolution.operatorAuthorizationValidUntil, currentTime());
   }
-  const agent_url = options.agentUrlForKeyid?.(jwk.kid);
+  const agent_url = keyResolution.agentUrl ?? options.agentUrlForKeyid?.(jwk.kid);
   return {
     status: "verified",
     keyid: jwk.kid,

package/dist/lib/signing/webhook-verifier.mjs

@@ -1,11 +1,19 @@
 import { buildSignatureBase, canonicalTargetUri, getHeaderValue } from "./canonicalize.mjs";
 import { contentDigestMatches } from "./content-digest.mjs";
 import { RequestSignatureError, WebhookSignatureError } from "./errors.mjs";
+import { AgentResolverError } from "./agent-resolver/errors.mjs";
+import { BrandJsonResolverError } from "./brand-jwks.mjs";
 import { parseSignature, parseSignatureInput } from "./parser.mjs";
 import { jwkToPublicKey, verifySignature } from "./crypto.mjs";
+import { assertPublisherPins } from "./publisher-pins.mjs";
 import { InMemoryReplayStore } from "./replay.mjs";
 import { InMemoryRevocationStore } from "./revocation.mjs";
 import { ALLOWED_ALGS, CLOCK_SKEW_TOLERANCE_SECONDS, MAX_SIGNATURE_WINDOW_SECONDS } from "./types.mjs";
+function keyDiscoveryRetryable(error) {
+  if (error instanceof AgentResolverError) return error.recovery === "transient";
+  if (error instanceof BrandJsonResolverError) return error.recovery === "transient";
+  return true;
+}
 const WEBHOOK_SIGNING_TAG = "adcp/webhook-signing/v1";
 const WEBHOOK_MANDATORY_COMPONENTS = [
   "@method",
@@ -57,7 +65,22 @@ async function verifyWebhookSignature(request, options) {
   validateWindow(parsedInput.params.created, parsedInput.params.expires, now);
   validateCoveredComponents(parsedInput.components);
   const canonicalWebhookTarget = validateTargetUri(request.url);
-  const keyResolution = options.jwks.resolveWithMetadata ? await options.jwks.resolveWithMetadata(parsedInput.params.keyid) : { jwk: await options.jwks.resolve(parsedInput.params.keyid) };
+  let keyResolution;
+  try {
+    keyResolution = options.jwks.resolveWithMetadata ? await options.jwks.resolveWithMetadata(parsedInput.params.keyid) : { jwk: await options.jwks.resolve(parsedInput.params.keyid) };
+  } catch (error) {
+    try {
+      options.onKeyResolutionError?.(error);
+    } catch {
+    }
+    throw new WebhookSignatureError(
+      "webhook_signature_key_unknown",
+      7,
+      "Signing key discovery or publisher pin check failed.",
+      void 0,
+      keyDiscoveryRetryable(error)
+    );
+  }
   const jwk = keyResolution.jwk;
   if (!jwk) {
     throw new WebhookSignatureError(
@@ -139,6 +162,23 @@ async function verifyWebhookSignature(request, options) {
       "Content-Digest header does not match recomputed body hash."
     );
   }
+  if (options.publisherPins) {
+    try {
+      await assertPublisherPins(jwk, options.publisherPins, currentTime);
+    } catch (error) {
+      try {
+        options.onKeyResolutionError?.(error);
+      } catch {
+      }
+      throw new WebhookSignatureError(
+        "webhook_signature_key_unknown",
+        7,
+        "Signing key is outside the applicable publisher pins.",
+        void 0,
+        keyDiscoveryRetryable(error)
+      );
+    }
+  }
   if (keyResolution.operatorAuthorizationValidUntil !== void 0) {
     assertDelegatedOperatorAuthorizationActive(keyResolution.operatorAuthorizationValidUntil, currentTime());
   }
@@ -162,7 +202,7 @@ async function verifyWebhookSignature(request, options) {
   if (keyResolution.operatorAuthorizationValidUntil !== void 0) {
     assertDelegatedOperatorAuthorizationActive(keyResolution.operatorAuthorizationValidUntil, currentTime());
   }
-  const agent_url = options.agentUrlForKeyid?.(jwk.kid);
+  const agent_url = keyResolution.agentUrl ?? options.agentUrlForKeyid?.(jwk.kid);
   return {
     status: "verified",
     keyid: jwk.kid,

package/dist/lib/testing/storyboard/account-policy.d.mts

@@ -0,0 +1,2 @@
+/** Discovery and negotiation must never invent an unprovisioned account. */
+export declare const ACCOUNT_FREE_DISCOVERY_TASKS: ReadonlySet<string>;

package/dist/lib/testing/storyboard/account-policy.d.ts

@@ -0,0 +1,2 @@
+/** Discovery and negotiation must never invent an unprovisioned account. */
+export declare const ACCOUNT_FREE_DISCOVERY_TASKS: ReadonlySet<string>;

package/dist/lib/testing/storyboard/account-policy.js

@@ -0,0 +1,35 @@
+"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 account_policy_exports = {};
+__export(account_policy_exports, {
+  ACCOUNT_FREE_DISCOVERY_TASKS: () => ACCOUNT_FREE_DISCOVERY_TASKS
+});
+module.exports = __toCommonJS(account_policy_exports);
+const ACCOUNT_FREE_DISCOVERY_TASKS = /* @__PURE__ */ new Set([
+  "get_products",
+  "list_products",
+  "get_signals",
+  "request_proposals",
+  "refine_proposals",
+  "decline_proposals"
+]);
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ACCOUNT_FREE_DISCOVERY_TASKS
+});

package/dist/lib/testing/storyboard/account-policy.mjs

@@ -0,0 +1,11 @@
+const ACCOUNT_FREE_DISCOVERY_TASKS = /* @__PURE__ */ new Set([
+  "get_products",
+  "list_products",
+  "get_signals",
+  "request_proposals",
+  "refine_proposals",
+  "decline_proposals"
+]);
+export {
+  ACCOUNT_FREE_DISCOVERY_TASKS
+};

package/dist/lib/testing/storyboard/context.js

@@ -100,15 +100,21 @@ function readCompactMediaBuyFields(data) {
 const CONTEXT_EXTRACTORS = {
   sync_accounts(data) {
     const d = data;
+    if (d?.dry_run === true) return {};
     const accounts = d?.accounts;
     if (!accounts?.[0]) return {};
     const first = accounts[0];
+    if (first.action === "failed") return {};
     const extracted = {};
     if (first.account_id) extracted.account_id = first.account_id;
     if (first.status) extracted.account_status = first.status;
     const accountRef = {};
     if (first.brand) accountRef.brand = first.brand;
     if (first.operator) accountRef.operator = first.operator;
+    for (const field of ["operator_unit", "currency", "timezone", "sandbox"]) {
+      if (first[field] !== void 0) accountRef[field] = first[field];
+    }
+    if (!first.brand && !first.operator && first.account_id) accountRef.account_id = first.account_id;
     extracted.account = accountRef;
     return extracted;
   },

package/dist/lib/testing/storyboard/context.mjs

@@ -67,15 +67,21 @@ function readCompactMediaBuyFields(data) {
 const CONTEXT_EXTRACTORS = {
   sync_accounts(data) {
     const d = data;
+    if (d?.dry_run === true) return {};
     const accounts = d?.accounts;
     if (!accounts?.[0]) return {};
     const first = accounts[0];
+    if (first.action === "failed") return {};
     const extracted = {};
     if (first.account_id) extracted.account_id = first.account_id;
     if (first.status) extracted.account_status = first.status;
     const accountRef = {};
     if (first.brand) accountRef.brand = first.brand;
     if (first.operator) accountRef.operator = first.operator;
+    for (const field of ["operator_unit", "currency", "timezone", "sandbox"]) {
+      if (first[field] !== void 0) accountRef[field] = first[field];
+    }
+    if (!first.brand && !first.operator && first.account_id) accountRef.account_id = first.account_id;
     extracted.account = accountRef;
     return extracted;
   },

package/dist/lib/testing/storyboard/request-builder.js

@@ -24,6 +24,7 @@ __export(request_builder_exports, {
   hasRequestEnricher: () => hasRequestEnricher
 });
 module.exports = __toCommonJS(request_builder_exports);
+var import_account_policy = require('./account-policy.js');
 var import_node_crypto = require("node:crypto");
 var import_client = require('../client.js');
 var import_context = require('./context.js');
@@ -102,6 +103,15 @@ function resolveMediaBuyAccount(fixtureAccount, contextAccount, options) {
   }
   return resolvedAccount;
 }
+function resolveDiscoveryAccount(task, fixtureAccount, contextAccount, options) {
+  if (import_account_policy.ACCOUNT_FREE_DISCOVERY_TASKS.has(task) && contextAccount === void 0 && hasUnresolvedContextReference(fixtureAccount))
+    return void 0;
+  if (import_account_policy.ACCOUNT_FREE_DISCOVERY_TASKS.has(task) && fixtureAccount === void 0 && contextAccount === void 0)
+    return void 0;
+  if (contextAccount === void 0 && fixtureAccount && typeof fixtureAccount === "object" && "account_id" in fixtureAccount)
+    return fixtureAccount;
+  return resolveMediaBuyAccount(fixtureAccount, contextAccount, options);
+}
 const OPERATION_SCOPED_CONTROLLER_SCENARIOS = /* @__PURE__ */ new Set([
   "force_create_media_buy_arm",
   "force_get_products_arm",
@@ -193,7 +203,7 @@ const REQUEST_ENRICHERS = {
     ) : {};
     const fixtureAccount = fixtureFields.account;
     const fixtureWholesaleAccount = fixtureFields.buying_mode === "wholesale" && fixtureAccount !== void 0 && !hasUnresolvedContextReference(fixtureAccount) ? fixtureAccount : void 0;
-    const resolvedAccount = fixtureWholesaleAccount ?? resolveMediaBuyAccount(fixtureAccount, context.account, options);
+    const resolvedAccount = fixtureWholesaleAccount ?? resolveDiscoveryAccount("get_products", fixtureAccount, context.account, options);
     if (fixtureFields.buying_mode === "wholesale") {
       return {
         ...fixtureFields,
@@ -471,7 +481,7 @@ const REQUEST_ENRICHERS = {
     ) : {};
     const fixtureAccount = fixtureFields.account;
     const fixtureWholesaleAccount = fixtureFields.discovery_mode === "wholesale" && fixtureAccount !== void 0 && !hasUnresolvedContextReference(fixtureAccount) ? fixtureAccount : void 0;
-    const account = fixtureWholesaleAccount ?? resolveMediaBuyAccount(fixtureAccount, context.account, options);
+    const account = fixtureWholesaleAccount ?? resolveDiscoveryAccount("get_signals", fixtureAccount, context.account, options);
     if (fixtureFields.discovery_mode === "wholesale") {
       return { ...fixtureFields, account };
     }

package/dist/lib/testing/storyboard/request-builder.mjs

@@ -1,3 +1,4 @@
+import { ACCOUNT_FREE_DISCOVERY_TASKS } from "./account-policy.mjs";
 import { createHash } from "node:crypto";
 import { resolveBrand, resolveAccount } from "../client.mjs";
 import { injectContext } from "./context.mjs";
@@ -76,6 +77,15 @@ function resolveMediaBuyAccount(fixtureAccount, contextAccount, options) {
   }
   return resolvedAccount;
 }
+function resolveDiscoveryAccount(task, fixtureAccount, contextAccount, options) {
+  if (ACCOUNT_FREE_DISCOVERY_TASKS.has(task) && contextAccount === void 0 && hasUnresolvedContextReference(fixtureAccount))
+    return void 0;
+  if (ACCOUNT_FREE_DISCOVERY_TASKS.has(task) && fixtureAccount === void 0 && contextAccount === void 0)
+    return void 0;
+  if (contextAccount === void 0 && fixtureAccount && typeof fixtureAccount === "object" && "account_id" in fixtureAccount)
+    return fixtureAccount;
+  return resolveMediaBuyAccount(fixtureAccount, contextAccount, options);
+}
 const OPERATION_SCOPED_CONTROLLER_SCENARIOS = /* @__PURE__ */ new Set([
   "force_create_media_buy_arm",
   "force_get_products_arm",
@@ -167,7 +177,7 @@ const REQUEST_ENRICHERS = {
     ) : {};
     const fixtureAccount = fixtureFields.account;
     const fixtureWholesaleAccount = fixtureFields.buying_mode === "wholesale" && fixtureAccount !== void 0 && !hasUnresolvedContextReference(fixtureAccount) ? fixtureAccount : void 0;
-    const resolvedAccount = fixtureWholesaleAccount ?? resolveMediaBuyAccount(fixtureAccount, context.account, options);
+    const resolvedAccount = fixtureWholesaleAccount ?? resolveDiscoveryAccount("get_products", fixtureAccount, context.account, options);
     if (fixtureFields.buying_mode === "wholesale") {
       return {
         ...fixtureFields,
@@ -445,7 +455,7 @@ const REQUEST_ENRICHERS = {
     ) : {};
     const fixtureAccount = fixtureFields.account;
     const fixtureWholesaleAccount = fixtureFields.discovery_mode === "wholesale" && fixtureAccount !== void 0 && !hasUnresolvedContextReference(fixtureAccount) ? fixtureAccount : void 0;
-    const account = fixtureWholesaleAccount ?? resolveMediaBuyAccount(fixtureAccount, context.account, options);
+    const account = fixtureWholesaleAccount ?? resolveDiscoveryAccount("get_signals", fixtureAccount, context.account, options);
     if (fixtureFields.discovery_mode === "wholesale") {
       return { ...fixtureFields, account };
     }

package/dist/lib/testing/storyboard/runner.js

@@ -61,6 +61,7 @@ module.exports = __toCommonJS(runner_exports);
 var import_node_crypto = require("node:crypto");
 var import_node_fs = require("node:fs");
 var import_node_path = require("node:path");
+var import_account_policy = require('./account-policy.js');
 var import_client = require('../client.js');
 var import_protocols = require('../../protocols/index.js');
 var import_rawResponseCapture = require('../../protocols/rawResponseCapture.js');
@@ -4291,7 +4292,7 @@ async function executeStep(client, step, storyboardId, phaseId, context, allStep
   const updatedContext = { ...context };
   (0, import_context.forwardAliasCache)(context, updatedContext);
   const hasData = taskResult?.data !== void 0 && taskResult?.data !== null;
-  if (passed && hasData && taskResult) {
+  if (passed && hasData && taskResult && !(effectiveStep.task === "sync_accounts" && request.dry_run === true)) {
     const extracted = (0, import_context.extractContextWithProvenance)(effectiveStep.task, taskResult.data, step.id);
     for (const group of extracted.clearGroups ?? []) {
       if (group.when && !group.when.values.includes(updatedContext[group.when.key])) continue;
@@ -6210,7 +6211,7 @@ function applyBrandInvariant(request, options, taskName, stepFlags) {
         result.account = merged;
       }
     }
-  } else if (topAccountOk && taskName !== "list_accounts") {
+  } else if (topAccountOk && taskName !== "list_accounts" && !import_account_policy.ACCOUNT_FREE_DISCOVERY_TASKS.has(taskName ?? "")) {
     result.account = (0, import_client2.resolveAccount)(options);
   }
   return result;

package/dist/lib/testing/storyboard/runner.mjs

@@ -1,6 +1,7 @@
 import { createHash, createHmac } from "node:crypto";
 import { existsSync, readFileSync } from "node:fs";
 import { basename, join } from "node:path";
+import { ACCOUNT_FREE_DISCOVERY_TASKS } from "./account-policy.mjs";
 import {
   createTestClient,
   getOrCreateClientResolution,
@@ -4313,7 +4314,7 @@ async function executeStep(client, step, storyboardId, phaseId, context, allStep
   const updatedContext = { ...context };
   forwardAliasCache(context, updatedContext);
   const hasData = taskResult?.data !== void 0 && taskResult?.data !== null;
-  if (passed && hasData && taskResult) {
+  if (passed && hasData && taskResult && !(effectiveStep.task === "sync_accounts" && request.dry_run === true)) {
     const extracted = extractContextWithProvenance(effectiveStep.task, taskResult.data, step.id);
     for (const group of extracted.clearGroups ?? []) {
       if (group.when && !group.when.values.includes(updatedContext[group.when.key])) continue;
@@ -6232,7 +6233,7 @@ function applyBrandInvariant(request, options, taskName, stepFlags) {
         result.account = merged;
       }
     }
-  } else if (topAccountOk && taskName !== "list_accounts") {
+  } else if (topAccountOk && taskName !== "list_accounts" && !ACCOUNT_FREE_DISCOVERY_TASKS.has(taskName ?? "")) {
     result.account = resolveAccount(options);
   }
   return result;

package/dist/lib/testing/storyboard/validations.d.mts

@@ -197,7 +197,7 @@ export interface UpstreamTrafficQueryResult {
  */
 export declare function runValidations(validations: StoryboardValidation[], context: ValidationContext): ValidationResult[];
 /** Capability semver emitted in run summaries and used for advisory expiry. */
-export declare const RUNNER_CAPABILITY_VERSION = "14.0.0";
+export declare const RUNNER_CAPABILITY_VERSION = "14.2.0";
 /** True when a failed validation contributes to the owning step's grade. */
 export declare function validationFailsStep(result: ValidationResult): boolean;
 /**

package/dist/lib/testing/storyboard/validations.d.ts

@@ -197,7 +197,7 @@ export interface UpstreamTrafficQueryResult {
  */
 export declare function runValidations(validations: StoryboardValidation[], context: ValidationContext): ValidationResult[];
 /** Capability semver emitted in run summaries and used for advisory expiry. */
-export declare const RUNNER_CAPABILITY_VERSION = "14.0.0";
+export declare const RUNNER_CAPABILITY_VERSION = "14.2.0";
 /** True when a failed validation contributes to the owning step's grade. */
 export declare function validationFailsStep(result: ValidationResult): boolean;
 /**

package/dist/lib/types/accept-proposal.d.ts

@@ -145,6 +145,11 @@ export type ActivationKey = {
  */
 export type AdvertiserIndustry = 'automotive' | 'automotive.electric_vehicles' | 'automotive.parts_accessories' | 'automotive.luxury' | 'beauty_cosmetics' | 'beauty_cosmetics.skincare' | 'beauty_cosmetics.fragrance' | 'beauty_cosmetics.haircare' | 'cannabis' | 'cpg' | 'cpg.personal_care' | 'cpg.household' | 'dating' | 'education' | 'education.higher_education' | 'education.online_learning' | 'education.k12' | 'energy_utilities' | 'energy_utilities.renewable' | 'fashion_apparel' | 'fashion_apparel.luxury' | 'fashion_apparel.sportswear' | 'finance' | 'finance.banking' | 'finance.insurance' | 'finance.investment' | 'finance.cryptocurrency' | 'food_beverage' | 'food_beverage.alcohol' | 'food_beverage.restaurants' | 'food_beverage.packaged_goods' | 'gambling_betting' | 'gambling_betting.sports_betting' | 'gambling_betting.casino' | 'gaming' | 'gaming.mobile' | 'gaming.console_pc' | 'gaming.esports' | 'government_nonprofit' | 'government_nonprofit.political' | 'government_nonprofit.charity' | 'healthcare' | 'healthcare.pharmaceutical' | 'healthcare.medical_devices' | 'healthcare.wellness' | 'home_garden' | 'home_garden.furniture' | 'home_garden.home_improvement' | 'media_entertainment' | 'media_entertainment.podcasts' | 'media_entertainment.music' | 'media_entertainment.film_tv' | 'media_entertainment.publishing' | 'media_entertainment.live_events' | 'pets' | 'professional_services' | 'professional_services.legal' | 'professional_services.consulting' | 'real_estate' | 'real_estate.residential' | 'real_estate.commercial' | 'recruitment_hr' | 'retail' | 'retail.ecommerce' | 'retail.department_stores' | 'sports_fitness' | 'sports_fitness.equipment' | 'sports_fitness.teams_leagues' | 'technology' | 'technology.software' | 'technology.hardware' | 'technology.ai_ml' | 'telecom' | 'telecom.mobile_carriers' | 'telecom.internet_providers' | 'transportation_logistics' | 'travel_hospitality' | 'travel_hospitality.airlines' | 'travel_hospitality.hotels' | 'travel_hospitality.cruise' | 'travel_hospitality.tourism';
 
+/**
+ * User-level bases that may resolve age for demographic targeting execution. Population estimates are deliberately absent because aggregate composition cannot establish an individual impression's age.
+ */
+export type AgeDeterminationBasis = 'verified' | 'declared' | 'inferred';
+
 /**
  * Methods for verifying user age for compliance. Does not include 'inferred' as it is not accepted for regulatory compliance.
  */
@@ -1083,7 +1088,20 @@ export type DemographicSystem = 'nielsen' | 'nielsen_audio' | 'barb' | 'agf' | '
  * Canonical demographic audience targeting intent with optional constraints on how age may be determined. This is distinct from age_restriction: demographics selects an audience, while age_restriction expresses a legal eligibility or verification floor. Fresh create/update targeting MUST compile exactly or be rejected. During get_products, a seller may offer a different configured predicate only through sparse targeting_resolution modifications on a distinguishable product_id; selecting that product accepts the alternative. Sellers never silently broaden, narrow, default, drop, or substitute the basis.
  */
 export interface DemographicTargetingIntent {
-    age: DemographicAgeRange & {};
+    age: DemographicAgeRange & {
+        /**
+         * User-level age determination bases the buyer permits for this predicate. Sellers MUST use only these bases or reject the request; they MUST NOT silently fall back to another basis. When omitted, the buyer imposes no determination-basis constraint beyond product capability and any age_restriction. population_estimate is structurally unavailable because aggregate evidence cannot identify an eligible user.
+         *
+         * @minItems 1
+         */
+        accepted_bases?: [AgeDeterminationBasis, ...AgeDeterminationBasis[]];
+        /**
+         * Verification methods acceptable when verified is an accepted basis. This field narrows verified demographic execution; age_restriction.accepted_methods independently governs legal eligibility and the two sets are intersected when both are present.
+         *
+         * @minItems 1
+         */
+        accepted_verification_methods?: [AgeVerificationMethod, ...AgeVerificationMethod[]];
+    };
 }
 
 /**

package/dist/lib/types/buy-products.d.ts

@@ -145,6 +145,11 @@ export type ActivationKey = {
  */
 export type AdvertiserIndustry = 'automotive' | 'automotive.electric_vehicles' | 'automotive.parts_accessories' | 'automotive.luxury' | 'beauty_cosmetics' | 'beauty_cosmetics.skincare' | 'beauty_cosmetics.fragrance' | 'beauty_cosmetics.haircare' | 'cannabis' | 'cpg' | 'cpg.personal_care' | 'cpg.household' | 'dating' | 'education' | 'education.higher_education' | 'education.online_learning' | 'education.k12' | 'energy_utilities' | 'energy_utilities.renewable' | 'fashion_apparel' | 'fashion_apparel.luxury' | 'fashion_apparel.sportswear' | 'finance' | 'finance.banking' | 'finance.insurance' | 'finance.investment' | 'finance.cryptocurrency' | 'food_beverage' | 'food_beverage.alcohol' | 'food_beverage.restaurants' | 'food_beverage.packaged_goods' | 'gambling_betting' | 'gambling_betting.sports_betting' | 'gambling_betting.casino' | 'gaming' | 'gaming.mobile' | 'gaming.console_pc' | 'gaming.esports' | 'government_nonprofit' | 'government_nonprofit.political' | 'government_nonprofit.charity' | 'healthcare' | 'healthcare.pharmaceutical' | 'healthcare.medical_devices' | 'healthcare.wellness' | 'home_garden' | 'home_garden.furniture' | 'home_garden.home_improvement' | 'media_entertainment' | 'media_entertainment.podcasts' | 'media_entertainment.music' | 'media_entertainment.film_tv' | 'media_entertainment.publishing' | 'media_entertainment.live_events' | 'pets' | 'professional_services' | 'professional_services.legal' | 'professional_services.consulting' | 'real_estate' | 'real_estate.residential' | 'real_estate.commercial' | 'recruitment_hr' | 'retail' | 'retail.ecommerce' | 'retail.department_stores' | 'sports_fitness' | 'sports_fitness.equipment' | 'sports_fitness.teams_leagues' | 'technology' | 'technology.software' | 'technology.hardware' | 'technology.ai_ml' | 'telecom' | 'telecom.mobile_carriers' | 'telecom.internet_providers' | 'transportation_logistics' | 'travel_hospitality' | 'travel_hospitality.airlines' | 'travel_hospitality.hotels' | 'travel_hospitality.cruise' | 'travel_hospitality.tourism';
 
+/**
+ * User-level bases that may resolve age for demographic targeting execution. Population estimates are deliberately absent because aggregate composition cannot establish an individual impression's age.
+ */
+export type AgeDeterminationBasis = 'verified' | 'declared' | 'inferred';
+
 /**
  * Age restriction for compliance. Use for legal requirements (alcohol, gambling), not audience targeting.
  */
@@ -1152,7 +1157,20 @@ export type DemographicSystem = 'nielsen' | 'nielsen_audio' | 'barb' | 'agf' | '
  * Canonical demographic audience targeting intent with optional constraints on how age may be determined. This is distinct from age_restriction: demographics selects an audience, while age_restriction expresses a legal eligibility or verification floor. Fresh create/update targeting MUST compile exactly or be rejected. During get_products, a seller may offer a different configured predicate only through sparse targeting_resolution modifications on a distinguishable product_id; selecting that product accepts the alternative. Sellers never silently broaden, narrow, default, drop, or substitute the basis.
  */
 export interface DemographicTargetingIntent {
-    age: DemographicAgeRange & {};
+    age: DemographicAgeRange & {
+        /**
+         * User-level age determination bases the buyer permits for this predicate. Sellers MUST use only these bases or reject the request; they MUST NOT silently fall back to another basis. When omitted, the buyer imposes no determination-basis constraint beyond product capability and any age_restriction. population_estimate is structurally unavailable because aggregate evidence cannot identify an eligible user.
+         *
+         * @minItems 1
+         */
+        accepted_bases?: [AgeDeterminationBasis, ...AgeDeterminationBasis[]];
+        /**
+         * Verification methods acceptable when verified is an accepted basis. This field narrows verified demographic execution; age_restriction.accepted_methods independently governs legal eligibility and the two sets are intersected when both are present.
+         *
+         * @minItems 1
+         */
+        accepted_verification_methods?: [AgeVerificationMethod, ...AgeVerificationMethod[]];
+    };
 }
 
 /**

package/dist/lib/types/check-governance.d.ts

@@ -445,6 +445,11 @@ export type ActivationKey = {
  */
 export type AdvertiserIndustry = 'automotive' | 'automotive.electric_vehicles' | 'automotive.parts_accessories' | 'automotive.luxury' | 'beauty_cosmetics' | 'beauty_cosmetics.skincare' | 'beauty_cosmetics.fragrance' | 'beauty_cosmetics.haircare' | 'cannabis' | 'cpg' | 'cpg.personal_care' | 'cpg.household' | 'dating' | 'education' | 'education.higher_education' | 'education.online_learning' | 'education.k12' | 'energy_utilities' | 'energy_utilities.renewable' | 'fashion_apparel' | 'fashion_apparel.luxury' | 'fashion_apparel.sportswear' | 'finance' | 'finance.banking' | 'finance.insurance' | 'finance.investment' | 'finance.cryptocurrency' | 'food_beverage' | 'food_beverage.alcohol' | 'food_beverage.restaurants' | 'food_beverage.packaged_goods' | 'gambling_betting' | 'gambling_betting.sports_betting' | 'gambling_betting.casino' | 'gaming' | 'gaming.mobile' | 'gaming.console_pc' | 'gaming.esports' | 'government_nonprofit' | 'government_nonprofit.political' | 'government_nonprofit.charity' | 'healthcare' | 'healthcare.pharmaceutical' | 'healthcare.medical_devices' | 'healthcare.wellness' | 'home_garden' | 'home_garden.furniture' | 'home_garden.home_improvement' | 'media_entertainment' | 'media_entertainment.podcasts' | 'media_entertainment.music' | 'media_entertainment.film_tv' | 'media_entertainment.publishing' | 'media_entertainment.live_events' | 'pets' | 'professional_services' | 'professional_services.legal' | 'professional_services.consulting' | 'real_estate' | 'real_estate.residential' | 'real_estate.commercial' | 'recruitment_hr' | 'retail' | 'retail.ecommerce' | 'retail.department_stores' | 'sports_fitness' | 'sports_fitness.equipment' | 'sports_fitness.teams_leagues' | 'technology' | 'technology.software' | 'technology.hardware' | 'technology.ai_ml' | 'telecom' | 'telecom.mobile_carriers' | 'telecom.internet_providers' | 'transportation_logistics' | 'travel_hospitality' | 'travel_hospitality.airlines' | 'travel_hospitality.hotels' | 'travel_hospitality.cruise' | 'travel_hospitality.tourism';
 
+/**
+ * User-level bases that may resolve age for demographic targeting execution. Population estimates are deliberately absent because aggregate composition cannot establish an individual impression's age.
+ */
+export type AgeDeterminationBasis = 'verified' | 'declared' | 'inferred';
+
 /**
  * Methods for verifying user age for compliance. Does not include 'inferred' as it is not accepted for regulatory compliance.
  */
@@ -1585,7 +1590,20 @@ export type DemographicSystem = 'nielsen' | 'nielsen_audio' | 'barb' | 'agf' | '
  * Canonical demographic audience targeting intent with optional constraints on how age may be determined. This is distinct from age_restriction: demographics selects an audience, while age_restriction expresses a legal eligibility or verification floor. Fresh create/update targeting MUST compile exactly or be rejected. During get_products, a seller may offer a different configured predicate only through sparse targeting_resolution modifications on a distinguishable product_id; selecting that product accepts the alternative. Sellers never silently broaden, narrow, default, drop, or substitute the basis.
  */
 export interface DemographicTargetingIntent {
-    age: DemographicAgeRange & {};
+    age: DemographicAgeRange & {
+        /**
+         * User-level age determination bases the buyer permits for this predicate. Sellers MUST use only these bases or reject the request; they MUST NOT silently fall back to another basis. When omitted, the buyer imposes no determination-basis constraint beyond product capability and any age_restriction. population_estimate is structurally unavailable because aggregate evidence cannot identify an eligible user.
+         *
+         * @minItems 1
+         */
+        accepted_bases?: [AgeDeterminationBasis, ...AgeDeterminationBasis[]];
+        /**
+         * Verification methods acceptable when verified is an accepted basis. This field narrows verified demographic execution; age_restriction.accepted_methods independently governs legal eligibility and the two sets are intersected when both are present.
+         *
+         * @minItems 1
+         */
+        accepted_verification_methods?: [AgeVerificationMethod, ...AgeVerificationMethod[]];
+    };
 }
 
 /**

package/dist/lib/types/comply-test-controller.d.ts

@@ -486,6 +486,11 @@ export interface AdInventoryConfiguration {
     supported_formats?: string[];
 }
 
+/**
+ * User-level bases that may resolve age for demographic targeting execution. Population estimates are deliberately absent because aggregate composition cannot establish an individual impression's age.
+ */
+export type AgeDeterminationBasis = 'verified' | 'declared' | 'inferred';
+
 /**
  * Methods for verifying user age for compliance. Does not include 'inferred' as it is not accepted for regulatory compliance.
  */
@@ -5526,7 +5531,20 @@ export interface DemographicTargetingCapability {
  * Canonical demographic audience targeting intent with optional constraints on how age may be determined. This is distinct from age_restriction: demographics selects an audience, while age_restriction expresses a legal eligibility or verification floor. Fresh create/update targeting MUST compile exactly or be rejected. During get_products, a seller may offer a different configured predicate only through sparse targeting_resolution modifications on a distinguishable product_id; selecting that product accepts the alternative. Sellers never silently broaden, narrow, default, drop, or substitute the basis.
  */
 export interface DemographicTargetingIntent {
-    age: DemographicAgeRange & {};
+    age: DemographicAgeRange & {
+        /**
+         * User-level age determination bases the buyer permits for this predicate. Sellers MUST use only these bases or reject the request; they MUST NOT silently fall back to another basis. When omitted, the buyer imposes no determination-basis constraint beyond product capability and any age_restriction. population_estimate is structurally unavailable because aggregate evidence cannot identify an eligible user.
+         *
+         * @minItems 1
+         */
+        accepted_bases?: [AgeDeterminationBasis, ...AgeDeterminationBasis[]];
+        /**
+         * Verification methods acceptable when verified is an accepted basis. This field narrows verified demographic execution; age_restriction.accepted_methods independently governs legal eligibility and the two sets are intersected when both are present.
+         *
+         * @minItems 1
+         */
+        accepted_verification_methods?: [AgeVerificationMethod, ...AgeVerificationMethod[]];
+    };
 }
 
 /**

package/dist/lib/types/control-media-buy.d.ts

@@ -129,6 +129,11 @@ export type ActivationKey = {
     value: string;
 };
 
+/**
+ * User-level bases that may resolve age for demographic targeting execution. Population estimates are deliberately absent because aggregate composition cannot establish an individual impression's age.
+ */
+export type AgeDeterminationBasis = 'verified' | 'declared' | 'inferred';
+
 /**
  * Age restriction for compliance. Use for legal requirements (alcohol, gambling), not audience targeting.
  */
@@ -583,7 +588,20 @@ export type DemographicAgeRange = {} & {
  * Canonical demographic audience targeting intent with optional constraints on how age may be determined. This is distinct from age_restriction: demographics selects an audience, while age_restriction expresses a legal eligibility or verification floor. Fresh create/update targeting MUST compile exactly or be rejected. During get_products, a seller may offer a different configured predicate only through sparse targeting_resolution modifications on a distinguishable product_id; selecting that product accepts the alternative. Sellers never silently broaden, narrow, default, drop, or substitute the basis.
  */
 export interface DemographicTargetingIntent {
-    age: DemographicAgeRange & {};
+    age: DemographicAgeRange & {
+        /**
+         * User-level age determination bases the buyer permits for this predicate. Sellers MUST use only these bases or reject the request; they MUST NOT silently fall back to another basis. When omitted, the buyer imposes no determination-basis constraint beyond product capability and any age_restriction. population_estimate is structurally unavailable because aggregate evidence cannot identify an eligible user.
+         *
+         * @minItems 1
+         */
+        accepted_bases?: [AgeDeterminationBasis, ...AgeDeterminationBasis[]];
+        /**
+         * Verification methods acceptable when verified is an accepted basis. This field narrows verified demographic execution; age_restriction.accepted_methods independently governs legal eligibility and the two sets are intersected when both are present.
+         *
+         * @minItems 1
+         */
+        accepted_verification_methods?: [AgeVerificationMethod, ...AgeVerificationMethod[]];
+    };
 }
 
 /**