@adcp/sdk 15.9.1 → 16.0.0-beta.2

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

@@ -0,0 +1,191 @@
+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";
+/**
+ * Signature-path outcome (WBA §4, DR-0023): 400 for a field that does not
+ * parse, 403 for a signature that does not verify (with `Accept-Signature`
+ * unless the key is revoked), 429 for a replay. Any AdCP body is the generic
+ * authentication error; signature-specific detail stays in `reason` (logs).
+ * Infrastructure the verifier depends on is reported separately by
+ * {@link WebBotAuthUnavailableError}.
+ */
+export declare class WebBotAuthError extends Error {
+    readonly status: 400 | 403 | 429;
+    readonly reason: string;
+    readonly headers: Record<string, string>;
+    get body(): Record<string, unknown>;
+    /**
+     * The signer's identity could not be established because key discovery
+     * failed (WBA §6.10) or its revocation status is unknown. The request is
+     * unverified; servers apply their unverified-request policy.
+     */
+    get unverified(): boolean;
+    constructor(status: 400 | 403 | 429, reason: string);
+}
+/**
+ * Infrastructure the verifier depends on failed (replay store, revocation
+ * history store). Not a signature outcome and never answered as one: the
+ * application layer decides how to report the outage (the SDK's server
+ * integrations answer 503 SERVICE_UNAVAILABLE).
+ */
+export declare class WebBotAuthUnavailableError extends Error {
+    readonly reason: string;
+    constructor(reason: string, cause?: unknown);
+}
+export declare function selectSignatureProfile(request: Pick<RequestLike, 'headers'>): 'web-bot-auth' | 'rfc9421';
+/**
+ * RFC 7638 JWK SHA-256 thumbprint, synchronous. Byte-identical to jose's
+ * `calculateJwkThumbprint` for OKP, EC and RSA keys (tested).
+ */
+export declare function jwkThumbprint(jwk: Partial<Pick<AdcpJsonWebKey, 'kty' | 'crv' | 'x' | 'y'>> & {
+    n?: unknown;
+    e?: unknown;
+}): 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';
+}
+declare const AUTHORIZATION_FAILURE_MESSAGES: {
+    readonly key_revoked: "Agent identity key is revoked";
+    readonly identity_not_bound: "Agent identity is not onboarded for this operation";
+    readonly revocation_unavailable: "Identity revocation information is unavailable";
+    readonly authorization_failed: "Agent authorization failed";
+    readonly authorization_unavailable: "Agent authorization is temporarily unavailable";
+};
+export declare function createWebBotAuthAuthorizationFailure(reason: keyof typeof AUTHORIZATION_FAILURE_MESSAGES): 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 {
+    /** Key discovery (WBA §5.5). The only network dependency of verification. */
+    directory: SignatureDirectoryResolver;
+    /** Published fixture keys are allowed only outside production. */
+    allowTestKeys?: boolean;
+    /** Atomic, shared across endpoints and replicas. Nonce scope is the identity origin, not the rotating kid. */
+    replayStore: ReplayStore;
+    now?: () => number;
+    /** Older #7894 vector draft expects 403; ratified R2 defaults to 429. */
+    replayStatus?: 403 | 429;
+    /**
+     * @deprecated Revocation is an identity and authorization check, not part of
+     * signature verification: call `OriginRevocationResolver.status()` after
+     * verification (`createIdentity33PrincipalResolver({ revocation })` does).
+     * When supplied it is still consulted: a revoked key is a 403 without
+     * `Accept-Signature`, unknown status leaves the identity unverified, and a
+     * history-store failure is a {@link WebBotAuthUnavailableError}.
+     */
+    isRevoked?: (origin: string, keyid: string) => Promise<boolean>;
+    /** @deprecated Only affects the deprecated `isRevoked` path: `false` tolerates unknown status. */
+    requireFreshRevocation?: boolean;
+    /** @deprecated No effect; revocation outcomes are no longer deferred into tool errors. */
+    deferAuthorizationErrors?: boolean;
+}
+export declare function verifyWebBotAuth(request: RequestLike, options: VerifyWebBotAuthOptions): Promise<VerifiedWebBotSigner[]>;
+export interface VerifiedSignatureDirectory {
+    keys: AdcpJsonWebKey[];
+    /** Signed: the earliest proof expiry. Unsigned: verification time plus the unsigned-age bound. */
+    expires: number;
+    /** Whether every key carried an Appendix B signature. */
+    signed: boolean;
+    /** Preserve exact bytes and response headers for auditing. */
+    proof: ResponseLike;
+}
+/**
+ * Verify a key directory response (draft-meunier-http-message-signatures-directory).
+ * Appendix B signatures are a SHOULD there: a directory without
+ * `Signature-Input` is accepted as a plain JWKS unless `requireSigned`, with
+ * every key checked against its RFC 7638 thumbprint. When signatures are
+ * present, every key must carry a valid one.
+ */
+export declare function verifyKeyDirectory(response: ResponseLike, now?: number, options?: {
+    allowTestKeys?: boolean;
+    requireSigned?: boolean;
+    maxUnsignedAgeSeconds?: number;
+}): VerifiedSignatureDirectory;
+/** Signed directories only (Appendix B). Prefer {@link verifyKeyDirectory}. */
+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;
+    /** Refuse plain JWKS directories without Appendix B signatures. Default false. */
+    requireSignedDirectories?: boolean;
+    /** How long an unsigned directory may keep verifying after a failed refresh (seconds). Default 86400. */
+    maxUnsignedDirectoryAgeSeconds?: number;
+}
+/**
+ * Multi-origin key discovery. Cache keys never collapse origins sharing a
+ * kid. A failed refresh (any transport error or non-200, 404/410 included) is
+ * a discovery failure: it never evicts a cached, unexpired directory, which
+ * keeps verifying (WBA §6.10). Without one, the request is unverified.
+ */
+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;
+    /** The directory currently used to verify `origin`, including one kept through a failed refresh. */
+    getVerifiedDirectory(origin: string): VerifiedSignatureDirectory | undefined;
+    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;
+export {};