@idealyst/oauth-client 0.0.1

package/README.md

@@ -0,0 +1,310 @@
+# @idealyst/oauth-client
+
+Universal OAuth2 client for web and React Native applications with a single API.
+
+## Features
+
+- 🌐 **Universal**: Works on both web and React Native with the same API
+- 🔐 **Secure**: Uses PKCE for mobile, supports client secrets for web
+- 🏪 **Storage**: Automatic token storage with customizable adapters
+- 🔄 **Refresh**: Automatic token refresh handling
+- 🚪 **Logout**: Proper logout with token revocation
+- 📱 **Mobile**: Uses `react-native-app-auth` for secure system browser flow
+- 🎯 **TypeScript**: Fully typed for better developer experience
+
+## Installation
+
+```bash
+npm install @idealyst/oauth-client
+# or
+yarn add @idealyst/oauth-client
+```
+
+### Additional Dependencies
+
+#### For React Native:
+```bash
+npm install react-native-app-auth @react-native-async-storage/async-storage
+# Follow react-native-app-auth setup instructions for iOS/Android
+```
+
+#### For Web:
+No additional dependencies required.
+
+## Quick Start
+
+```typescript
+import { createOAuthClient, providers } from '@idealyst/oauth-client'
+
+// Create OAuth client (works on both web and mobile)
+const client = createOAuthClient({
+  ...providers.google,
+  clientId: 'your-google-client-id',
+  redirectUrl: 'com.yourapp://oauth/callback', // Mobile
+  // redirectUrl: 'http://localhost:3000/auth/callback', // Web
+})
+
+// Authorize user - same API on web and mobile!
+try {
+  const result = await client.authorize()
+  console.log('Access token:', result.tokens.accessToken)
+  console.log('User data:', result.user)
+} catch (error) {
+  console.error('Authorization failed:', error)
+}
+```
+
+## API Reference
+
+### createOAuthClient(config, storage?)
+
+Creates a platform-specific OAuth client with a unified API.
+
+```typescript
+const client = createOAuthClient({
+  issuer: 'https://accounts.google.com',
+  clientId: 'your-client-id',
+  redirectUrl: 'your-app://oauth',
+  scopes: ['openid', 'profile', 'email'],
+  
+  // Optional
+  additionalParameters: { prompt: 'consent' },
+  customHeaders: { 'X-Custom': 'value' },
+})
+```
+
+**⚠️ Security**: Client secrets are **never** used in this library. All flows use PKCE for security, which is the OAuth 2.1 standard for public clients.
+
+### OAuthClient Methods
+
+#### authorize()
+Initiates the OAuth flow and returns tokens.
+
+```typescript
+const result = await client.authorize()
+// result.tokens: { accessToken, refreshToken, idToken, expiresAt, ... }
+// result.user: Additional user data (provider-specific)
+```
+
+#### refresh(refreshToken)
+Refreshes an expired access token.
+
+```typescript
+const result = await client.refresh(refreshToken)
+```
+
+#### getStoredTokens()
+Retrieves stored tokens from storage.
+
+```typescript
+const tokens = await client.getStoredTokens()
+if (tokens?.expiresAt && tokens.expiresAt < new Date()) {
+  // Token is expired, refresh it
+}
+```
+
+#### revoke(token)
+Revokes a specific token.
+
+```typescript
+await client.revoke(accessToken)
+```
+
+#### logout()
+Logs out the user, revokes tokens, and clears storage.
+
+```typescript
+await client.logout()
+```
+
+#### clearStoredTokens()
+Manually clears stored tokens.
+
+```typescript
+await client.clearStoredTokens()
+```
+
+## Provider Configurations
+
+Pre-configured settings for popular OAuth providers:
+
+```typescript
+import { providers } from '@idealyst/oauth-client'
+
+// Google
+const googleClient = createOAuthClient({
+  ...providers.google,
+  clientId: 'your-google-client-id',
+  redirectUrl: 'your-redirect-url',
+})
+
+// GitHub
+const githubClient = createOAuthClient({
+  ...providers.github,
+  clientId: 'your-github-client-id',
+  redirectUrl: 'your-redirect-url',
+})
+
+// Microsoft
+const msClient = createOAuthClient({
+  ...providers.microsoft,
+  clientId: 'your-microsoft-client-id',
+  redirectUrl: 'your-redirect-url',
+})
+
+// Auth0
+const auth0Client = createOAuthClient({
+  ...providers.auth0('your-domain.auth0.com'),
+  clientId: 'your-auth0-client-id',
+  redirectUrl: 'your-redirect-url',
+})
+
+// Okta
+const oktaClient = createOAuthClient({
+  ...providers.okta('dev-123.okta.com'),
+  clientId: 'your-okta-client-id',
+  redirectUrl: 'your-redirect-url',
+})
+```
+
+## Custom Storage
+
+By default, the library uses `localStorage` on web and `AsyncStorage` on mobile. You can provide a custom storage adapter:
+
+```typescript
+import { createOAuthClient } from '@idealyst/oauth-client'
+
+const customStorage = {
+  async getItem(key: string): Promise<string | null> {
+    // Your storage implementation
+  },
+  async setItem(key: string, value: string): Promise<void> {
+    // Your storage implementation
+  },
+  async removeItem(key: string): Promise<void> {
+    // Your storage implementation
+  },
+}
+
+const client = createOAuthClient(config, customStorage)
+```
+
+## Platform-Specific Configuration
+
+### Web Configuration
+
+For web applications, use standard HTTP redirect URLs:
+
+```typescript
+const webClient = createOAuthClient({
+  ...providers.google,
+  clientId: 'your-google-client-id',
+  redirectUrl: 'https://yourapp.com/auth/callback',
+})
+```
+
+**⚠️ Security Note**: Client secrets should **NEVER** be included in client-side code. This library uses PKCE (Proof Key for Code Exchange) which provides security for public clients without requiring client secrets.
+
+### Mobile Configuration
+
+For mobile apps, you need to:
+
+1. **Configure custom URL scheme** in your app
+2. **Register the URL scheme** with your OAuth provider
+3. **Use the custom URL** as redirect URL
+
+```typescript
+const mobileClient = createOAuthClient({
+  ...providers.google,
+  clientId: 'your-google-client-id',
+  redirectUrl: 'com.yourapp://oauth/callback',
+})
+```
+
+## React Native Setup
+
+### iOS Configuration
+
+1. Add URL scheme to your `Info.plist`:
+
+```xml
+<key>CFBundleURLTypes</key>
+<array>
+  <dict>
+    <key>CFBundleURLName</key>
+    <string>com.yourapp.oauth</string>
+    <key>CFBundleURLSchemes</key>
+    <array>
+      <string>com.yourapp</string>
+    </array>
+  </dict>
+</array>
+```
+
+### Android Configuration
+
+1. Add intent filter to `android/app/src/main/AndroidManifest.xml`:
+
+```xml
+<activity android:name=".MainActivity">
+  <intent-filter android:label="filter_react_native">
+    <action android:name="android.intent.action.VIEW" />
+    <category android:name="android.intent.category.DEFAULT" />
+    <category android:name="android.intent.category.BROWSABLE" />
+    <data android:scheme="com.yourapp" />
+  </intent-filter>
+</activity>
+```
+
+2. Follow the [react-native-app-auth setup guide](https://github.com/FormidableLabs/react-native-app-auth#setup) for additional configuration.
+
+### OAuth Provider Setup
+
+Register your custom URL scheme as a valid redirect URI in your OAuth provider:
+
+- **Google**: Add `com.yourapp://oauth/callback` to "Authorized redirect URIs"
+- **GitHub**: Set "Authorization callback URL" to `com.yourapp://oauth/callback`
+- **Other providers**: Add the URL scheme to allowed callback URLs
+
+## How Mobile OAuth Works
+
+1. **App opens system browser** (Safari/Chrome) with OAuth URL
+2. **User authenticates** in the browser (can use saved passwords, Touch ID, etc.)
+3. **Provider redirects** to your custom URL scheme (`com.yourapp://oauth/callback`)
+4. **OS recognizes the scheme** and opens your app
+5. **react-native-app-auth** automatically extracts tokens and returns them
+
+This provides the most secure OAuth flow for mobile apps, as recommended by OAuth 2.0 security best practices.
+
+## Error Handling
+
+```typescript
+try {
+  const result = await client.authorize()
+} catch (error) {
+  if (error.message.includes('User cancelled')) {
+    // User cancelled the authorization
+  } else if (error.message.includes('network')) {
+    // Network error
+  } else {
+    // Other OAuth error
+  }
+}
+```
+
+## TypeScript
+
+The library is fully typed. Import types as needed:
+
+```typescript
+import type { 
+  OAuthConfig, 
+  OAuthTokens, 
+  OAuthResult, 
+  OAuthClient 
+} from '@idealyst/oauth-client'
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@idealyst/oauth-client",
+  "version": "0.0.1",
+  "description": "Universal OAuth2 client for web and React Native",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "yarn build"
+  },
+  "keywords": [
+    "oauth",
+    "oauth2",
+    "authentication",
+    "react",
+    "react-native",
+    "cross-platform"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "react-native-app-auth": "^7.2.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.18",
+    "@types/react-native": "^0.73.0",
+    "react": "^19.1.0",
+    "react-native": "^0.80.1",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.3"
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "react-native": ">=0.72"
+  },
+  "peerDependenciesMeta": {
+    "react-native": {
+      "optional": true
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/examples/google-example.ts

@@ -0,0 +1,108 @@
+import { createOAuthClient, providers } from '../index'
+
+// Example: Google OAuth - works on both web and mobile
+export async function setupGoogleOAuth() {
+  const client = createOAuthClient({
+    ...providers.google,
+    clientId: 'your-google-client-id',
+    redirectUrl: 'com.yourapp://oauth/callback', // Mobile
+    // redirectUrl: 'https://yourapp.com/auth/callback', // Web
+    scopes: ['openid', 'profile', 'email'],
+  })
+
+  try {
+    // Authorize user - same API on both platforms!
+    const result = await client.authorize()
+    console.log('Access token:', result.tokens.accessToken)
+    console.log('User info:', result.user)
+
+    // Token management works the same on both platforms
+    const storedTokens = await client.getStoredTokens()
+    if (storedTokens) {
+      console.log('Stored tokens:', storedTokens)
+      
+      // Check if token needs refresh
+      if (storedTokens.expiresAt && storedTokens.expiresAt < new Date()) {
+        if (storedTokens.refreshToken) {
+          const refreshed = await client.refresh(storedTokens.refreshToken)
+          console.log('Refreshed tokens:', refreshed.tokens)
+        }
+      }
+    }
+
+    // Logout when done
+    await client.logout()
+    console.log('Logged out successfully')
+
+  } catch (error) {
+    console.error('OAuth error:', error)
+  }
+}
+
+// Example: Multiple providers
+export async function setupMultipleProviders() {
+  const providers = [
+    { name: 'Google', config: { ...providers.google, clientId: 'google-client-id' } },
+    { name: 'GitHub', config: { ...providers.github, clientId: 'github-client-id' } },
+    { name: 'Microsoft', config: { ...providers.microsoft, clientId: 'ms-client-id' } },
+  ]
+
+  for (const provider of providers) {
+    try {
+      const client = createOAuthClient({
+        ...provider.config,
+        redirectUrl: 'com.yourapp://oauth/callback',
+      })
+      
+      const result = await client.authorize()
+      console.log(`${provider.name} login successful:`, result.tokens.accessToken)
+      return { provider: provider.name, tokens: result.tokens }
+    } catch (error) {
+      console.warn(`${provider.name} login failed:`, error)
+    }
+  }
+  
+  throw new Error('All OAuth providers failed')
+}
+
+// Example: Custom provider configuration
+export async function setupCustomProvider() {
+  const client = createOAuthClient({
+    issuer: 'https://your-oauth-server.com',
+    clientId: 'your-client-id',
+    redirectUrl: 'com.yourapp://oauth/callback',
+    scopes: ['read', 'write'],
+    additionalParameters: {
+      prompt: 'consent',
+    },
+    customHeaders: {
+      'X-Custom-Header': 'value',
+    },
+  })
+
+  try {
+    const result = await client.authorize()
+    return result.tokens
+  } catch (error) {
+    console.error('Custom OAuth error:', error)
+    throw error
+  }
+}
+
+// Example: Platform-specific configuration
+export async function setupPlatformSpecificOAuth() {
+  // Check if we're on mobile or web and configure accordingly
+  const isMobile = typeof navigator !== 'undefined' && navigator.product === 'ReactNative'
+  
+  const client = createOAuthClient({
+    ...providers.google,
+    clientId: 'your-google-client-id',
+    redirectUrl: isMobile 
+      ? 'com.yourapp://oauth/callback'  // Mobile deep link
+      : 'https://yourapp.com/auth/callback', // Web callback
+    scopes: ['openid', 'profile', 'email'],
+    // Note: No client secret needed - PKCE provides security for public clients
+  })
+
+  return await client.authorize()
+}

package/src/index.ts

@@ -0,0 +1,55 @@
+export * from './types'
+export * from './storage'
+
+import type { OAuthConfig, OAuthClient, StorageAdapter } from './types'
+import { WebOAuthClient } from './web-client'
+import { NativeOAuthClient } from './native-client'
+import { createDefaultStorage } from './storage'
+
+export function createOAuthClient(
+  config: OAuthConfig, 
+  storage?: StorageAdapter
+): OAuthClient {
+  const storageAdapter = storage || createDefaultStorage()
+  
+  // Check if we're in React Native environment
+  if (typeof navigator !== 'undefined' && navigator.product === 'ReactNative') {
+    return new NativeOAuthClient(config, storageAdapter)
+  }
+  
+  // Default to web client
+  return new WebOAuthClient(config, storageAdapter)
+}
+
+// Common provider configurations
+export const providers = {
+  google: {
+    issuer: 'https://accounts.google.com',
+    scopes: ['openid', 'profile', 'email'],
+  },
+  
+  github: {
+    issuer: 'https://github.com',
+    authorizationEndpoint: 'https://github.com/login/oauth/authorize',
+    tokenEndpoint: 'https://github.com/login/oauth/access_token',
+    scopes: ['user'],
+  },
+  
+  microsoft: {
+    issuer: 'https://login.microsoftonline.com/common/v2.0',
+    scopes: ['openid', 'profile', 'email'],
+  },
+  
+  auth0: (domain: string) => ({
+    issuer: `https://${domain}`,
+    scopes: ['openid', 'profile', 'email'],
+  }),
+  
+  okta: (domain: string) => ({
+    issuer: `https://${domain}`,
+    scopes: ['openid', 'profile', 'email'],
+  }),
+} as const
+
+export { WebOAuthClient } from './web-client'
+export { NativeOAuthClient } from './native-client'

package/src/native-client.ts

@@ -0,0 +1,159 @@
+import { authorize, refresh, revoke, type AuthConfiguration, type AuthorizeResult } from 'react-native-app-auth'
+import type { OAuthClient, OAuthConfig, OAuthResult, OAuthTokens, StorageAdapter } from './types'
+
+export class NativeOAuthClient implements OAuthClient {
+  private config: OAuthConfig
+  private storage: StorageAdapter
+  private storageKey: string
+  private authConfig: AuthConfiguration
+
+  constructor(config: OAuthConfig, storage: StorageAdapter) {
+    this.config = config
+    this.storage = storage
+    this.storageKey = `oauth_tokens_${config.clientId}`
+    
+    this.authConfig = {
+      issuer: config.issuer,
+      clientId: config.clientId,
+      redirectUrl: config.redirectUrl,
+      scopes: config.scopes || [],
+      additionalParameters: config.additionalParameters || {},
+      customHeaders: config.customHeaders || {},
+      usesPkce: true,
+      usesStateParam: true,
+      
+      // Optional endpoint overrides
+      ...(config.authorizationEndpoint && { 
+        authorizationEndpoint: config.authorizationEndpoint 
+      }),
+      ...(config.tokenEndpoint && { 
+        tokenEndpoint: config.tokenEndpoint 
+      }),
+      ...(config.revocationEndpoint && { 
+        revocationEndpoint: config.revocationEndpoint 
+      }),
+      ...(config.endSessionEndpoint && { 
+        endSessionEndpoint: config.endSessionEndpoint 
+      }),
+    }
+  }
+
+  async authorize(): Promise<OAuthResult> {
+    try {
+      const result: AuthorizeResult = await authorize(this.authConfig)
+      
+      const tokens: OAuthTokens = {
+        accessToken: result.accessToken,
+        refreshToken: result.refreshToken,
+        idToken: result.idToken,
+        tokenType: result.tokenType || 'Bearer',
+        expiresAt: result.accessTokenExpirationDate 
+          ? new Date(result.accessTokenExpirationDate) 
+          : undefined,
+        scopes: result.scopes,
+      }
+
+      await this.storeTokens(tokens)
+
+      return { 
+        tokens,
+        user: result.additionalParameters 
+      }
+    } catch (error: any) {
+      throw new Error(`Authorization failed: ${error.message || error}`)
+    }
+  }
+
+  async refresh(refreshToken: string): Promise<OAuthResult> {
+    try {
+      const result = await refresh(this.authConfig, {
+        refreshToken,
+      })
+
+      const tokens: OAuthTokens = {
+        accessToken: result.accessToken,
+        refreshToken: result.refreshToken || refreshToken, // Keep original if not returned
+        idToken: result.idToken,
+        tokenType: result.tokenType || 'Bearer',
+        expiresAt: result.accessTokenExpirationDate 
+          ? new Date(result.accessTokenExpirationDate)
+          : undefined,
+        scopes: result.scopes,
+      }
+
+      await this.storeTokens(tokens)
+
+      return { 
+        tokens,
+        user: result.additionalParameters 
+      }
+    } catch (error: any) {
+      throw new Error(`Token refresh failed: ${error.message || error}`)
+    }
+  }
+
+  async revoke(token: string): Promise<void> {
+    try {
+      await revoke(this.authConfig, {
+        tokenToRevoke: token,
+        sendClientId: true,
+      })
+    } catch (error: any) {
+      // Some providers return errors for already revoked tokens
+      // Don't throw unless it's a network error
+      if (error.message?.includes('network') || error.message?.includes('connection')) {
+        throw new Error(`Token revocation failed: ${error.message || error}`)
+      }
+    }
+  }
+
+  async logout(): Promise<void> {
+    const tokens = await this.getStoredTokens()
+    
+    // Revoke tokens if available
+    if (tokens?.accessToken) {
+      try {
+        await this.revoke(tokens.accessToken)
+      } catch (error) {
+        console.warn('Failed to revoke access token:', error)
+      }
+    }
+
+    if (tokens?.refreshToken) {
+      try {
+        await this.revoke(tokens.refreshToken)
+      } catch (error) {
+        console.warn('Failed to revoke refresh token:', error)
+      }
+    }
+
+    await this.clearStoredTokens()
+  }
+
+  async getStoredTokens(): Promise<OAuthTokens | null> {
+    const stored = await this.storage.getItem(this.storageKey)
+    if (!stored) return null
+
+    try {
+      const tokens = JSON.parse(stored)
+      return {
+        ...tokens,
+        expiresAt: tokens.expiresAt ? new Date(tokens.expiresAt) : undefined,
+      }
+    } catch {
+      return null
+    }
+  }
+
+  async clearStoredTokens(): Promise<void> {
+    await this.storage.removeItem(this.storageKey)
+  }
+
+  private async storeTokens(tokens: OAuthTokens): Promise<void> {
+    const serializable = {
+      ...tokens,
+      expiresAt: tokens.expiresAt?.toISOString(),
+    }
+    await this.storage.setItem(this.storageKey, JSON.stringify(serializable))
+  }
+}

package/src/storage.ts

@@ -0,0 +1,60 @@
+import type { StorageAdapter } from './types'
+
+export class WebStorage implements StorageAdapter {
+  async getItem(key: string): Promise<string | null> {
+    if (typeof localStorage === 'undefined') {
+      return null
+    }
+    return localStorage.getItem(key)
+  }
+
+  async setItem(key: string, value: string): Promise<void> {
+    if (typeof localStorage === 'undefined') {
+      return
+    }
+    localStorage.setItem(key, value)
+  }
+
+  async removeItem(key: string): Promise<void> {
+    if (typeof localStorage === 'undefined') {
+      return
+    }
+    localStorage.removeItem(key)
+  }
+}
+
+export class ReactNativeStorage implements StorageAdapter {
+  private AsyncStorage: any
+
+  constructor() {
+    try {
+      this.AsyncStorage = require('@react-native-async-storage/async-storage').default
+    } catch {
+      throw new Error(
+        'AsyncStorage is required for React Native. Please install @react-native-async-storage/async-storage'
+      )
+    }
+  }
+
+  async getItem(key: string): Promise<string | null> {
+    return await this.AsyncStorage.getItem(key)
+  }
+
+  async setItem(key: string, value: string): Promise<void> {
+    await this.AsyncStorage.setItem(key, value)
+  }
+
+  async removeItem(key: string): Promise<void> {
+    await this.AsyncStorage.removeItem(key)
+  }
+}
+
+export function createDefaultStorage(): StorageAdapter {
+  // Check if we're in React Native environment
+  if (typeof navigator !== 'undefined' && navigator.product === 'ReactNative') {
+    return new ReactNativeStorage()
+  }
+  
+  // Default to web storage
+  return new WebStorage()
+}

package/src/types.ts

@@ -0,0 +1,47 @@
+export interface OAuthConfig {
+  clientId: string
+  redirectUrl: string
+  additionalParameters?: Record<string, string>
+  customHeaders?: Record<string, string>
+  scopes?: string[]
+  
+  // Provider endpoints
+  issuer: string
+  authorizationEndpoint?: string
+  tokenEndpoint?: string
+  revocationEndpoint?: string
+  endSessionEndpoint?: string
+  
+  // Mobile-specific  
+  androidPackageName?: string
+  iosUrlScheme?: string
+}
+
+export interface OAuthTokens {
+  accessToken: string
+  refreshToken?: string
+  idToken?: string
+  tokenType?: string
+  expiresAt?: Date
+  scopes?: string[]
+}
+
+export interface OAuthResult {
+  tokens: OAuthTokens
+  user?: any
+}
+
+export interface OAuthClient {
+  authorize(): Promise<OAuthResult>
+  refresh(refreshToken: string): Promise<OAuthResult>
+  revoke(token: string): Promise<void>
+  logout(): Promise<void>
+  getStoredTokens(): Promise<OAuthTokens | null>
+  clearStoredTokens(): Promise<void>
+}
+
+export interface StorageAdapter {
+  getItem(key: string): Promise<string | null>
+  setItem(key: string, value: string): Promise<void>
+  removeItem(key: string): Promise<void>
+}

package/src/web-client.ts

@@ -0,0 +1,272 @@
+import type { OAuthClient, OAuthConfig, OAuthResult, OAuthTokens, StorageAdapter } from './types'
+
+export class WebOAuthClient implements OAuthClient {
+  private config: OAuthConfig
+  private storage: StorageAdapter
+  private storageKey: string
+
+  constructor(config: OAuthConfig, storage: StorageAdapter) {
+    this.config = config
+    this.storage = storage
+    this.storageKey = `oauth_tokens_${config.clientId}`
+  }
+
+  async authorize(): Promise<OAuthResult> {
+    const codeVerifier = this.generateCodeVerifier()
+    const codeChallenge = await this.generateCodeChallenge(codeVerifier)
+    const state = this.generateState()
+
+    // Store PKCE values for later use
+    sessionStorage.setItem('oauth_code_verifier', codeVerifier)
+    sessionStorage.setItem('oauth_state', state)
+
+    const authUrl = this.buildAuthUrl(codeChallenge, state)
+
+    // Check if we're already in a redirect callback
+    const urlParams = new URLSearchParams(window.location.search)
+    const code = urlParams.get('code')
+    const returnedState = urlParams.get('state')
+    const error = urlParams.get('error')
+
+    if (error) {
+      throw new Error(`OAuth error: ${error}`)
+    }
+
+    if (code && returnedState) {
+      // Validate state
+      const storedState = sessionStorage.getItem('oauth_state')
+      if (storedState !== returnedState) {
+        throw new Error('Invalid state parameter')
+      }
+
+      // Exchange code for tokens
+      const tokens = await this.exchangeCodeForTokens(code, codeVerifier)
+      await this.storeTokens(tokens)
+
+      // Clean up URL
+      window.history.replaceState({}, document.title, window.location.pathname)
+
+      return { tokens }
+    }
+
+    // Redirect to authorization server
+    window.location.href = authUrl
+    
+    // This won't be reached due to redirect, but TypeScript needs it
+    throw new Error('Authorization flow initiated')
+  }
+
+  async refresh(refreshToken: string): Promise<OAuthResult> {
+    const tokenEndpoint = this.config.tokenEndpoint || `${this.config.issuer}/token`
+    
+    const body = new URLSearchParams({
+      grant_type: 'refresh_token',
+      refresh_token: refreshToken,
+      client_id: this.config.clientId,
+    })
+
+    // Note: Client secrets should NEVER be in client-side code
+    // This is for public clients only (PKCE provides security)
+
+    const response = await fetch(tokenEndpoint, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/x-www-form-urlencoded',
+        ...this.config.customHeaders,
+      },
+      body: body.toString(),
+    })
+
+    if (!response.ok) {
+      throw new Error(`Token refresh failed: ${response.statusText}`)
+    }
+
+    const data = await response.json()
+    const tokens = this.parseTokenResponse(data)
+    await this.storeTokens(tokens)
+
+    return { tokens }
+  }
+
+  async revoke(token: string): Promise<void> {
+    const revokeEndpoint = this.config.revocationEndpoint || `${this.config.issuer}/revoke`
+    
+    const body = new URLSearchParams({
+      token,
+      client_id: this.config.clientId,
+    })
+
+    // Note: Client secrets should NEVER be in client-side code
+    // Using public client flow only
+
+    const response = await fetch(revokeEndpoint, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/x-www-form-urlencoded',
+        ...this.config.customHeaders,
+      },
+      body: body.toString(),
+    })
+
+    if (!response.ok && response.status !== 404) {
+      throw new Error(`Token revocation failed: ${response.statusText}`)
+    }
+  }
+
+  async logout(): Promise<void> {
+    const tokens = await this.getStoredTokens()
+    
+    if (tokens?.accessToken) {
+      try {
+        await this.revoke(tokens.accessToken)
+      } catch (error) {
+        console.warn('Failed to revoke access token:', error)
+      }
+    }
+
+    if (tokens?.refreshToken) {
+      try {
+        await this.revoke(tokens.refreshToken)
+      } catch (error) {
+        console.warn('Failed to revoke refresh token:', error)
+      }
+    }
+
+    await this.clearStoredTokens()
+
+    // Redirect to end session endpoint if available
+    if (this.config.endSessionEndpoint && tokens?.idToken) {
+      const endSessionUrl = new URL(this.config.endSessionEndpoint)
+      endSessionUrl.searchParams.set('id_token_hint', tokens.idToken)
+      endSessionUrl.searchParams.set('post_logout_redirect_uri', this.config.redirectUrl)
+      window.location.href = endSessionUrl.toString()
+    }
+  }
+
+  async getStoredTokens(): Promise<OAuthTokens | null> {
+    const stored = await this.storage.getItem(this.storageKey)
+    if (!stored) return null
+
+    try {
+      const tokens = JSON.parse(stored)
+      return {
+        ...tokens,
+        expiresAt: tokens.expiresAt ? new Date(tokens.expiresAt) : undefined,
+      }
+    } catch {
+      return null
+    }
+  }
+
+  async clearStoredTokens(): Promise<void> {
+    await this.storage.removeItem(this.storageKey)
+  }
+
+  private async storeTokens(tokens: OAuthTokens): Promise<void> {
+    const serializable = {
+      ...tokens,
+      expiresAt: tokens.expiresAt?.toISOString(),
+    }
+    await this.storage.setItem(this.storageKey, JSON.stringify(serializable))
+  }
+
+  private buildAuthUrl(codeChallenge: string, state: string): string {
+    const authEndpoint = this.config.authorizationEndpoint || `${this.config.issuer}/auth`
+    const url = new URL(authEndpoint)
+
+    url.searchParams.set('response_type', 'code')
+    url.searchParams.set('client_id', this.config.clientId)
+    url.searchParams.set('redirect_uri', this.config.redirectUrl)
+    url.searchParams.set('code_challenge', codeChallenge)
+    url.searchParams.set('code_challenge_method', 'S256')
+    url.searchParams.set('state', state)
+
+    if (this.config.scopes?.length) {
+      url.searchParams.set('scope', this.config.scopes.join(' '))
+    }
+
+    // Add additional parameters
+    if (this.config.additionalParameters) {
+      Object.entries(this.config.additionalParameters).forEach(([key, value]) => {
+        url.searchParams.set(key, value)
+      })
+    }
+
+    return url.toString()
+  }
+
+  private async exchangeCodeForTokens(code: string, codeVerifier: string): Promise<OAuthTokens> {
+    const tokenEndpoint = this.config.tokenEndpoint || `${this.config.issuer}/token`
+    
+    const body = new URLSearchParams({
+      grant_type: 'authorization_code',
+      code,
+      redirect_uri: this.config.redirectUrl,
+      client_id: this.config.clientId,
+      code_verifier: codeVerifier,
+    })
+
+    // Note: Client secrets should NEVER be in client-side code
+    // PKCE provides security for public clients
+
+    const response = await fetch(tokenEndpoint, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/x-www-form-urlencoded',
+        ...this.config.customHeaders,
+      },
+      body: body.toString(),
+    })
+
+    if (!response.ok) {
+      const errorData = await response.text()
+      throw new Error(`Token exchange failed: ${response.statusText} - ${errorData}`)
+    }
+
+    const data = await response.json()
+    return this.parseTokenResponse(data)
+  }
+
+  private parseTokenResponse(data: any): OAuthTokens {
+    const expiresAt = data.expires_in 
+      ? new Date(Date.now() + data.expires_in * 1000)
+      : undefined
+
+    return {
+      accessToken: data.access_token,
+      refreshToken: data.refresh_token,
+      idToken: data.id_token,
+      tokenType: data.token_type || 'Bearer',
+      expiresAt,
+      scopes: data.scope ? data.scope.split(' ') : undefined,
+    }
+  }
+
+  private generateCodeVerifier(): string {
+    const array = new Uint8Array(32)
+    crypto.getRandomValues(array)
+    return btoa(String.fromCharCode.apply(null, Array.from(array)))
+      .replace(/\+/g, '-')
+      .replace(/\//g, '_')
+      .replace(/=/g, '')
+  }
+
+  private async generateCodeChallenge(verifier: string): Promise<string> {
+    const encoder = new TextEncoder()
+    const data = encoder.encode(verifier)
+    const digest = await crypto.subtle.digest('SHA-256', data)
+    return btoa(String.fromCharCode.apply(null, Array.from(new Uint8Array(digest))))
+      .replace(/\+/g, '-')
+      .replace(/\//g, '_')
+      .replace(/=/g, '')
+  }
+
+  private generateState(): string {
+    const array = new Uint8Array(16)
+    crypto.getRandomValues(array)
+    return btoa(String.fromCharCode.apply(null, Array.from(array)))
+      .replace(/\+/g, '-')
+      .replace(/\//g, '_')
+      .replace(/=/g, '')
+  }
+}