@sudowealth/schwab-api/dist/src/auth/oauth-state-utils.d.ts

TypeScript client for Charles Schwab API with OAuth support, market data, trading functionality, and complete type safety

import { z, type ZodSchema } from 'zod';
/**
 * Base OAuth state schema for PKCE flow
 */
export declare const BasicOAuthStateSchema: z.ZodObject<{
    pkce_code_verifier: z.ZodOptional<z.ZodString>;
    csrf_token: z.ZodOptional<z.ZodString>;
    timestamp: z.ZodOptional<z.ZodNumber>;
}, "strip", z.ZodTypeAny, {
    timestamp?: number | undefined;
    pkce_code_verifier?: string | undefined;
    csrf_token?: string | undefined;
}, {
    timestamp?: number | undefined;
    pkce_code_verifier?: string | undefined;
    csrf_token?: string | undefined;
}>;
/**
 * Extended OAuth state schema with PKCE support
 */
export declare const PKCEOAuthStateSchema: z.ZodObject<{
    csrf_token: z.ZodOptional<z.ZodString>;
    timestamp: z.ZodOptional<z.ZodNumber>;
} & {
    pkce_code_verifier: z.ZodString;
    pkce_code_challenge: z.ZodOptional<z.ZodString>;
    pkce_method: z.ZodOptional<z.ZodLiteral<"S256">>;
}, "strip", z.ZodTypeAny, {
    pkce_code_verifier: string;
    timestamp?: number | undefined;
    csrf_token?: string | undefined;
    pkce_code_challenge?: string | undefined;
    pkce_method?: "S256" | undefined;
}, {
    pkce_code_verifier: string;
    timestamp?: number | undefined;
    csrf_token?: string | undefined;
    pkce_code_challenge?: string | undefined;
    pkce_method?: "S256" | undefined;
}>;
/**
 * Generic OAuth state type
 */
export type OAuthState = z.infer<typeof BasicOAuthStateSchema> & {
    [key: string]: any;
};
/**
 * Options for OAuth state encoding/decoding
 */
export interface OAuthStateOptions {
    /**
     * Include CSRF token for additional security
     */
    includeCSRF?: boolean;
    /**
     * Include timestamp for state expiration checks
     */
    includeTimestamp?: boolean;
    /**
     * Custom data to include in state
     */
    customData?: Record<string, any>;
}
/**
 * Encode OAuth state to a base64 string
 *
 * @param state State object to encode
 * @param options Encoding options
 * @returns Base64-encoded state string
 */
export declare function encodeOAuthState<T extends Record<string, any>>(state: T, options?: OAuthStateOptions): string;
/**
 * Decode OAuth state from a base64 string
 *
 * @param encodedState Base64-encoded state string
 * @returns Decoded state object or null if decoding fails
 */
export declare function decodeOAuthState<T = OAuthState>(encodedState: string): T | null;
/**
 * Validate OAuth state against a schema
 *
 * @param state State object to validate
 * @param schema Zod schema to validate against
 * @returns True if valid, false otherwise
 */
export declare function validateOAuthState<T>(state: unknown, schema: ZodSchema<T>): state is T;
/**
 * Merge application state with PKCE parameters
 *
 * @param appState Application-specific state
 * @param pkceVerifier PKCE code verifier
 * @param pkceChallenge PKCE code challenge
 * @returns Merged state object
 */
export declare function mergeStateWithPKCE<T extends Record<string, any>>(appState: T, pkceVerifier: string, pkceChallenge?: string): T & {
    pkce_code_verifier: string;
    pkce_code_challenge?: string;
};
/**
 * Extract PKCE parameters from state
 *
 * @param state State object containing PKCE parameters
 * @returns PKCE parameters or null if not found
 */
export declare function extractPKCEFromState(state: unknown): {
    codeVerifier: string;
    codeChallenge?: string;
} | null;
/**
 * Create OAuth state with CSRF token
 *
 * @param data State data
 * @returns State with CSRF token
 */
export declare function createStateWithCSRF<T extends Record<string, any>>(data: T): T & {
    csrf_token: string;
    timestamp: number;
};
/**
 * Verify OAuth state CSRF token and timestamp
 *
 * @param state State object to verify
 * @param expectedCSRF Expected CSRF token
 * @param maxAgeMs Maximum age in milliseconds (default: 10 minutes)
 * @returns True if valid, false otherwise
 */
export declare function verifyStateWithCSRF(state: unknown, expectedCSRF?: string, maxAgeMs?: number): boolean;
/**
 * Extract client ID from various state formats
 * Supports both direct clientId and nested oauthReqInfo.clientId
 *
 * @param state State object
 * @returns Client ID or null if not found
 */
export declare function extractClientIdFromState(state: unknown): string | null;
/**
 * Advanced state verification with custom validation
 *
 * @param encodedState Encoded state string
 * @param options Verification options
 * @returns Decoded and validated state or null
 */
export declare function decodeAndVerifyState<T = OAuthState>(encodedState: string, options?: {
    schema?: ZodSchema<T>;
    expectedCSRF?: string;
    maxAgeMs?: number;
    requiredFields?: string[];
}): T | null;