@adcp/sdk 6.9.0 → 6.11.0

package/dist/lib/server/credential-policy.d.ts

@@ -0,0 +1,221 @@
+/**
+ * Credential discipline at the request boundary.
+ *
+ * Scans incoming buyer args for credential-shaped keys at any depth and
+ * rejects with `INVALID_REQUEST` when `credentialPolicy === 'authInfo-only'`.
+ * Closes the bug class observed in storefront fan-out paths where buyer-
+ * supplied keys like `<platform>_access_token` (top-level, in `context`,
+ * or in `ext`) flow through to upstream calls.
+ *
+ * Default mode is `'lax'` for back-compat. Opt into `'authInfo-only'` to
+ * enforce: credentials must arrive on `authInfo` (the framework-resolved
+ * bearer / signature / OAuth principal) and never on the args bag.
+ *
+ * Pattern set is extensible. Adopters whose platform vocabulary uses
+ * additional credential names extend via `credentialPolicy.patterns.extend`
+ * or replace the matcher entirely. Per-tool opt-out via
+ * `credentialPolicy.tools`.
+ *
+ * @see {@link AdcpServerConfig.credentialPolicy}
+ * @see docs/guides/CTX-METADATA-SAFETY.md
+ */
+/**
+ * Enforcement mode.
+ *
+ * - `'lax'` — no scan; current behavior.
+ * - `'authInfo-only'` — scan args for credential-shaped keys; reject any
+ *   match with `INVALID_REQUEST` listing the offending paths (not values).
+ *   Adopters who legitimately accept buyer-presented credentials opt out
+ *   per-tool via {@link CredentialPolicyConfig.tools}.
+ */
+export type CredentialPolicyMode = 'lax' | 'authInfo-only';
+/**
+ * Patterns that flag a key as credential-shaped. Values matching ANY
+ * regex (or returning `true` from the matcher) are treated as
+ * credential-bearing.
+ */
+export interface CredentialPatternsConfig {
+    /**
+     * Additional patterns appended to {@link DEFAULT_CREDENTIAL_PATTERNS}.
+     * Use for platform-specific names the defaults don't cover (e.g.
+     * `/^bearer$/i`, `/credentials/i`, `/^[a-z]+Pat$/`).
+     */
+    extend?: RegExp[];
+    /**
+     * Replace the regex-based check entirely. Receives each property name
+     * encountered during recursion, plus the parent path. Return `true`
+     * to flag as credential-bearing. Mutually exclusive with `extend` —
+     * setting both throws at server construction.
+     */
+    matcher?: (key: string, path: readonly string[]) => boolean;
+}
+/**
+ * Per-tool override shape. Adopters specify either a mode string for
+ * coarse-grained override (`'lax'` lets every credential-shaped key
+ * through; `'authInfo-only'` rejects them all) or a granular
+ * `{ allow: [...] }` allowlist that permits specific credential paths
+ * while still rejecting unlisted ones.
+ *
+ * The `allow` shape is the recommended choice for storefronts that
+ * legitimately accept ONE specific buyer-presented credential per
+ * tool — `tools: { activate_signal: 'lax' }` opens the tool to every
+ * credential-shaped key (including `password=`, `client_secret=`),
+ * while `tools: { activate_signal: { allow: ['delivery.api_token'] } }`
+ * permits only the spec-blessed field and still rejects everything
+ * else.
+ */
+export type ToolCredentialPolicy = CredentialPolicyMode | {
+    readonly allow: readonly string[];
+};
+/**
+ * Full credential-policy configuration. Pass a string for the simple
+ * case (`credentialPolicy: 'authInfo-only'`) or this shape for
+ * pattern customization or per-tool overrides.
+ */
+export interface CredentialPolicyConfig {
+    policy: CredentialPolicyMode;
+    patterns?: CredentialPatternsConfig;
+    /**
+     * Per-tool mode overrides. Storefronts that legitimately accept
+     * buyer-presented credentials on a specific tool opt that tool out
+     * of the server-wide `'authInfo-only'`:
+     *
+     * ```ts
+     * credentialPolicy: {
+     *   policy: 'authInfo-only',
+     *   tools: {
+     *     // Coarse: lets every credential-shaped key through
+     *     legacy_tool: 'lax',
+     *
+     *     // Granular: only the listed paths are allowlisted; other
+     *     // credential-shaped keys still reject. Recommended for
+     *     // tools where the legitimate buyer-presented credential is
+     *     // a known, named field.
+     *     activate_signal: { allow: ['delivery.api_token'] },
+     *   },
+     * }
+     * ```
+     *
+     * Allowlist entries are exact path matches against the
+     * dot-notation path the scanner emits — e.g. `'snap_access_token'`
+     * (top-level), `'context.linkedin_access_token'` (nested),
+     * `'packages.0.extra.tiktok_access_token'` (array element).
+     */
+    tools?: Record<string, ToolCredentialPolicy>;
+    /**
+     * Extend the credential-shaped-key scan to cover `ctx.authInfo.extra`
+     * in addition to the buyer args bag. Default `false`.
+     *
+     * Custom authenticators that stamp values into `authInfo.extra` (token
+     * introspection responses, JWT claim sets, OAuth scope blobs) are
+     * outside L1's args-bag scan. Adopter handler code that reads
+     * `ctx.authInfo.extra.<credential>` for upstream auth produces a
+     * silent leak surface: a buggy `BuyerAgentRegistry.resolve` factory
+     * that throws an error embedding `extra` lands the value in
+     * `logger.error` before `redactCredentialPatterns` (which only catches
+     * labeled `Bearer <token>` shapes and ≥32-char base64 blobs) could
+     * mask it.
+     *
+     * Orthogonal to {@link policy} — adopters can mix-and-match. Common
+     * shapes:
+     *
+     * - `policy: 'authInfo-only', scanAuthInfo: true` — strictest.
+     * - `policy: 'lax', scanAuthInfo: true` — trust args, defend log
+     *   propagation of authInfo extras.
+     * - `policy: 'authInfo-only', scanAuthInfo: false` — current default
+     *   if `scanAuthInfo` is omitted; args-only enforcement.
+     *
+     * **Default `false` is deliberate.** OAuth introspection blobs and
+     * JWT claims in `extra` will false-positive on default patterns
+     * like `/_token$/i` (e.g. `id_token`, `access_token` claims that
+     * the framework's authenticator legitimately stamps).
+     *
+     * **Wire-envelope discipline.** Args-bag hits are reported in
+     * `details.credential_paths` (the buyer already sent these — no
+     * info disclosure). `authInfo.extra` hits are NOT reported on
+     * the wire; they're logged server-side only. Returning paths
+     * to the buyer would create a probing oracle for the structure
+     * of `authInfo.extra` (an internal value the buyer has no read
+     * access to). The wire envelope reports a coarse signal —
+     * `details.scope: 'credentials'` plus a generic message —
+     * without enumerating which `extra` field tripped the scan.
+     *
+     * See adcontextprotocol/adcp-client#1539.
+     */
+    scanAuthInfo?: boolean;
+}
+export type CredentialPolicy = CredentialPolicyMode | CredentialPolicyConfig;
+/**
+ * Default credential-name patterns. Catches the three vectors observed
+ * in PR scope3data/agentic-adapters#248 plus the broader credential
+ * vocabulary common in TS ecosystems and HTTPSig / OAuth flows.
+ * Adopters whose platform names fall outside this set extend via
+ * {@link CredentialPatternsConfig.extend}.
+ *
+ * Coverage:
+ *   - `_token$` (case-insensitive) — `*_access_token`, `bearer_token`,
+ *     `id_token`, `session_token`, `auth_token`, `refresh_token`.
+ *   - `_secret$` / `_password$` — `client_secret`, `db_password`.
+ *   - `api[_-]?key` (case-insensitive) — `api_key`, `apiKey`, `api-key`,
+ *     and prefixed variants like `criteo_api_key`.
+ *   - `private[_-]?key` (case-insensitive) — `private_key`, `privateKey`,
+ *     `private-key`. Common in JWT / RFC 9421 signing-key flows.
+ *   - `^authorization$` / `^cookie$` (case-insensitive) — HTTP-header
+ *     value smuggled as a field.
+ *   - `^bearer$` — bare `bearer` field.
+ *   - `^accessToken$` / `^refreshToken$` (case-insensitive) — camelCase
+ *     and PascalCase exact matches.
+ *
+ * Intentionally excluded from defaults (too many false positives):
+ *   - bare `key` / `principal` / `kid` / `pat` — too short to risk
+ *     matching legitimate routing fields.
+ *   - `*Token$` PascalCase suffix without a known prefix — e.g.
+ *     `paymentToken` could be a legitimate wire field. Adopters who
+ *     want broader coverage extend.
+ */
+export declare const DEFAULT_CREDENTIAL_PATTERNS: readonly RegExp[];
+/**
+ * Recursively scan `value` for credential-shaped keys. Returns dotted
+ * paths to every match (e.g. `['snap_access_token',
+ * 'context.snap_access_token', 'ext.snap_access_token']`). Empty array
+ * means clean.
+ *
+ * Scope:
+ *   - Walks own string-keyed data properties only. Symbol keys,
+ *     prototype-chain inherited properties, and accessor (getter/setter)
+ *     properties are skipped — JSON-derived inputs (the only source the
+ *     framework dispatches) cannot carry any of those. Hand-built
+ *     objects with credential-named getters are still flagged
+ *     fail-closed (the property name is matched against the regex
+ *     set), but the getter is never invoked, so a throwing or
+ *     side-effecting getter cannot reach the dispatcher.
+ *   - Walks both plain objects and arrays; array indices appear as
+ *     numeric path segments.
+ *   - Stops at primitives.
+ *   - Cycle-safe via a `WeakSet` tracking visited objects.
+ */
+export declare function scanArgsForCredentials(value: unknown, patterns?: CredentialPatternsConfig): string[];
+/**
+ * Normalize a `CredentialPolicy` (string or object) plus a tool name
+ * to the effective {@link ToolCredentialPolicy} for that tool —
+ * either a mode string or an `{ allow: [...] }` allowlist. Per-tool
+ * overrides win; otherwise the server-wide policy applies.
+ *
+ * Caller dispatch:
+ *
+ * ```ts
+ * const effective = resolveCredentialPolicyForTool(policy, toolName);
+ * if (effective === 'lax') return; // skip scan
+ * const hits = scanArgsForCredentials(args, patterns);
+ * if (typeof effective === 'object') {
+ *   // Granular allow — filter hits by the allowlist
+ *   const blocked = hits.filter(p => !effective.allow.includes(p));
+ *   if (blocked.length > 0) reject(blocked);
+ * } else {
+ *   // 'authInfo-only' — every hit blocks
+ *   if (hits.length > 0) reject(hits);
+ * }
+ * ```
+ */
+export declare function resolveCredentialPolicyForTool(policy: CredentialPolicy | undefined, toolName: string): ToolCredentialPolicy;
+//# sourceMappingURL=credential-policy.d.ts.map

package/dist/lib/server/credential-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"credential-policy.d.ts","sourceRoot":"","sources":["../../../src/lib/server/credential-policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH;;;;;;;;GAQG;AACH,MAAM,MAAM,oBAAoB,GAAG,KAAK,GAAG,eAAe,CAAC;AAE3D;;;;GAIG;AACH,MAAM,WAAW,wBAAwB;IACvC;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAElB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,KAAK,OAAO,CAAC;CAC7D;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,oBAAoB,GAAG,oBAAoB,GAAG;IAAE,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,CAAC;AAEhG;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,oBAAoB,CAAC;IAC7B,QAAQ,CAAC,EAAE,wBAAwB,CAAC;IACpC;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC;IAE7C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAuCG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,MAAM,gBAAgB,GAAG,oBAAoB,GAAG,sBAAsB,CAAC;AAE7E;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,eAAO,MAAM,2BAA2B,EAAE,SAAS,MAAM,EAWvD,CAAC;AAmCH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,wBAAwB,GAAG,MAAM,EAAE,CAqDpG;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,8BAA8B,CAC5C,MAAM,EAAE,gBAAgB,GAAG,SAAS,EACpC,QAAQ,EAAE,MAAM,GACf,oBAAoB,CAItB"}

package/dist/lib/server/credential-policy.js

@@ -0,0 +1,260 @@
+"use strict";
+/**
+ * Credential discipline at the request boundary.
+ *
+ * Scans incoming buyer args for credential-shaped keys at any depth and
+ * rejects with `INVALID_REQUEST` when `credentialPolicy === 'authInfo-only'`.
+ * Closes the bug class observed in storefront fan-out paths where buyer-
+ * supplied keys like `<platform>_access_token` (top-level, in `context`,
+ * or in `ext`) flow through to upstream calls.
+ *
+ * Default mode is `'lax'` for back-compat. Opt into `'authInfo-only'` to
+ * enforce: credentials must arrive on `authInfo` (the framework-resolved
+ * bearer / signature / OAuth principal) and never on the args bag.
+ *
+ * Pattern set is extensible. Adopters whose platform vocabulary uses
+ * additional credential names extend via `credentialPolicy.patterns.extend`
+ * or replace the matcher entirely. Per-tool opt-out via
+ * `credentialPolicy.tools`.
+ *
+ * @see {@link AdcpServerConfig.credentialPolicy}
+ * @see docs/guides/CTX-METADATA-SAFETY.md
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_CREDENTIAL_PATTERNS = void 0;
+exports.scanArgsForCredentials = scanArgsForCredentials;
+exports.resolveCredentialPolicyForTool = resolveCredentialPolicyForTool;
+exports.validateCredentialPolicy = validateCredentialPolicy;
+/**
+ * Default credential-name patterns. Catches the three vectors observed
+ * in PR scope3data/agentic-adapters#248 plus the broader credential
+ * vocabulary common in TS ecosystems and HTTPSig / OAuth flows.
+ * Adopters whose platform names fall outside this set extend via
+ * {@link CredentialPatternsConfig.extend}.
+ *
+ * Coverage:
+ *   - `_token$` (case-insensitive) — `*_access_token`, `bearer_token`,
+ *     `id_token`, `session_token`, `auth_token`, `refresh_token`.
+ *   - `_secret$` / `_password$` — `client_secret`, `db_password`.
+ *   - `api[_-]?key` (case-insensitive) — `api_key`, `apiKey`, `api-key`,
+ *     and prefixed variants like `criteo_api_key`.
+ *   - `private[_-]?key` (case-insensitive) — `private_key`, `privateKey`,
+ *     `private-key`. Common in JWT / RFC 9421 signing-key flows.
+ *   - `^authorization$` / `^cookie$` (case-insensitive) — HTTP-header
+ *     value smuggled as a field.
+ *   - `^bearer$` — bare `bearer` field.
+ *   - `^accessToken$` / `^refreshToken$` (case-insensitive) — camelCase
+ *     and PascalCase exact matches.
+ *
+ * Intentionally excluded from defaults (too many false positives):
+ *   - bare `key` / `principal` / `kid` / `pat` — too short to risk
+ *     matching legitimate routing fields.
+ *   - `*Token$` PascalCase suffix without a known prefix — e.g.
+ *     `paymentToken` could be a legitimate wire field. Adopters who
+ *     want broader coverage extend.
+ */
+exports.DEFAULT_CREDENTIAL_PATTERNS = Object.freeze([
+    /_token$/i,
+    /_secret$/i,
+    /_password$/i,
+    /api[_-]?key/i,
+    /private[_-]?key/i,
+    /^authorization$/i,
+    /^cookie$/i,
+    /^bearer$/i,
+    /^accessToken$/i,
+    /^refreshToken$/i,
+]);
+/**
+ * Strip `/g` and `/y` flags from a regex. With those flags set,
+ * `RegExp.prototype.test` advances `lastIndex`, causing alternating-skip
+ * behavior on repeated calls against the same pattern instance. The
+ * scanner calls `.test()` per key per request and reuses the regex
+ * instance across calls, so `/credentials/gi` (a natural footgun) would
+ * produce non-deterministic hits. Strip the offending flags rather than
+ * forcing adopters to read a footnote.
+ */
+function stripStatefulFlags(rx) {
+    if (!rx.global && !rx.sticky)
+        return rx;
+    return new RegExp(rx.source, rx.flags.replace(/[gy]/g, ''));
+}
+function buildMatcher(patterns) {
+    if (patterns?.matcher && patterns.extend) {
+        throw new Error('createAdcpServer: credentialPolicy.patterns cannot set both `matcher` and `extend`. ' +
+            '`matcher` fully replaces the regex-based check; `extend` adds to the default set. ' +
+            'Pick one — they answer different questions and combining them silently drops the regex set.');
+    }
+    if (patterns?.matcher) {
+        return patterns.matcher;
+    }
+    const regexes = patterns?.extend
+        ? [...exports.DEFAULT_CREDENTIAL_PATTERNS, ...patterns.extend.map(stripStatefulFlags)]
+        : exports.DEFAULT_CREDENTIAL_PATTERNS;
+    return (key) => regexes.some(rx => rx.test(key));
+}
+/**
+ * Recursively scan `value` for credential-shaped keys. Returns dotted
+ * paths to every match (e.g. `['snap_access_token',
+ * 'context.snap_access_token', 'ext.snap_access_token']`). Empty array
+ * means clean.
+ *
+ * Scope:
+ *   - Walks own string-keyed data properties only. Symbol keys,
+ *     prototype-chain inherited properties, and accessor (getter/setter)
+ *     properties are skipped — JSON-derived inputs (the only source the
+ *     framework dispatches) cannot carry any of those. Hand-built
+ *     objects with credential-named getters are still flagged
+ *     fail-closed (the property name is matched against the regex
+ *     set), but the getter is never invoked, so a throwing or
+ *     side-effecting getter cannot reach the dispatcher.
+ *   - Walks both plain objects and arrays; array indices appear as
+ *     numeric path segments.
+ *   - Stops at primitives.
+ *   - Cycle-safe via a `WeakSet` tracking visited objects.
+ */
+function scanArgsForCredentials(value, patterns) {
+    const matcher = buildMatcher(patterns);
+    const hits = [];
+    const seen = new WeakSet();
+    const walk = (node, path) => {
+        if (node === null || typeof node !== 'object')
+            return;
+        if (seen.has(node))
+            return;
+        seen.add(node);
+        if (Array.isArray(node)) {
+            for (let i = 0; i < node.length; i++) {
+                walk(node[i], [...path, String(i)]);
+            }
+            return;
+        }
+        // Use property descriptors so accessor (getter/setter) properties
+        // are visible to the scanner without invoking the getter — a
+        // throwing getter on a credential-named property would otherwise
+        // either crash the dispatcher or land the surrounding `params`
+        // object in an outer error log. Data-only inputs (JSON.parse,
+        // structured clone) never have accessor descriptors, so this is
+        // a defensive measure for hand-built test inputs and any future
+        // transport that bypasses JSON parsing.
+        let descriptors;
+        try {
+            descriptors = Object.getOwnPropertyDescriptors(node);
+        }
+        catch {
+            // Proxy-trapped property enumeration that throws — fail closed
+            // by recording the parent path as suspicious. Cannot enumerate
+            // to a finer-grained location.
+            hits.push([...path, '<unreadable>'].join('.'));
+            return;
+        }
+        for (const key of Object.keys(descriptors)) {
+            const desc = descriptors[key];
+            if (desc === undefined)
+                continue;
+            const childPath = [...path, key];
+            if (matcher(key, path)) {
+                hits.push(childPath.join('.'));
+            }
+            // Only recurse into data descriptors. Accessor descriptors
+            // (no `value` slot) are flagged-by-name above but never invoked.
+            if ('value' in desc) {
+                walk(desc.value, childPath);
+            }
+        }
+    };
+    walk(value, []);
+    return hits;
+}
+/**
+ * Normalize a `CredentialPolicy` (string or object) plus a tool name
+ * to the effective {@link ToolCredentialPolicy} for that tool —
+ * either a mode string or an `{ allow: [...] }` allowlist. Per-tool
+ * overrides win; otherwise the server-wide policy applies.
+ *
+ * Caller dispatch:
+ *
+ * ```ts
+ * const effective = resolveCredentialPolicyForTool(policy, toolName);
+ * if (effective === 'lax') return; // skip scan
+ * const hits = scanArgsForCredentials(args, patterns);
+ * if (typeof effective === 'object') {
+ *   // Granular allow — filter hits by the allowlist
+ *   const blocked = hits.filter(p => !effective.allow.includes(p));
+ *   if (blocked.length > 0) reject(blocked);
+ * } else {
+ *   // 'authInfo-only' — every hit blocks
+ *   if (hits.length > 0) reject(hits);
+ * }
+ * ```
+ */
+function resolveCredentialPolicyForTool(policy, toolName) {
+    if (policy === undefined)
+        return 'lax';
+    if (typeof policy === 'string')
+        return policy;
+    return policy.tools?.[toolName] ?? policy.policy;
+}
+/**
+ * Validate a `CredentialPolicy` at server construction. Catches typos
+ * in `tools` keys (`activte_signal` instead of `activate_signal`) and
+ * the both-`extend`-and-`matcher` config error before any traffic
+ * dispatches. Throws `Error` with a specific message; callers convert
+ * to their construction-time error envelope of choice.
+ *
+ * `knownToolNames` is the set of tool names the framework will
+ * register for this server (spec tools for the claimed specialisms +
+ * any adopter-supplied custom tools). Pass after the registration
+ * loop completes so the set is authoritative.
+ *
+ * @internal — adopters cannot construct `knownToolNames` outside the
+ * framework. The framework calls this once, late in `createAdcpServer`,
+ * after every tool (including `get_adcp_capabilities`) is registered.
+ */
+function validateCredentialPolicy(policy, knownToolNames) {
+    if (policy === undefined || typeof policy === 'string')
+        return;
+    // Surface the both-fields-set conflict at construction, not on the
+    // first credential-bearing request. Mirrors the runtime check in
+    // `buildMatcher` so adopters get the same diagnostic regardless of
+    // whether traffic is flowing yet.
+    if (policy.patterns?.matcher && policy.patterns?.extend) {
+        throw new Error('createAdcpServer: credentialPolicy.patterns cannot set both `matcher` and `extend`. ' +
+            '`matcher` fully replaces the regex-based check; `extend` adds to the default set. Pick one.');
+    }
+    if (!policy.tools)
+        return;
+    const unknownTools = Object.keys(policy.tools).filter(name => !knownToolNames.has(name));
+    if (unknownTools.length > 0) {
+        const known = [...knownToolNames].sort().join(', ');
+        throw new Error(`createAdcpServer: credentialPolicy.tools references unregistered tool name(s): ${unknownTools
+            .map(n => JSON.stringify(n))
+            .join(', ')}. ` +
+            `A typo in this map silently no-ops the per-tool override and the server-wide policy applies, ` +
+            `which fails-closed on tools that needed an opt-out. ` +
+            `Known tool names: ${known}.`);
+    }
+    // Validate granular allow-shape entries — each must be a non-empty
+    // array of strings. An empty `allow` is the same as 'authInfo-only'
+    // for that tool (no path is permitted) and is almost certainly a
+    // bug — surface it at construction. Non-string entries would
+    // silently never match the dotted-path strings the scanner emits.
+    for (const [toolName, toolPolicy] of Object.entries(policy.tools)) {
+        if (typeof toolPolicy === 'string')
+            continue;
+        if (!Array.isArray(toolPolicy.allow)) {
+            throw new Error(`createAdcpServer: credentialPolicy.tools[${JSON.stringify(toolName)}].allow must be an array of path strings.`);
+        }
+        if (toolPolicy.allow.length === 0) {
+            throw new Error(`createAdcpServer: credentialPolicy.tools[${JSON.stringify(toolName)}].allow is empty. ` +
+                `An empty allow list is equivalent to 'authInfo-only' for this tool — drop the entry or use the string shorthand.`);
+        }
+        const nonStrings = toolPolicy.allow.filter(p => typeof p !== 'string');
+        if (nonStrings.length > 0) {
+            throw new Error(`createAdcpServer: credentialPolicy.tools[${JSON.stringify(toolName)}].allow contains non-string entries: ` +
+                `${nonStrings.map(n => JSON.stringify(n)).join(', ')}. ` +
+                `Allowlist entries are exact-match path strings (e.g. 'context.snap_access_token').`);
+        }
+    }
+}
+//# sourceMappingURL=credential-policy.js.map

package/dist/lib/server/credential-policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"credential-policy.js","sourceRoot":"","sources":["../../../src/lib/server/credential-policy.ts"],"names":[],"mappings":"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"}

package/dist/lib/server/decisioning/async-outcome.d.ts

@@ -112,6 +112,23 @@ export declare class AdcpError extends Error {
  * one without going through `ctx.handoffToTask(fn)`.
  */
 declare const TASK_HANDOFF_BRAND: unique symbol;
+/**
+ * Optional overrides for `ctx.handoffToTask`.
+ *
+ * @public
+ */
+export interface TaskHandoffOptions {
+    /**
+     * Use this exact string as the `task_id` instead of letting the framework
+     * mint a fresh one. Required when an upstream system (or a test-controller
+     * directive such as `force_create_media_buy_arm`) has already issued the ID
+     * and the spec contract demands the response echoes it verbatim.
+     *
+     * Constraints: non-empty, ≤ 128 characters. Throws if violated.
+     * The caller is responsible for uniqueness within the account.
+     */
+    task_id?: string;
+}
 /**
  * Marker the framework recognizes as "promote this call to a task."
  * Returned from `ctx.handoffToTask(fn)`. Type parameter `TResult` is the

package/dist/lib/server/decisioning/async-outcome.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"async-outcome.d.ts","sourceRoot":"","sources":["../../../../src/lib/server/decisioning/async-outcome.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,EAAoB,KAAK,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAEnF;;;;;;;GAOG;AACH,eAAO,MAAM,iBAAiB,k8BAAkB,CAAC;AAEjD,MAAM,MAAM,SAAS,GAAG,iBAAiB,CAAC;AA+B1C;;;;;;;;;;GAUG;AACH,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,SAAS,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;IAChC,QAAQ,EAAE,WAAW,GAAG,aAAa,GAAG,UAAU,CAAC;IACnD,OAAO,EAAE,MAAM,CAAC;IAChB,8EAA8E;IAC9E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,2CAA2C;IAC3C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,SAAU,SAAQ,KAAK;IAClC,QAAQ,CAAC,IAAI,EAAG,WAAW,CAAU;IACrC,QAAQ,CAAC,IAAI,EAAE,SAAS,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;IACzC,QAAQ,CAAC,QAAQ,EAAE,WAAW,GAAG,aAAa,GAAG,UAAU,CAAC;IAC5D,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;gBAGzC,IAAI,EAAE,SAAS,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,EAC/B,OAAO,EAAE;QACP;;;;;WAKG;QACH,QAAQ,CAAC,EAAE,WAAW,GAAG,aAAa,GAAG,UAAU,CAAC;QACpD,OAAO,EAAE,MAAM,CAAC;QAChB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACnC;IAgBH,kFAAkF;IAClF,iBAAiB,IAAI,mBAAmB;IAYxC;;;;;;OAMG;IACM,QAAQ,IAAI,MAAM;CAG5B;AAMD;;;;GAIG;AACH,QAAA,MAAM,kBAAkB,EAAE,OAAO,MAAqD,CAAC;AAavF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,WAAW,WAAW,CAAC,OAAO;IAClC,QAAQ,CAAC,CAAC,kBAAkB,CAAC,EAAE,IAAI,CAAC;CASrC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,QAAQ,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrD,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5B;AAED,MAAM,WAAW,mBAAmB;IAClC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB"}
+{"version":3,"file":"async-outcome.d.ts","sourceRoot":"","sources":["../../../../src/lib/server/decisioning/async-outcome.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,EAAoB,KAAK,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAEnF;;;;;;;GAOG;AACH,eAAO,MAAM,iBAAiB,k8BAAkB,CAAC;AAEjD,MAAM,MAAM,SAAS,GAAG,iBAAiB,CAAC;AA+B1C;;;;;;;;;;GAUG;AACH,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,SAAS,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;IAChC,QAAQ,EAAE,WAAW,GAAG,aAAa,GAAG,UAAU,CAAC;IACnD,OAAO,EAAE,MAAM,CAAC;IAChB,8EAA8E;IAC9E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,2CAA2C;IAC3C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,SAAU,SAAQ,KAAK;IAClC,QAAQ,CAAC,IAAI,EAAG,WAAW,CAAU;IACrC,QAAQ,CAAC,IAAI,EAAE,SAAS,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;IACzC,QAAQ,CAAC,QAAQ,EAAE,WAAW,GAAG,aAAa,GAAG,UAAU,CAAC;IAC5D,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;gBAGzC,IAAI,EAAE,SAAS,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,EAC/B,OAAO,EAAE;QACP;;;;;WAKG;QACH,QAAQ,CAAC,EAAE,WAAW,GAAG,aAAa,GAAG,UAAU,CAAC;QACpD,OAAO,EAAE,MAAM,CAAC;QAChB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACnC;IAgBH,kFAAkF;IAClF,iBAAiB,IAAI,mBAAmB;IAYxC;;;;;;OAMG;IACM,QAAQ,IAAI,MAAM;CAG5B;AAMD;;;;GAIG;AACH,QAAA,MAAM,kBAAkB,EAAE,OAAO,MAAqD,CAAC;AAEvF;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAiBD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,WAAW,WAAW,CAAC,OAAO;IAClC,QAAQ,CAAC,CAAC,kBAAkB,CAAC,EAAE,IAAI,CAAC;CASrC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,QAAQ,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrD,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5B;AAED,MAAM,WAAW,mBAAmB;IAClC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB"}

package/dist/lib/server/decisioning/async-outcome.js

@@ -19,7 +19,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.AdcpError = exports.KNOWN_ERROR_CODES = void 0;
 exports._createTaskHandoff = _createTaskHandoff;
 exports.isTaskHandoff = isTaskHandoff;
-exports._extractTaskFn = _extractTaskFn;
+exports._extractHandoffEntry = _extractHandoffEntry;
 const enums_generated_1 = require("../../types/enums.generated");
 const error_codes_1 = require("../../types/error-codes");
 /**
@@ -140,32 +140,34 @@ exports.AdcpError = AdcpError;
  */
 const TASK_HANDOFF_BRAND = Symbol.for('@adcp/decisioning/task-handoff');
 /**
- * The handoff function lives in a WeakMap keyed by the `TaskHandoff`
- * marker object — NOT on the marker itself. This means the framework
- * can extract the function (it has the WeakMap reference) but adopters
- * holding only a `TaskHandoff<T>` value cannot invoke or inspect it.
- * Closes round-6 CR-3 / Protocol-L2: `_taskFn` was previously a
- * type-visible field that adopters could forge with their own
+ * The handoff fn and options live in a WeakMap keyed by the `TaskHandoff`
+ * marker object — NOT on the marker itself. Both are stored atomically in a
+ * single entry so `isTaskHandoff` and `_extractHandoffEntry` always see a
+ * consistent pair. Closes round-6 CR-3 / Protocol-L2: `_taskFn` was
+ * previously a type-visible field that adopters could forge with their own
  * `Symbol.for(...)` call.
  */
-const taskHandoffFns = new WeakMap();
+const taskHandoffEntries = new WeakMap();
 /**
  * Construct a `TaskHandoff<T>` marker. The framework's `ctx.handoffToTask`
  * helper invokes this; adopters don't call it directly.
  *
- * The `fn` is stashed in a module-private WeakMap keyed by the marker
- * object. Adopters can hold the marker and pass it through return
- * values, but cannot extract or invoke `fn` themselves — only the
- * framework's `_extractTaskFn` can.
+ * The `fn` and `options` are stashed atomically in a module-private WeakMap
+ * keyed by the marker object. Adopters can hold the marker and pass it through
+ * return values, but cannot extract or invoke `fn` themselves — only the
+ * framework's `_extractHandoffEntry` can.
  *
  * @internal
  */
-function _createTaskHandoff(fn) {
+function _createTaskHandoff(fn, options) {
     // Frozen object so adopters can't mutate the brand field. Even if
     // they did, the dispatch seam keys on identity (WeakMap), not on
     // mutable structure.
     const marker = Object.freeze({ [TASK_HANDOFF_BRAND]: true });
-    taskHandoffFns.set(marker, fn);
+    taskHandoffEntries.set(marker, {
+        fn: fn,
+        options,
+    });
     return marker;
 }
 /**
@@ -182,17 +184,20 @@ function isTaskHandoff(value) {
     return (typeof value === 'object' &&
         value !== null &&
         value[TASK_HANDOFF_BRAND] === true &&
-        taskHandoffFns.has(value));
+        taskHandoffEntries.has(value));
 }
 /**
- * Extract the handoff function from a marker. Framework-only — the
+ * Extract the handoff fn and options from a marker. Framework-only — the
  * dispatch seam in `from-platform.ts` calls this after `isTaskHandoff`.
  * Returns `undefined` if the marker wasn't created by `_createTaskHandoff`
  * (forgery).
  *
  * @internal
  */
-function _extractTaskFn(handoff) {
-    return taskHandoffFns.get(handoff);
+function _extractHandoffEntry(handoff) {
+    const entry = taskHandoffEntries.get(handoff);
+    if (!entry)
+        return undefined;
+    return entry;
 }
 //# sourceMappingURL=async-outcome.js.map

package/dist/lib/server/decisioning/async-outcome.js.map

@@ -1 +1 @@
-{"version":3,"file":"async-outcome.js","sourceRoot":"","sources":["../../../../src/lib/server/decisioning/async-outcome.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"async-outcome.js","sourceRoot":"","sources":["../../../../src/lib/server/decisioning/async-outcome.ts"],"names":[],"mappings":"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"}

package/dist/lib/server/decisioning/context.d.ts

@@ -23,7 +23,7 @@
  */
 import type { Account } from './account';
 import type { Format, FormatReferenceStructuredObject, PropertyList, CollectionList } from '../../types/tools.generated';
-import type { TaskHandoff, TaskHandoffContext } from './async-outcome';
+import type { TaskHandoff, TaskHandoffContext, TaskHandoffOptions } from './async-outcome';
 import type { CtxMetadataRef, ResourceKind } from '../ctx-metadata';
 import type { BuyerAgent } from './buyer-agent';
 export interface RequestContext<TAccount = Account> {
@@ -111,8 +111,14 @@ export interface RequestContext<TAccount = Account> {
      *   return await this.commitSync(req);
      * }
      * ```
+     *
+     * Pass `options.task_id` when an upstream system or test-controller directive
+     * has already issued the task id and the spec contract requires the response
+     * to echo it verbatim (e.g. `force_create_media_buy_arm`). The framework uses
+     * the supplied id instead of minting a fresh one; `taskCtx.id` reflects it.
+     * Constraints: non-empty, ≤ 128 characters. Throws if violated.
      */
-    handoffToTask<TResult>(fn: (taskCtx: TaskHandoffContext) => Promise<TResult>): TaskHandoff<TResult>;
+    handoffToTask<TResult>(fn: (taskCtx: TaskHandoffContext) => Promise<TResult>, options?: TaskHandoffOptions): TaskHandoff<TResult>;
 }
 export interface WorkflowStateReader {
     /**