@korajs/auth 1.0.0-beta.12 → 1.0.0-beta.13

package/src/provider/oauth/oauth-types.ts

@@ -0,0 +1,184 @@
+import { KoraError } from '@korajs/core'
+
+// ============================================================================
+// OAuth Provider Configuration
+// ============================================================================
+
+/**
+ * Configuration for an OAuth 2.0 provider.
+ */
+export interface OAuthProviderConfig {
+	/** Provider identifier (e.g., 'google', 'github', 'microsoft') */
+	providerId: string
+	/** OAuth client ID */
+	clientId: string
+	/** OAuth client secret. Required for confidential server-side clients. */
+	clientSecret?: string
+	/** Authorization endpoint URL */
+	authorizationUrl: string
+	/** Token exchange endpoint URL */
+	tokenUrl: string
+	/** User info endpoint URL */
+	userInfoUrl: string
+	/** OAuth scopes to request */
+	scopes: string[]
+	/** Redirect URI for the callback */
+	redirectUri: string
+	/**
+	 * Enable PKCE (Proof Key for Code Exchange).
+	 *
+	 * Required for public clients such as desktop and mobile apps, and recommended
+	 * whenever the provider supports it.
+	 */
+	pkce?: boolean
+}
+
+// ============================================================================
+// OAuth Tokens
+// ============================================================================
+
+/**
+ * Tokens returned by the OAuth provider after code exchange.
+ */
+export interface OAuthTokens {
+	/** OAuth access token */
+	accessToken: string
+	/** Token type (usually 'Bearer') */
+	tokenType: string
+	/** Access token expiry in seconds (if provided) */
+	expiresIn?: number
+	/** Refresh token (if provided) */
+	refreshToken?: string
+	/** ID token (if provided, e.g., OpenID Connect) */
+	idToken?: string
+	/** Granted scopes (may differ from requested scopes) */
+	scope?: string
+}
+
+// ============================================================================
+// OAuth User Info
+// ============================================================================
+
+/**
+ * User information from the OAuth provider.
+ */
+export interface OAuthUserInfo {
+	/** Provider-specific user ID */
+	providerId: string
+	/** Provider name (e.g., 'google', 'github') */
+	provider: string
+	/** User's email address (may be null if not granted) */
+	email: string | null
+	/** Whether the email is verified by the provider */
+	emailVerified: boolean
+	/** User's display name */
+	name: string | null
+	/** URL to the user's avatar/profile picture */
+	avatarUrl: string | null
+	/** Raw profile data from the provider */
+	rawProfile: Record<string, unknown>
+}
+
+// ============================================================================
+// OAuth State
+// ============================================================================
+
+/**
+ * State stored during the OAuth flow for CSRF protection.
+ */
+export interface OAuthState {
+	/** Random state parameter for CSRF protection */
+	state: string
+	/** Provider ID */
+	provider: string
+	/** Redirect URI used for this flow */
+	redirectUri: string
+	/** When this state was created (ms since epoch) */
+	createdAt: number
+	/** When this state expires (ms since epoch) */
+	expiresAt: number
+	/** Optional: user-defined data to pass through the flow */
+	metadata?: Record<string, unknown>
+	/** PKCE code verifier, stored server-side until the callback is consumed. */
+	codeVerifier?: string
+}
+
+/**
+ * Store for OAuth state parameters.
+ */
+export interface OAuthStateStore {
+	/** Store a state parameter for later validation. */
+	store(state: OAuthState): Promise<void>
+	/** Consume a state parameter (single-use). Returns null if not found or expired. */
+	consume(stateValue: string): Promise<OAuthState | null>
+	/** Clean up expired states. */
+	cleanExpired(): Promise<number>
+}
+
+// ============================================================================
+// Linked Identity
+// ============================================================================
+
+/**
+ * A linked OAuth identity for a user.
+ * Users can have multiple linked identities (e.g., Google + GitHub).
+ */
+export interface LinkedIdentity {
+	/** Unique ID of this link */
+	id: string
+	/** Kora user ID */
+	userId: string
+	/** OAuth provider name */
+	provider: string
+	/** Provider-specific user ID */
+	providerUserId: string
+	/** Provider email (at time of linking) */
+	email: string | null
+	/** When this identity was linked */
+	linkedAt: number
+}
+
+// ============================================================================
+// Errors
+// ============================================================================
+
+export class OAuthError extends KoraError {
+	constructor(message: string, code: string, context?: Record<string, unknown>) {
+		super(message, code, context)
+		this.name = 'OAuthError'
+	}
+}
+
+export class OAuthStateMismatchError extends OAuthError {
+	constructor() {
+		super('OAuth state parameter does not match. Possible CSRF attack.', 'OAUTH_STATE_MISMATCH')
+	}
+}
+
+export class OAuthCodeExchangeError extends OAuthError {
+	constructor(details?: string) {
+		super(
+			`Failed to exchange authorization code for tokens.${details ? ` ${details}` : ''}`,
+			'OAUTH_CODE_EXCHANGE_FAILED',
+			details ? { details } : undefined,
+		)
+	}
+}
+
+export class OAuthUserInfoError extends OAuthError {
+	constructor(details?: string) {
+		super(
+			`Failed to fetch user info from OAuth provider.${details ? ` ${details}` : ''}`,
+			'OAUTH_USER_INFO_FAILED',
+			details ? { details } : undefined,
+		)
+	}
+}
+
+export class OAuthProviderNotFoundError extends OAuthError {
+	constructor(provider: string) {
+		super(`OAuth provider "${provider}" is not configured.`, 'OAUTH_PROVIDER_NOT_FOUND', {
+			provider,
+		})
+	}
+}

package/src/provider/oauth/postgres-oauth-store.ts

@@ -0,0 +1,296 @@
+import { randomUUID } from 'node:crypto'
+import { ensurePostgresSchema } from '../../postgres/ensure-schema'
+import { DuplicateLinkedIdentityError, type LinkedIdentityStore } from './linked-identity-store'
+import type { LinkedIdentity, OAuthState, OAuthStateStore } from './oauth-types'
+
+interface PostgresClient {
+	begin<T>(fn: (sql: PostgresClient) => Promise<T>): Promise<T>
+	(template: TemplateStringsArray, ...args: unknown[]): Promise<Record<string, unknown>[]>
+}
+
+interface OAuthStateRow {
+	state: string
+	provider: string
+	redirect_uri: string
+	created_at: string | number
+	expires_at: string | number
+	metadata_json: string | null
+	code_verifier: string | null
+}
+
+interface LinkedIdentityRow {
+	id: string
+	user_id: string
+	provider: string
+	provider_user_id: string
+	email: string | null
+	linked_at: string | number
+}
+
+export class PostgresOAuthStateStore implements OAuthStateStore {
+	private readonly sql: PostgresClient
+	private readonly ready: Promise<void>
+
+	constructor(sql: PostgresClient) {
+		this.sql = sql
+		this.ready = this.ensureTables()
+	}
+
+	async store(state: OAuthState): Promise<void> {
+		await this.ready
+		await this.sql`
+			INSERT INTO auth_oauth_states
+				(state, provider, redirect_uri, created_at, expires_at, metadata_json, code_verifier)
+			VALUES (
+				${state.state},
+				${state.provider},
+				${state.redirectUri},
+				${state.createdAt},
+				${state.expiresAt},
+				${state.metadata ? JSON.stringify(state.metadata) : null},
+				${state.codeVerifier ?? null}
+			)
+			ON CONFLICT (state) DO UPDATE SET
+				provider = EXCLUDED.provider,
+				redirect_uri = EXCLUDED.redirect_uri,
+				created_at = EXCLUDED.created_at,
+				expires_at = EXCLUDED.expires_at,
+				metadata_json = EXCLUDED.metadata_json,
+				code_verifier = EXCLUDED.code_verifier
+		`
+	}
+
+	async consume(stateValue: string): Promise<OAuthState | null> {
+		await this.ready
+		return this.sql.begin(async (tx) => {
+			const rows = (await tx`
+				DELETE FROM auth_oauth_states
+				WHERE state = ${stateValue}
+				RETURNING *
+			`) as unknown as OAuthStateRow[]
+
+			const row = rows[0]
+			if (!row || Date.now() > Number(row.expires_at)) {
+				return null
+			}
+			return rowToOAuthState(row)
+		})
+	}
+
+	async cleanExpired(): Promise<number> {
+		await this.ready
+		const rows = await this.sql`
+			DELETE FROM auth_oauth_states
+			WHERE expires_at < ${Date.now()}
+			RETURNING state
+		`
+		return rows.length
+	}
+
+	private async ensureTables(): Promise<void> {
+		// Concurrency-safe on an empty database shared by several instances.
+		await ensurePostgresSchema(this.sql, async (sql) => {
+			await sql`
+				CREATE TABLE IF NOT EXISTS auth_oauth_states (
+					state TEXT PRIMARY KEY,
+					provider TEXT NOT NULL,
+					redirect_uri TEXT NOT NULL,
+					created_at BIGINT NOT NULL,
+					expires_at BIGINT NOT NULL,
+					metadata_json TEXT,
+					code_verifier TEXT
+				)
+			`
+
+			await sql`
+				CREATE INDEX IF NOT EXISTS idx_auth_oauth_states_expires_at
+					ON auth_oauth_states(expires_at)
+			`
+		})
+	}
+}
+
+export class PostgresLinkedIdentityStore implements LinkedIdentityStore {
+	private readonly sql: PostgresClient
+	private readonly ready: Promise<void>
+
+	constructor(sql: PostgresClient) {
+		this.sql = sql
+		this.ready = this.ensureTables()
+	}
+
+	async findByProvider(provider: string, providerUserId: string): Promise<LinkedIdentity | null> {
+		await this.ready
+		const rows = (await this.sql`
+			SELECT * FROM auth_linked_identities
+			WHERE provider = ${provider} AND provider_user_id = ${providerUserId}
+		`) as unknown as LinkedIdentityRow[]
+
+		return rows[0] ? rowToLinkedIdentity(rows[0]) : null
+	}
+
+	async findByUser(userId: string): Promise<LinkedIdentity[]> {
+		await this.ready
+		const rows = (await this.sql`
+			SELECT * FROM auth_linked_identities
+			WHERE user_id = ${userId}
+			ORDER BY linked_at ASC
+		`) as unknown as LinkedIdentityRow[]
+
+		return rows.map(rowToLinkedIdentity)
+	}
+
+	async create(params: {
+		userId: string
+		provider: string
+		providerUserId: string
+		email: string | null
+	}): Promise<LinkedIdentity> {
+		await this.ready
+		const identity: LinkedIdentity = {
+			id: randomUUID(),
+			userId: params.userId,
+			provider: params.provider,
+			providerUserId: params.providerUserId,
+			email: params.email,
+			linkedAt: Date.now(),
+		}
+
+		try {
+			await this.sql`
+				INSERT INTO auth_linked_identities
+					(id, user_id, provider, provider_user_id, email, linked_at)
+				VALUES (
+					${identity.id},
+					${identity.userId},
+					${identity.provider},
+					${identity.providerUserId},
+					${identity.email},
+					${identity.linkedAt}
+				)
+			`
+		} catch (error) {
+			if (isUniqueViolation(error)) {
+				throw new DuplicateLinkedIdentityError(params.provider)
+			}
+			throw error
+		}
+
+		return identity
+	}
+
+	async delete(userId: string, provider: string): Promise<void> {
+		await this.ready
+		await this.sql`
+			DELETE FROM auth_linked_identities
+			WHERE user_id = ${userId} AND provider = ${provider}
+		`
+	}
+
+	private async ensureTables(): Promise<void> {
+		// Concurrency-safe on an empty database shared by several instances.
+		await ensurePostgresSchema(this.sql, async (sql) => {
+			await sql`
+				CREATE TABLE IF NOT EXISTS auth_linked_identities (
+					id TEXT PRIMARY KEY,
+					user_id TEXT NOT NULL,
+					provider TEXT NOT NULL,
+					provider_user_id TEXT NOT NULL,
+					email TEXT,
+					linked_at BIGINT NOT NULL,
+					UNIQUE(provider, provider_user_id),
+					UNIQUE(user_id, provider)
+				)
+			`
+
+			await sql`
+				CREATE INDEX IF NOT EXISTS idx_auth_linked_identities_user_id
+					ON auth_linked_identities(user_id)
+			`
+		})
+	}
+}
+
+export async function createPostgresOAuthStateStore(options: {
+	connectionString: string
+}): Promise<PostgresOAuthStateStore> {
+	const postgresClient = await loadPostgresDeps()
+	const sql = postgresClient(options.connectionString) as unknown as PostgresClient
+	return new PostgresOAuthStateStore(sql)
+}
+
+export async function createPostgresLinkedIdentityStore(options: {
+	connectionString: string
+}): Promise<PostgresLinkedIdentityStore> {
+	const postgresClient = await loadPostgresDeps()
+	const sql = postgresClient(options.connectionString) as unknown as PostgresClient
+	return new PostgresLinkedIdentityStore(sql)
+}
+
+export async function createPostgresOAuthStores(options: { connectionString: string }): Promise<{
+	stateStore: PostgresOAuthStateStore
+	linkedIdentityStore: PostgresLinkedIdentityStore
+}> {
+	const postgresClient = await loadPostgresDeps()
+	const sql = postgresClient(options.connectionString) as unknown as PostgresClient
+	return {
+		stateStore: new PostgresOAuthStateStore(sql),
+		linkedIdentityStore: new PostgresLinkedIdentityStore(sql),
+	}
+}
+
+async function loadPostgresDeps(): Promise<(connectionString: string) => unknown> {
+	try {
+		const dynamicImport = new Function('specifier', 'return import(specifier)') as (
+			specifier: string,
+		) => Promise<unknown>
+
+		const postgresMod = (await dynamicImport('postgres')) as { default: (cs: string) => unknown }
+		return postgresMod.default
+	} catch {
+		throw new Error(
+			'PostgreSQL OAuth stores require the "postgres" package. Install it in your project dependencies.',
+		)
+	}
+}
+
+function rowToOAuthState(row: OAuthStateRow): OAuthState {
+	return {
+		state: row.state,
+		provider: row.provider,
+		redirectUri: row.redirect_uri,
+		createdAt: Number(row.created_at),
+		expiresAt: Number(row.expires_at),
+		metadata: parseMetadata(row.metadata_json),
+		codeVerifier: row.code_verifier ?? undefined,
+	}
+}
+
+function parseMetadata(value: string | null): Record<string, unknown> | undefined {
+	if (!value) return undefined
+	const parsed = JSON.parse(value) as unknown
+	return typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)
+		? (parsed as Record<string, unknown>)
+		: undefined
+}
+
+function rowToLinkedIdentity(row: LinkedIdentityRow): LinkedIdentity {
+	return {
+		id: row.id,
+		userId: row.user_id,
+		provider: row.provider,
+		providerUserId: row.provider_user_id,
+		email: row.email,
+		linkedAt: Number(row.linked_at),
+	}
+}
+
+function isUniqueViolation(error: unknown): boolean {
+	if (!(error instanceof Error)) return false
+	const code = (error as Error & { code?: string }).code
+	return (
+		code === '23505' ||
+		error.message.includes('unique constraint') ||
+		error.message.includes('duplicate key')
+	)
+}