clearauth 0.3.0

package/dist/oauth/callbacks.js

@@ -0,0 +1,286 @@
+/**
+ * OAuth Callback Utilities
+ *
+ * Shared logic for OAuth callback handling including:
+ * - State parameter validation (CSRF protection)
+ * - User upsert (create or update user by OAuth provider ID)
+ * - Session creation after successful OAuth
+ * - Error handling
+ */
+import { base64url } from 'oslo/encoding';
+/**
+ * Generate a secure random session ID
+ * @param entropySize Number of bytes of entropy (default: 25 = 200 bits)
+ * @internal
+ */
+function generateSessionId(entropySize = 25) {
+    const bytes = new Uint8Array(entropySize);
+    crypto.getRandomValues(bytes);
+    return base64url.encode(bytes).replace(/=/g, '');
+}
+/**
+ * Upsert user from OAuth profile
+ *
+ * Creates a new user or updates an existing user based on the OAuth provider ID.
+ * Uses github_id or google_id column to identify existing users.
+ *
+ * @param db - Kysely database instance
+ * @param provider - OAuth provider name ('github' or 'google')
+ * @param profile - Normalized OAuth user profile
+ * @returns User record from database
+ *
+ * @example
+ * ```ts
+ * const user = await upsertOAuthUser(db, 'github', profile)
+ * ```
+ */
+export async function upsertOAuthUser(db, provider, profile) {
+    const providerIdColumn = provider === 'github' ? 'github_id' : 'google_id';
+    // Check if user exists by provider ID
+    const existingUser = await db
+        .selectFrom('users')
+        .selectAll()
+        .where(providerIdColumn, '=', profile.id)
+        .executeTakeFirst();
+    if (existingUser) {
+        // Update existing user with latest profile data
+        const updatedUser = await db
+            .updateTable('users')
+            .set({
+            email: profile.email,
+            name: profile.name,
+            avatar_url: profile.avatar_url,
+            email_verified: profile.email_verified ?? existingUser.email_verified,
+        })
+            .where('id', '=', existingUser.id)
+            .returningAll()
+            .executeTakeFirstOrThrow();
+        return updatedUser;
+    }
+    // Check if user exists by email (linking accounts)
+    const userByEmail = await db
+        .selectFrom('users')
+        .selectAll()
+        .where('email', '=', profile.email)
+        .executeTakeFirst();
+    if (userByEmail) {
+        // Link OAuth provider to existing email account
+        const updatedUser = await db
+            .updateTable('users')
+            .set({
+            [providerIdColumn]: profile.id,
+            name: profile.name || userByEmail.name,
+            avatar_url: profile.avatar_url || userByEmail.avatar_url,
+            email_verified: profile.email_verified || userByEmail.email_verified,
+        })
+            .where('id', '=', userByEmail.id)
+            .returningAll()
+            .executeTakeFirstOrThrow();
+        return updatedUser;
+    }
+    // Create new user
+    const newUser = {
+        email: profile.email,
+        email_verified: profile.email_verified ?? false,
+        password_hash: null, // OAuth-only user
+        [providerIdColumn]: profile.id,
+        name: profile.name,
+        avatar_url: profile.avatar_url,
+    };
+    const createdUser = await db
+        .insertInto('users')
+        .values(newUser)
+        .returningAll()
+        .executeTakeFirstOrThrow();
+    return createdUser;
+}
+/**
+ * Create session for user
+ *
+ * Creates a new session record in the database and returns the session ID.
+ * Sessions expire after the configured duration (default: 30 days).
+ *
+ * @param db - Kysely database instance
+ * @param userId - User ID to create session for
+ * @param expiresInSeconds - Session expiration time in seconds (default: 2592000 = 30 days)
+ * @param context - Optional request context (IP address, user agent)
+ * @returns Session ID
+ *
+ * @example
+ * ```ts
+ * const sessionId = await createSession(db, user.id, 2592000, { ipAddress, userAgent })
+ * ```
+ */
+export async function createSession(db, userId, expiresInSeconds = 2592000, // 30 days
+context) {
+    // Generate secure random session ID
+    const sessionId = generateSessionId(25); // 200 bits of entropy
+    const expiresAt = new Date(Date.now() + expiresInSeconds * 1000);
+    const newSession = {
+        id: sessionId,
+        user_id: userId,
+        expires_at: expiresAt,
+        ip_address: context?.ipAddress || null,
+        user_agent: context?.userAgent || null,
+    };
+    await db.insertInto('sessions').values(newSession).execute();
+    return sessionId;
+}
+/**
+ * Validate session
+ *
+ * Checks if a session exists and is not expired.
+ *
+ * @param db - Kysely database instance
+ * @param sessionId - Session ID to validate
+ * @returns User if session is valid, null otherwise
+ *
+ * @example
+ * ```ts
+ * const user = await validateSession(db, sessionId)
+ * if (!user) {
+ *   return new Response('Unauthorized', { status: 401 })
+ * }
+ * ```
+ */
+export async function validateSession(db, sessionId) {
+    const result = await db
+        .selectFrom('sessions')
+        .innerJoin('users', 'users.id', 'sessions.user_id')
+        .selectAll('users')
+        .where('sessions.id', '=', sessionId)
+        .where('sessions.expires_at', '>', new Date())
+        .executeTakeFirst();
+    return result || null;
+}
+/**
+ * Delete session (logout)
+ *
+ * Removes a session from the database.
+ *
+ * @param db - Kysely database instance
+ * @param sessionId - Session ID to delete
+ *
+ * @example
+ * ```ts
+ * await deleteSession(db, sessionId)
+ * ```
+ */
+export async function deleteSession(db, sessionId) {
+    await db.deleteFrom('sessions').where('id', '=', sessionId).execute();
+}
+/**
+ * Delete all sessions for a user
+ *
+ * Removes all sessions for a specific user (useful for password changes, etc.)
+ *
+ * @param db - Kysely database instance
+ * @param userId - User ID to delete sessions for
+ *
+ * @example
+ * ```ts
+ * await deleteAllUserSessions(db, userId)
+ * ```
+ */
+export async function deleteAllUserSessions(db, userId) {
+    await db.deleteFrom('sessions').where('user_id', '=', userId).execute();
+}
+/**
+ * Clean up expired sessions
+ *
+ * Removes all expired sessions from the database.
+ * This should be run periodically as a background job.
+ *
+ * @param db - Kysely database instance
+ * @returns Number of sessions deleted
+ *
+ * @example
+ * ```ts
+ * const deleted = await cleanupExpiredSessions(db)
+ * console.log(`Cleaned up ${deleted} expired sessions`)
+ * ```
+ */
+export async function cleanupExpiredSessions(db) {
+    const result = await db
+        .deleteFrom('sessions')
+        .where('expires_at', '<=', new Date())
+        .executeTakeFirst();
+    return Number(result.numDeletedRows ?? 0);
+}
+/**
+ * Parse cookie header
+ *
+ * Parses the Cookie header and returns a map of cookie names to values.
+ *
+ * @param cookieHeader - Cookie header string
+ * @returns Map of cookie names to values
+ *
+ * @internal
+ */
+export function parseCookies(cookieHeader) {
+    const cookies = {};
+    if (!cookieHeader) {
+        return cookies;
+    }
+    const pairs = cookieHeader.split(';');
+    for (const pair of pairs) {
+        const [name, value] = pair.trim().split('=');
+        if (name && value) {
+            cookies[name] = decodeURIComponent(value);
+        }
+    }
+    return cookies;
+}
+/**
+ * Create cookie header
+ *
+ * Creates a Set-Cookie header string with appropriate security attributes.
+ *
+ * @param name - Cookie name
+ * @param value - Cookie value
+ * @param options - Cookie options
+ * @returns Set-Cookie header string
+ *
+ * @internal
+ */
+export function createCookieHeader(name, value, options = {}) {
+    const parts = [`${name}=${encodeURIComponent(value)}`];
+    if (options.httpOnly !== false) {
+        parts.push('HttpOnly');
+    }
+    if (options.secure !== false) {
+        parts.push('Secure');
+    }
+    if (options.sameSite) {
+        parts.push(`SameSite=${options.sameSite.charAt(0).toUpperCase()}${options.sameSite.slice(1)}`);
+    }
+    if (options.path) {
+        parts.push(`Path=${options.path}`);
+    }
+    if (options.maxAge !== undefined) {
+        parts.push(`Max-Age=${options.maxAge}`);
+    }
+    if (options.expires) {
+        parts.push(`Expires=${options.expires.toUTCString()}`);
+    }
+    return parts.join('; ');
+}
+/**
+ * Create delete cookie header
+ *
+ * Creates a Set-Cookie header that deletes a cookie.
+ *
+ * @param name - Cookie name
+ * @param options - Cookie options (path, etc.)
+ * @returns Set-Cookie header string
+ *
+ * @internal
+ */
+export function createDeleteCookieHeader(name, options = {}) {
+    return createCookieHeader(name, '', {
+        ...options,
+        maxAge: 0,
+        expires: new Date(0),
+    });
+}
+//# sourceMappingURL=callbacks.js.map

package/dist/oauth/callbacks.js.map

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

package/dist/oauth/github.d.ts

@@ -0,0 +1,47 @@
+/**
+ * GitHub OAuth Flow Implementation
+ *
+ * Handles GitHub OAuth authentication using Arctic.
+ * Implements authorization URL generation and callback handling.
+ */
+import type { ClearAuthConfig, OAuthCallbackResult } from '../types.js';
+/**
+ * Generate GitHub OAuth authorization URL
+ *
+ * Creates the URL to redirect users to GitHub for authentication.
+ * Includes a state parameter for CSRF protection.
+ *
+ * @param config - Mech Auth configuration
+ * @returns Object containing the authorization URL and state parameter
+ *
+ * @example
+ * ```ts
+ * const { url, state } = await generateGitHubAuthUrl(config)
+ * // Store state in cookie for validation
+ * // Redirect user to url
+ * ```
+ */
+export declare function generateGitHubAuthUrl(config: ClearAuthConfig): Promise<{
+    url: URL;
+    state: string;
+}>;
+/**
+ * Handle GitHub OAuth callback
+ *
+ * Validates the OAuth callback, exchanges the authorization code for tokens,
+ * and fetches the user's profile from GitHub.
+ *
+ * @param config - Mech Auth configuration
+ * @param code - Authorization code from GitHub
+ * @param storedState - State parameter stored in cookie
+ * @param returnedState - State parameter returned by GitHub
+ * @returns OAuth callback result with user profile and tokens
+ * @throws Error if state validation fails or API requests fail
+ *
+ * @example
+ * ```ts
+ * const result = await handleGitHubCallback(config, code, storedState, returnedState)
+ * // Use result.profile to create or update user
+ * ```
+ */
+export declare function handleGitHubCallback(config: ClearAuthConfig, code: string, storedState: string, returnedState: string): Promise<OAuthCallbackResult>;

package/dist/oauth/github.js

@@ -0,0 +1,136 @@
+/**
+ * GitHub OAuth Flow Implementation
+ *
+ * Handles GitHub OAuth authentication using Arctic.
+ * Implements authorization URL generation and callback handling.
+ */
+import { generateState } from 'arctic';
+import { createGitHubProvider } from './arctic-providers.js';
+/**
+ * Generate GitHub OAuth authorization URL
+ *
+ * Creates the URL to redirect users to GitHub for authentication.
+ * Includes a state parameter for CSRF protection.
+ *
+ * @param config - Mech Auth configuration
+ * @returns Object containing the authorization URL and state parameter
+ *
+ * @example
+ * ```ts
+ * const { url, state } = await generateGitHubAuthUrl(config)
+ * // Store state in cookie for validation
+ * // Redirect user to url
+ * ```
+ */
+export async function generateGitHubAuthUrl(config) {
+    const github = createGitHubProvider(config);
+    const state = generateState();
+    // Request user:email scope to access user's email addresses
+    const url = github.createAuthorizationURL(state, ['user:email']);
+    return { url, state };
+}
+/**
+ * Handle GitHub OAuth callback
+ *
+ * Validates the OAuth callback, exchanges the authorization code for tokens,
+ * and fetches the user's profile from GitHub.
+ *
+ * @param config - Mech Auth configuration
+ * @param code - Authorization code from GitHub
+ * @param storedState - State parameter stored in cookie
+ * @param returnedState - State parameter returned by GitHub
+ * @returns OAuth callback result with user profile and tokens
+ * @throws Error if state validation fails or API requests fail
+ *
+ * @example
+ * ```ts
+ * const result = await handleGitHubCallback(config, code, storedState, returnedState)
+ * // Use result.profile to create or update user
+ * ```
+ */
+export async function handleGitHubCallback(config, code, storedState, returnedState) {
+    // Validate state parameter (CSRF protection)
+    if (storedState !== returnedState) {
+        throw new Error('Invalid OAuth state parameter');
+    }
+    const github = createGitHubProvider(config);
+    // Exchange authorization code for access token
+    const tokens = await github.validateAuthorizationCode(code);
+    const accessToken = tokens.accessToken();
+    // Fetch user profile from GitHub API
+    const profile = await fetchGitHubUserProfile(accessToken);
+    return {
+        profile,
+        accessToken,
+    };
+}
+/**
+ * Fetch user profile from GitHub API
+ *
+ * Retrieves the user's profile information and email addresses from GitHub.
+ * If the user's email is not public, fetches it from the emails endpoint.
+ *
+ * @param accessToken - GitHub access token
+ * @returns Normalized user profile
+ * @throws Error if API requests fail or email cannot be found
+ *
+ * @internal
+ */
+async function fetchGitHubUserProfile(accessToken) {
+    // Fetch user profile
+    const userResponse = await fetch('https://api.github.com/user', {
+        headers: {
+            Authorization: `Bearer ${accessToken}`,
+            Accept: 'application/vnd.github.v3+json',
+            'User-Agent': 'Mech-Auth',
+        },
+    });
+    if (!userResponse.ok) {
+        throw new Error(`GitHub API error: ${userResponse.status} ${userResponse.statusText}`);
+    }
+    const user = await userResponse.json();
+    // If email is not public, fetch from emails endpoint
+    let email = user.email;
+    let emailVerified = false;
+    if (!email) {
+        const emailsResponse = await fetch('https://api.github.com/user/emails', {
+            headers: {
+                Authorization: `Bearer ${accessToken}`,
+                Accept: 'application/vnd.github.v3+json',
+                'User-Agent': 'Mech-Auth',
+            },
+        });
+        if (!emailsResponse.ok) {
+            throw new Error(`GitHub API error (emails): ${emailsResponse.status} ${emailsResponse.statusText}`);
+        }
+        const emails = await emailsResponse.json();
+        // Find primary verified email
+        const primaryEmail = emails.find((e) => e.primary && e.verified);
+        if (primaryEmail) {
+            email = primaryEmail.email;
+            emailVerified = primaryEmail.verified;
+        }
+        else {
+            // Fall back to first verified email
+            const verifiedEmail = emails.find((e) => e.verified);
+            if (verifiedEmail) {
+                email = verifiedEmail.email;
+                emailVerified = verifiedEmail.verified;
+            }
+            else {
+                throw new Error('No verified email found in GitHub account');
+            }
+        }
+    }
+    if (!email) {
+        throw new Error('No email found in GitHub account');
+    }
+    return {
+        id: user.id.toString(),
+        email,
+        name: user.name,
+        avatar_url: user.avatar_url,
+        email_verified: emailVerified,
+    };
+}
+//# sourceMappingURL=github.js.map

package/dist/oauth/github.js.map

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

package/dist/oauth/google.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Google OAuth Flow Implementation
+ *
+ * Handles Google OAuth authentication using Arctic.
+ * Implements authorization URL generation and callback handling with PKCE.
+ */
+import type { ClearAuthConfig, OAuthCallbackResult } from '../types.js';
+/**
+ * Generate Google OAuth authorization URL
+ *
+ * Creates the URL to redirect users to Google for authentication.
+ * Includes state and code verifier parameters for CSRF protection and PKCE.
+ *
+ * @param config - Mech Auth configuration
+ * @returns Object containing the authorization URL, state parameter, and code verifier
+ *
+ * @example
+ * ```ts
+ * const { url, state, codeVerifier } = await generateGoogleAuthUrl(config)
+ * // Store state and codeVerifier in cookies for validation
+ * // Redirect user to url
+ * ```
+ */
+export declare function generateGoogleAuthUrl(config: ClearAuthConfig): Promise<{
+    url: URL;
+    state: string;
+    codeVerifier: string;
+}>;
+/**
+ * Handle Google OAuth callback
+ *
+ * Validates the OAuth callback, exchanges the authorization code for tokens,
+ * and fetches the user's profile from Google.
+ *
+ * @param config - Mech Auth configuration
+ * @param code - Authorization code from Google
+ * @param storedState - State parameter stored in cookie
+ * @param returnedState - State parameter returned by Google
+ * @param codeVerifier - Code verifier stored in cookie (for PKCE)
+ * @returns OAuth callback result with user profile and tokens
+ * @throws Error if state validation fails or API requests fail
+ *
+ * @example
+ * ```ts
+ * const result = await handleGoogleCallback(config, code, storedState, returnedState, codeVerifier)
+ * // Use result.profile to create or update user
+ * ```
+ */
+export declare function handleGoogleCallback(config: ClearAuthConfig, code: string, storedState: string, returnedState: string, codeVerifier: string): Promise<OAuthCallbackResult>;

package/dist/oauth/google.js

@@ -0,0 +1,104 @@
+/**
+ * Google OAuth Flow Implementation
+ *
+ * Handles Google OAuth authentication using Arctic.
+ * Implements authorization URL generation and callback handling with PKCE.
+ */
+import { generateState, generateCodeVerifier } from 'arctic';
+import { createGoogleProvider } from './arctic-providers.js';
+/**
+ * Generate Google OAuth authorization URL
+ *
+ * Creates the URL to redirect users to Google for authentication.
+ * Includes state and code verifier parameters for CSRF protection and PKCE.
+ *
+ * @param config - Mech Auth configuration
+ * @returns Object containing the authorization URL, state parameter, and code verifier
+ *
+ * @example
+ * ```ts
+ * const { url, state, codeVerifier } = await generateGoogleAuthUrl(config)
+ * // Store state and codeVerifier in cookies for validation
+ * // Redirect user to url
+ * ```
+ */
+export async function generateGoogleAuthUrl(config) {
+    const google = createGoogleProvider(config);
+    const state = generateState();
+    const codeVerifier = generateCodeVerifier();
+    // Request email and profile scopes
+    const url = google.createAuthorizationURL(state, codeVerifier, ['openid', 'email', 'profile']);
+    return { url, state, codeVerifier };
+}
+/**
+ * Handle Google OAuth callback
+ *
+ * Validates the OAuth callback, exchanges the authorization code for tokens,
+ * and fetches the user's profile from Google.
+ *
+ * @param config - Mech Auth configuration
+ * @param code - Authorization code from Google
+ * @param storedState - State parameter stored in cookie
+ * @param returnedState - State parameter returned by Google
+ * @param codeVerifier - Code verifier stored in cookie (for PKCE)
+ * @returns OAuth callback result with user profile and tokens
+ * @throws Error if state validation fails or API requests fail
+ *
+ * @example
+ * ```ts
+ * const result = await handleGoogleCallback(config, code, storedState, returnedState, codeVerifier)
+ * // Use result.profile to create or update user
+ * ```
+ */
+export async function handleGoogleCallback(config, code, storedState, returnedState, codeVerifier) {
+    // Validate state parameter (CSRF protection)
+    if (storedState !== returnedState) {
+        throw new Error('Invalid OAuth state parameter');
+    }
+    const google = createGoogleProvider(config);
+    // Exchange authorization code for access token (with PKCE)
+    const tokens = await google.validateAuthorizationCode(code, codeVerifier);
+    const accessToken = tokens.accessToken();
+    const refreshToken = tokens.refreshToken();
+    // Fetch user profile from Google API
+    const profile = await fetchGoogleUserProfile(accessToken);
+    return {
+        profile,
+        accessToken,
+        refreshToken,
+    };
+}
+/**
+ * Fetch user profile from Google API
+ *
+ * Retrieves the user's profile information from Google's userinfo endpoint.
+ *
+ * @param accessToken - Google access token
+ * @returns Normalized user profile
+ * @throws Error if API request fails
+ *
+ * @internal
+ */
+async function fetchGoogleUserProfile(accessToken) {
+    // Fetch user profile from Google's userinfo endpoint
+    const response = await fetch('https://www.googleapis.com/oauth2/v3/userinfo', {
+        headers: {
+            Authorization: `Bearer ${accessToken}`,
+        },
+    });
+    if (!response.ok) {
+        throw new Error(`Google API error: ${response.status} ${response.statusText}`);
+    }
+    const user = await response.json();
+    if (!user.email) {
+        throw new Error('No email found in Google account');
+    }
+    return {
+        id: user.sub,
+        email: user.email,
+        name: user.name || null,
+        avatar_url: user.picture || null,
+        email_verified: user.email_verified,
+    };
+}
+//# sourceMappingURL=google.js.map

package/dist/oauth/google.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"google.js","sourceRoot":"","sources":["../../src/oauth/google.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,QAAQ,CAAA;AAE5D,OAAO,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAA;AAe5D;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CAAC,MAAuB;IAKjE,MAAM,MAAM,GAAG,oBAAoB,CAAC,MAAM,CAAC,CAAA;IAC3C,MAAM,KAAK,GAAG,aAAa,EAAE,CAAA;IAC7B,MAAM,YAAY,GAAG,oBAAoB,EAAE,CAAA;IAE3C,mCAAmC;IACnC,MAAM,GAAG,GAAG,MAAM,CAAC,sBAAsB,CAAC,KAAK,EAAE,YAAY,EAAE,CAAC,QAAQ,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC,CAAA;IAE9F,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,YAAY,EAAE,CAAA;AACrC,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,MAAuB,EACvB,IAAY,EACZ,WAAmB,EACnB,aAAqB,EACrB,YAAoB;IAEpB,6CAA6C;IAC7C,IAAI,WAAW,KAAK,aAAa,EAAE,CAAC;QAClC,MAAM,IAAI,KAAK,CAAC,+BAA+B,CAAC,CAAA;IAClD,CAAC;IAED,MAAM,MAAM,GAAG,oBAAoB,CAAC,MAAM,CAAC,CAAA;IAE3C,2DAA2D;IAC3D,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,yBAAyB,CAAC,IAAI,EAAE,YAAY,CAAC,CAAA;IACzE,MAAM,WAAW,GAAG,MAAM,CAAC,WAAW,EAAE,CAAA;IACxC,MAAM,YAAY,GAAG,MAAM,CAAC,YAAY,EAAE,CAAA;IAE1C,qCAAqC;IACrC,MAAM,OAAO,GAAG,MAAM,sBAAsB,CAAC,WAAW,CAAC,CAAA;IAEzD,OAAO;QACL,OAAO;QACP,WAAW;QACX,YAAY;KACb,CAAA;AACH,CAAC;AAED;;;;;;;;;;GAUG;AACH,KAAK,UAAU,sBAAsB,CAAC,WAAmB;IACvD,qDAAqD;IACrD,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,+CAA+C,EAAE;QAC5E,OAAO,EAAE;YACP,aAAa,EAAE,UAAU,WAAW,EAAE;SACvC;KACF,CAAC,CAAA;IAEF,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;QACjB,MAAM,IAAI,KAAK,CAAC,qBAAqB,QAAQ,CAAC,MAAM,IAAI,QAAQ,CAAC,UAAU,EAAE,CAAC,CAAA;IAChF,CAAC;IAED,MAAM,IAAI,GAAe,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAA;IAE9C,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC;QAChB,MAAM,IAAI,KAAK,CAAC,kCAAkC,CAAC,CAAA;IACrD,CAAC;IAED,OAAO;QACL,EAAE,EAAE,IAAI,CAAC,GAAG;QACZ,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,IAAI,EAAE,IAAI,CAAC,IAAI,IAAI,IAAI;QACvB,UAAU,EAAE,IAAI,CAAC,OAAO,IAAI,IAAI;QAChC,cAAc,EAAE,IAAI,CAAC,cAAc;KACpC,CAAA;AACH,CAAC"}

package/dist/oauth/handler.d.ts

@@ -0,0 +1,31 @@
+/**
+ * OAuth HTTP Request Handler
+ *
+ * Handles OAuth-related HTTP requests for GitHub and Google authentication.
+ * Provides login initiation and callback handling endpoints.
+ */
+import type { ClearAuthConfig } from '../types.js';
+/**
+ * OAuth Request Handler
+ *
+ * Main handler for OAuth-related requests. Routes requests to appropriate
+ * provider handlers based on URL path.
+ *
+ * @param request - HTTP request
+ * @param config - Clear Auth configuration
+ * @returns HTTP response
+ *
+ * @example
+ * ```ts
+ * export default {
+ *   async fetch(request: Request, env: Env) {
+ *     const url = new URL(request.url)
+ *     if (url.pathname.startsWith('/auth/oauth/')) {
+ *       return handleOAuthRequest(request, config)
+ *     }
+ *     // ... other routes
+ *   }
+ * }
+ * ```
+ */
+export declare function handleOAuthRequest(request: Request, config: ClearAuthConfig): Promise<Response>;