# @constructive-io/oauth

> Minimal OAuth 2.0 client for social authentication A lightweight OAuth 2.0 client for social authentication with Google, GitHub, Facebook, and LinkedIn. Uses [`@constructive-io/csrf`](../csrf) for secure state management. No external auth library dependencies - uses native fetch for HTTP requests. ## Installation ```bash pnpm add @constructive-io/oauth ``` ## Usage ### Basic Setup ```typescript import { createOAuthClient } from '@constructive-io/oauth'; const client = createOAuthClient({ providers: { google: { clientId: process.env.GOOGLE_CLIENT_ID, clientSecret: process.env.GOOGLE_CLIENT_SECRET, }, github: { clientId: process.env.GITHUB_CLIENT_ID, clientSecret: process.env.GITHUB_CLIENT_SECRET, }, }, baseUrl: 'https://api.example.com', }); // Generate authorization URL const { url, state } = client.getAuthorizationUrl({ provider: 'google' }); // After user authorizes, exchange code for profile const profile = await client.handleCallback({ provider: 'google', code }); ``` ### Express Middleware ```typescript import express from 'express'; import cookieParser from 'cookie-parser'; import { createOAuthMiddleware } from '@constructive-io/oauth'; const app = express(); app.use(cookieParser()); const oauth = createOAuthMiddleware({ providers: { google: { clientId: '...', clientSecret: '...' }, github: { clientId: '...', clientSecret: '...' }, facebook: { clientId: '...', clientSecret: '...' }, linkedin: { clientId: '...', clientSecret: '...' }, }, baseUrl: 'https://api.example.com', onSuccess: async (profile, context) => { // Handle successful authentication // Create/update user in database, generate session token, etc. return { user: profile }; }, onError: (error, context) => { console.error('OAuth error:', error); }, successRedirect: 'https://app.example.com/dashboard', errorRedirect: 'https://app.example.com/login?error=auth_failed', }); // Mount routes app.get('/auth/:provider', oauth.initiateAuth); app.get('/auth/:provider/callback', oauth.handleCallback); app.get('/auth/providers', oauth.getProviders); ``` ## Supported Providers | Provider | Scopes | |----------|--------| | Google | `openid`, `email`, `profile` | | GitHub | `user:email`, `read:user` | | Facebook | `email`, `public_profile` | | LinkedIn | `openid`, `profile`, `email` | ## API ### `createOAuthClient(config)` Creates an OAuth client instance. ### `createOAuthMiddleware(config)` Creates Express route handlers for OAuth flows. ### `OAuthProfile` The normalized user profile returned after authentication: ```typescript interface OAuthProfile { provider: string; // 'google', 'github', etc. providerId: string; // Provider's unique user ID email: string | null; name: string | null; picture: string | null; raw: unknown; // Original provider response } ```