/**
 * PKCE (Proof Key for Code Exchange) Service
 *
 * Implements OAuth 2.1 PKCE per RFC 7636 for CAR security hardening.
 * PKCE prevents authorization code interception attacks by binding
 * the authorization request to the token exchange request.
 *
 * Key features:
 * - Cryptographically secure code_verifier generation
 * - S256 code_challenge computation (SHA-256)
 * - Verification of code_verifier against stored challenge
 * - Redis/KV storage support for challenge state
 *
 * @packageDocumentation
 */
import { VorionError } from '../common/errors.js';
import { z } from 'zod';
/**
 * PKCE code_verifier minimum length per RFC 7636
 */
export declare const CODE_VERIFIER_MIN_LENGTH = 43;
/**
 * PKCE code_verifier maximum length per RFC 7636
 */
export declare const CODE_VERIFIER_MAX_LENGTH = 128;
/**
 * PKCE challenge method - only S256 is supported per OAuth 2.1
 */
export declare const PKCEChallengeMethod: {
    readonly S256: "S256";
};
export type PKCEChallengeMethod = (typeof PKCEChallengeMethod)[keyof typeof PKCEChallengeMethod];
export declare const pkceChallengeMethodSchema: z.ZodLiteral<"S256">;
/**
 * PKCE pair containing verifier and challenge
 */
export interface PKCEPair {
    /** The code_verifier - a cryptographically random string */
    codeVerifier: string;
    /** The code_challenge - BASE64URL(SHA256(code_verifier)) */
    codeChallenge: string;
    /** The challenge method - always S256 */
    codeChallengeMethod: PKCEChallengeMethod;
}
export declare const pkcePairSchema: z.ZodObject<{
    codeVerifier: z.ZodString;
    codeChallenge: z.ZodString;
    codeChallengeMethod: z.ZodLiteral<"S256">;
}, "strip", z.ZodTypeAny, {
    codeVerifier?: string;
    codeChallenge?: string;
    codeChallengeMethod?: "S256";
}, {
    codeVerifier?: string;
    codeChallenge?: string;
    codeChallengeMethod?: "S256";
}>;
/**
 * PKCE verification result
 */
export interface PKCEVerificationResult {
    /** Whether verification succeeded */
    valid: boolean;
    /** Error reason if verification failed */
    error?: string;
    /** Error code for programmatic handling */
    errorCode?: 'INVALID_VERIFIER' | 'CHALLENGE_MISMATCH' | 'CHALLENGE_EXPIRED' | 'CHALLENGE_NOT_FOUND';
    /** Verification timestamp */
    verifiedAt: string;
}
export declare const pkceVerificationResultSchema: z.ZodObject<{
    valid: z.ZodBoolean;
    error: z.ZodOptional<z.ZodString>;
    errorCode: z.ZodOptional<z.ZodEnum<["INVALID_VERIFIER", "CHALLENGE_MISMATCH", "CHALLENGE_EXPIRED", "CHALLENGE_NOT_FOUND"]>>;
    verifiedAt: z.ZodString;
}, "strip", z.ZodTypeAny, {
    error?: string;
    valid?: boolean;
    errorCode?: "INVALID_VERIFIER" | "CHALLENGE_MISMATCH" | "CHALLENGE_EXPIRED" | "CHALLENGE_NOT_FOUND";
    verifiedAt?: string;
}, {
    error?: string;
    valid?: boolean;
    errorCode?: "INVALID_VERIFIER" | "CHALLENGE_MISMATCH" | "CHALLENGE_EXPIRED" | "CHALLENGE_NOT_FOUND";
    verifiedAt?: string;
}>;
/**
 * Stored PKCE challenge state
 */
export interface PKCEChallengeState {
    /** The code_challenge from authorization request */
    codeChallenge: string;
    /** The challenge method (S256) */
    codeChallengeMethod: PKCEChallengeMethod;
    /** When the challenge was created */
    createdAt: number;
    /** When the challenge expires */
    expiresAt: number;
    /** Associated state token for CSRF protection */
    state?: string;
    /** Client ID that initiated the request */
    clientId?: string;
    /** Redirect URI for callback */
    redirectUri?: string;
}
export declare const pkceChallengeStateSchema: z.ZodObject<{
    codeChallenge: z.ZodString;
    codeChallengeMethod: z.ZodLiteral<"S256">;
    createdAt: z.ZodNumber;
    expiresAt: z.ZodNumber;
    state: z.ZodOptional<z.ZodString>;
    clientId: z.ZodOptional<z.ZodString>;
    redirectUri: z.ZodOptional<z.ZodString>;
}, "strip", z.ZodTypeAny, {
    clientId?: string;
    createdAt?: number;
    expiresAt?: number;
    state?: string;
    codeChallenge?: string;
    codeChallengeMethod?: "S256";
    redirectUri?: string;
}, {
    clientId?: string;
    createdAt?: number;
    expiresAt?: number;
    state?: string;
    codeChallenge?: string;
    codeChallengeMethod?: "S256";
    redirectUri?: string;
}>;
/**
 * PKCE configuration
 */
export interface PKCEConfig {
    /** Code verifier length (default: 64) */
    verifierLength: number;
    /** Challenge expiry in milliseconds (default: 10 minutes) */
    challengeExpiryMs: number;
    /** Require PKCE for all OAuth flows */
    required: boolean;
}
export declare const pkceConfigSchema: z.ZodObject<{
    verifierLength: z.ZodDefault<z.ZodNumber>;
    challengeExpiryMs: z.ZodDefault<z.ZodNumber>;
    required: z.ZodDefault<z.ZodBoolean>;
}, "strip", z.ZodTypeAny, {
    required?: boolean;
    verifierLength?: number;
    challengeExpiryMs?: number;
}, {
    required?: boolean;
    verifierLength?: number;
    challengeExpiryMs?: number;
}>;
/**
 * PKCE challenge store interface
 */
export interface PKCEChallengeStore {
    /** Store a challenge with its associated authorization code */
    store(authorizationCode: string, state: PKCEChallengeState): Promise<void>;
    /** Retrieve and delete a challenge (one-time use) */
    retrieve(authorizationCode: string): Promise<PKCEChallengeState | null>;
    /** Delete a challenge */
    delete(authorizationCode: string): Promise<void>;
}
/**
 * PKCE-specific error
 */
export declare class PKCEError extends VorionError {
    code: string;
    statusCode: number;
    constructor(message: string, details?: Record<string, unknown>);
}
/**
 * Generate a cryptographically secure code_verifier
 */
declare function generateCodeVerifier(length?: number): string;
/**
 * Calculate code_challenge from code_verifier using S256 method
 * code_challenge = BASE64URL(SHA256(code_verifier))
 */
declare function calculateCodeChallenge(codeVerifier: string): Promise<string>;
/**
 * Validate code_verifier format per RFC 7636
 */
declare function isValidCodeVerifier(codeVerifier: string): boolean;
/**
 * PKCE Service for generating and verifying PKCE challenges
 *
 * @example
 * ```typescript
 * const pkce = new PKCEService();
 *
 * // Generate a PKCE pair for authorization request
 * const pair = await pkce.generatePair();
 * // Send code_challenge to authorization endpoint
 * // Store code_verifier securely for token exchange
 *
 * // On callback, verify the code_verifier
 * const result = await pkce.verify(codeVerifier, storedChallenge);
 * ```
 */
export declare class PKCEService {
    private config;
    private challengeStore;
    /**
     * Create a new PKCE service
     *
     * @param config - PKCE configuration
     * @param challengeStore - Store for PKCE challenges (defaults to in-memory)
     */
    constructor(config?: Partial<PKCEConfig>, challengeStore?: PKCEChallengeStore);
    /**
     * Generate a PKCE pair (code_verifier and code_challenge)
     *
     * @returns PKCE pair with verifier, challenge, and method
     */
    generatePair(): Promise<PKCEPair>;
    /**
     * Store a PKCE challenge for later verification
     *
     * @param authorizationCode - The authorization code from OAuth callback
     * @param codeChallenge - The code_challenge from authorization request
     * @param options - Additional options (state, clientId, redirectUri)
     */
    storeChallenge(authorizationCode: string, codeChallenge: string, options?: {
        state?: string;
        clientId?: string;
        redirectUri?: string;
    }): Promise<void>;
    /**
     * Verify a code_verifier against a stored challenge
     *
     * @param authorizationCode - The authorization code
     * @param codeVerifier - The code_verifier from token exchange request
     * @returns Verification result
     */
    verifyChallenge(authorizationCode: string, codeVerifier: string): Promise<PKCEVerificationResult>;
    /**
     * Verify a code_verifier directly against a code_challenge
     * (without using the store - for stateless verification)
     *
     * @param codeVerifier - The code_verifier from token exchange
     * @param codeChallenge - The code_challenge from authorization request
     * @returns Verification result
     */
    verifyDirect(codeVerifier: string, codeChallenge: string): Promise<PKCEVerificationResult>;
    /**
     * Generate a code_challenge from a code_verifier
     *
     * @param codeVerifier - The code_verifier to hash
     * @returns The code_challenge (BASE64URL(SHA256(code_verifier)))
     */
    generateChallenge(codeVerifier: string): Promise<string>;
    /**
     * Check if PKCE is required
     */
    isRequired(): boolean;
    /**
     * Get current configuration
     */
    getConfig(): Readonly<PKCEConfig>;
}
/**
 * Create a PKCE service with default configuration for OAuth 2.1
 */
export declare function createPKCEService(config?: Partial<PKCEConfig>, challengeStore?: PKCEChallengeStore): PKCEService;
export { generateCodeVerifier, calculateCodeChallenge, isValidCodeVerifier, };
//# sourceMappingURL=pkce.d.ts.map