@adcp/sdk 16.0.0-beta.6 → 16.0.0-beta.8

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

@@ -1,6 +1,5 @@
 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';
@@ -9,11 +8,21 @@ 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";
+/** The profile's signature algorithms (wba-profile.mdx "Profile rules"). ES256 is RFC 9421 profile only. */
+export declare const WEB_BOT_AUTH_ALGORITHMS: readonly ["ed25519", "rsa-pss-sha512"];
 /**
- * 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).
+ * The profile's `Accept-Signature` member (RFC 9421 §5.1): the label, the
+ * components the profile requires, and its parameters. A replay challenge
+ * carries the fresh `nonce` the signer uses on its next attempt.
+ */
+export declare function webBotAuthAcceptSignature(label?: string, hasBody?: boolean, nonce?: string): string;
+/**
+ * Signature-path outcome (wba-profile.mdx "Error responses"): 400 when the
+ * signature fields do not parse; 403 with `Accept-Signature` when a signature
+ * fails verification or the profile rules (without it for a revoked key); 429
+ * with `Accept-Signature` carrying a fresh `nonce` for a reused signature or
+ * nonce. A 429 for local load shedding carries `Retry-After` instead. Any AdCP
+ * body is the generic authentication error; detail stays in `reason` (logs).
  * Infrastructure the verifier depends on is reported separately by
  * {@link WebBotAuthUnavailableError}.
  */
@@ -40,6 +49,16 @@ export declare class WebBotAuthUnavailableError extends Error {
     readonly reason: string;
     constructor(reason: string, cause?: unknown);
 }
+/**
+ * The answer to an unsigned request to an operation in `required_for` from a
+ * caller with no other credential the verifier accepts, when the verifier
+ * advertises only `web-bot-auth`: 403 with `Accept-Signature`. A verifier that
+ * also advertises the AdCP RFC 9421 profile answers as that profile does (401
+ * `request_signature_required`) and adds {@link webBotAuthAcceptSignature}.
+ */
+export declare function unsignedWebBotAuthError(hasBody: boolean): WebBotAuthError;
+/** Whether a `request_signing.profiles` advertisement names Web Bot Auth and not the AdCP RFC 9421 profile. */
+export declare function advertisesOnlyWebBotAuth(profiles: readonly string[] | undefined): boolean;
 export declare function selectSignatureProfile(request: Pick<RequestLike, 'headers'>): 'web-bot-auth' | 'rfc9421';
 /**
  * RFC 7638 JWK SHA-256 thumbprint, synchronous. Byte-identical to jose's
@@ -49,10 +68,13 @@ export declare function jwkThumbprint(jwk: Partial<Pick<AdcpJsonWebKey, 'kty' |
     n?: unknown;
     e?: unknown;
 }): string;
+/**
+ * Refuse a Web Bot Auth signing key the profile does not allow, at wire-up
+ * time rather than on the first request.
+ */
+export declare function assertWebBotAuthSigningKey(key: WebBotSigningKey): void;
 /** 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';
@@ -92,7 +114,10 @@ export interface VerifyWebBotAuthOptions {
     /** 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. */
+    /**
+     * @deprecated No effect. A reused signature or nonce is always 429 with
+     * `Accept-Signature` carrying a fresh nonce (adcp#7894, `negative/002`).
+     */
     replayStatus?: 403 | 429;
     /**
      * @deprecated Revocation is an identity and authorization check, not part of
@@ -108,30 +133,39 @@ export interface VerifyWebBotAuthOptions {
     /** @deprecated No effect; revocation outcomes are no longer deferred into tool errors. */
     deferAuthorizationErrors?: boolean;
 }
+/**
+ * Verify a Web Bot Auth request (wba-profile.mdx "Verification"). Resolves to
+ * exactly one verified signer: the profile takes one `web-bot-auth` signature
+ * and one `Signature-Agent` member per request. The array shape is kept for
+ * principal resolvers written against earlier drafts.
+ */
 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. */
+    /** The earliest proof expiry. */
     expires: number;
-    /** Whether every key carried an Appendix B signature. */
-    signed: boolean;
+    /** @deprecated Always `true`: the profile accepts only signed directories (WBA Appendix B.1). */
+    signed: true;
     /** 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.
+ * Verify a key directory response (wba-profile.mdx "Key directories", WBA
+ * Appendix B.1). The response must be signed once per key, each signature
+ * covering `"@authority";req` and `content-digest` with `created`, `expires`,
+ * the key's thumbprint as `keyid` and `tag="http-message-signatures-directory"`,
+ * and verifying under the key the directory itself provides. An unsigned
+ * directory is a discovery failure.
  */
 export declare function verifyKeyDirectory(response: ResponseLike, now?: number, options?: {
     allowTestKeys?: boolean;
+    /** @deprecated No effect: directories must always be signed. */
     requireSigned?: boolean;
+    /** @deprecated No effect: unsigned directories are refused. */
     maxUnsignedAgeSeconds?: number;
-}): VerifiedSignatureDirectory;
-/** Signed directories only (Appendix B). Prefer {@link verifyKeyDirectory}. */
-export declare function verifySignatureDirectory(response: ResponseLike, now?: number, allowTestKeys?: boolean): VerifiedSignatureDirectory;
+}): Promise<VerifiedSignatureDirectory>;
+/** @deprecated Same as {@link verifyKeyDirectory}: every directory must be signed. */
+export declare function verifySignatureDirectory(response: ResponseLike, now?: number, allowTestKeys?: boolean): Promise<VerifiedSignatureDirectory>;
 export interface SignatureDirectoryResolverOptions {
     now?: () => number;
     fetchOptions?: Pick<SsrfFetchOptions, 'lookup' | 'trustedFetchFn'>;
@@ -139,9 +173,9 @@ export interface SignatureDirectoryResolverOptions {
     maxOrigins?: number;
     /** Globally bound concurrency across attacker-selected origins. */
     maxConcurrentFetches?: number;
-    /** Refuse plain JWKS directories without Appendix B signatures. Default false. */
+    /** @deprecated No effect: signed directories (WBA Appendix B.1) are always required. */
     requireSignedDirectories?: boolean;
-    /** How long an unsigned directory may keep verifying after a failed refresh (seconds). Default 86400. */
+    /** @deprecated No effect: unsigned directories are refused. */
     maxUnsignedDirectoryAgeSeconds?: number;
 }
 /**
@@ -168,9 +202,9 @@ export interface WebBotSigningOptions {
     origin: string;
     label?: string;
     now?: () => number;
+    /** 64 bytes, unpadded Base64URL or canonical Base64. Defaults to 64 fresh random bytes. */
     nonce?: string;
     windowSeconds?: number;
-    relay?: boolean;
 }
 export type WebBotSigningKey = {
     privateKey: AdcpJsonWebKey;
@@ -178,6 +212,11 @@ export type WebBotSigningKey = {
     publicKey: AdcpJsonWebKey;
     provider: SigningProvider;
 };
+/**
+ * Sign a request under the profile: one `web-bot-auth` signature labelled
+ * `label`, one covered `Signature-Agent` member naming `origin`, a 64-byte
+ * nonce, and a lifetime of at most 300 seconds.
+ */
 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?: {

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

@@ -1,6 +1,5 @@
 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';
@@ -9,11 +8,21 @@ 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";
+/** The profile's signature algorithms (wba-profile.mdx "Profile rules"). ES256 is RFC 9421 profile only. */
+export declare const WEB_BOT_AUTH_ALGORITHMS: readonly ["ed25519", "rsa-pss-sha512"];
 /**
- * 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).
+ * The profile's `Accept-Signature` member (RFC 9421 §5.1): the label, the
+ * components the profile requires, and its parameters. A replay challenge
+ * carries the fresh `nonce` the signer uses on its next attempt.
+ */
+export declare function webBotAuthAcceptSignature(label?: string, hasBody?: boolean, nonce?: string): string;
+/**
+ * Signature-path outcome (wba-profile.mdx "Error responses"): 400 when the
+ * signature fields do not parse; 403 with `Accept-Signature` when a signature
+ * fails verification or the profile rules (without it for a revoked key); 429
+ * with `Accept-Signature` carrying a fresh `nonce` for a reused signature or
+ * nonce. A 429 for local load shedding carries `Retry-After` instead. Any AdCP
+ * body is the generic authentication error; detail stays in `reason` (logs).
  * Infrastructure the verifier depends on is reported separately by
  * {@link WebBotAuthUnavailableError}.
  */
@@ -40,6 +49,16 @@ export declare class WebBotAuthUnavailableError extends Error {
     readonly reason: string;
     constructor(reason: string, cause?: unknown);
 }
+/**
+ * The answer to an unsigned request to an operation in `required_for` from a
+ * caller with no other credential the verifier accepts, when the verifier
+ * advertises only `web-bot-auth`: 403 with `Accept-Signature`. A verifier that
+ * also advertises the AdCP RFC 9421 profile answers as that profile does (401
+ * `request_signature_required`) and adds {@link webBotAuthAcceptSignature}.
+ */
+export declare function unsignedWebBotAuthError(hasBody: boolean): WebBotAuthError;
+/** Whether a `request_signing.profiles` advertisement names Web Bot Auth and not the AdCP RFC 9421 profile. */
+export declare function advertisesOnlyWebBotAuth(profiles: readonly string[] | undefined): boolean;
 export declare function selectSignatureProfile(request: Pick<RequestLike, 'headers'>): 'web-bot-auth' | 'rfc9421';
 /**
  * RFC 7638 JWK SHA-256 thumbprint, synchronous. Byte-identical to jose's
@@ -49,10 +68,13 @@ export declare function jwkThumbprint(jwk: Partial<Pick<AdcpJsonWebKey, 'kty' |
     n?: unknown;
     e?: unknown;
 }): string;
+/**
+ * Refuse a Web Bot Auth signing key the profile does not allow, at wire-up
+ * time rather than on the first request.
+ */
+export declare function assertWebBotAuthSigningKey(key: WebBotSigningKey): void;
 /** 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';
@@ -92,7 +114,10 @@ export interface VerifyWebBotAuthOptions {
     /** 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. */
+    /**
+     * @deprecated No effect. A reused signature or nonce is always 429 with
+     * `Accept-Signature` carrying a fresh nonce (adcp#7894, `negative/002`).
+     */
     replayStatus?: 403 | 429;
     /**
      * @deprecated Revocation is an identity and authorization check, not part of
@@ -108,30 +133,39 @@ export interface VerifyWebBotAuthOptions {
     /** @deprecated No effect; revocation outcomes are no longer deferred into tool errors. */
     deferAuthorizationErrors?: boolean;
 }
+/**
+ * Verify a Web Bot Auth request (wba-profile.mdx "Verification"). Resolves to
+ * exactly one verified signer: the profile takes one `web-bot-auth` signature
+ * and one `Signature-Agent` member per request. The array shape is kept for
+ * principal resolvers written against earlier drafts.
+ */
 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. */
+    /** The earliest proof expiry. */
     expires: number;
-    /** Whether every key carried an Appendix B signature. */
-    signed: boolean;
+    /** @deprecated Always `true`: the profile accepts only signed directories (WBA Appendix B.1). */
+    signed: true;
     /** 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.
+ * Verify a key directory response (wba-profile.mdx "Key directories", WBA
+ * Appendix B.1). The response must be signed once per key, each signature
+ * covering `"@authority";req` and `content-digest` with `created`, `expires`,
+ * the key's thumbprint as `keyid` and `tag="http-message-signatures-directory"`,
+ * and verifying under the key the directory itself provides. An unsigned
+ * directory is a discovery failure.
  */
 export declare function verifyKeyDirectory(response: ResponseLike, now?: number, options?: {
     allowTestKeys?: boolean;
+    /** @deprecated No effect: directories must always be signed. */
     requireSigned?: boolean;
+    /** @deprecated No effect: unsigned directories are refused. */
     maxUnsignedAgeSeconds?: number;
-}): VerifiedSignatureDirectory;
-/** Signed directories only (Appendix B). Prefer {@link verifyKeyDirectory}. */
-export declare function verifySignatureDirectory(response: ResponseLike, now?: number, allowTestKeys?: boolean): VerifiedSignatureDirectory;
+}): Promise<VerifiedSignatureDirectory>;
+/** @deprecated Same as {@link verifyKeyDirectory}: every directory must be signed. */
+export declare function verifySignatureDirectory(response: ResponseLike, now?: number, allowTestKeys?: boolean): Promise<VerifiedSignatureDirectory>;
 export interface SignatureDirectoryResolverOptions {
     now?: () => number;
     fetchOptions?: Pick<SsrfFetchOptions, 'lookup' | 'trustedFetchFn'>;
@@ -139,9 +173,9 @@ export interface SignatureDirectoryResolverOptions {
     maxOrigins?: number;
     /** Globally bound concurrency across attacker-selected origins. */
     maxConcurrentFetches?: number;
-    /** Refuse plain JWKS directories without Appendix B signatures. Default false. */
+    /** @deprecated No effect: signed directories (WBA Appendix B.1) are always required. */
     requireSignedDirectories?: boolean;
-    /** How long an unsigned directory may keep verifying after a failed refresh (seconds). Default 86400. */
+    /** @deprecated No effect: unsigned directories are refused. */
     maxUnsignedDirectoryAgeSeconds?: number;
 }
 /**
@@ -168,9 +202,9 @@ export interface WebBotSigningOptions {
     origin: string;
     label?: string;
     now?: () => number;
+    /** 64 bytes, unpadded Base64URL or canonical Base64. Defaults to 64 fresh random bytes. */
     nonce?: string;
     windowSeconds?: number;
-    relay?: boolean;
 }
 export type WebBotSigningKey = {
     privateKey: AdcpJsonWebKey;
@@ -178,6 +212,11 @@ export type WebBotSigningKey = {
     publicKey: AdcpJsonWebKey;
     provider: SigningProvider;
 };
+/**
+ * Sign a request under the profile: one `web-bot-auth` signature labelled
+ * `label`, one covered `Signature-Agent` member naming `origin`, a 64-byte
+ * nonce, and a lifetime of at most 300 seconds.
+ */
 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?: {