@adcp/sdk 6.9.0 → 6.10.0

package/dist/lib/server/operational-platform.d.ts

@@ -0,0 +1,239 @@
+/**
+ * `OperationalPlatform` — in-process operational contract.
+ *
+ * `DecisioningPlatform` covers buyer-facing MCP request dispatch:
+ * `platform.sales.updateMediaBuy(req, ctx)` etc., where `ctx` is a
+ * `RequestContext` built by the framework from `authInfo` via
+ * `AccountStore.resolve`, threading `state`, `resolve`, `ctxMetadata`,
+ * and `handoffToTask`.
+ *
+ * In-process consumers are different. The price-optimization poller,
+ * audience-sync task poller, scheduled jobs, and the storefront
+ * fan-out path do NOT have an MCP request to derive auth from. They
+ * have a stored task with an access token (or, for fan-out, no token
+ * — the storefront synthesizes one per upstream target). They cannot
+ * honestly satisfy `RequestContext`. Every adopter doing operational
+ * work would otherwise reinvent this seam.
+ *
+ * `OperationalPlatform` is the named contract for that seam. Five
+ * methods covering the real operational surface:
+ *
+ * 1. `extractContext` — synthesize a per-call platform context from
+ *    a stored token (and optional request args, for fan-out callers).
+ *    The single CTX-METADATA-SAFETY boundary outside
+ *    `AccountStore.resolve`: anything touching credentials in an
+ *    in-process consumer flows through here.
+ * 2. `updateMediaBuy` — required. Fan-out callers dispatch one of
+ *    these per upstream target.
+ * 3. `getMediaBuyDelivery` — required. Pollers read delivery metrics
+ *    here.
+ * 4. `pollAudienceStatuses` — optional. Audience-sync pollers only.
+ * 5. `getProducts` — optional. Storefront bundle composition only;
+ *    server-side internal call, not buyer-facing dispatch.
+ *
+ * Naming the contract honestly — "operational" rather than "adapter"
+ * — separates it from any v5 `PlatformAdapter` baggage and from
+ * `DecisioningPlatform`'s MCP-request flow. Tests mock
+ * `OperationalPlatform`, not the broader v6 interface.
+ *
+ * Errors: methods throw `AdcpError` for structured rejection, matching
+ * `DecisioningPlatform`'s convention. Generic thrown `Error` /
+ * `TypeError` propagate; callers catch and log per their needs.
+ *
+ * Status: 6.10. See adcontextprotocol/adcp-client#1530.
+ *
+ * @see DecisioningPlatform — buyer-facing MCP dispatch
+ * @see docs/guides/CTX-METADATA-SAFETY.md — credential discipline
+ * @public
+ */
+import type { GetMediaBuyDeliveryResponse, GetProductsResponse, UpdateMediaBuyRequest, UpdateMediaBuyResponse } from '../types/tools.generated';
+import type { AudienceStatus } from './decisioning/specialisms/audiences';
+/**
+ * Minimal context for in-process operational calls. Adopters extend
+ * with platform-specific fields (advertiser id, sandbox mode, region,
+ * etc.); the type parameter on `OperationalPlatform<TCtx>` carries
+ * the extension through.
+ *
+ * `accessToken` is the only field shared across adopters: the rest of
+ * the context shape is platform-internal. Pollers and scheduled jobs
+ * that legitimately have no token (server-side internal scans) leave
+ * it `undefined`.
+ *
+ * @example
+ * ```ts
+ * interface SnapOpCtx extends OperationalContext {
+ *   advertiserId: string;
+ *   sandbox: boolean;
+ * }
+ *
+ * const snapOps = defineOperationalPlatform<SnapOpCtx>({
+ *   platformId: 'snap',
+ *   extractContext: async (args, sessionToken) => ({
+ *     accessToken: sessionToken,
+ *     advertiserId: String(args.advertiser_id ?? ''),
+ *     sandbox: Boolean(args.sandbox),
+ *   }),
+ *   // ...
+ * });
+ * ```
+ */
+export interface OperationalContext {
+    /**
+     * The access token used by upstream HTTP calls. `undefined` for
+     * server-side internal scans that don't authenticate against a
+     * specific tenant.
+     */
+    accessToken: string | undefined;
+}
+/**
+ * In-process operational contract. Implementations dispatch to
+ * upstream platform APIs from pollers, scheduled jobs, fan-out paths,
+ * and other contexts that don't carry an MCP request.
+ *
+ * Type parameter `TCtx` extends {@link OperationalContext} to carry
+ * platform-specific context fields through every method.
+ */
+export interface OperationalPlatform<TCtx extends OperationalContext = OperationalContext> {
+    /**
+     * Stable platform identifier matching `DecisioningPlatform`'s
+     * registered name. Used by registries and routing layers to look up
+     * the operational delegate by platform.
+     */
+    readonly platformId: string;
+    /**
+     * Synthesize an operational context from a stored token (and
+     * optional request args for fan-out callers). The single
+     * documented credential-synthesis path outside
+     * `AccountStore.resolve` — so the only place adopters need
+     * CTX-METADATA-SAFETY review on the operational side.
+     *
+     * Three call patterns this method serves:
+     *   - **Poller / scheduled job**: `args` is `{}`, `sessionToken` is
+     *     the stored token. Returns a context bound to that token.
+     *   - **Storefront fan-out**: `args` is the (scrubbed) buyer
+     *     request body, `sessionToken` is the storefront's master
+     *     credential. Returns a context for one upstream target.
+     *   - **Server-side internal scan**: `args` is `{}`, `sessionToken`
+     *     is `undefined`, `requireAuth` is `false`. Returns a
+     *     no-token context.
+     *
+     * @param args - Optional request args (storefront fan-out path)
+     * @param sessionToken - Stored access token (poller path)
+     * @param requireAuth - Throw `AdcpError('AUTH_REQUIRED')` when no
+     *   token is available. Defaults to `true`.
+     *
+     * @remarks Post-migration the SDK will likely split this into
+     * `synthesizeFromToken` / `synthesizeFromArgs` (see #1530 for the
+     * follow-up). The combined signature today matches the v5
+     * `PlatformAdapter.extractContext` shape so v5 adapters duck-type
+     * satisfy this interface during migration without a wrapper.
+     */
+    extractContext(args: Record<string, unknown>, sessionToken?: string, requireAuth?: boolean): Promise<TCtx>;
+    /**
+     * Update a media buy upstream. Required because every operational
+     * consumer assumes it — adapters that can't update media buys have
+     * no business registering as operational.
+     *
+     * Throw `AdcpError` for structured rejection (`NOT_CANCELLABLE`,
+     * `CONFLICT`, etc.). Generic thrown errors propagate to the caller.
+     */
+    updateMediaBuy(ctx: TCtx, request: UpdateMediaBuyRequest): Promise<UpdateMediaBuyResponse>;
+    /**
+     * Fetch delivery metrics for one or more media buys. Required for
+     * the same reason as `updateMediaBuy`: every operational consumer
+     * assumes it.
+     *
+     * `mediaBuyIds` is plural — matches the wire-spec
+     * `GetMediaBuyDeliveryRequest.media_buy_ids` field (per AdCP 3.0
+     * and PR #1342). Pollers that batch-query N buys in one upstream
+     * call pass an array; single-buy callers pass `[id]`. Decomposed
+     * here (vs. taking the full request shape) because pollers
+     * synthesize requests internally and don't have a typed wire
+     * payload to thread.
+     *
+     * `args` carries optional adopter-specific pass-through (e.g.
+     * tenant-scoped query parameters); pollers leave it `undefined`.
+     */
+    getMediaBuyDelivery(ctx: TCtx, mediaBuyIds: readonly string[], startTime: string, endTime: string, args?: Record<string, unknown>): Promise<GetMediaBuyDeliveryResponse>;
+    /**
+     * Poll upstream for the current status of one or more audiences.
+     * Optional — only audience-sync pollers need this.
+     *
+     * Takes opaque `platformData` (whatever the adapter stored when
+     * initiating the sync) plus a fresh access token. No operational
+     * context is threaded because the original sync may have been
+     * initiated under a now-expired auth principal; the poller carries
+     * a freshly-resolved token from its own credential store.
+     *
+     * **`platformData` is for opaque upstream IDs only — never for
+     * bearer tokens.** The fresh `accessToken` argument is the blessed
+     * credential channel; reading a stale token from `platformData`
+     * defeats the design and lands requests with revoked auth.
+     *
+     * Returns a `Map<audience_id, AudienceStatus>`. Audiences not
+     * resolvable upstream are omitted from the map. Throw
+     * `AdcpError('REFERENCE_NOT_FOUND')` only when the entire batch
+     * is unresolvable for the tenant.
+     *
+     * Plural method name aligns with `AudiencePlatform.pollAudienceStatuses`
+     * (the buyer-facing analog), which also returns
+     * `Map<string, AudienceStatus>`. Signature differs because operational
+     * callers don't have a `RequestContext` to thread.
+     */
+    pollAudienceStatuses?(platformData: Record<string, unknown>, accessToken: string): Promise<Map<string, AudienceStatus>>;
+    /**
+     * Discover advertising products. Used by storefront bundle services
+     * to query upstream platforms for products available for bundling
+     * — server-side internal call, not buyer-facing dispatch.
+     *
+     * Optional: bundle-search is opt-in per storefront, and not every
+     * upstream platform exposes a product-discovery surface.
+     *
+     * Signature differs from `SalesPlatform.getProducts` because the
+     * caller is a storefront bundle service, not an MCP request
+     * handler — they have a brief and brand context, not a typed
+     * `GetProductsRequest` wire payload.
+     */
+    getProducts?(ctx: TCtx, brief: string, contextId?: string, brand?: Record<string, unknown>, sourceChain?: readonly string[]): Promise<GetProductsResponse>;
+}
+/**
+ * Type-level identity for an `OperationalPlatform` object literal.
+ * Forces the contextual type so handler bodies get typed `ctx` and
+ * `request` parameters in TypeScript without an explicit annotation.
+ *
+ * Mirrors the `definePlatform` family for `DecisioningPlatform`
+ * sub-interfaces — see `decisioning/platform-helpers.ts`.
+ *
+ * @example
+ * ```ts
+ * import { defineOperationalPlatform } from '@adcp/sdk/server';
+ * import { AdcpError } from '@adcp/sdk/server';
+ *
+ * interface SnapOpCtx extends OperationalContext {
+ *   advertiserId: string;
+ * }
+ *
+ * export const snapOperational = defineOperationalPlatform<SnapOpCtx>({
+ *   platformId: 'snap',
+ *   extractContext: async (args, sessionToken, requireAuth = true) => {
+ *     const token = sessionToken ?? String(args.snap_access_token ?? '');
+ *     if (!token && requireAuth) {
+ *       throw new AdcpError('AUTH_REQUIRED', { message: 'No Snap token available' });
+ *     }
+ *     return {
+ *       accessToken: token || undefined,
+ *       advertiserId: String(args.advertiser_id ?? ''),
+ *     };
+ *   },
+ *   updateMediaBuy: async (ctx, request) => {
+ *     // ctx.advertiserId typed ✓; request: UpdateMediaBuyRequest ✓
+ *     return upstream.update(ctx, request);
+ *   },
+ *   getMediaBuyDelivery: async (ctx, id, start, end) => {
+ *     return upstream.delivery(ctx, id, start, end);
+ *   },
+ * });
+ * ```
+ */
+export declare function defineOperationalPlatform<TCtx extends OperationalContext = OperationalContext>(ops: OperationalPlatform<TCtx>): OperationalPlatform<TCtx>;
+//# sourceMappingURL=operational-platform.d.ts.map

package/dist/lib/server/operational-platform.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"operational-platform.d.ts","sourceRoot":"","sources":["../../../src/lib/server/operational-platform.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AAEH,OAAO,KAAK,EACV,2BAA2B,EAC3B,mBAAmB,EACnB,qBAAqB,EACrB,sBAAsB,EACvB,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qCAAqC,CAAC;AAE1E;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;OAIG;IACH,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;CACjC;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,mBAAmB,CAAC,IAAI,SAAS,kBAAkB,GAAG,kBAAkB;IACvF;;;;OAIG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAE5B;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,cAAc,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,CAAC,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE3G;;;;;;;OAOG;IACH,cAAc,CAAC,GAAG,EAAE,IAAI,EAAE,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAAC;IAE3F;;;;;;;;;;;;;;;OAeG;IACH,mBAAmB,CACjB,GAAG,EAAE,IAAI,EACT,WAAW,EAAE,SAAS,MAAM,EAAE,EAC9B,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,OAAO,CAAC,2BAA2B,CAAC,CAAC;IAExC;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,oBAAoB,CAAC,CACnB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACrC,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC,CAAC;IAExC;;;;;;;;;;;;OAYG;IACH,WAAW,CAAC,CACV,GAAG,EAAE,IAAI,EACT,KAAK,EAAE,MAAM,EACb,SAAS,CAAC,EAAE,MAAM,EAClB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,GAC9B,OAAO,CAAC,mBAAmB,CAAC,CAAC;CACjC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,SAAS,kBAAkB,GAAG,kBAAkB,EAC5F,GAAG,EAAE,mBAAmB,CAAC,IAAI,CAAC,GAC7B,mBAAmB,CAAC,IAAI,CAAC,CAE3B"}

package/dist/lib/server/operational-platform.js

@@ -0,0 +1,94 @@
+"use strict";
+/**
+ * `OperationalPlatform` — in-process operational contract.
+ *
+ * `DecisioningPlatform` covers buyer-facing MCP request dispatch:
+ * `platform.sales.updateMediaBuy(req, ctx)` etc., where `ctx` is a
+ * `RequestContext` built by the framework from `authInfo` via
+ * `AccountStore.resolve`, threading `state`, `resolve`, `ctxMetadata`,
+ * and `handoffToTask`.
+ *
+ * In-process consumers are different. The price-optimization poller,
+ * audience-sync task poller, scheduled jobs, and the storefront
+ * fan-out path do NOT have an MCP request to derive auth from. They
+ * have a stored task with an access token (or, for fan-out, no token
+ * — the storefront synthesizes one per upstream target). They cannot
+ * honestly satisfy `RequestContext`. Every adopter doing operational
+ * work would otherwise reinvent this seam.
+ *
+ * `OperationalPlatform` is the named contract for that seam. Five
+ * methods covering the real operational surface:
+ *
+ * 1. `extractContext` — synthesize a per-call platform context from
+ *    a stored token (and optional request args, for fan-out callers).
+ *    The single CTX-METADATA-SAFETY boundary outside
+ *    `AccountStore.resolve`: anything touching credentials in an
+ *    in-process consumer flows through here.
+ * 2. `updateMediaBuy` — required. Fan-out callers dispatch one of
+ *    these per upstream target.
+ * 3. `getMediaBuyDelivery` — required. Pollers read delivery metrics
+ *    here.
+ * 4. `pollAudienceStatuses` — optional. Audience-sync pollers only.
+ * 5. `getProducts` — optional. Storefront bundle composition only;
+ *    server-side internal call, not buyer-facing dispatch.
+ *
+ * Naming the contract honestly — "operational" rather than "adapter"
+ * — separates it from any v5 `PlatformAdapter` baggage and from
+ * `DecisioningPlatform`'s MCP-request flow. Tests mock
+ * `OperationalPlatform`, not the broader v6 interface.
+ *
+ * Errors: methods throw `AdcpError` for structured rejection, matching
+ * `DecisioningPlatform`'s convention. Generic thrown `Error` /
+ * `TypeError` propagate; callers catch and log per their needs.
+ *
+ * Status: 6.10. See adcontextprotocol/adcp-client#1530.
+ *
+ * @see DecisioningPlatform — buyer-facing MCP dispatch
+ * @see docs/guides/CTX-METADATA-SAFETY.md — credential discipline
+ * @public
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defineOperationalPlatform = defineOperationalPlatform;
+/**
+ * Type-level identity for an `OperationalPlatform` object literal.
+ * Forces the contextual type so handler bodies get typed `ctx` and
+ * `request` parameters in TypeScript without an explicit annotation.
+ *
+ * Mirrors the `definePlatform` family for `DecisioningPlatform`
+ * sub-interfaces — see `decisioning/platform-helpers.ts`.
+ *
+ * @example
+ * ```ts
+ * import { defineOperationalPlatform } from '@adcp/sdk/server';
+ * import { AdcpError } from '@adcp/sdk/server';
+ *
+ * interface SnapOpCtx extends OperationalContext {
+ *   advertiserId: string;
+ * }
+ *
+ * export const snapOperational = defineOperationalPlatform<SnapOpCtx>({
+ *   platformId: 'snap',
+ *   extractContext: async (args, sessionToken, requireAuth = true) => {
+ *     const token = sessionToken ?? String(args.snap_access_token ?? '');
+ *     if (!token && requireAuth) {
+ *       throw new AdcpError('AUTH_REQUIRED', { message: 'No Snap token available' });
+ *     }
+ *     return {
+ *       accessToken: token || undefined,
+ *       advertiserId: String(args.advertiser_id ?? ''),
+ *     };
+ *   },
+ *   updateMediaBuy: async (ctx, request) => {
+ *     // ctx.advertiserId typed ✓; request: UpdateMediaBuyRequest ✓
+ *     return upstream.update(ctx, request);
+ *   },
+ *   getMediaBuyDelivery: async (ctx, id, start, end) => {
+ *     return upstream.delivery(ctx, id, start, end);
+ *   },
+ * });
+ * ```
+ */
+function defineOperationalPlatform(ops) {
+    return ops;
+}
+//# sourceMappingURL=operational-platform.js.map

package/dist/lib/server/operational-platform.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"operational-platform.js","sourceRoot":"","sources":["../../../src/lib/server/operational-platform.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;;AA2NH,8DAIC;AA3CD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,SAAgB,yBAAyB,CACvC,GAA8B;IAE9B,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/lib/server/wire-safe.d.ts

@@ -0,0 +1,211 @@
+/**
+ * Wire-spec field discipline at the operational fan-out boundary.
+ *
+ * `WireSafe<T>` is a branded type that signals "this object has been
+ * stripped to AdCP wire-spec fields and is safe to forward upstream."
+ * The brand is constructed only by {@link pickWireSpecFields} (or
+ * variants). Code that spreads a buyer request directly cannot satisfy
+ * the brand — `{ ...buyerReq, paused: true }` is `T`, not
+ * `WireSafe<T>`.
+ *
+ * The brand is the L2 of #1529: where L1 (`credentialPolicy`,
+ * `src/lib/server/credential-policy.ts`) catches credential-shaped
+ * keys at the buyer-facing dispatch boundary, L2 catches structural
+ * leakage at the operational dispatch boundary — storefront fan-out
+ * code that picks per-target args from a buyer request, where the
+ * scrub happens BEFORE the credential scan would have run on the
+ * upstream call.
+ *
+ * **The brand is opt-in at the type level.** `OperationalPlatform`
+ * methods accept plain `UpdateMediaBuyRequest` etc. (not branded —
+ * see #1530's interface), so adopters who don't use the helper
+ * aren't broken. Adopters who DO use the helper get the safety
+ * benefit at the picking site: assigning the result to a
+ * `WireSafe<UpdateMediaBuyRequest>` variable forces `pickWireSpecFields`
+ * to be the constructor; spreading the buyer request elsewhere fails
+ * to satisfy the brand.
+ *
+ * **Migration footgun:** `pickWireSpecFields` ALONE doesn't close
+ * the round-2 / round-3 vectors (nested `context.<x>_access_token`,
+ * nested `ext.<x>_access_token`). `ext` and `context` are wire-spec
+ * fields, so the helper preserves them whole. Storefronts that fan
+ * out MUST chain {@link scrubExtensions} after the pick — that helper
+ * filters ext/context to a caller-specified key allowlist AND
+ * recursively drops credential-shaped keys at any depth (using the
+ * L1 default pattern set or an adopter-supplied matcher). Calling
+ * `pickWireSpecFields` without `scrubExtensions` reopens the
+ * round-2/round-3 attack surface.
+ *
+ * @see docs/guides/CTX-METADATA-SAFETY.md
+ * @see scripts/generate-wire-spec-fields.ts — codegen for the
+ *      allowlist constants this module reads.
+ *
+ * @public
+ */
+import { type CredentialPatternsConfig } from './credential-policy';
+import { WIRE_SPEC_FIELDS, type WireSpecRequestName } from './wire-spec-fields.generated';
+declare const __wireSafe: unique symbol;
+/**
+ * A request shape that has been narrowed to AdCP wire-spec fields.
+ * Cannot be produced by spreading a buyer request — only via
+ * {@link pickWireSpecFields} or by typed `as WireSafe<T>` assertion
+ * at a known-safe construction site (e.g. a poller that builds the
+ * request from stored state, not from buyer input).
+ *
+ * The brand is what makes this load-bearing: `{ ...buyerRequest }` is
+ * `T`, not `WireSafe<T>`, so passing it where `WireSafe<T>` is
+ * required is a compile error.
+ */
+export type WireSafe<T> = T & {
+    readonly [__wireSafe]: true;
+};
+export type { WireSpecRequestName };
+export { WIRE_SPEC_FIELDS };
+/**
+ * The wire-spec request type associated with a `WireSpecRequestName`.
+ * Internal — adopters access it transparently via
+ * `pickWireSpecFields`'s return narrowing.
+ */
+type WireSpecRequestShape<K extends WireSpecRequestName> = (typeof WIRE_SPEC_FIELDS)[K]['__type'];
+/**
+ * Strip a buyer request to the wire-spec fields defined for
+ * `schemaName` and return the result branded `WireSafe<T>`. The
+ * canonical constructor of {@link WireSafe}.
+ *
+ * Drops every property NOT in the schema's `properties` allowlist,
+ * including buyer-supplied unknown keys (`<platform>_access_token`,
+ * `account: { brand: 'attacker.com' }`-style identity-pivot fields,
+ * arbitrary attacker payload). The allowlist comes from codegen — the
+ * AdCP request schema IS the allowlist; drift is structurally
+ * impossible.
+ *
+ * **Top-level only.** `ext` and `context` are wire-spec fields and
+ * are preserved verbatim by this helper. Storefronts MUST chain
+ * {@link scrubExtensions} to drop nested credentials in those
+ * envelopes. See the module-level migration footgun warning.
+ *
+ * Storefronts call this once per upstream target during fan-out:
+ *
+ * ```ts
+ * const safe = pickWireSpecFields(buyerReq, 'UpdateMediaBuyRequest');
+ * for (const target of targets) {
+ *   const perTarget = scrubExtensions(safe, { ... });
+ *   await operational.updateMediaBuy(ctxFor(target), perTarget);
+ * }
+ * ```
+ *
+ * Pollers that construct requests from stored state typically don't
+ * need this — their inputs aren't buyer-controlled. They can opt in
+ * for symmetric type safety with `as WireSafe<T>` if their type
+ * system encourages it, or call this helper anyway (the strip is a
+ * no-op when input is already wire-spec only).
+ *
+ * @param request - Buyer-supplied (or otherwise untrusted) input.
+ * @param schemaName - PascalCase request type name from
+ *   {@link WIRE_SPEC_FIELDS}. TypeScript narrows the return type to
+ *   `WireSafe<RequestType>` based on this — so
+ *   `pickWireSpecFields(req, 'UpdateMediaBuyRequest')` returns
+ *   `WireSafe<UpdateMediaBuyRequest>`.
+ *
+ * @example
+ * ```ts
+ * import { pickWireSpecFields } from '@adcp/sdk/server';
+ *
+ * // Buyer sends:
+ * //   { media_buy_id: 'mb_1', paused: true, snap_access_token: 'attacker' }
+ * const safe = pickWireSpecFields(buyerReq, 'UpdateMediaBuyRequest');
+ * // safe: WireSafe<UpdateMediaBuyRequest>
+ * //   value: { media_buy_id: 'mb_1', paused: true } — credential dropped
+ * ```
+ */
+export declare function pickWireSpecFields<K extends WireSpecRequestName>(request: unknown, schemaName: K): WireSafe<WireSpecRequestShape<K>>;
+/**
+ * Apply an extension-object allowlist to a `WireSafe<T>` and
+ * recursively scrub credential-shaped values. Closes the round-2 /
+ * round-3 nested-credential vectors that `pickWireSpecFields` alone
+ * leaves open (because `ext` and `context` are wire-spec fields and
+ * are preserved verbatim by the pick).
+ *
+ * Three operations, applied in order:
+ *
+ * 1. **Top-level allowlist filter** (when `allowedExtKeys` is set):
+ *    drop keys from `ext` and `context` that aren't in the
+ *    allowlist. Pass an empty Set to drop both fields entirely;
+ *    pass `undefined` to leave the top level untouched.
+ * 2. **Recursive credential scan** (when `recursiveCredentialScan`
+ *    is `true`, default): walk surviving values in `ext`/`context`
+ *    at any depth and drop nested keys that match the L1
+ *    credential-pattern set (or an adopter-supplied matcher). Closes
+ *    `ext.partner.token` and similar deep-nesting attack vectors.
+ * 3. **Adopter inject** (when `inject` is set): merge
+ *    storefront-controlled values into `ext` and/or `context`.
+ *    Inject runs LAST so storefront-resolved credentials override
+ *    any allowlisted buyer values that collide.
+ *
+ * The `WireSafe<T>` brand survives — the operation is closed over
+ * the wire-spec field set.
+ *
+ * @example
+ * ```ts
+ * const safe = pickWireSpecFields(buyerReq, 'UpdateMediaBuyRequest');
+ * const perTarget = scrubExtensions(safe, {
+ *   allowedExtKeys: new Set(['scope3_api_key', 'partner_request_id']),
+ *   inject: {
+ *     context: {
+ *       managed_access_token: target.token,
+ *       managed_advertiser_id: target.advertiserId,
+ *     },
+ *   },
+ * });
+ * ```
+ */
+export interface ScrubExtensionsOptions {
+    /**
+     * Set of keys permitted to survive on `ext` and `context`. Keys
+     * outside this set are dropped from both. Pass `undefined` to leave
+     * `ext`/`context` top-level untouched (only the recursive scan and
+     * `inject` apply); pass an empty set to drop both entirely.
+     */
+    allowedExtKeys?: ReadonlySet<string>;
+    /**
+     * When true (default), recursively walk surviving `ext`/`context`
+     * values and drop nested keys matching the credential-pattern set.
+     * Closes round-4-style deep-nesting attack vectors that the
+     * top-level allowlist alone cannot — e.g. an adopter who allowlists
+     * `partner` and forgets that `partner.token` is buyer-controlled.
+     *
+     * Set to `false` only when you've validated the surviving
+     * `ext`/`context` shapes yourself (e.g. via Zod-typed extensions).
+     */
+    recursiveCredentialScan?: boolean;
+    /**
+     * Optional matcher overrides for the recursive scan. Defaults to
+     * the L1 credential-policy default pattern set
+     * ({@link DEFAULT_CREDENTIAL_PATTERNS}). Pass `extend` to add
+     * adopter-specific patterns; pass `matcher` to fully replace the
+     * regex set.
+     */
+    credentialPatterns?: CredentialPatternsConfig;
+    /**
+     * Adopter-controlled values to merge into `ext` and/or `context`
+     * AFTER the allowlist filter and recursive scan run. Used to inject
+     * storefront-owned routing tokens (e.g. resolved per-target
+     * advertiser IDs) into the per-target request.
+     *
+     * **Adopter-side ONLY — values here MUST be storefront-derived,
+     * never read from the incoming buyer request.** Threading buyer-
+     * controlled values through `inject` defeats the discipline.
+     * Values injected here bypass the recursive credential scan and
+     * are merged in after it completes — ensure they are fully
+     * storefront-derived, never shaped by buyer input.
+     */
+    inject?: {
+        ext?: Record<string, unknown>;
+        context?: Record<string, unknown>;
+    };
+}
+/**
+ * Implementation of {@link ScrubExtensionsOptions}. See JSDoc above.
+ */
+export declare function scrubExtensions<T extends object>(request: WireSafe<T>, options: ScrubExtensionsOptions): WireSafe<T>;
+//# sourceMappingURL=wire-safe.d.ts.map

package/dist/lib/server/wire-safe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wire-safe.d.ts","sourceRoot":"","sources":["../../../src/lib/server/wire-safe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAEH,OAAO,EAA0B,KAAK,wBAAwB,EAAE,MAAM,qBAAqB,CAAC;AAC5F,OAAO,EAAE,gBAAgB,EAAE,KAAK,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AAE1F,OAAO,CAAC,MAAM,UAAU,EAAE,OAAO,MAAM,CAAC;AAExC;;;;;;;;;;GAUG;AACH,MAAM,MAAM,QAAQ,CAAC,CAAC,IAAI,CAAC,GAAG;IAAE,QAAQ,CAAC,CAAC,UAAU,CAAC,EAAE,IAAI,CAAA;CAAE,CAAC;AAE9D,YAAY,EAAE,mBAAmB,EAAE,CAAC;AAEpC,OAAO,EAAE,gBAAgB,EAAE,CAAC;AAE5B;;;;GAIG;AACH,KAAK,oBAAoB,CAAC,CAAC,SAAS,mBAAmB,IAAI,CAAC,OAAO,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;AAElG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,mBAAmB,EAC9D,OAAO,EAAE,OAAO,EAChB,UAAU,EAAE,CAAC,GACZ,QAAQ,CAAC,oBAAoB,CAAC,CAAC,CAAC,CAAC,CAuBnC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;;;OAKG;IACH,cAAc,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAErC;;;;;;;;;OASG;IACH,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAElC;;;;;;OAMG;IACH,kBAAkB,CAAC,EAAE,wBAAwB,CAAC;IAE9C;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,EAAE;QACP,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAC9B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACnC,CAAC;CACH;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,MAAM,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,sBAAsB,GAAG,QAAQ,CAAC,CAAC,CAAC,CAyDpH"}