raffel 0.1.2 → 0.2.2

package/dist/middleware/auth/oauth2.d.ts

@@ -0,0 +1,294 @@
+/**
+ * OAuth2/OIDC Authentication Strategies
+ *
+ * Provides authentication strategies for OAuth2 and OpenID Connect (OIDC) flows.
+ *
+ * Features:
+ * - OAuth2 authorization code flow
+ * - OIDC with auto-discovery (.well-known/openid-configuration)
+ * - Provider presets (Google, GitHub, Microsoft)
+ * - Token validation (access token and ID token)
+ * - Token refresh support
+ * - State parameter for CSRF protection
+ *
+ * @example
+ * ```typescript
+ * // Using OAuth2 with Google preset
+ * const oauth2 = createOAuth2Strategy({
+ *   provider: 'google',
+ *   clientId: process.env.GOOGLE_CLIENT_ID!,
+ *   clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
+ *   redirectUri: 'https://myapp.com/auth/callback',
+ *   scopes: ['openid', 'email', 'profile'],
+ * })
+ *
+ * server.use(createAuthMiddleware({
+ *   strategies: [oauth2],
+ * }))
+ *
+ * // OAuth2 flow endpoints
+ * server.get('/auth/login', async (_, ctx) => {
+ *   const url = oauth2.getAuthorizationUrl({ state: generateState() })
+ *   return { redirect: url }
+ * })
+ *
+ * server.get('/auth/callback', async (input, ctx) => {
+ *   const { code, state } = input
+ *   const tokens = await oauth2.exchangeCode(code)
+ *   // Store tokens in session
+ *   return { success: true }
+ * })
+ * ```
+ */
+import type { AuthStrategy } from '../auth.js';
+/**
+ * OAuth2 provider presets
+ */
+export type OAuth2Provider = 'google' | 'github' | 'microsoft' | 'apple' | 'facebook' | 'custom';
+/**
+ * OAuth2 configuration
+ */
+export interface OAuth2Config {
+    /** Provider preset (uses predefined URLs and scopes) */
+    provider?: OAuth2Provider;
+    /** OAuth2 client ID */
+    clientId: string;
+    /** OAuth2 client secret */
+    clientSecret: string;
+    /** Redirect URI after authorization */
+    redirectUri: string;
+    /** OAuth2 scopes to request */
+    scopes?: string[];
+    /** Authorization endpoint URL */
+    authorizationUrl?: string;
+    /** Token endpoint URL */
+    tokenUrl?: string;
+    /** User info endpoint URL (for validating access tokens) */
+    userInfoUrl?: string;
+    /** Include client credentials in body instead of header (default: false) */
+    clientCredentialsInBody?: boolean;
+    /** Token validation method */
+    tokenValidation?: 'userinfo' | 'introspection' | 'none';
+    /** Introspection endpoint URL (if using introspection validation) */
+    introspectionUrl?: string;
+    /** Revocation endpoint URL (for revoking tokens) */
+    revocationUrl?: string;
+    /** Custom headers for token requests */
+    tokenRequestHeaders?: Record<string, string>;
+    /** Request timeout in ms (default: 10000) */
+    timeout?: number;
+}
+/**
+ * OIDC configuration (extends OAuth2)
+ */
+export interface OIDCConfig extends Omit<OAuth2Config, 'provider'> {
+    /** OIDC issuer URL (used for auto-discovery) */
+    issuer: string;
+    /** Audience for ID token validation (default: clientId) */
+    audience?: string;
+    /** Whether to validate ID token signature (default: true) */
+    validateIdToken?: boolean;
+    /** Clock skew tolerance in seconds for token validation (default: 60) */
+    clockSkew?: number;
+}
+/**
+ * OAuth2 tokens returned from token exchange
+ */
+export interface OAuth2Tokens {
+    accessToken: string;
+    tokenType: string;
+    expiresIn?: number;
+    refreshToken?: string;
+    scope?: string;
+    idToken?: string;
+}
+/**
+ * OIDC discovery document
+ */
+export interface OIDCDiscoveryDocument {
+    issuer: string;
+    authorization_endpoint: string;
+    token_endpoint: string;
+    userinfo_endpoint?: string;
+    jwks_uri: string;
+    scopes_supported?: string[];
+    response_types_supported: string[];
+    token_endpoint_auth_methods_supported?: string[];
+    id_token_signing_alg_values_supported?: string[];
+    introspection_endpoint?: string;
+    revocation_endpoint?: string;
+}
+/**
+ * User info from OAuth2/OIDC provider
+ */
+export interface OAuth2UserInfo {
+    sub: string;
+    email?: string;
+    email_verified?: boolean;
+    name?: string;
+    given_name?: string;
+    family_name?: string;
+    picture?: string;
+    locale?: string;
+    [key: string]: unknown;
+}
+/**
+ * Extended OAuth2 strategy with flow helpers
+ */
+export interface OAuth2StrategyWithFlow extends AuthStrategy {
+    /** Get authorization URL for redirect */
+    getAuthorizationUrl(options?: {
+        state?: string;
+        nonce?: string;
+        additionalParams?: Record<string, string>;
+    }): string;
+    /** Exchange authorization code for tokens */
+    exchangeCode(code: string): Promise<OAuth2Tokens>;
+    /** Refresh access token using refresh token */
+    refreshToken(refreshToken: string): Promise<OAuth2Tokens>;
+    /** Get user info using access token */
+    getUserInfo(accessToken: string): Promise<OAuth2UserInfo>;
+    /** Revoke a token */
+    revokeToken?(token: string, tokenType?: 'access_token' | 'refresh_token'): Promise<void>;
+    /** Provider configuration (resolved URLs) */
+    readonly config: ResolvedOAuth2Config;
+}
+/**
+ * Extended OIDC strategy with discovery
+ */
+export interface OIDCStrategyWithFlow extends OAuth2StrategyWithFlow {
+    /** OIDC discovery document */
+    readonly discovery: OIDCDiscoveryDocument | null;
+    /** Validate ID token */
+    validateIdToken(idToken: string): Promise<Record<string, unknown>>;
+}
+/**
+ * Resolved OAuth2 configuration with all URLs
+ */
+export interface ResolvedOAuth2Config {
+    clientId: string;
+    clientSecret: string;
+    redirectUri: string;
+    scopes: string[];
+    authorizationUrl: string;
+    tokenUrl: string;
+    userInfoUrl?: string;
+    introspectionUrl?: string;
+    revocationUrl?: string;
+}
+/**
+ * Provider preset configurations
+ */
+export declare const OAuth2Providers: Record<Exclude<OAuth2Provider, 'custom'>, {
+    authorizationUrl: string;
+    tokenUrl: string;
+    userInfoUrl: string;
+    defaultScopes: string[];
+    revocationUrl?: string;
+}>;
+/**
+ * Create an OAuth2 authentication strategy
+ *
+ * This strategy validates access tokens from the Authorization header by calling
+ * the userinfo endpoint. It also provides helper methods for the OAuth2 flow.
+ *
+ * @example
+ * ```typescript
+ * const oauth2 = createOAuth2Strategy({
+ *   provider: 'google',
+ *   clientId: process.env.GOOGLE_CLIENT_ID!,
+ *   clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
+ *   redirectUri: 'https://myapp.com/auth/callback',
+ * })
+ *
+ * // Use as auth strategy
+ * server.use(createAuthMiddleware({ strategies: [oauth2] }))
+ *
+ * // Use flow helpers
+ * const authUrl = oauth2.getAuthorizationUrl({ state: 'random-state' })
+ * const tokens = await oauth2.exchangeCode(code)
+ * ```
+ */
+export declare function createOAuth2Strategy(config: OAuth2Config): OAuth2StrategyWithFlow;
+/**
+ * Create an OIDC authentication strategy with auto-discovery
+ *
+ * This strategy automatically discovers endpoints from the issuer's
+ * .well-known/openid-configuration and validates ID tokens.
+ *
+ * @example
+ * ```typescript
+ * const oidc = createOIDCStrategy({
+ *   issuer: 'https://accounts.google.com',
+ *   clientId: process.env.GOOGLE_CLIENT_ID!,
+ *   clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
+ *   redirectUri: 'https://myapp.com/auth/callback',
+ * })
+ *
+ * server.use(createAuthMiddleware({ strategies: [oidc] }))
+ * ```
+ */
+export declare function createOIDCStrategy(config: OIDCConfig): OIDCStrategyWithFlow;
+/**
+ * Create a Google OAuth2 strategy
+ */
+export declare function createGoogleOAuth2Strategy(config: {
+    clientId: string;
+    clientSecret: string;
+    redirectUri: string;
+    scopes?: string[];
+}): OAuth2StrategyWithFlow;
+/**
+ * Create a GitHub OAuth2 strategy
+ */
+export declare function createGitHubOAuth2Strategy(config: {
+    clientId: string;
+    clientSecret: string;
+    redirectUri: string;
+    scopes?: string[];
+}): OAuth2StrategyWithFlow;
+/**
+ * Create a Microsoft OAuth2 strategy
+ */
+export declare function createMicrosoftOAuth2Strategy(config: {
+    clientId: string;
+    clientSecret: string;
+    redirectUri: string;
+    scopes?: string[];
+    tenant?: string;
+}): OAuth2StrategyWithFlow;
+/**
+ * Create an Apple OAuth2 strategy
+ *
+ * Note: Apple requires additional setup including a service ID and private key
+ * for generating client secrets. This is a simplified version.
+ */
+export declare function createAppleOAuth2Strategy(config: {
+    clientId: string;
+    clientSecret: string;
+    redirectUri: string;
+    scopes?: string[];
+}): OAuth2StrategyWithFlow;
+/**
+ * Create a Facebook OAuth2 strategy
+ */
+export declare function createFacebookOAuth2Strategy(config: {
+    clientId: string;
+    clientSecret: string;
+    redirectUri: string;
+    scopes?: string[];
+}): OAuth2StrategyWithFlow;
+/**
+ * Generate a random state parameter for CSRF protection
+ */
+export declare function generateState(length?: number): string;
+/**
+ * Generate a nonce for OIDC
+ */
+export declare function generateNonce(length?: number): string;
+/**
+ * Clear the OIDC discovery document cache
+ * Useful for testing or forcing a refresh
+ */
+export declare function clearDiscoveryCache(): void;
+//# sourceMappingURL=oauth2.d.ts.map

package/dist/middleware/auth/oauth2.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth2.d.ts","sourceRoot":"","sources":["../../../src/middleware/auth/oauth2.ts"],"names":[],"mappings":"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"}

package/dist/middleware/auth/oauth2.int.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=oauth2.int.test.d.ts.map

package/dist/middleware/auth/oauth2.int.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth2.int.test.d.ts","sourceRoot":"","sources":["../../../src/middleware/auth/oauth2.int.test.ts"],"names":[],"mappings":""}