@bagelink/auth 1.4.178 → 1.4.180

package/src/sso.ts

@@ -0,0 +1,565 @@
+import type { SSOProvider, AuthenticationResponse } from './types'
+
+// Global reference to auth API - will be set by setAuthContext
+let authApiRef: any = null
+
+/**
+ * Set the auth context for SSO operations
+ * This is called automatically when using useAuth()
+ */
+export function setAuthContext(authApi: any) {
+	authApiRef = authApi
+}
+
+/**
+ * Get current auth context
+ */
+function getAuthApi() {
+	if (!authApiRef) {
+		throw new Error('SSO auth context not initialized. Make sure to call useAuth() before using SSO methods.')
+	}
+	return authApiRef
+}
+
+/**
+ * SSO Provider Configuration
+ */
+export interface SSOProviderConfig {
+	/** Provider identifier */
+	id: SSOProvider
+	/** Display name */
+	name: string
+	/** Brand color (hex) */
+	color: string
+	/** Icon identifier (for UI libraries) */
+	icon: string
+	/** Default OAuth scopes */
+	defaultScopes: string[]
+	/** Provider-specific metadata */
+	metadata?: {
+		authDomain?: string
+		buttonText?: string
+		[key: string]: any
+	}
+}
+
+/**
+ * OAuth Flow Options
+ */
+export interface OAuthFlowOptions {
+	/** Custom redirect URI (defaults to current origin + /auth/callback) */
+	redirectUri?: string
+	/** State parameter for CSRF protection (auto-generated if not provided) */
+	state?: string
+	/** Custom scopes (overrides provider defaults) */
+	scopes?: string[]
+	/** Additional OAuth parameters (prompt, login_hint, hd, domain, etc.) */
+	params?: Record<string, string>
+	/** Popup window dimensions */
+	popupDimensions?: {
+		width?: number
+		height?: number
+	}
+	/** Timeout for popup flow in milliseconds (default: 90000) */
+	popupTimeout?: number
+}
+
+/**
+ * Popup Result
+ */
+export interface PopupResult {
+	code: string
+	state?: string
+	error?: string
+}
+
+/**
+ * SSO Error Types
+ */
+export class SSOError extends Error {
+	constructor(message: string, public code: string) {
+		super(message)
+		this.name = 'SSOError'
+	}
+}
+
+export class PopupBlockedError extends SSOError {
+	constructor() {
+		super('Popup was blocked. Please allow popups for this site.', 'POPUP_BLOCKED')
+		this.name = 'PopupBlockedError'
+	}
+}
+
+export class PopupClosedError extends SSOError {
+	constructor() {
+		super('Popup was closed by user', 'POPUP_CLOSED')
+		this.name = 'PopupClosedError'
+	}
+}
+
+export class PopupTimeoutError extends SSOError {
+	constructor() {
+		super('Popup authentication timed out', 'POPUP_TIMEOUT')
+		this.name = 'PopupTimeoutError'
+	}
+}
+
+export class StateMismatchError extends SSOError {
+	constructor() {
+		super('State mismatch - possible CSRF attack', 'STATE_MISMATCH')
+		this.name = 'StateMismatchError'
+	}
+}
+
+/**
+ * SSO Provider Instance with functional methods
+ */
+export interface SSOProviderInstance extends SSOProviderConfig {
+	/**
+	 * Initiate OAuth flow with redirect (most common)
+	 * User is redirected to provider's authorization page
+	 */
+	redirect: (options?: OAuthFlowOptions) => Promise<void>
+
+	/**
+	 * Initiate OAuth flow in a popup window
+	 * Returns the authorization code without leaving the page
+	 */
+	popup: (options?: OAuthFlowOptions) => Promise<AuthenticationResponse>
+
+	/**
+	 * Complete OAuth flow after callback
+	 * Call this on your callback page
+	 */
+	callback: (code: string, state?: string) => Promise<AuthenticationResponse>
+
+	/**
+	 * Link this provider to the current logged-in user
+	 */
+	link: (code: string) => Promise<void>
+
+	/**
+	 * Unlink this provider from the current user
+	 */
+	unlink: () => Promise<void>
+
+	/**
+	 * Get authorization URL without redirecting
+	 */
+	getAuthUrl: (options?: OAuthFlowOptions) => Promise<string>
+
+	/**
+	 * Whether this provider supports popup flow
+	 * Some providers (like Apple) work better with redirect
+	 */
+	supportsPopup?: boolean
+}
+
+/**
+ * Helper to generate random state for CSRF protection
+ * Uses 32 bytes (64 hex chars) for enhanced security
+ */
+function generateState(): string {
+	const array = new Uint8Array(32)
+	crypto.getRandomValues(array)
+	return Array.from(array, byte => byte.toString(16).padStart(2, '0')).join('')
+}
+
+/**
+ * Helper to open popup window centered on screen
+ */
+function openPopup(url: string, width = 500, height = 600): Window | null {
+	const left = window.screenX + (window.outerWidth - width) / 2
+	const top = window.screenY + (window.outerHeight - height) / 2
+	return window.open(
+		url,
+		'oauth-popup',
+		`width=${width},height=${height},left=${left},top=${top},toolbar=no,menubar=no,location=no,status=no`
+	)
+}
+
+/**
+ * Helper to wait for OAuth callback in popup
+ * Uses postMessage for reliable communication with polling fallback
+ */
+function waitForPopupCallback(popup: Window, provider: string, timeoutMs = 90000): Promise<PopupResult> {
+	return new Promise((resolve, reject) => {
+		let done = false
+		const finish = (fn: () => void) => {
+			if (!done) {
+				done = true
+				fn()
+			}
+		}
+
+		// Timeout handler
+		const timer = setTimeout(() => {
+			finish(() => { reject(new PopupTimeoutError()) })
+		}, timeoutMs)
+
+		// postMessage listener (preferred method)
+		function onMessage(ev: MessageEvent) {
+			try {
+				// Strict origin check
+				if (ev.origin !== window.location.origin) return
+
+				const data = ev.data || {}
+				if (data.type !== 'auth:complete' || data.provider !== provider) return
+
+				cleanup()
+				if (data.error) {
+					reject(new SSOError(data.error, 'OAUTH_ERROR'))
+				} else if (data.code) {
+					resolve({ code: data.code, state: data.state })
+				}
+			} catch {
+				// Ignore message parsing errors
+			}
+		}
+
+		// Polling fallback (for when postMessage isn't available)
+		const pollInterval = setInterval(() => {
+			try {
+				if (popup.closed) {
+					cleanup()
+					reject(new PopupClosedError())
+					return
+				}
+
+				// Try to read popup URL (only works when same-origin)
+				const url = new URL(popup.location.href)
+				if (url.origin === window.location.origin) {
+					const code = url.searchParams.get('code')
+					const state = url.searchParams.get('state') ?? undefined
+					const error = url.searchParams.get('error')
+
+					if (code || error) {
+						cleanup()
+						try {
+							popup.close()
+						} catch {
+							// Ignore close errors
+						}
+
+						if (error) {
+							reject(new SSOError(error, 'OAUTH_ERROR'))
+						} else if (code) {
+							resolve({ code, state })
+						}
+					}
+				}
+			} catch {
+				// Cross-origin error - popup hasn't redirected back yet
+				// This is expected and normal
+			}
+		}, 150)
+
+		function cleanup() {
+			finish(() => {
+				clearInterval(pollInterval)
+				clearTimeout(timer)
+				window.removeEventListener('message', onMessage)
+				try {
+					popup.close()
+				} catch {
+					// Ignore close errors
+				}
+			})
+		}
+
+		window.addEventListener('message', onMessage)
+	})
+}
+
+/**
+ * Create SSO Provider Instance with methods
+ */
+function createSSOProvider(config: SSOProviderConfig): SSOProviderInstance {
+	const getDefaultRedirectUri = () => {
+		if (typeof window !== 'undefined') {
+			return `${window.location.origin}/auth/callback`
+		}
+		return `/auth/callback`
+	}
+
+	/**
+	 * Get per-provider state storage key
+	 */
+	const getStateKey = () => `oauth_state:${config.id}`
+
+	return {
+		...config,
+
+		async redirect(options: OAuthFlowOptions = {}) {
+			const auth = getAuthApi()
+			const redirectUri = options.redirectUri ?? getDefaultRedirectUri()
+			const state = options.state ?? generateState()
+
+			// Store state AND provider in sessionStorage for verification
+			if (typeof sessionStorage !== 'undefined') {
+				sessionStorage.setItem(getStateKey(), state)
+				// Map state -> provider so we can identify which provider on callback
+				sessionStorage.setItem(`oauth_provider:${state}`, config.id)
+			}
+
+			const authUrl = await auth.initiateSSO({
+				provider: config.id,
+				redirect_uri: redirectUri,
+				state,
+				scopes: options.scopes ?? config.defaultScopes,
+				params: options.params,
+			})
+
+			window.location.href = authUrl
+		},
+
+		async popup(options: OAuthFlowOptions = {}) {
+			const auth = getAuthApi()
+			const redirectUri = options.redirectUri ?? getDefaultRedirectUri()
+			const state = options.state ?? generateState()
+			const timeout = options.popupTimeout ?? 90000
+
+			// Store state AND provider in sessionStorage for verification
+			if (typeof sessionStorage !== 'undefined') {
+				sessionStorage.setItem(getStateKey(), state)
+				// Map state -> provider so we can identify which provider on callback
+				sessionStorage.setItem(`oauth_provider:${state}`, config.id)
+			}
+
+			const authUrl = await auth.initiateSSO({
+				provider: config.id,
+				redirect_uri: redirectUri,
+				state,
+				scopes: options.scopes ?? config.defaultScopes,
+				params: options.params,
+			})
+
+			const { width = 500, height = 600 } = options.popupDimensions ?? {}
+			const popupWindow = openPopup(authUrl, width, height)
+
+			if (!popupWindow) {
+				throw new PopupBlockedError()
+			}
+
+			const result = await waitForPopupCallback(popupWindow, config.id, timeout)
+
+			return auth.loginWithSSO({
+				provider: config.id,
+				code: result.code,
+				state: result.state,
+			})
+		},
+
+		async callback(code: string, state?: string) {
+			const auth = getAuthApi()
+
+			// Verify state if it was stored (per-provider key)
+			if (typeof sessionStorage !== 'undefined' && state) {
+				const storedState = sessionStorage.getItem(getStateKey())
+				sessionStorage.removeItem(getStateKey())
+				// Clean up provider mapping
+				sessionStorage.removeItem(`oauth_provider:${state}`)
+
+				if (storedState && storedState !== state) {
+					throw new StateMismatchError()
+				}
+			}
+
+			return auth.loginWithSSO({
+				provider: config.id,
+				code,
+				state,
+			})
+		},
+
+		async link(code: string) {
+			const auth = getAuthApi()
+			await auth.linkSSOProvider({
+				provider: config.id,
+				code,
+			})
+		},
+
+		async unlink() {
+			const auth = getAuthApi()
+			await auth.unlinkSSOProvider(config.id)
+		},
+
+		async getAuthUrl(options: OAuthFlowOptions = {}) {
+			const auth = getAuthApi()
+			const redirectUri = options.redirectUri ?? getDefaultRedirectUri()
+			const state = options.state ?? generateState()
+
+			return auth.initiateSSO({
+				provider: config.id,
+				redirect_uri: redirectUri,
+				state,
+				scopes: options.scopes ?? config.defaultScopes,
+				params: options.params,
+			})
+		},
+
+		supportsPopup: true, // Default, can be overridden per provider
+	}
+}
+
+/**
+ * SSO Provider Implementations
+ */
+export const sso = {
+	/**
+	 * Google OAuth Provider
+	 * https://developers.google.com/identity/protocols/oauth2
+	 */
+	google: createSSOProvider({
+		id: 'google',
+		name: 'Google',
+		color: '#4285F4',
+		icon: 'google',
+		defaultScopes: ['openid', 'email', 'profile'],
+		metadata: {
+			authDomain: 'accounts.google.com',
+			buttonText: 'Continue with Google',
+		},
+	}),
+
+	/**
+	 * Microsoft OAuth Provider (Azure AD / Microsoft Entra ID)
+	 * https://learn.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-auth-code-flow
+	 */
+	microsoft: createSSOProvider({
+		id: 'microsoft',
+		name: 'Microsoft',
+		color: '#00A4EF',
+		icon: 'microsoft',
+		defaultScopes: ['openid', 'email', 'profile', 'User.Read'],
+		metadata: {
+			authDomain: 'login.microsoftonline.com',
+			buttonText: 'Continue with Microsoft',
+		},
+	}),
+
+	/**
+	 * GitHub OAuth Provider
+	 * https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps
+	 */
+	github: createSSOProvider({
+		id: 'github',
+		name: 'GitHub',
+		color: '#24292E',
+		icon: 'github',
+		defaultScopes: ['read:user', 'user:email'],
+		metadata: {
+			authDomain: 'github.com',
+			buttonText: 'Continue with GitHub',
+		},
+	}),
+
+	/**
+	 * Okta OAuth Provider
+	 * https://developer.okta.com/docs/guides/implement-grant-type/authcode/main/
+	 */
+	okta: createSSOProvider({
+		id: 'okta',
+		name: 'Okta',
+		color: '#007DC1',
+		icon: 'okta',
+		defaultScopes: ['openid', 'email', 'profile'],
+		metadata: {
+			buttonText: 'Continue with Okta',
+		},
+	}),
+
+	/**
+	 * Apple Sign In Provider
+	 * https://developer.apple.com/documentation/sign_in_with_apple/sign_in_with_apple_rest_api
+	 * Note: Apple works best with redirect flow on web
+	 */
+	apple: {
+		...createSSOProvider({
+			id: 'apple',
+			name: 'Apple',
+			color: '#000000',
+			icon: 'apple',
+			defaultScopes: ['name', 'email'],
+			metadata: {
+				authDomain: 'appleid.apple.com',
+				buttonText: 'Continue with Apple',
+			},
+		}),
+		supportsPopup: false, // Apple prefers redirect on web
+		// Override popup to use redirect for better UX
+		async popup(options?: OAuthFlowOptions) {
+			return this.redirect(options) as any
+		},
+	},
+
+	/**
+	 * Facebook OAuth Provider
+	 * https://developers.facebook.com/docs/facebook-login/guides/advanced/manual-flow
+	 */
+	facebook: createSSOProvider({
+		id: 'facebook',
+		name: 'Facebook',
+		color: '#1877F2',
+		icon: 'facebook',
+		defaultScopes: ['email', 'public_profile'],
+		metadata: {
+			authDomain: 'www.facebook.com',
+			buttonText: 'Continue with Facebook',
+		},
+	}),
+}
+
+/**
+ * Array of all SSO providers
+ */
+export const ssoProviders = Object.values(sso) as readonly SSOProviderInstance[]
+
+/**
+ * Get SSO provider instance by ID
+ */
+export function getSSOProvider(provider: SSOProvider): SSOProviderInstance | undefined {
+	return sso[provider]
+}
+
+/**
+ * Get all available SSO providers
+ */
+export function getAllSSOProviders(): readonly SSOProviderInstance[] {
+	return ssoProviders
+}
+
+/**
+ * Check if a provider is supported
+ */
+export function isSupportedProvider(provider: string): provider is SSOProvider {
+	return provider in sso
+}
+
+/**
+ * Handle OAuth callback from URL
+ * Call this on your callback page to automatically detect and process the callback
+ */
+export async function handleOAuthCallback(): Promise<AuthenticationResponse | null> {
+	if (typeof window === 'undefined') {
+		return null
+	}
+
+	const urlParams = new URLSearchParams(window.location.search)
+	const code = urlParams.get('code')
+	const state = urlParams.get('state')
+
+	if (!code || !state) {
+		return null
+	}
+
+	// Get the provider from sessionStorage (stored during redirect/popup)
+	const provider = sessionStorage.getItem(`oauth_provider:${state}`) as SSOProvider | null
+
+	if (!provider || !isSupportedProvider(provider)) {
+		throw new Error('Unable to determine OAuth provider. State may have expired.')
+	}
+
+	return sso[provider].callback(code, state)
+}

package/src/types.ts

@@ -42,6 +42,8 @@ export type AuthenticationMethodType =
 	| 'sso'
 	| 'otp'
 
+export type SSOProvider = 'google' | 'microsoft' | 'github' | 'okta' | 'apple' | 'facebook'
+
 export interface AuthenticationAccount {
 	created_at?: string
 	updated_at?: string
@@ -216,11 +218,36 @@ export interface OTPMetadata {
 }
 
 export interface SSOMetadata {
-	provider: string
+	provider: SSOProvider
 	sso_user_info: { [key: string]: any }
 	can_create_account?: boolean
 }
 
+export interface SSOInitiateRequest {
+	provider: SSOProvider
+	redirect_uri?: string
+	state?: string
+	scopes?: string[]
+	params?: Record<string, string> // Additional OAuth params (prompt, login_hint, hd, etc.)
+	code_challenge?: string // For PKCE flow
+	code_challenge_method?: 'S256' | 'plain'
+}
+
+export interface SSOCallbackRequest {
+	provider: SSOProvider
+	code: string
+	state?: string
+}
+
+export interface SSOLinkRequest {
+	provider: SSOProvider
+	code: string
+}
+
+export interface SSOUnlinkRequest {
+	provider: SSOProvider
+}
+
 export interface AuthenticationResponse {
 	success: boolean
 	account_id?: string
@@ -263,6 +290,10 @@ export type DeleteSessionResponse = AxiosResponse<MessageResponse>
 export type DeleteAllSessionsResponse = AxiosResponse<MessageResponse>
 export type CleanupSessionsResponse = AxiosResponse<MessageResponse>
 export type GetMethodsResponse = AxiosResponse<AvailableMethodsResponse>
+export type SSOInitiateResponse = AxiosResponse<{ authorization_url: string }>
+export type SSOCallbackResponse = AxiosResponse<AuthenticationResponse>
+export type SSOLinkResponse = AxiosResponse<MessageResponse>
+export type SSOUnlinkResponse = AxiosResponse<MessageResponse>
 
 // ============================================
 // Helper Functions (exported for convenience)
@@ -306,7 +337,7 @@ export function accountToUser(account: AccountInfo | null): User | null {
 
 	// Fallback - use account info directly
 	// Extract email from authentication methods
-	const emailMethod = account.authentication_methods?.find(
+	const emailMethod = account.authentication_methods.find(
 		m => m.type === 'password' || m.type === 'email_token',
 	)