@stackwright-pro/auth 0.2.0-alpha.1 → 0.2.0-alpha.2

package/dist/index.d.mts

@@ -1,372 +1,9 @@
-import { z } from 'zod';
+import { AuthProvider as AuthProvider$1, PKIConfig, AuthContext as AuthContext$1, AuthUser, AuthSession, OIDCConfig, RBACConfig, ComponentAuthConfig } from '@stackwright-pro/types';
+export { AuthConfig, AuthSession, AuthUser, ComponentAuthConfig, OIDCConfig, PKIConfig, RBACConfig, authConfigSchema, authSessionSchema, authUserSchema, componentAuthSchema, oidcConfigSchema, pkiConfigSchema, rbacConfigSchema } from '@stackwright-pro/types';
 import { X509Certificate } from '@peculiar/x509';
 import * as React from 'react';
 import React__default, { ReactNode, ReactElement } from 'react';
 
-/**
- * HMAC Header Signing for PKI Gateway Authentication
- *
- * Prevents header forgery attacks by HMAC-signing certificate headers
- * at the gateway (nginx/HAProxy) and verifying them in the application.
- *
- * Without this, any request that bypasses the reverse proxy can forge
- * x-client-cert-* headers and impersonate any certificate identity.
- *
- * Canonical string format:
- *   {prefix}dn:{value}\n{prefix}issuer:{value}\n...{prefix}fingerprint:{value}\n_ts:{timestamp}
- *
- * @see packages/auth/test/integration/docker/nginx/nginx.conf for gateway setup
- */
-interface HeaderSigningConfig {
-    /** Shared HMAC secret between gateway and application */
-    secret: string;
-    /** Header name for the signature (default: 'x-client-cert-sig') */
-    signatureHeader?: string;
-    /** Header name for the timestamp (default: 'x-client-cert-sig-ts') */
-    timestampHeader?: string;
-    /** Maximum age of signature in seconds (default: 30) */
-    maxAge?: number;
-    /** Custom header prefix if not using default 'x-client-cert-' */
-    headerPrefix?: string;
-}
-/**
- * Signs certificate headers with HMAC-SHA256.
- *
- * Used by the gateway (nginx via lua-resty-hmac, or a sidecar) to sign
- * headers before forwarding to the application.
- *
- * @returns Object with `signature` and `timestamp` to set as additional headers
- */
-declare function signCertHeaders(headers: Record<string, string>, config: HeaderSigningConfig): {
-    signature: string;
-    timestamp: string;
-};
-/**
- * Verifies the HMAC signature on certificate headers.
- *
- * Call this in the auth provider BEFORE trusting any cert header values.
- * Returns `{ valid: true }` only when the signature is both correct and fresh.
- */
-declare function verifyCertHeaders(headers: Record<string, string | undefined>, config: HeaderSigningConfig): {
-    valid: boolean;
-    reason?: string;
-};
-
-/**
- * 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 (in-memory).
- * Contains user info and expiration details.
- *
- * Note: `refreshToken` is the **plaintext** value used by application code.
- * When serialised to a JWT (via SessionManager.signSession), the refresh
- * token is encrypted with JWE (A256GCM) and stored as `encRefreshToken`.
- * It is never written to the JWT in plaintext.
- *
- * Legacy JWTs containing a plain `refreshToken` claim are accepted for
- * backward compatibility but trigger a deprecation warning.
- */
-interface AuthSession {
-    user: AuthUser;
-    expiresAt: number;
-    issuedAt: number;
-    refreshToken?: string;
-    /** Unique session identifier (JWT ID) for revocation support */
-    jti?: 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[];
-    /** HMAC signing config for verifying gateway-provided cert headers */
-    headerSigning?: HeaderSigningConfig;
-}
-/**
- * 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;
-    };
-    /** When true (default), authenticate() throws if expectedState is missing from context. */
-    requireState?: 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>;
-    /** Expected state for OIDC CSRF validation (stored server-side before redirect) */
-    expectedState?: string;
-    /** Expected nonce for OIDC ID token replay protection */
-    expectedNonce?: string;
-    /** PKCE code verifier for OIDC authorization code exchange */
-    codeVerifier?: 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>>;
-    headerSigning: z.ZodOptional<z.ZodObject<{
-        secret: z.ZodString;
-        signatureHeader: z.ZodOptional<z.ZodString>;
-        timestampHeader: z.ZodOptional<z.ZodString>;
-        maxAge: z.ZodOptional<z.ZodNumber>;
-        headerPrefix: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>>;
-}, 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>>;
-    requireState: z.ZodOptional<z.ZodBoolean>;
-}, 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>>;
-    headerSigning: z.ZodOptional<z.ZodObject<{
-        secret: z.ZodString;
-        signatureHeader: z.ZodOptional<z.ZodString>;
-        timestampHeader: z.ZodOptional<z.ZodString>;
-        maxAge: z.ZodOptional<z.ZodNumber>;
-        headerPrefix: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>>;
-}, 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>>;
-    requireState: z.ZodOptional<z.ZodBoolean>;
-}, 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>;
-
 /**
  * Authentication Audit Logging
  *
@@ -1217,6 +854,55 @@ interface AuthProviderProps {
  */
 declare function AuthProvider({ user, session, rbacConfig, isLoading, children, }: AuthProviderProps): ReactElement;
 
+/**
+ * HMAC Header Signing for PKI Gateway Authentication
+ *
+ * Prevents header forgery attacks by HMAC-signing certificate headers
+ * at the gateway (nginx/HAProxy) and verifying them in the application.
+ *
+ * Without this, any request that bypasses the reverse proxy can forge
+ * x-client-cert-* headers and impersonate any certificate identity.
+ *
+ * Canonical string format:
+ *   {prefix}dn:{value}\n{prefix}issuer:{value}\n...{prefix}fingerprint:{value}\n_ts:{timestamp}
+ *
+ * @see packages/auth/test/integration/docker/nginx/nginx.conf for gateway setup
+ */
+interface HeaderSigningConfig {
+    /** Shared HMAC secret between gateway and application */
+    secret: string;
+    /** Header name for the signature (default: 'x-client-cert-sig') */
+    signatureHeader?: string;
+    /** Header name for the timestamp (default: 'x-client-cert-sig-ts') */
+    timestampHeader?: string;
+    /** Maximum age of signature in seconds (default: 30) */
+    maxAge?: number;
+    /** Custom header prefix if not using default 'x-client-cert-' */
+    headerPrefix?: string;
+}
+/**
+ * Signs certificate headers with HMAC-SHA256.
+ *
+ * Used by the gateway (nginx via lua-resty-hmac, or a sidecar) to sign
+ * headers before forwarding to the application.
+ *
+ * @returns Object with `signature` and `timestamp` to set as additional headers
+ */
+declare function signCertHeaders(headers: Record<string, string>, config: HeaderSigningConfig): {
+    signature: string;
+    timestamp: string;
+};
+/**
+ * Verifies the HMAC signature on certificate headers.
+ *
+ * Call this in the auth provider BEFORE trusting any cert header values.
+ * Returns `{ valid: true }` only when the signature is both correct and fresh.
+ */
+declare function verifyCertHeaders(headers: Record<string, string | undefined>, config: HeaderSigningConfig): {
+    valid: boolean;
+    reason?: string;
+};
+
 /**
  * DoD CAC Profile Configuration
  *
@@ -1364,4 +1050,4 @@ declare function hasAuthConfig(item: any): item is {
     auth: ComponentAuthConfig;
 };
 
-export { type AuditEvent, AuditEventType, type AuditLogger, type AuthConfig, AuthContext, type AuthContextValue, AuthProvider, type AuthProviderProps, type AuthSession, type AuthUser, type AuthorizationRequest, type BuildAuthorizationUrlOptions, type ComponentAuthConfig, type ComponentProps, CompositeAuditLogger, ConsoleAuditLogger, type CookieOptions, DOD_CAC_PROFILE, type HeaderSigningConfig, InMemoryRevocationStore, KeycloakAdapter, NoopAuditLogger, type OIDCConfig, type OIDCMetadata, OIDCProvider, type PKIConfig, PKIProvider, type ParsedCertificate, type RBACConfig, RBACEngine, type RevocationStore, SessionManager, type SessionManagerConfig, type TokenSet, authConfigSchema, authSessionSchema, authUserSchema, buildAuthorizationUrl, clearCookie, componentAuthSchema, createAuditEvent, createDoDCACConfig, createDoDCACDevConfig, decryptToken, deriveEncryptionKey, discoverOIDC, encryptToken, exchangeCodeForTokens, extractEDIPI, generateCodeChallenge, generateCodeVerifier, generateJti, generateNonce, generateState, getAuthDecorator, hasAuthConfig, maybeWrapWithAuth, oidcConfigSchema, parseCertFromHeaders, parseCertificate, parseCookies, pkiConfigSchema, rbacConfigSchema, refreshAccessToken, registerAuthDecorator, serializeCookie, signCertHeaders, useAuth, useRequireAuth, validateDoDCAC, validateIdToken, verifyCertHeaders, verifyState, withAuth, withAuthFallback };
+export { type AuditEvent, AuditEventType, type AuditLogger, AuthContext, type AuthContextValue, AuthProvider, type AuthProviderProps, type AuthorizationRequest, type BuildAuthorizationUrlOptions, type ComponentProps, CompositeAuditLogger, ConsoleAuditLogger, type CookieOptions, DOD_CAC_PROFILE, type HeaderSigningConfig, InMemoryRevocationStore, KeycloakAdapter, NoopAuditLogger, type OIDCMetadata, OIDCProvider, PKIProvider, type ParsedCertificate, RBACEngine, type RevocationStore, SessionManager, type SessionManagerConfig, type TokenSet, buildAuthorizationUrl, clearCookie, createAuditEvent, createDoDCACConfig, createDoDCACDevConfig, decryptToken, deriveEncryptionKey, discoverOIDC, encryptToken, exchangeCodeForTokens, extractEDIPI, generateCodeChallenge, generateCodeVerifier, generateJti, generateNonce, generateState, getAuthDecorator, hasAuthConfig, maybeWrapWithAuth, parseCertFromHeaders, parseCertificate, parseCookies, refreshAccessToken, registerAuthDecorator, serializeCookie, signCertHeaders, useAuth, useRequireAuth, validateDoDCAC, validateIdToken, verifyCertHeaders, verifyState, withAuth, withAuthFallback };