@stackwright-pro/auth 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,1009 @@
+import { z } from 'zod';
+import { X509Certificate } from '@peculiar/x509';
+import * as React from 'react';
+import React__default, { ReactNode, ReactElement } from 'react';
+
+/**
+ * Core Type Definitions for Stackwright Auth
+ *
+ * These types define the foundational contract for authentication.
+ * All auth functionality builds on these interfaces.
+ */
+/**
+ * Authenticated user representation
+ * Normalized across PKI and OIDC providers
+ */
+interface AuthUser {
+    id: string;
+    email?: string;
+    name?: string;
+    roles: string[];
+    permissions?: string[];
+    metadata?: Record<string, any>;
+}
+/**
+ * Session representation
+ * Contains user info and expiration details
+ */
+interface AuthSession {
+    user: AuthUser;
+    expiresAt: number;
+    issuedAt: number;
+    refreshToken?: string;
+}
+/**
+ * PKI-specific configuration
+ * Supports DoD CAC, PIV cards, and custom PKI deployments
+ */
+interface PKIConfig {
+    type: 'pki';
+    profile: 'dod_cac' | 'piv' | 'custom';
+    source: 'gateway_headers' | 'direct_tls';
+    headerPrefix?: string;
+    verifiedHeader?: string;
+    requiredValue?: string;
+    caChain?: string;
+    requiredOU?: string[];
+    allowedIssuers?: string[];
+}
+/**
+ * OIDC configuration
+ * Supports major providers + custom OIDC implementations
+ */
+interface OIDCConfig {
+    type: 'oidc';
+    provider: 'cognito' | 'azure_ad' | 'authentik' | 'keycloak' | 'okta' | 'auth0' | 'custom';
+    discoveryUrl: string;
+    clientId: string;
+    clientSecret: string;
+    redirectUri?: string;
+    claimsMapping?: {
+        user_id?: string;
+        email?: string;
+        name?: string;
+        roles?: string;
+    };
+    quirks?: {
+        skipIssuerCheck?: boolean;
+        useRefreshTokenRotation?: boolean;
+    };
+}
+/**
+ * Union of all auth configurations
+ * Discriminated by 'type' field for type safety
+ */
+type AuthConfig = PKIConfig | OIDCConfig;
+/**
+ * Component-level auth configuration (from YAML)
+ * Defines access requirements for individual components
+ */
+interface ComponentAuthConfig {
+    required_roles?: string[];
+    required_permissions?: string[];
+    fallback?: 'hide' | 'placeholder' | 'message';
+    fallback_message?: string;
+}
+/**
+ * Role-based access control configuration
+ * Defines roles, permissions, and route protection
+ */
+interface RBACConfig {
+    roles: Array<{
+        name: string;
+        permissions?: string[];
+    }>;
+    protected_routes?: Array<{
+        path: string;
+        roles: string[];
+    }>;
+    public_routes?: string[];
+}
+/**
+ * Auth context passed to providers during authentication
+ */
+interface AuthContext$1 {
+    headers?: Record<string, string>;
+    query?: Record<string, string>;
+    cookies?: Record<string, string>;
+}
+/**
+ * Provider interface that both PKI and OIDC implementations must satisfy
+ * Ensures consistent behavior across auth strategies
+ */
+interface AuthProvider$1 {
+    authenticate(context: AuthContext$1): Promise<AuthUser | null>;
+    validate(session: AuthSession): Promise<boolean>;
+    refresh?(session: AuthSession): Promise<AuthSession | null>;
+}
+
+/**
+ * Zod Schemas for Runtime Validation
+ *
+ * These schemas provide runtime validation for all auth-related data structures.
+ * They mirror the TypeScript types but enforce validation at runtime.
+ */
+
+/**
+ * PKI Configuration Schema
+ * Validates PKI auth config with sensible defaults
+ */
+declare const pkiConfigSchema: z.ZodObject<{
+    type: z.ZodLiteral<"pki">;
+    profile: z.ZodEnum<{
+        dod_cac: "dod_cac";
+        piv: "piv";
+        custom: "custom";
+    }>;
+    source: z.ZodEnum<{
+        gateway_headers: "gateway_headers";
+        direct_tls: "direct_tls";
+    }>;
+    headerPrefix: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    verifiedHeader: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    requiredValue: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    caChain: z.ZodOptional<z.ZodString>;
+    requiredOU: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    allowedIssuers: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+/**
+ * OIDC Configuration Schema
+ * Validates OIDC provider config including claims mapping and quirks
+ */
+declare const oidcConfigSchema: z.ZodObject<{
+    type: z.ZodLiteral<"oidc">;
+    provider: z.ZodEnum<{
+        custom: "custom";
+        cognito: "cognito";
+        azure_ad: "azure_ad";
+        authentik: "authentik";
+        keycloak: "keycloak";
+        okta: "okta";
+        auth0: "auth0";
+    }>;
+    discoveryUrl: z.ZodString;
+    clientId: z.ZodString;
+    clientSecret: z.ZodString;
+    redirectUri: z.ZodOptional<z.ZodString>;
+    claimsMapping: z.ZodOptional<z.ZodObject<{
+        user_id: z.ZodOptional<z.ZodString>;
+        email: z.ZodOptional<z.ZodString>;
+        name: z.ZodOptional<z.ZodString>;
+        roles: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    quirks: z.ZodOptional<z.ZodObject<{
+        skipIssuerCheck: z.ZodOptional<z.ZodBoolean>;
+        useRefreshTokenRotation: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/**
+ * Discriminated Union Schema
+ * Auto-discriminates based on 'type' field for type-safe validation
+ */
+declare const authConfigSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"pki">;
+    profile: z.ZodEnum<{
+        dod_cac: "dod_cac";
+        piv: "piv";
+        custom: "custom";
+    }>;
+    source: z.ZodEnum<{
+        gateway_headers: "gateway_headers";
+        direct_tls: "direct_tls";
+    }>;
+    headerPrefix: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    verifiedHeader: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    requiredValue: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    caChain: z.ZodOptional<z.ZodString>;
+    requiredOU: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    allowedIssuers: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"oidc">;
+    provider: z.ZodEnum<{
+        custom: "custom";
+        cognito: "cognito";
+        azure_ad: "azure_ad";
+        authentik: "authentik";
+        keycloak: "keycloak";
+        okta: "okta";
+        auth0: "auth0";
+    }>;
+    discoveryUrl: z.ZodString;
+    clientId: z.ZodString;
+    clientSecret: z.ZodString;
+    redirectUri: z.ZodOptional<z.ZodString>;
+    claimsMapping: z.ZodOptional<z.ZodObject<{
+        user_id: z.ZodOptional<z.ZodString>;
+        email: z.ZodOptional<z.ZodString>;
+        name: z.ZodOptional<z.ZodString>;
+        roles: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    quirks: z.ZodOptional<z.ZodObject<{
+        skipIssuerCheck: z.ZodOptional<z.ZodBoolean>;
+        useRefreshTokenRotation: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+}, z.core.$strip>], "type">;
+/**
+ * Component Auth Configuration Schema
+ * Validates YAML-based component auth requirements
+ */
+declare const componentAuthSchema: z.ZodOptional<z.ZodObject<{
+    required_roles: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    required_permissions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    fallback: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
+        hide: "hide";
+        placeholder: "placeholder";
+        message: "message";
+    }>>>;
+    fallback_message: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>>;
+/**
+ * RBAC Configuration Schema
+ * Validates role definitions, permissions, and route protection rules
+ */
+declare const rbacConfigSchema: z.ZodObject<{
+    roles: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        permissions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+    protected_routes: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        roles: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>>;
+    public_routes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+/**
+ * Auth User Schema
+ * Validates user objects with required id and roles
+ */
+declare const authUserSchema: z.ZodObject<{
+    id: z.ZodString;
+    email: z.ZodOptional<z.ZodString>;
+    name: z.ZodOptional<z.ZodString>;
+    roles: z.ZodArray<z.ZodString>;
+    permissions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+}, z.core.$strip>;
+/**
+ * Auth Session Schema
+ * Validates session structure including expiration timestamps
+ */
+declare const authSessionSchema: z.ZodObject<{
+    user: z.ZodObject<{
+        id: z.ZodString;
+        email: z.ZodOptional<z.ZodString>;
+        name: z.ZodOptional<z.ZodString>;
+        roles: z.ZodArray<z.ZodString>;
+        permissions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+    }, z.core.$strip>;
+    expiresAt: z.ZodNumber;
+    issuedAt: z.ZodNumber;
+    refreshToken: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+
+/**
+ * PKI Authentication Provider
+ *
+ * Implements certificate-based authentication supporting:
+ * - Gateway header extraction (e.g., from NGINX, HAProxy)
+ * - Direct TLS termination
+ * - DoD CAC profile validation
+ * - Custom PKI deployments
+ */
+
+declare class PKIProvider implements AuthProvider$1 {
+    private config;
+    constructor(config: PKIConfig);
+    authenticate(context: AuthContext$1): Promise<AuthUser | null>;
+    validate(session: AuthSession): Promise<boolean>;
+    /**
+     * Extract roles from certificate based on organizational units
+     * Can be customized per deployment via subclassing
+     */
+    private extractRolesFromCertificate;
+}
+
+/**
+ * OIDC Authentication Provider
+ *
+ * Implements the AuthProvider interface for OAuth2/OIDC authentication.
+ * Supports major providers (Cognito, Azure AD, Keycloak, etc.) with
+ * configurable claims mapping and provider-specific quirks handling.
+ */
+
+/**
+ * OIDC Provider
+ *
+ * Handles OAuth2/OIDC authentication flows including:
+ * - Discovery of OIDC configuration
+ * - Authorization code exchange
+ * - JWT validation
+ * - Session refresh
+ * - Provider-specific quirks (Keycloak, Cognito, etc.)
+ */
+declare class OIDCProvider implements AuthProvider$1 {
+    private config;
+    private metadata;
+    constructor(config: OIDCConfig);
+    /**
+     * Initialize provider by discovering OIDC configuration
+     *
+     * Call this during app startup to pre-fetch OIDC metadata.
+     * If not called, metadata will be lazily loaded on first use.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Get metadata (lazy load if not initialized)
+     *
+     * @returns OIDC metadata
+     */
+    private getMetadata;
+    /**
+     * Authenticate user by exchanging authorization code for tokens
+     *
+     * This is called after the user is redirected back from the OIDC provider
+     * with an authorization code in the query parameters.
+     *
+     * @param context - Auth context with query params containing authorization code
+     * @returns Authenticated user or null if no code present
+     * @throws Error if token exchange or validation fails
+     */
+    authenticate(context: AuthContext$1): Promise<AuthUser | null>;
+    /**
+     * Validate session (check if token is still valid)
+     *
+     * Simple time-based validation. For more security, you could:
+     * - Call the userinfo endpoint
+     * - Verify token hasn't been revoked
+     * - Check against a session store
+     *
+     * @param session - Session to validate
+     * @returns true if session is still valid
+     */
+    validate(session: AuthSession): Promise<boolean>;
+    /**
+     * Refresh session using refresh token
+     *
+     * When the access token expires, use the refresh token to get new tokens
+     * without requiring the user to re-authenticate.
+     *
+     * @param session - Session with refresh token
+     * @returns Updated session with new tokens, or null if refresh failed
+     */
+    refresh(session: AuthSession): Promise<AuthSession | null>;
+    /**
+     * Get authorization URL for initiating OIDC login
+     *
+     * Redirect users to this URL to start the authentication flow.
+     *
+     * @param redirectUri - Where to redirect after authentication
+     * @param state - CSRF protection token (recommended)
+     * @returns Authorization URL
+     */
+    getAuthorizationUrl(redirectUri: string, state?: string): Promise<string>;
+    /**
+     * Extract claim value with fallback
+     *
+     * Tries custom mapped key first, then falls back to default key.
+     *
+     * @param claims - JWT claims
+     * @param mappedKey - Custom mapped key from config
+     * @param defaultKey - Default OIDC key
+     * @returns Claim value or undefined
+     */
+    private getClaimValue;
+    /**
+     * Extract roles from claims (provider-specific logic)
+     *
+     * Different OIDC providers store roles in different places:
+     * - Standard: 'roles' claim
+     * - Keycloak: realm_access.roles
+     * - Cognito: cognito:groups
+     * - Azure AD: roles claim
+     *
+     * @param claims - JWT claims
+     * @returns Array of role strings
+     */
+    private extractRoles;
+}
+
+/**
+ * X.509 Certificate Parser
+ *
+ * Utilities for parsing and validating X.509 certificates.
+ * Supports both PEM/DER formats and gateway header extraction.
+ */
+
+interface ParsedCertificate {
+    subject: {
+        commonName?: string;
+        email?: string;
+        organizationalUnit?: string[];
+        organization?: string;
+        country?: string;
+    };
+    issuer: {
+        commonName?: string;
+        organization?: string;
+    };
+    serialNumber: string;
+    notBefore: Date;
+    notAfter: Date;
+    isValid: boolean;
+}
+/**
+ * Parse X.509 certificate from PEM string or DER buffer
+ */
+declare function parseCertificate(pemOrDer: string | ArrayBuffer): ParsedCertificate;
+/**
+ * Extract EDIPI from DoD CAC certificate
+ * EDIPI is stored in OID 2.16.840.1.101.2.1.11.42
+ */
+declare function extractEDIPI(cert: X509Certificate): string | undefined;
+/**
+ * Validate certificate against DoD CAC requirements
+ */
+declare function validateDoDCAC(parsed: ParsedCertificate): boolean;
+/**
+ * Parse certificate from gateway headers (x-client-cert-* pattern)
+ */
+declare function parseCertFromHeaders(headers: Record<string, string>, prefix?: string): ParsedCertificate | null;
+
+/**
+ * OIDC Discovery Client
+ *
+ * Handles OIDC provider discovery and authorization URL generation.
+ * Follows the OpenID Connect Discovery 1.0 specification.
+ */
+/**
+ * OIDC Provider Metadata (from .well-known/openid-configuration)
+ */
+interface OIDCMetadata {
+    issuer: string;
+    authorization_endpoint: string;
+    token_endpoint: string;
+    jwks_uri: string;
+    userinfo_endpoint?: string;
+    end_session_endpoint?: string;
+    scopes_supported?: string[];
+    response_types_supported?: string[];
+}
+/**
+ * Discover OIDC provider configuration
+ *
+ * Fetches the OIDC discovery document from the well-known endpoint.
+ * This is the first step in any OIDC flow.
+ *
+ * @param discoveryUrl - Full URL to .well-known/openid-configuration
+ * @returns OIDC metadata with endpoints and capabilities
+ * @throws Error if discovery fails or metadata is invalid
+ */
+declare function discoverOIDC(discoveryUrl: string): Promise<OIDCMetadata>;
+/**
+ * Generate authorization URL for OIDC login
+ *
+ * Builds the URL to redirect users to for authentication.
+ * Follows OAuth 2.0 authorization code flow.
+ *
+ * @param metadata - OIDC provider metadata from discovery
+ * @param clientId - OAuth client ID
+ * @param redirectUri - Where to redirect after authentication
+ * @param state - CSRF protection token (recommended)
+ * @param scopes - OAuth scopes to request
+ * @returns Authorization URL to redirect user to
+ */
+declare function buildAuthorizationUrl(metadata: OIDCMetadata, clientId: string, redirectUri: string, state?: string, scopes?: string[]): string;
+
+/**
+ * OIDC Token Exchange & Validation
+ *
+ * Handles OAuth2 token exchange, refresh, and JWT validation.
+ * Uses jose for secure JWT operations.
+ */
+
+interface TokenSet {
+    access_token: string;
+    id_token: string;
+    refresh_token?: string;
+    expires_in: number;
+    token_type: string;
+}
+/**
+ * Exchange authorization code for tokens
+ *
+ * This is step 2 of the OAuth2 authorization code flow.
+ * The authorization code is exchanged for access/ID/refresh tokens.
+ *
+ * @param metadata - OIDC provider metadata
+ * @param code - Authorization code from callback
+ * @param clientId - OAuth client ID
+ * @param clientSecret - OAuth client secret
+ * @param redirectUri - Must match the redirect_uri used in authorization
+ * @returns Token set with access_token, id_token, and optionally refresh_token
+ * @throws Error if token exchange fails
+ */
+declare function exchangeCodeForTokens(metadata: OIDCMetadata, code: string, clientId: string, clientSecret: string, redirectUri: string): Promise<TokenSet>;
+/**
+ * Refresh access token using refresh token
+ *
+ * When access tokens expire, use the refresh token to get new ones
+ * without requiring user to re-authenticate.
+ *
+ * @param metadata - OIDC provider metadata
+ * @param refreshToken - Refresh token from initial token exchange
+ * @param clientId - OAuth client ID
+ * @param clientSecret - OAuth client secret
+ * @returns New token set
+ * @throws Error if refresh fails
+ */
+declare function refreshAccessToken(metadata: OIDCMetadata, refreshToken: string, clientId: string, clientSecret: string): Promise<TokenSet>;
+/**
+ * Validate ID token JWT and extract claims
+ *
+ * Verifies the JWT signature using the provider's JWKS and validates
+ * standard claims (issuer, audience, expiration).
+ *
+ * This is critical for security - never trust an ID token without validation!
+ *
+ * @param idToken - JWT ID token from token exchange
+ * @param jwksUri - JWKS URI from OIDC metadata
+ * @param issuer - Expected issuer (should match token's iss claim)
+ * @param clientId - Expected audience (should match token's aud claim)
+ * @param skipIssuerCheck - Skip issuer validation (use for Keycloak quirks)
+ * @returns Validated JWT payload with user claims
+ * @throws Error if JWT validation fails
+ */
+declare function validateIdToken(idToken: string, jwksUri: string, issuer: string, clientId: string, skipIssuerCheck?: boolean): Promise<Record<string, any>>;
+
+/**
+ * Keycloak-specific OIDC Adapter
+ *
+ * Keycloak has several quirks in its OIDC implementation that require
+ * special handling. This adapter normalizes Keycloak behavior.
+ *
+ * Known Issues:
+ * 1. Issuer in token doesn't always match discovery URL
+ * 2. Refresh token rotation is inconsistent
+ * 3. Claims structure differs from standard OIDC
+ * 4. Role mapping is non-standard (realm_access.roles)
+ */
+/**
+ * Keycloak-specific OIDC adapter
+ *
+ * Use this when working with Keycloak to handle its many quirks.
+ * Tested with Keycloak 19.x - 23.x
+ */
+declare class KeycloakAdapter {
+    /**
+     * Normalize Keycloak issuer (remove /auth prefix if present)
+     *
+     * Keycloak's issuer URLs changed between versions:
+     * - Pre-17: https://keycloak.example.com/auth/realms/myrealm
+     * - Post-17: https://keycloak.example.com/realms/myrealm
+     *
+     * This normalizes to the post-17 format.
+     *
+     * @param issuer - Issuer from token or metadata
+     * @returns Normalized issuer
+     */
+    static normalizeIssuer(issuer: string): string;
+    /**
+     * Map Keycloak-specific claims to standard format
+     *
+     * Keycloak stores roles and groups in non-standard locations:
+     * - Roles: realm_access.roles (not standard)
+     * - Groups: groups array (sometimes, if configured)
+     * - Username: preferred_username (not always 'name')
+     *
+     * @param tokenPayload - Raw JWT payload from Keycloak
+     * @returns Normalized claims matching AuthUser interface
+     */
+    static mapClaims(tokenPayload: Record<string, any>): Record<string, any>;
+    /**
+     * Keycloak refresh tokens should be refreshed earlier than spec suggests
+     *
+     * Keycloak's refresh token rotation is buggy and sometimes fails if you
+     * wait too long. Refresh aggressively when less than 10 minutes remain.
+     *
+     * @param expiresIn - Seconds until token expires
+     * @returns true if token should be refreshed now
+     */
+    static shouldRefreshToken(expiresIn: number): boolean;
+}
+
+interface SessionManagerConfig {
+    /**
+     * Secret key for JWT signing (must be at least 32 bytes)
+     */
+    secret: string;
+    /**
+     * Session duration in seconds (default: 15 minutes)
+     */
+    sessionDuration?: number;
+    /**
+     * Algorithm for JWT signing (default: HS256)
+     */
+    algorithm?: string;
+    /**
+     * Issuer claim for JWT
+     */
+    issuer?: string;
+    /**
+     * Audience claim for JWT
+     */
+    audience?: string;
+}
+declare class SessionManager {
+    private secret;
+    private sessionDuration;
+    private algorithm;
+    private issuer?;
+    private audience?;
+    constructor(config: SessionManagerConfig);
+    /**
+     * Create a new session for authenticated user
+     */
+    createSession(user: AuthUser, refreshToken?: string): Promise<AuthSession>;
+    /**
+     * Sign session into a JWT
+     */
+    signSession(session: AuthSession): Promise<string>;
+    /**
+     * Verify and decode session JWT
+     */
+    verifySession(jwt: string): Promise<AuthSession | null>;
+    /**
+     * Check if session is expired
+     */
+    isExpired(session: AuthSession): boolean;
+    /**
+     * Check if session should be refreshed (within 5 minutes of expiry)
+     */
+    shouldRefresh(session: AuthSession): boolean;
+    /**
+     * Refresh session (extend expiration)
+     */
+    refreshSession(session: AuthSession): Promise<AuthSession>;
+    /**
+     * Serialize session to string (for cookies/localStorage)
+     */
+    serialize(session: AuthSession): Promise<string>;
+    /**
+     * Deserialize session from string
+     */
+    deserialize(serialized: string): Promise<AuthSession | null>;
+}
+
+/**
+ * Cookie options for session cookies
+ */
+interface CookieOptions {
+    /**
+     * Cookie name (default: 'stackwright_session')
+     */
+    name?: string;
+    /**
+     * Domain for cookie
+     */
+    domain?: string;
+    /**
+     * Path for cookie (default: '/')
+     */
+    path?: string;
+    /**
+     * Max age in seconds
+     */
+    maxAge?: number;
+    /**
+     * HttpOnly flag (default: true)
+     */
+    httpOnly?: boolean;
+    /**
+     * Secure flag (default: true in production)
+     */
+    secure?: boolean;
+    /**
+     * SameSite policy (default: 'lax')
+     */
+    sameSite?: 'strict' | 'lax' | 'none';
+}
+/**
+ * Serialize cookie with options
+ */
+declare function serializeCookie(name: string, value: string, options?: CookieOptions): string;
+/**
+ * Parse cookie string into key-value pairs
+ */
+declare function parseCookies(cookieHeader?: string): Record<string, string>;
+/**
+ * Create a cookie header for clearing/deleting a cookie
+ */
+declare function clearCookie(name: string, options?: Pick<CookieOptions, 'domain' | 'path'>): string;
+
+/**
+ * RBAC Engine for checking roles and permissions
+ */
+declare class RBACEngine {
+    private config;
+    private rolePermissions;
+    constructor(config: RBACConfig);
+    /**
+     * Build internal map of role → permissions for fast lookups
+     */
+    private buildRolePermissionMap;
+    /**
+     * Check if user has a specific role
+     */
+    hasRole(user: AuthUser, role: string): boolean;
+    /**
+     * Check if user has any of the specified roles
+     */
+    hasAnyRole(user: AuthUser, roles: string[]): boolean;
+    /**
+     * Check if user has all of the specified roles
+     */
+    hasAllRoles(user: AuthUser, roles: string[]): boolean;
+    /**
+     * Check if user has a specific permission
+     * Permissions are checked both:
+     * 1. Directly in user.permissions array
+     * 2. Through role-based permissions from config
+     */
+    hasPermission(user: AuthUser, permission: string): boolean;
+    /**
+     * Check if user has any of the specified permissions
+     */
+    hasAnyPermission(user: AuthUser, permissions: string[]): boolean;
+    /**
+     * Check if user has all of the specified permissions
+     */
+    hasAllPermissions(user: AuthUser, permissions: string[]): boolean;
+    /**
+     * Check if route is public (no auth required)
+     */
+    isPublicRoute(path: string): boolean;
+    /**
+     * Check if user can access a route based on protected_routes config
+     */
+    canAccessRoute(user: AuthUser | null, path: string): boolean;
+    /**
+     * Check if user can access a component based on component auth config
+     */
+    canAccessComponent(user: AuthUser | null, authConfig: ComponentAuthConfig | undefined): boolean;
+    private matchPath;
+}
+
+/**
+ * Auth context value provided to component tree
+ */
+interface AuthContextValue {
+    /**
+     * Currently authenticated user (null if not authenticated)
+     */
+    user: AuthUser | null;
+    /**
+     * Current session (null if not authenticated)
+     */
+    session: AuthSession | null;
+    /**
+     * Whether user is authenticated
+     */
+    isAuthenticated: boolean;
+    /**
+     * Whether auth is still loading
+     */
+    isLoading: boolean;
+    /**
+     * Check if user has a specific role
+     */
+    hasRole: (role: string) => boolean;
+    /**
+     * Check if user has a specific permission
+     */
+    hasPermission: (permission: string) => boolean;
+    /**
+     * Check if user has any of the specified roles
+     */
+    hasAnyRole: (roles: string[]) => boolean;
+    /**
+     * Check if user has all of the specified permissions
+     */
+    hasAllPermissions: (permissions: string[]) => boolean;
+}
+/**
+ * Auth context - provides authentication state to components
+ */
+declare const AuthContext: React.Context<AuthContextValue | null>;
+/**
+ * Hook to access auth context
+ * Throws error if used outside AuthProvider
+ */
+declare function useAuth(): AuthContextValue;
+/**
+ * Hook to require authentication
+ * Returns null and logs warning if not authenticated
+ */
+declare function useRequireAuth(): AuthContextValue | null;
+
+interface AuthProviderProps {
+    /**
+     * Current authenticated user (null if not authenticated)
+     */
+    user: AuthUser | null;
+    /**
+     * Current session (null if not authenticated)
+     */
+    session: AuthSession | null;
+    /**
+     * RBAC configuration for role/permission checking
+     */
+    rbacConfig: RBACConfig;
+    /**
+     * Whether auth is still loading
+     */
+    isLoading?: boolean;
+    /**
+     * Child components
+     */
+    children: ReactNode;
+}
+/**
+ * AuthProvider - Provides authentication state to component tree
+ *
+ * @example
+ * ```tsx
+ * <AuthProvider user={user} session={session} rbacConfig={config}>
+ *   <App />
+ * </AuthProvider>
+ * ```
+ */
+declare function AuthProvider({ user, session, rbacConfig, isLoading, children, }: AuthProviderProps): ReactElement;
+
+/**
+ * DoD CAC Profile Configuration
+ *
+ * Pre-built profile for DoD Common Access Card (CAC) certificates.
+ *
+ * This profile includes:
+ * - List of trusted DoD CA issuers
+ * - Required OU validation (DOD)
+ * - EDIPI extraction for user ID
+ *
+ * Last updated: 2025-01 (DoD PKI CA list)
+ *
+ * Note: DoD PKI infrastructure is regularly updated. Verify current CA list at:
+ * https://public.cyber.mil/pki-pke/
+ */
+
+/**
+ * DoD CAC profile configuration
+ *
+ * This provides sensible defaults for DoD CAC authentication in most deployments.
+ * Assumes gateway (e.g., NGINX, HAProxy) handles mTLS and forwards headers.
+ */
+declare const DOD_CAC_PROFILE: Omit<PKIConfig, 'type'>;
+/**
+ * Create DoD CAC configuration with custom overrides
+ *
+ * @example
+ * ```typescript
+ * const config = createDoDCACConfig({
+ *   source: 'direct_tls', // If terminating TLS in Node.js
+ *   headerPrefix: 'ssl-client-', // Custom gateway header prefix
+ * });
+ * ```
+ */
+declare function createDoDCACConfig(overrides?: Partial<PKIConfig>): PKIConfig;
+/**
+ * Minimal DoD CAC config for development/testing
+ * Relaxes some requirements for local testing without real CAC cards
+ */
+declare function createDoDCACDevConfig(): PKIConfig;
+
+/**
+ * Props that any component wrapped with withAuth will receive
+ */
+interface ComponentProps {
+    id?: string;
+    [key: string]: any;
+}
+/**
+ * Higher-order component that wraps a component with authentication checks
+ *
+ * @example
+ * ```tsx
+ * const ProtectedButton = withAuth(Button, {
+ *   required_roles: ['ADMIN'],
+ *   fallback: 'message',
+ *   fallback_message: 'Only admins can see this button'
+ * });
+ * ```
+ *
+ * @param Component - The component to wrap
+ * @param authConfig - Authentication requirements from YAML
+ * @returns Wrapped component with auth enforcement
+ */
+declare function withAuth<P extends ComponentProps>(Component: React__default.ComponentType<P>, authConfig?: ComponentAuthConfig): React__default.ComponentType<P>;
+/**
+ * Custom fallback component (for advanced use cases)
+ */
+declare function withAuthFallback<P extends ComponentProps>(Component: React__default.ComponentType<P>, authConfig: ComponentAuthConfig, FallbackComponent: React__default.ComponentType<any>): React__default.ComponentType<P>;
+
+/**
+ * Register the auth decorator for use by content renderers
+ *
+ * This should be called once in your app's initialization (e.g., _app.tsx)
+ * to enable auth-aware component rendering.
+ *
+ * @example
+ * ```tsx
+ * // In pages/_app.tsx
+ * import { registerAuthDecorator } from '@stackwright-pro/auth';
+ *
+ * registerAuthDecorator();
+ *
+ * function MyApp({ Component, pageProps }: AppProps) {
+ *   return (
+ *     <AuthProvider {...authProps}>
+ *       <Component {...pageProps} />
+ *     </AuthProvider>
+ *   );
+ * }
+ * ```
+ */
+declare function registerAuthDecorator(): void;
+/**
+ * Get the registered auth decorator (for use by content renderers)
+ *
+ * Returns null if auth is not registered, allowing graceful degradation.
+ * This is the function that OSS core would call to check if auth is available.
+ *
+ * @returns The withAuth decorator function, or null if not registered
+ */
+declare function getAuthDecorator(): typeof withAuth | null;
+/**
+ * Wrap a component with auth if decorator is registered and config exists
+ *
+ * This is a safe wrapper that OSS packages can use without depending on auth.
+ * If auth is not registered, returns the original component unchanged.
+ * If auth config is missing/undefined, returns the original component unchanged.
+ *
+ * @example
+ * ```tsx
+ * // In content renderer (can live in OSS core!)\n * function renderContentItem(item: ContentItem) {
+ *   const Component = getComponentFromRegistry(item.type);
+ *
+ *   // Apply auth if available
+ *   const WrappedComponent = maybeWrapWithAuth(Component, item.auth);
+ *
+ *   return <WrappedComponent {...item} />;
+ * }
+ * ```
+ *
+ * @param Component - Component to wrap
+ * @param authConfig - Auth configuration from YAML (optional)
+ * @returns Wrapped component if auth is registered, original component otherwise
+ */
+declare function maybeWrapWithAuth<P extends {
+    id?: string;
+    [key: string]: any;
+}>(Component: React__default.ComponentType<P>, authConfig?: ComponentAuthConfig): React__default.ComponentType<P>;
+/**
+ * Type guard to check if content item has auth config
+ *
+ * Useful for conditionally applying auth in renderers without
+ * needing to import auth types.
+ *
+ * @example
+ * ```tsx
+ * if (hasAuthConfig(item)) {
+ *   // TypeScript knows item.auth exists
+ *   WrappedComponent = maybeWrapWithAuth(Component, item.auth);
+ * }
+ * ```
+ */
+declare function hasAuthConfig(item: any): item is {
+    auth: ComponentAuthConfig;
+};
+
+export { type AuthConfig, AuthContext, type AuthContextValue, AuthProvider, type AuthProviderProps, type AuthSession, type AuthUser, type ComponentAuthConfig, type ComponentProps, type CookieOptions, DOD_CAC_PROFILE, KeycloakAdapter, type OIDCConfig, type OIDCMetadata, OIDCProvider, type PKIConfig, PKIProvider, type ParsedCertificate, type RBACConfig, RBACEngine, SessionManager, type SessionManagerConfig, type TokenSet, authConfigSchema, authSessionSchema, authUserSchema, buildAuthorizationUrl, clearCookie, componentAuthSchema, createDoDCACConfig, createDoDCACDevConfig, discoverOIDC, exchangeCodeForTokens, extractEDIPI, getAuthDecorator, hasAuthConfig, maybeWrapWithAuth, oidcConfigSchema, parseCertFromHeaders, parseCertificate, parseCookies, pkiConfigSchema, rbacConfigSchema, refreshAccessToken, registerAuthDecorator, serializeCookie, useAuth, useRequireAuth, validateDoDCAC, validateIdToken, withAuth, withAuthFallback };