@adcp/sdk 6.5.0 → 6.7.0

package/dist/lib/server/upstream-helpers.d.ts

@@ -0,0 +1,182 @@
+/**
+ * Adapter translation helpers for AdCP seller agents.
+ *
+ * Every AdCP adapter needs the same two things:
+ *
+ * 1. Bidirectional key translation (AdCP wire values ↔ upstream platform values).
+ * 2. A thin typed HTTP client for upstream platform APIs.
+ *
+ * These helpers replace the per-adapter boilerplate that appears in every
+ * reference adapter (sales-social, signal-marketplace, creative-template,
+ * sales-guaranteed) without encoding any domain-specific logic.
+ */
+/**
+ * A reversible bidirectional mapping between two sets of string keys.
+ *
+ * @example
+ * ```ts
+ * const channelMap = createTranslationMap({
+ *   olv: 'video',
+ *   ctv: 'ctv',
+ *   display: 'display',
+ *   streaming_audio: 'audio',
+ * });
+ *
+ * channelMap.toUpstream('olv');     // 'video'
+ * channelMap.toAdcp('video');       // 'olv'
+ * channelMap.hasAdcp('olv');        // true
+ * channelMap.hasUpstream('audio');  // true
+ * ```
+ *
+ * Keys on the left side of the map argument are the AdCP wire values;
+ * keys on the right are the upstream platform values.
+ *
+ * Both lookup methods return `undefined` for unknown keys — callers
+ * should either guard with `has*()` or handle `undefined` explicitly.
+ */
+export interface TranslationMap<A extends string, B extends string> {
+    /** Translate an AdCP wire value to the upstream platform value. */
+    toUpstream(adcpKey: A): B | undefined;
+    /** Translate an upstream platform value back to the AdCP wire value. */
+    toAdcp(upstreamKey: B): A | undefined;
+    /** True when `adcpKey` is a known AdCP-side key. */
+    hasAdcp(adcpKey: string): adcpKey is A;
+    /** True when `upstreamKey` is a known upstream-side key. */
+    hasUpstream(upstreamKey: string): upstreamKey is B;
+}
+/**
+ * Build a bidirectional translation map from a `{ adcpKey: upstreamKey }`
+ * record. Keys on the left are AdCP wire values; values on the right are
+ * upstream platform values.
+ *
+ * TypeScript infers literal types from the object literal, so `toUpstream`
+ * and `toAdcp` return the precise union of known values rather than `string`.
+ *
+ * @example
+ * ```ts
+ * const channelMap = createTranslationMap({
+ *   olv: 'video',
+ *   ctv: 'ctv',
+ * });
+ * channelMap.toUpstream('olv'); // 'video' | undefined
+ * channelMap.toAdcp('video');   // 'olv' | undefined
+ * ```
+ */
+export declare function createTranslationMap<const M extends Record<string, string>>(adcpToUpstream: M): TranslationMap<keyof M & string, M[keyof M & string]>;
+/**
+ * Per-request context passed from the handler to the auth resolver.
+ *
+ * Adopters define their own shape — common fields include the AdCP
+ * principal (`principal`), resolved tenant id (`operatorId`), or any
+ * adapter-specific routing key. The SDK does not interpret this; it
+ * simply forwards it to `dynamic_bearer.getToken` so the resolver can
+ * pick the right credential per call.
+ *
+ * @example multi-tenant credential lookup
+ * ```ts
+ * upstream.get('/items', undefined, undefined, {
+ *   authContext: { operatorId: ctx.account.id }
+ * });
+ * ```
+ *
+ * @example pass-through of caller-presented credential
+ * ```ts
+ * upstream.get('/items', undefined, undefined, {
+ *   authContext: { principal: ctx.auth.principal }
+ * });
+ * ```
+ */
+export type AuthContext = Record<string, unknown>;
+/**
+ * Authentication configuration for the upstream HTTP client.
+ *
+ * - `static_bearer` — fixed Bearer token injected into every request.
+ * - `dynamic_bearer` — async token factory; called per-request. Receives
+ *   the optional `authContext` passed to the method call, so the same
+ *   resolver can return a master key for tenant-fan-out, a
+ *   per-operator key, or pass-through of the caller's principal.
+ *   OAuth client-credentials refresh is handled transparently.
+ * - `api_key` — fixed key injected into a named header.
+ * - `none` — no authentication header injected.
+ */
+export type UpstreamAuth = {
+    kind: 'static_bearer';
+    token: string;
+} | {
+    kind: 'dynamic_bearer';
+    getToken: (ctx?: AuthContext) => Promise<string>;
+} | {
+    kind: 'api_key';
+    header: string;
+    key: string;
+} | {
+    kind: 'none';
+};
+export interface UpstreamHttpClientOptions {
+    /** Base URL of the upstream API (no trailing slash). */
+    baseUrl: string;
+    /**
+     * Authentication strategy for outgoing requests.
+     * Pass `{ kind: 'none' }` for unauthenticated internal services.
+     */
+    auth: UpstreamAuth;
+    /**
+     * Additional headers to include on every request (e.g. tenant ID,
+     * API version, content-type overrides). Per-request headers passed
+     * to individual method calls are merged on top and take precedence.
+     */
+    defaultHeaders?: Record<string, string>;
+    /**
+     * Override the underlying fetch implementation. Defaults to
+     * `globalThis.fetch`. Adopters wiring `@adcp/sdk/upstream-recorder` pass
+     * `recorder.wrapFetch(globalThis.fetch)` so outbound calls flow through
+     * the recorder's per-principal scoping; production builds with the
+     * recorder disabled fall back to the same global with zero overhead.
+     */
+    fetch?: typeof globalThis.fetch;
+}
+/** Result shape returned by every method on the upstream HTTP client. */
+export interface UpstreamHttpResult<T> {
+    /** HTTP status code returned by the upstream. */
+    status: number;
+    /**
+     * Parsed response body, or `null` when the upstream returned a 404
+     * or an empty body. Non-2xx responses throw — use the `status` field
+     * only for within-2xx distinction (e.g. 201 Created vs 200 OK).
+     */
+    body: T | null;
+}
+/** Per-call options that don't fit naturally into positional method args. */
+export interface UpstreamCallOptions {
+    /**
+     * Forwarded to `dynamic_bearer.getToken(ctx)` so handlers can pick
+     * the right credential per call. Ignored by other auth kinds.
+     */
+    authContext?: AuthContext;
+}
+export interface UpstreamHttpClient {
+    get<T>(path: string, params?: Record<string, string | number | boolean | undefined>, headers?: Record<string, string>, options?: UpstreamCallOptions): Promise<UpstreamHttpResult<T>>;
+    post<T>(path: string, body: unknown, headers?: Record<string, string>, options?: UpstreamCallOptions): Promise<UpstreamHttpResult<T>>;
+    put<T>(path: string, body: unknown, headers?: Record<string, string>, options?: UpstreamCallOptions): Promise<UpstreamHttpResult<T>>;
+    delete<T>(path: string, headers?: Record<string, string>, options?: UpstreamCallOptions): Promise<UpstreamHttpResult<T>>;
+}
+/**
+ * Create a thin typed HTTP client for upstream platform APIs.
+ *
+ * Handles auth injection, query-string serialization, and 404→null
+ * translation so adapters can focus on domain logic.
+ *
+ * @example
+ * ```ts
+ * const upstream = createUpstreamHttpClient({
+ *   baseUrl: process.env.UPSTREAM_URL!,
+ *   auth: { kind: 'static_bearer', token: process.env.UPSTREAM_TOKEN! },
+ *   defaultHeaders: { 'X-Tenant-Id': tenantId },
+ * });
+ *
+ * const { body } = await upstream.get<Cohort[]>('/v2/cohorts');
+ * const cohorts = body ?? [];
+ * ```
+ */
+export declare function createUpstreamHttpClient(options: UpstreamHttpClientOptions): UpstreamHttpClient;
+//# sourceMappingURL=upstream-helpers.d.ts.map

package/dist/lib/server/upstream-helpers.d.ts.map

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

package/dist/lib/server/upstream-helpers.js

@@ -0,0 +1,140 @@
+"use strict";
+/**
+ * Adapter translation helpers for AdCP seller agents.
+ *
+ * Every AdCP adapter needs the same two things:
+ *
+ * 1. Bidirectional key translation (AdCP wire values ↔ upstream platform values).
+ * 2. A thin typed HTTP client for upstream platform APIs.
+ *
+ * These helpers replace the per-adapter boilerplate that appears in every
+ * reference adapter (sales-social, signal-marketplace, creative-template,
+ * sales-guaranteed) without encoding any domain-specific logic.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createTranslationMap = createTranslationMap;
+exports.createUpstreamHttpClient = createUpstreamHttpClient;
+/**
+ * Build a bidirectional translation map from a `{ adcpKey: upstreamKey }`
+ * record. Keys on the left are AdCP wire values; values on the right are
+ * upstream platform values.
+ *
+ * TypeScript infers literal types from the object literal, so `toUpstream`
+ * and `toAdcp` return the precise union of known values rather than `string`.
+ *
+ * @example
+ * ```ts
+ * const channelMap = createTranslationMap({
+ *   olv: 'video',
+ *   ctv: 'ctv',
+ * });
+ * channelMap.toUpstream('olv'); // 'video' | undefined
+ * channelMap.toAdcp('video');   // 'olv' | undefined
+ * ```
+ */
+function createTranslationMap(adcpToUpstream) {
+    const forward = new Map(Object.entries(adcpToUpstream));
+    const reverse = new Map();
+    for (const [a, b] of forward) {
+        reverse.set(b, a);
+    }
+    return {
+        toUpstream: (k) => forward.get(k),
+        toAdcp: (k) => reverse.get(k),
+        hasAdcp: (k) => forward.has(k),
+        hasUpstream: (k) => reverse.has(k),
+    };
+}
+async function resolveAuthHeader(auth, ctx) {
+    switch (auth.kind) {
+        case 'static_bearer':
+            return { Authorization: `Bearer ${auth.token}` };
+        case 'dynamic_bearer': {
+            const token = await auth.getToken(ctx);
+            return { Authorization: `Bearer ${token}` };
+        }
+        case 'api_key':
+            return { [auth.header]: auth.key };
+        case 'none':
+            return {};
+    }
+}
+async function doRequest(baseUrl, auth, defaultHeaders, fetchImpl, method, path, options) {
+    const authHeader = await resolveAuthHeader(auth, options.authContext);
+    const mergedHeaders = {
+        ...defaultHeaders,
+        ...authHeader,
+        ...options.headers,
+    };
+    let url = `${baseUrl}${path}`;
+    if (options.params) {
+        const qs = Object.entries(options.params)
+            .filter(([, v]) => v !== undefined)
+            .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(String(v))}`)
+            .join('&');
+        if (qs)
+            url = `${url}?${qs}`;
+    }
+    const init = { method, headers: mergedHeaders };
+    if (options.body !== undefined) {
+        init.body = JSON.stringify(options.body);
+        mergedHeaders['Content-Type'] = 'application/json';
+    }
+    const res = await fetchImpl(url, init);
+    // 404 → null body (not an error — resource absent is a common upstream signal)
+    if (res.status === 404)
+        return { status: 404, body: null };
+    const text = await res.text();
+    // Non-2xx always throws — callers must not silently swallow errors
+    if (!res.ok) {
+        throw new Error(`Upstream ${method} ${path} failed: ${res.status} ${text.slice(0, 200)}`);
+    }
+    // Empty body (204 No Content, etc.)
+    if (!text)
+        return { status: res.status, body: null };
+    const body = JSON.parse(text);
+    return { status: res.status, body };
+}
+/**
+ * Create a thin typed HTTP client for upstream platform APIs.
+ *
+ * Handles auth injection, query-string serialization, and 404→null
+ * translation so adapters can focus on domain logic.
+ *
+ * @example
+ * ```ts
+ * const upstream = createUpstreamHttpClient({
+ *   baseUrl: process.env.UPSTREAM_URL!,
+ *   auth: { kind: 'static_bearer', token: process.env.UPSTREAM_TOKEN! },
+ *   defaultHeaders: { 'X-Tenant-Id': tenantId },
+ * });
+ *
+ * const { body } = await upstream.get<Cohort[]>('/v2/cohorts');
+ * const cohorts = body ?? [];
+ * ```
+ */
+function createUpstreamHttpClient(options) {
+    const { baseUrl, auth, defaultHeaders = {}, fetch: fetchImpl = globalThis.fetch } = options;
+    return {
+        get: (path, params, headers, opts) => doRequest(baseUrl, auth, defaultHeaders, fetchImpl, 'GET', path, {
+            params,
+            headers,
+            authContext: opts?.authContext,
+        }),
+        post: (path, body, headers, opts) => doRequest(baseUrl, auth, defaultHeaders, fetchImpl, 'POST', path, {
+            body,
+            headers,
+            authContext: opts?.authContext,
+        }),
+        put: (path, body, headers, opts) => doRequest(baseUrl, auth, defaultHeaders, fetchImpl, 'PUT', path, {
+            body,
+            headers,
+            authContext: opts?.authContext,
+        }),
+        delete: (path, headers, opts) => doRequest(baseUrl, auth, defaultHeaders, fetchImpl, 'DELETE', path, {
+            headers,
+            authContext: opts?.authContext,
+        }),
+    };
+}
+//# sourceMappingURL=upstream-helpers.js.map

package/dist/lib/server/upstream-helpers.js.map

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

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

@@ -0,0 +1,44 @@
+/**
+ * Origin canonicalization for the brand_json_url verifier algorithm.
+ * `security.mdx` §"Quickstart: implement a `brand_json_url`-based verifier"
+ * step 3 mandates: ASCII-lowercase the host, then convert to IDNA-2008
+ * A-label (Punycode) form before byte-equality. A non-canonical comparison
+ * (raw `Example.COM` vs `example.com`, or U-label vs A-label) silently
+ * rejects legitimate traffic.
+ *
+ * Node's WHATWG URL parser already performs IDNA-2008 A-label conversion
+ * and ASCII-lowercases the host on construction (`new URL('https://Bücher.example/').hostname`
+ * returns `xn--bcher-kva.example`). We delegate to it rather than vendoring
+ * an IDNA implementation — the rule is "use the platform's IDNA-2008", not
+ * "ship our own".
+ */
+export declare class CanonicalizeError extends Error {
+    readonly meta: {
+        input: string;
+    };
+    constructor(message: string, meta: {
+        input: string;
+    });
+}
+/**
+ * Canonicalize a hostname (no scheme, no port, no path). Throws on inputs
+ * that the URL parser rejects.
+ */
+export declare function canonicalizeHost(host: string): string;
+/**
+ * Canonicalize the origin component (scheme + host) of a URL or origin string.
+ * Accepts either a full URL (`https://Example.COM/path`) or a bare origin
+ * (`https://Example.COM`). Output is `https://example.com` form — scheme +
+ * canonical host, no port when default, no path/query.
+ *
+ * Used for the step-7 `identity.key_origins` consistency check: the verifier
+ * compares the canonicalized host of the resolved `jwks_uri` against the
+ * canonicalized host of the declared `key_origins.{purpose}` value.
+ */
+export declare function canonicalizeOrigin(originOrUrl: string): string;
+/**
+ * Compare two origins (scheme + host + port) for byte-equality after
+ * canonicalization. Wrong scheme, wrong port, or wrong host all return false.
+ */
+export declare function originsEqual(a: string, b: string): boolean;
+//# sourceMappingURL=canonicalize.d.ts.map

package/dist/lib/signing/agent-resolver/canonicalize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonicalize.d.ts","sourceRoot":"","sources":["../../../../src/lib/signing/agent-resolver/canonicalize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,qBAAa,iBAAkB,SAAQ,KAAK;IAGxC,QAAQ,CAAC,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE;gBADhC,OAAO,EAAE,MAAM,EACN,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE;CAKnC;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAUrD;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAe9D;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAM1D"}

package/dist/lib/signing/agent-resolver/canonicalize.js

@@ -0,0 +1,85 @@
+"use strict";
+/**
+ * Origin canonicalization for the brand_json_url verifier algorithm.
+ * `security.mdx` §"Quickstart: implement a `brand_json_url`-based verifier"
+ * step 3 mandates: ASCII-lowercase the host, then convert to IDNA-2008
+ * A-label (Punycode) form before byte-equality. A non-canonical comparison
+ * (raw `Example.COM` vs `example.com`, or U-label vs A-label) silently
+ * rejects legitimate traffic.
+ *
+ * Node's WHATWG URL parser already performs IDNA-2008 A-label conversion
+ * and ASCII-lowercases the host on construction (`new URL('https://Bücher.example/').hostname`
+ * returns `xn--bcher-kva.example`). We delegate to it rather than vendoring
+ * an IDNA implementation — the rule is "use the platform's IDNA-2008", not
+ * "ship our own".
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CanonicalizeError = void 0;
+exports.canonicalizeHost = canonicalizeHost;
+exports.canonicalizeOrigin = canonicalizeOrigin;
+exports.originsEqual = originsEqual;
+class CanonicalizeError extends Error {
+    meta;
+    constructor(message, meta) {
+        super(message);
+        this.meta = meta;
+        this.name = 'CanonicalizeError';
+    }
+}
+exports.CanonicalizeError = CanonicalizeError;
+/**
+ * Canonicalize a hostname (no scheme, no port, no path). Throws on inputs
+ * that the URL parser rejects.
+ */
+function canonicalizeHost(host) {
+    if (typeof host !== 'string' || host.length === 0) {
+        throw new CanonicalizeError('Empty host', { input: host });
+    }
+    try {
+        const u = new URL(`https://${host}/`);
+        return u.hostname;
+    }
+    catch {
+        throw new CanonicalizeError(`Invalid host: ${host}`, { input: host });
+    }
+}
+/**
+ * Canonicalize the origin component (scheme + host) of a URL or origin string.
+ * Accepts either a full URL (`https://Example.COM/path`) or a bare origin
+ * (`https://Example.COM`). Output is `https://example.com` form — scheme +
+ * canonical host, no port when default, no path/query.
+ *
+ * Used for the step-7 `identity.key_origins` consistency check: the verifier
+ * compares the canonicalized host of the resolved `jwks_uri` against the
+ * canonicalized host of the declared `key_origins.{purpose}` value.
+ */
+function canonicalizeOrigin(originOrUrl) {
+    if (typeof originOrUrl !== 'string' || originOrUrl.length === 0) {
+        throw new CanonicalizeError('Empty origin', { input: originOrUrl });
+    }
+    let parsed;
+    try {
+        parsed = new URL(originOrUrl);
+    }
+    catch {
+        throw new CanonicalizeError(`Invalid origin: ${originOrUrl}`, { input: originOrUrl });
+    }
+    if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') {
+        throw new CanonicalizeError(`Unsupported scheme: ${parsed.protocol}`, { input: originOrUrl });
+    }
+    const port = parsed.port ? `:${parsed.port}` : '';
+    return `${parsed.protocol}//${parsed.hostname}${port}`;
+}
+/**
+ * Compare two origins (scheme + host + port) for byte-equality after
+ * canonicalization. Wrong scheme, wrong port, or wrong host all return false.
+ */
+function originsEqual(a, b) {
+    try {
+        return canonicalizeOrigin(a) === canonicalizeOrigin(b);
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=canonicalize.js.map

package/dist/lib/signing/agent-resolver/canonicalize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonicalize.js","sourceRoot":"","sources":["../../../../src/lib/signing/agent-resolver/canonicalize.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;GAaG;;;AAgBH,4CAUC;AAYD,gDAeC;AAMD,oCAMC;AA/DD,MAAa,iBAAkB,SAAQ,KAAK;IAG/B;IAFX,YACE,OAAe,EACN,IAAuB;QAEhC,KAAK,CAAC,OAAO,CAAC,CAAC;QAFN,SAAI,GAAJ,IAAI,CAAmB;QAGhC,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;IAClC,CAAC;CACF;AARD,8CAQC;AAED;;;GAGG;AACH,SAAgB,gBAAgB,CAAC,IAAY;IAC3C,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAClD,MAAM,IAAI,iBAAiB,CAAC,YAAY,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IAC7D,CAAC;IACD,IAAI,CAAC;QACH,MAAM,CAAC,GAAG,IAAI,GAAG,CAAC,WAAW,IAAI,GAAG,CAAC,CAAC;QACtC,OAAO,CAAC,CAAC,QAAQ,CAAC;IACpB,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,iBAAiB,CAAC,iBAAiB,IAAI,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IACxE,CAAC;AACH,CAAC;AAED;;;;;;;;;GASG;AACH,SAAgB,kBAAkB,CAAC,WAAmB;IACpD,IAAI,OAAO,WAAW,KAAK,QAAQ,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAChE,MAAM,IAAI,iBAAiB,CAAC,cAAc,EAAE,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC,CAAC;IACtE,CAAC;IACD,IAAI,MAAW,CAAC;IAChB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,GAAG,CAAC,WAAW,CAAC,CAAC;IAChC,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,iBAAiB,CAAC,mBAAmB,WAAW,EAAE,EAAE,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC,CAAC;IACxF,CAAC;IACD,IAAI,MAAM,CAAC,QAAQ,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;QAChE,MAAM,IAAI,iBAAiB,CAAC,uBAAuB,MAAM,CAAC,QAAQ,EAAE,EAAE,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC,CAAC;IAChG,CAAC;IACD,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IAClD,OAAO,GAAG,MAAM,CAAC,QAAQ,KAAK,MAAM,CAAC,QAAQ,GAAG,IAAI,EAAE,CAAC;AACzD,CAAC;AAED;;;GAGG;AACH,SAAgB,YAAY,CAAC,CAAS,EAAE,CAAS;IAC/C,IAAI,CAAC;QACH,OAAO,kBAAkB,CAAC,CAAC,CAAC,KAAK,kBAAkB,CAAC,CAAC,CAAC,CAAC;IACzD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}

package/dist/lib/signing/agent-resolver/capabilities-types.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Forward-compat narrow access for `identity.brand_json_url` and the
+ * surrounding fields from a `get_adcp_capabilities` response. The field
+ * lands in the spec as a typed property in 3.1's additive minor (PR
+ * adcontextprotocol/adcp#3690); 3.0.5 already accepts it on the wire by
+ * relaxing `identity.additionalProperties` to `true`, but the generated
+ * TS surface won't include it until codegen runs against a release that
+ * declares it as a typed property. This file bridges the gap on both
+ * sides:
+ *
+ *   - **Verifier side**: `readBrandJsonUrl(caps)` peels the field out of
+ *     an unknown payload without forcing the caller into `as any`.
+ *   - **Publisher side**: TS sellers constructing their capabilities
+ *     response in 3.0.5+ can spread `IdentityPosture` over the generated
+ *     `identity` shape to set `brand_json_url` without losing types on
+ *     the rest of the block:
+ *
+ *       ```ts
+ *       import type { IdentityPosture } from '@adcp/sdk/signing/server';
+ *       const identity: IdentityPosture = {
+ *         per_principal_key_isolation: true,
+ *         key_origins: { request_signing: 'https://keys.example.com' },
+ *         brand_json_url: 'https://example.com/.well-known/brand.json',
+ *       };
+ *       return { adcp: {...}, identity, ... };
+ *       ```
+ *
+ * This file goes away — replaced by the generated type — when the SDK's
+ * schema pin moves to a release that includes the field as a typed
+ * property.
+ */
+import type { GetAdCPCapabilitiesResponse } from '../../types/tools.generated';
+export type IdentityKeyOriginPurpose = 'governance_signing' | 'request_signing' | 'webhook_signing' | 'tmp_signing';
+export interface IdentityKeyOrigins {
+    governance_signing?: string;
+    request_signing?: string;
+    webhook_signing?: string;
+    tmp_signing?: string;
+}
+export interface IdentityPosture {
+    per_principal_key_isolation?: boolean;
+    key_origins?: IdentityKeyOrigins;
+    compromise_notification?: {
+        emits?: boolean;
+        accepts?: boolean;
+    };
+    brand_json_url?: string;
+}
+export type CapabilitiesWithBrandJsonUrl = GetAdCPCapabilitiesResponse & {
+    identity?: IdentityPosture;
+};
+export declare function readIdentityPosture(caps: unknown): IdentityPosture | undefined;
+export declare function readBrandJsonUrl(caps: unknown): string | undefined;
+//# sourceMappingURL=capabilities-types.d.ts.map

package/dist/lib/signing/agent-resolver/capabilities-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities-types.d.ts","sourceRoot":"","sources":["../../../../src/lib/signing/agent-resolver/capabilities-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,6BAA6B,CAAC;AAE/E,MAAM,MAAM,wBAAwB,GAAG,oBAAoB,GAAG,iBAAiB,GAAG,iBAAiB,GAAG,aAAa,CAAC;AAEpH,MAAM,WAAW,kBAAkB;IACjC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,eAAe;IAC9B,2BAA2B,CAAC,EAAE,OAAO,CAAC;IACtC,WAAW,CAAC,EAAE,kBAAkB,CAAC;IACjC,uBAAuB,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IACjE,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,MAAM,4BAA4B,GAAG,2BAA2B,GAAG;IACvE,QAAQ,CAAC,EAAE,eAAe,CAAC;CAC5B,CAAC;AAEF,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,OAAO,GAAG,eAAe,GAAG,SAAS,CAK9E;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAIlE"}

package/dist/lib/signing/agent-resolver/capabilities-types.js

@@ -0,0 +1,49 @@
+"use strict";
+/**
+ * Forward-compat narrow access for `identity.brand_json_url` and the
+ * surrounding fields from a `get_adcp_capabilities` response. The field
+ * lands in the spec as a typed property in 3.1's additive minor (PR
+ * adcontextprotocol/adcp#3690); 3.0.5 already accepts it on the wire by
+ * relaxing `identity.additionalProperties` to `true`, but the generated
+ * TS surface won't include it until codegen runs against a release that
+ * declares it as a typed property. This file bridges the gap on both
+ * sides:
+ *
+ *   - **Verifier side**: `readBrandJsonUrl(caps)` peels the field out of
+ *     an unknown payload without forcing the caller into `as any`.
+ *   - **Publisher side**: TS sellers constructing their capabilities
+ *     response in 3.0.5+ can spread `IdentityPosture` over the generated
+ *     `identity` shape to set `brand_json_url` without losing types on
+ *     the rest of the block:
+ *
+ *       ```ts
+ *       import type { IdentityPosture } from '@adcp/sdk/signing/server';
+ *       const identity: IdentityPosture = {
+ *         per_principal_key_isolation: true,
+ *         key_origins: { request_signing: 'https://keys.example.com' },
+ *         brand_json_url: 'https://example.com/.well-known/brand.json',
+ *       };
+ *       return { adcp: {...}, identity, ... };
+ *       ```
+ *
+ * This file goes away — replaced by the generated type — when the SDK's
+ * schema pin moves to a release that includes the field as a typed
+ * property.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readIdentityPosture = readIdentityPosture;
+exports.readBrandJsonUrl = readBrandJsonUrl;
+function readIdentityPosture(caps) {
+    if (!caps || typeof caps !== 'object')
+        return undefined;
+    const identity = caps.identity;
+    if (!identity || typeof identity !== 'object')
+        return undefined;
+    return identity;
+}
+function readBrandJsonUrl(caps) {
+    const identity = readIdentityPosture(caps);
+    const value = identity?.brand_json_url;
+    return typeof value === 'string' ? value : undefined;
+}
+//# sourceMappingURL=capabilities-types.js.map

package/dist/lib/signing/agent-resolver/capabilities-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities-types.js","sourceRoot":"","sources":["../../../../src/lib/signing/agent-resolver/capabilities-types.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;;AAwBH,kDAKC;AAED,4CAIC;AAXD,SAAgB,mBAAmB,CAAC,IAAa;IAC/C,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IACxD,MAAM,QAAQ,GAAI,IAA+B,CAAC,QAAQ,CAAC;IAC3D,IAAI,CAAC,QAAQ,IAAI,OAAO,QAAQ,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IAChE,OAAO,QAA2B,CAAC;AACrC,CAAC;AAED,SAAgB,gBAAgB,CAAC,IAAa;IAC5C,MAAM,QAAQ,GAAG,mBAAmB,CAAC,IAAI,CAAC,CAAC;IAC3C,MAAM,KAAK,GAAG,QAAQ,EAAE,cAAc,CAAC;IACvC,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;AACvD,CAAC"}