@adcp/sdk 15.9.0 → 16.0.0-beta.1

package/dist/lib/signing/web-bot-auth.d.mts

@@ -0,0 +1,117 @@
+import { type SsrfFetchOptions } from '../net/index.mjs';
+import { type RequestLike, type ResponseLike } from './canonicalize.mjs';
+import { type ParsedSignatureInput } from './parser.mjs';
+import type { JwksResolver } from './jwks.mjs';
+import type { ReplayStore } from './replay.mjs';
+import type { AdcpJsonWebKey } from './types.mjs';
+import type { SigningProvider } from './provider.mjs';
+export declare const WEB_BOT_AUTH_PROFILE: "web-bot-auth";
+export declare const WEB_BOT_AUTH_DRAFT_REVISION: "draft-ietf-webbotauth-httpsig-protocol-00";
+export declare const SIGNATURE_DIRECTORY_PATH = "/.well-known/http-message-signatures-directory";
+export declare const SIGNATURE_DIRECTORY_MEDIA_TYPE = "application/http-message-signatures-directory+json";
+/** HTTP outcome, deliberately separate from the legacy request_signature_* taxonomy. */
+export declare class WebBotAuthError extends Error {
+    readonly status: 400 | 403 | 429;
+    readonly reason: string;
+    readonly headers: Record<string, string>;
+    get body(): Record<string, unknown>;
+    constructor(status: 400 | 403 | 429, reason: string);
+}
+export declare function selectSignatureProfile(request: Pick<RequestLike, 'headers'>): 'web-bot-auth' | 'rfc9421';
+export declare function jwkThumbprint(jwk: Partial<Pick<AdcpJsonWebKey, 'kty' | 'crv' | 'x' | 'y'>>): string;
+/** Reject authority normalization differentials on received identifiers. */
+export declare function receivedAgentOrigin(value: string): string;
+/** RFC 9421 dictionary-member extraction, including relay member coverage. */
+export declare function buildWebBotAuthSignatureBase(input: ParsedSignatureInput, request: RequestLike, response?: ResponseLike): string;
+export declare function getWebBotAuthLegacyOriginGate(resolver: Function | undefined): ((origin: string) => Promise<void>) | undefined;
+export interface WebBotAuthAuthorizationFailure {
+    code: 'PERMISSION_DENIED' | 'SERVICE_UNAVAILABLE';
+    message: string;
+    recovery: 'correctable' | 'transient';
+}
+export declare function createWebBotAuthAuthorizationFailure(reason: 'key_revoked' | 'identity_not_bound' | 'revocation_unavailable'): WebBotAuthAuthorizationFailure;
+export declare function getWebBotAuthAuthorizationFailure(extra: Record<string, unknown> | undefined): WebBotAuthAuthorizationFailure | undefined;
+export declare function webBotAuthToolFailure(failure: WebBotAuthAuthorizationFailure, version?: string): {
+    isError: true;
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+};
+export declare function isVerifiedWebBotSigner(value: unknown): value is VerifiedWebBotSigner;
+export interface VerifiedWebBotSigner {
+    profile: 'web-bot-auth';
+    origin: string;
+    keyid: string;
+    label: string;
+    verified_at: number;
+    authorizationFailure?: WebBotAuthAuthorizationFailure;
+}
+export interface VerifyWebBotAuthOptions {
+    directory: SignatureDirectoryResolver;
+    /** Published fixture keys are allowed only outside production. */
+    allowTestKeys?: boolean;
+    /** Unknown revocation state is acceptable only for trusted read operations. */
+    requireFreshRevocation?: boolean;
+    /** SDK server adapters carry verified authorization denials into normal tool errors. */
+    deferAuthorizationErrors?: boolean;
+    /** Atomic, shared across endpoints and replicas. Nonce scope is the identity origin, not the rotating kid. */
+    replayStore: ReplayStore;
+    now?: () => number;
+    isRevoked: (origin: string, keyid: string) => Promise<boolean>;
+    /** Older #7894 vector draft expects 403; ratified R2 defaults to 429. */
+    replayStatus?: 403 | 429;
+}
+export declare function verifyWebBotAuth(request: RequestLike, options: VerifyWebBotAuthOptions): Promise<VerifiedWebBotSigner[]>;
+export interface VerifiedSignatureDirectory {
+    keys: AdcpJsonWebKey[];
+    expires: number;
+    /** Preserve exact signed bytes and response headers for auditing. */
+    proof: ResponseLike;
+}
+export declare function verifySignatureDirectory(response: ResponseLike, now?: number, allowTestKeys?: boolean): VerifiedSignatureDirectory;
+export interface SignatureDirectoryResolverOptions {
+    now?: () => number;
+    fetchOptions?: Pick<SsrfFetchOptions, 'lookup' | 'trustedFetchFn'>;
+    allowTestKeys?: boolean;
+    maxOrigins?: number;
+    /** Globally bound concurrency across attacker-selected origins. */
+    maxConcurrentFetches?: number;
+}
+/** Multi-origin discovery. Cache keys never collapse origins sharing a kid. */
+export declare class SignatureDirectoryResolver implements JwksResolver {
+    private readonly options;
+    private readonly cache;
+    private readonly failures;
+    private readonly keyMissCooldown;
+    private readonly pending;
+    constructor(options?: SignatureDirectoryResolverOptions);
+    resolve(keyid: string, signerOrigin?: string): Promise<AdcpJsonWebKey | null>;
+    private fetch;
+    get allowsTestKeys(): boolean;
+    getAuditProof(origin: string): ResponseLike | undefined;
+}
+export interface WebBotSigningOptions {
+    origin: string;
+    label?: string;
+    now?: () => number;
+    nonce?: string;
+    windowSeconds?: number;
+    relay?: boolean;
+}
+export type WebBotSigningKey = {
+    privateKey: AdcpJsonWebKey;
+} | {
+    publicKey: AdcpJsonWebKey;
+    provider: SigningProvider;
+};
+export declare function signWebBotAuth(request: RequestLike, key: WebBotSigningKey, options: WebBotSigningOptions): Promise<Record<string, string>>;
+/** Regenerate after rotation and periodically before proofs expire. No private material is published. */
+export declare function createSignedSignatureDirectory(originUrl: string, signingKeys: WebBotSigningKey[], options?: {
+    now?: () => number;
+    lifetimeSeconds?: number;
+}): Promise<ResponseLike>;
+/** Inject into the official MCP/A2A transport; signs the final outgoing bytes. */
+export declare function createWebBotAuthFetch(upstream: typeof fetch, key: WebBotSigningKey, options: WebBotSigningOptions & {
+    shouldSign?: (url: string, init?: RequestInit) => boolean;
+}): typeof fetch;

package/dist/lib/signing/web-bot-auth.d.ts

@@ -0,0 +1,117 @@
+import { type SsrfFetchOptions } from '../net';
+import { type RequestLike, type ResponseLike } from './canonicalize';
+import { type ParsedSignatureInput } from './parser';
+import type { JwksResolver } from './jwks';
+import type { ReplayStore } from './replay';
+import type { AdcpJsonWebKey } from './types';
+import type { SigningProvider } from './provider';
+export declare const WEB_BOT_AUTH_PROFILE: "web-bot-auth";
+export declare const WEB_BOT_AUTH_DRAFT_REVISION: "draft-ietf-webbotauth-httpsig-protocol-00";
+export declare const SIGNATURE_DIRECTORY_PATH = "/.well-known/http-message-signatures-directory";
+export declare const SIGNATURE_DIRECTORY_MEDIA_TYPE = "application/http-message-signatures-directory+json";
+/** HTTP outcome, deliberately separate from the legacy request_signature_* taxonomy. */
+export declare class WebBotAuthError extends Error {
+    readonly status: 400 | 403 | 429;
+    readonly reason: string;
+    readonly headers: Record<string, string>;
+    get body(): Record<string, unknown>;
+    constructor(status: 400 | 403 | 429, reason: string);
+}
+export declare function selectSignatureProfile(request: Pick<RequestLike, 'headers'>): 'web-bot-auth' | 'rfc9421';
+export declare function jwkThumbprint(jwk: Partial<Pick<AdcpJsonWebKey, 'kty' | 'crv' | 'x' | 'y'>>): string;
+/** Reject authority normalization differentials on received identifiers. */
+export declare function receivedAgentOrigin(value: string): string;
+/** RFC 9421 dictionary-member extraction, including relay member coverage. */
+export declare function buildWebBotAuthSignatureBase(input: ParsedSignatureInput, request: RequestLike, response?: ResponseLike): string;
+export declare function getWebBotAuthLegacyOriginGate(resolver: Function | undefined): ((origin: string) => Promise<void>) | undefined;
+export interface WebBotAuthAuthorizationFailure {
+    code: 'PERMISSION_DENIED' | 'SERVICE_UNAVAILABLE';
+    message: string;
+    recovery: 'correctable' | 'transient';
+}
+export declare function createWebBotAuthAuthorizationFailure(reason: 'key_revoked' | 'identity_not_bound' | 'revocation_unavailable'): WebBotAuthAuthorizationFailure;
+export declare function getWebBotAuthAuthorizationFailure(extra: Record<string, unknown> | undefined): WebBotAuthAuthorizationFailure | undefined;
+export declare function webBotAuthToolFailure(failure: WebBotAuthAuthorizationFailure, version?: string): {
+    isError: true;
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+};
+export declare function isVerifiedWebBotSigner(value: unknown): value is VerifiedWebBotSigner;
+export interface VerifiedWebBotSigner {
+    profile: 'web-bot-auth';
+    origin: string;
+    keyid: string;
+    label: string;
+    verified_at: number;
+    authorizationFailure?: WebBotAuthAuthorizationFailure;
+}
+export interface VerifyWebBotAuthOptions {
+    directory: SignatureDirectoryResolver;
+    /** Published fixture keys are allowed only outside production. */
+    allowTestKeys?: boolean;
+    /** Unknown revocation state is acceptable only for trusted read operations. */
+    requireFreshRevocation?: boolean;
+    /** SDK server adapters carry verified authorization denials into normal tool errors. */
+    deferAuthorizationErrors?: boolean;
+    /** Atomic, shared across endpoints and replicas. Nonce scope is the identity origin, not the rotating kid. */
+    replayStore: ReplayStore;
+    now?: () => number;
+    isRevoked: (origin: string, keyid: string) => Promise<boolean>;
+    /** Older #7894 vector draft expects 403; ratified R2 defaults to 429. */
+    replayStatus?: 403 | 429;
+}
+export declare function verifyWebBotAuth(request: RequestLike, options: VerifyWebBotAuthOptions): Promise<VerifiedWebBotSigner[]>;
+export interface VerifiedSignatureDirectory {
+    keys: AdcpJsonWebKey[];
+    expires: number;
+    /** Preserve exact signed bytes and response headers for auditing. */
+    proof: ResponseLike;
+}
+export declare function verifySignatureDirectory(response: ResponseLike, now?: number, allowTestKeys?: boolean): VerifiedSignatureDirectory;
+export interface SignatureDirectoryResolverOptions {
+    now?: () => number;
+    fetchOptions?: Pick<SsrfFetchOptions, 'lookup' | 'trustedFetchFn'>;
+    allowTestKeys?: boolean;
+    maxOrigins?: number;
+    /** Globally bound concurrency across attacker-selected origins. */
+    maxConcurrentFetches?: number;
+}
+/** Multi-origin discovery. Cache keys never collapse origins sharing a kid. */
+export declare class SignatureDirectoryResolver implements JwksResolver {
+    private readonly options;
+    private readonly cache;
+    private readonly failures;
+    private readonly keyMissCooldown;
+    private readonly pending;
+    constructor(options?: SignatureDirectoryResolverOptions);
+    resolve(keyid: string, signerOrigin?: string): Promise<AdcpJsonWebKey | null>;
+    private fetch;
+    get allowsTestKeys(): boolean;
+    getAuditProof(origin: string): ResponseLike | undefined;
+}
+export interface WebBotSigningOptions {
+    origin: string;
+    label?: string;
+    now?: () => number;
+    nonce?: string;
+    windowSeconds?: number;
+    relay?: boolean;
+}
+export type WebBotSigningKey = {
+    privateKey: AdcpJsonWebKey;
+} | {
+    publicKey: AdcpJsonWebKey;
+    provider: SigningProvider;
+};
+export declare function signWebBotAuth(request: RequestLike, key: WebBotSigningKey, options: WebBotSigningOptions): Promise<Record<string, string>>;
+/** Regenerate after rotation and periodically before proofs expire. No private material is published. */
+export declare function createSignedSignatureDirectory(originUrl: string, signingKeys: WebBotSigningKey[], options?: {
+    now?: () => number;
+    lifetimeSeconds?: number;
+}): Promise<ResponseLike>;
+/** Inject into the official MCP/A2A transport; signs the final outgoing bytes. */
+export declare function createWebBotAuthFetch(upstream: typeof fetch, key: WebBotSigningKey, options: WebBotSigningOptions & {
+    shouldSign?: (url: string, init?: RequestInit) => boolean;
+}): typeof fetch;