@adcp/sdk 16.0.0-beta.1 → 16.0.0-beta.2

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

@@ -9,16 +9,46 @@ 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. */
+/**
+ * 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';
-export declare function jwkThumbprint(jwk: Partial<Pick<AdcpJsonWebKey, 'kty' | 'crv' | 'x' | 'y'>>): string;
+/**
+ * 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. */
@@ -29,7 +59,14 @@ export interface WebBotAuthAuthorizationFailure {
     message: string;
     recovery: 'correctable' | 'transient';
 }
-export declare function createWebBotAuthAuthorizationFailure(reason: 'key_revoked' | 'identity_not_bound' | 'revocation_unavailable'): WebBotAuthAuthorizationFailure;
+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;
@@ -48,27 +85,52 @@ export interface VerifiedWebBotSigner {
     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;
-    /** 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;
+    /**
+     * @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;
-    /** Preserve exact signed bytes and response headers for auditing. */
+    /** 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;
@@ -77,8 +139,17 @@ export interface SignatureDirectoryResolverOptions {
     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 discovery. Cache keys never collapse origins sharing a kid. */
+/**
+ * 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;
@@ -89,6 +160,8 @@ export declare class SignatureDirectoryResolver implements JwksResolver {
     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 {
@@ -115,3 +188,4 @@ export declare function createSignedSignatureDirectory(originUrl: string, signin
 export declare function createWebBotAuthFetch(upstream: typeof fetch, key: WebBotSigningKey, options: WebBotSigningOptions & {
     shouldSign?: (url: string, init?: RequestInit) => boolean;
 }): typeof fetch;
+export {};

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

@@ -9,16 +9,46 @@ 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. */
+/**
+ * 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';
-export declare function jwkThumbprint(jwk: Partial<Pick<AdcpJsonWebKey, 'kty' | 'crv' | 'x' | 'y'>>): string;
+/**
+ * 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. */
@@ -29,7 +59,14 @@ export interface WebBotAuthAuthorizationFailure {
     message: string;
     recovery: 'correctable' | 'transient';
 }
-export declare function createWebBotAuthAuthorizationFailure(reason: 'key_revoked' | 'identity_not_bound' | 'revocation_unavailable'): WebBotAuthAuthorizationFailure;
+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;
@@ -48,27 +85,52 @@ export interface VerifiedWebBotSigner {
     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;
-    /** 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;
+    /**
+     * @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;
-    /** Preserve exact signed bytes and response headers for auditing. */
+    /** 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;
@@ -77,8 +139,17 @@ export interface SignatureDirectoryResolverOptions {
     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 discovery. Cache keys never collapse origins sharing a kid. */
+/**
+ * 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;
@@ -89,6 +160,8 @@ export declare class SignatureDirectoryResolver implements JwksResolver {
     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 {
@@ -115,3 +188,4 @@ export declare function createSignedSignatureDirectory(originUrl: string, signin
 export declare function createWebBotAuthFetch(upstream: typeof fetch, key: WebBotSigningKey, options: WebBotSigningOptions & {
     shouldSign?: (url: string, init?: RequestInit) => boolean;
 }): typeof fetch;
+export {};