/**
 * HTTP Signature Verification (Web Bot Auth)
 *
 * Implements RFC 9421 HTTP Message Signature verification for incoming requests.
 * This module provides functions to verify that HTTP requests were signed by
 * the claimed agent.
 *
 * @see https://www.rfc-editor.org/rfc/rfc9421
 * @see https://developers.cloudflare.com/bots/reference/bot-verification/web-bot-auth/
 */
import * as jose from 'jose';
/**
 * Key directory (JWKS) format.
 */
export interface KeyDirectory {
    keys: jose.JWK[];
    /** Optional URL to the agent's credential JWT */
    agentCredentialUrl?: string;
}
/**
 * Parsed signature input parameters.
 */
export interface SignatureInputParams {
    label: string;
    components: string[];
    alg: string;
    keyid: string;
    created: number;
    expires: number;
    nonce?: string;
    tag: string;
}
/**
 * Result of HTTP signature verification.
 */
export interface HttpVerificationResult {
    /** Whether the signature is valid */
    valid: boolean;
    /** The key ID (JWK thumbprint) that signed the request */
    keyId?: string;
    /** The Signature-Agent URL */
    signatureAgent?: string;
    /** Components that were signed */
    components?: string[];
    /** When the signature was created */
    created?: Date;
    /** When the signature expires */
    expires?: Date;
    /** The nonce if present */
    nonce?: string;
    /** Verification errors */
    errors: VerificationError[];
}
/**
 * Verification error.
 */
export interface VerificationError {
    code: string;
    message: string;
}
/**
 * Options for verifying HTTP signatures.
 */
export interface HttpVerifyOptions {
    /** Function to fetch public key by keyid */
    keyResolver: (keyId: string, signatureAgent: string) => Promise<jose.JWK | null>;
    /** Clock skew tolerance in seconds (default: 300 = 5 minutes) */
    clockSkew?: number;
    /** Whether to require specific components */
    requiredComponents?: string[];
    /** Current timestamp override for testing */
    now?: number;
}
/**
 * Incoming HTTP request to verify.
 */
export interface IncomingHttpRequest {
    /** HTTP method */
    method: string;
    /** Full URL */
    url: string;
    /** Request headers (case-insensitive lookup) */
    headers: Record<string, string>;
    /** Request body (for Content-Digest verification) */
    body?: string | Uint8Array;
}
/**
 * Fetch a key directory from the Signature-Agent URL.
 *
 * @param url - The key directory URL
 * @param maxAge - Maximum cache age in seconds (default: 3600)
 * @returns The key directory or null if fetch failed
 */
export declare function fetchKeyDirectory(url: string, maxAge?: number): Promise<KeyDirectory | null>;
/**
 * Find a key in a directory by its thumbprint (keyid).
 */
export declare function findKeyByThumbprint(directory: KeyDirectory, keyId: string): Promise<jose.JWK | null>;
/**
 * Create a default key resolver that fetches from the Signature-Agent URL.
 */
export declare function createDefaultKeyResolver(): (keyId: string, signatureAgent: string) => Promise<jose.JWK | null>;
/**
 * Verify an HTTP request signature.
 *
 * @param request - The incoming HTTP request
 * @param options - Verification options
 * @returns Verification result
 *
 * @example
 * ```typescript
 * const result = await verifyHttpSignature(
 *   {
 *     method: 'POST',
 *     url: 'https://api.example.com/action',
 *     headers: {
 *       'Signature-Agent': '"https://agent.example.com/.well-known/http-message-signatures-directory"',
 *       'Signature-Input': 'sig1=("@authority" "signature-agent");alg="ed25519";keyid="abc123";created=1700000000;expires=1700000060;tag="web-bot-auth"',
 *       'Signature': 'sig1=:base64signature:',
 *     }
 *   },
 *   {
 *     keyResolver: createDefaultKeyResolver()
 *   }
 * );
 *
 * if (result.valid) {
 *   console.log('Request verified from:', result.keyId);
 * }
 * ```
 */
export declare function verifyHttpSignature(request: IncomingHttpRequest, options: HttpVerifyOptions): Promise<HttpVerificationResult>;
/**
 * Verify Content-Digest header against request body.
 *
 * @param body - The request body
 * @param contentDigest - The Content-Digest header value
 * @returns Whether the digest matches
 */
export declare function verifyContentDigest(body: string | Uint8Array, contentDigest: string): Promise<boolean>;
/**
 * Clear the key directory cache.
 */
export declare function clearKeyDirectoryCache(): void;
/**
 * Result of fetching an agent credential from a key directory.
 */
export interface FetchAgentCredentialResult {
    /** The agent credential JWT, if found */
    credential: string | null;
    /** The key directory, if fetched successfully */
    directory: KeyDirectory | null;
    /** Error message if fetch failed */
    error?: string;
}
/**
 * Fetch an agent's credential from their key directory.
 *
 * This function fetches the key directory from the Signature-Agent URL,
 * then if an agentCredentialUrl is present, fetches the credential JWT.
 *
 * @param signatureAgentUrl - The Signature-Agent URL (key directory URL)
 * @returns The credential and directory, or null values if not found
 *
 * @example
 * ```typescript
 * const result = await fetchAgentCredential(
 *   'https://agent.example.com/.well-known/http-message-signatures-directory'
 * );
 *
 * if (result.credential) {
 *   const verified = await verifyCredential(result.credential, { keyResolver });
 *   console.log('Agent:', verified.credential.agentName);
 * }
 * ```
 */
export declare function fetchAgentCredential(signatureAgentUrl: string): Promise<FetchAgentCredentialResult>;
//# sourceMappingURL=http-verify.d.ts.map