@elevasis/core 0.1.0

package/src/integrations/oauth/api-schemas.ts

@@ -0,0 +1,92 @@
+/**
+ * OAuth Domain - Zod Validation Schemas
+ *
+ * Validation schemas for OAuth flow endpoints.
+ * Includes path params and query params for authorize/callback flows.
+ *
+ * Security:
+ * - All schemas use .strict() to prevent mass assignment attacks
+ * - Provider enum validation prevents invalid providers
+ * - OAuth code and state length limits prevent DoS
+ * - organizationId validation prevents injection
+ * - CSRF protection via state parameter validation
+ */
+
+import { z } from 'zod'
+import { OAuthProviderSchema, OAuthCodeSchema, OAuthStateParamSchema, CredentialNameSchema } from '../../platform/utils/validation'
+
+// ============================================================================
+// Path Parameters
+// ============================================================================
+
+/**
+ * Validate OAuth provider in URL path
+ * Used by: GET /oauth/authorize/:provider, GET /oauth/callback/:provider
+ *
+ * Security: Enum validation prevents bypass attacks with invalid providers
+ */
+export const OAuthProviderParamSchema = z
+  .object({
+    provider: OAuthProviderSchema
+  })
+  .strict()
+
+// ============================================================================
+// Query Parameters - Authorize Flow
+// ============================================================================
+
+/**
+ * OAuth authorize endpoint query parameters
+ * GET /oauth/authorize/:provider?credentialName=...&organizationId=...
+ *
+ * Security:
+ * - credentialName validated (alphanumeric + hyphens/underscores)
+ * - organizationId required (public endpoint, can't use JWT)
+ * - organizationId validated (string format for WorkOS/UUID)
+ */
+export const AuthorizeQuerySchema = z
+  .object({
+    credentialName: CredentialNameSchema,
+    organizationId: z.string().min(1) // WorkOS org IDs or UUIDs
+  })
+  .strict()
+
+// ============================================================================
+// Query Parameters - Callback Flow
+// ============================================================================
+
+/**
+ * OAuth callback endpoint query parameters
+ * GET /oauth/callback/:provider?code=...&state=...&error=...
+ *
+ * Security:
+ * - code length limited (10-1000 chars)
+ * - state parameter validated (Base64-encoded JSON, max 2KB)
+ * - error optional (provider-specific error codes)
+ *
+ * CSRF Protection:
+ * - State parameter contains organizationId and credentialName
+ * - State validated to ensure request originated from our authorize endpoint
+ */
+export const CallbackQuerySchema = z
+  .object({
+    code: OAuthCodeSchema.optional(),
+    state: OAuthStateParamSchema.optional(),
+    error: z.string().max(100).optional() // OAuth error codes (access_denied, etc.)
+  })
+  .passthrough() // OAuth2 spec: "client MUST ignore unrecognized response parameters"
+  .refine(
+    (data) => data.code || data.error,
+    {
+      message: 'Either code or error parameter must be provided'
+    }
+  )
+
+// ============================================================================
+// TypeScript Type Exports
+// ============================================================================
+
+// Export inferred types for use in route handlers
+export type OAuthProviderParam = z.infer<typeof OAuthProviderParamSchema>
+export type AuthorizeQuery = z.infer<typeof AuthorizeQuerySchema>
+export type CallbackQuery = z.infer<typeof CallbackQuerySchema>

package/src/integrations/oauth/index.ts

@@ -0,0 +1,19 @@
+/**
+ * OAuth Integration Exports
+ *
+ * Browser-safe exports (types and provider registry)
+ * Server-only exports (refresh functions with process.env) in ./server.ts
+ */
+
+export * from './types'
+export * from './provider-registry'
+
+// Validation schemas
+export {
+  OAuthProviderParamSchema,
+  AuthorizeQuerySchema,
+  CallbackQuerySchema,
+  type OAuthProviderParam,
+  type AuthorizeQuery,
+  type CallbackQuery
+} from './api-schemas'

package/src/integrations/oauth/provider-registry.ts

@@ -0,0 +1,61 @@
+import type { OAuthProviderConfig } from './types'
+
+/**
+ * OAuth Provider Registry
+ *
+ * Add new integration = add config object here (no new code needed)
+ *
+ * Standard token exchange methods:
+ * - basic-auth: client_id:client_secret in Authorization header
+ * - form-encoded: credentials in URL-encoded body (Google)
+ * - json-body: credentials in JSON body (most providers)
+ *
+ * Custom overrides for edge cases:
+ * - customAuthFlow: Override authorization URL building
+ * - customTokenExchange: Override token exchange logic
+ */
+export const OAUTH_PROVIDERS: Record<string, OAuthProviderConfig> = {
+  'google-sheets': {
+    id: 'google-sheets',
+    name: 'Google Sheets',
+    authUrl: 'https://accounts.google.com/o/oauth2/v2/auth',
+    tokenUrl: 'https://oauth2.googleapis.com/token',
+    authParams: {
+      access_type: 'offline', // Required for refresh token
+      prompt: 'consent' // Force consent to get refresh token on reconnect
+    },
+    tokenExchange: 'form-encoded',
+    scopes: ['https://www.googleapis.com/auth/spreadsheets']
+  },
+
+  dropbox: {
+    id: 'dropbox',
+    name: 'Dropbox',
+    authUrl: 'https://www.dropbox.com/oauth2/authorize',
+    tokenUrl: 'https://api.dropboxapi.com/oauth2/token',
+    authParams: {
+      token_access_type: 'offline' // Required for refresh token
+    },
+    tokenExchange: 'form-encoded',
+    scopes: ['files.content.write', 'files.content.read', 'files.metadata.write']
+  }
+}
+
+/**
+ * Get provider config by ID
+ * @throws Error if provider not found
+ */
+export function getProviderConfig(providerId: string): OAuthProviderConfig {
+  const config = OAUTH_PROVIDERS[providerId]
+  if (!config) {
+    throw new Error(`Unknown OAuth provider: ${providerId}`)
+  }
+  return config
+}
+
+/**
+ * List all available providers (for frontend)
+ */
+export function listProviders(): OAuthProviderConfig[] {
+  return Object.values(OAUTH_PROVIDERS)
+}

package/src/integrations/oauth/server/__tests__/refresh-concurrent.test.ts

@@ -0,0 +1,183 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { refreshOAuthTokenIfExpired, forceRefreshOAuthToken, _getInflightRefreshCount } from '../refresh'
+import type { OAuthToken } from '../../types'
+
+describe('concurrent OAuth token refresh deduplication', () => {
+  const originalFetch = global.fetch
+
+  beforeEach(() => {
+    process.env.DROPBOX_APP_KEY = 'test-dropbox-app-key'
+    process.env.DROPBOX_APP_SECRET = 'test-dropbox-app-secret'
+    process.env.GOOGLE_OAUTH_CLIENT_ID = 'test-google-client-id'
+    process.env.GOOGLE_OAUTH_CLIENT_SECRET = 'test-google-client-secret'
+  })
+
+  afterEach(() => {
+    global.fetch = originalFetch
+    vi.restoreAllMocks()
+  })
+
+  function makeExpiredToken(overrides?: Partial<OAuthToken>): OAuthToken {
+    return {
+      provider: 'dropbox',
+      accessToken: 'expired-access-token',
+      refreshToken: 'shared-refresh-token',
+      expiresAt: new Date(Date.now() - 10 * 60 * 1000).toISOString(),
+      tokenType: 'Bearer',
+      ...overrides
+    }
+  }
+
+  it('should make only one fetch call when two concurrent refreshes use the same token', async () => {
+    let resolveRefresh!: (value: Response) => void
+    const mockFetch = vi.fn().mockReturnValue(
+      new Promise<Response>((resolve) => {
+        resolveRefresh = resolve
+      })
+    )
+    global.fetch = mockFetch
+
+    const token = makeExpiredToken()
+
+    // Fire two concurrent refreshes
+    const promise1 = refreshOAuthTokenIfExpired(token)
+    const promise2 = refreshOAuthTokenIfExpired(token)
+
+    // While in-flight, there should be exactly one tracked refresh
+    expect(_getInflightRefreshCount()).toBe(1)
+
+    // Resolve the single fetch call
+    resolveRefresh(
+      new Response(
+        JSON.stringify({
+          access_token: 'new-access-token',
+          refresh_token: 'new-refresh-token',
+          expires_in: 3600
+        }),
+        { status: 200 }
+      )
+    )
+
+    const [result1, result2] = await Promise.all([promise1, promise2])
+
+    // Both get the same result
+    expect(result1.accessToken).toBe('new-access-token')
+    expect(result2.accessToken).toBe('new-access-token')
+
+    // Only one actual API call was made
+    expect(mockFetch).toHaveBeenCalledTimes(1)
+
+    // Map is cleaned up
+    expect(_getInflightRefreshCount()).toBe(0)
+  })
+
+  it('should make separate fetch calls for different providers', async () => {
+    const mockFetch = vi.fn().mockImplementation(() =>
+      Promise.resolve(
+        new Response(
+          JSON.stringify({
+            access_token: 'new-token',
+            refresh_token: 'new-refresh',
+            expires_in: 3600
+          }),
+          { status: 200 }
+        )
+      )
+    )
+    global.fetch = mockFetch
+
+    const dropboxToken = makeExpiredToken()
+    const googleToken = makeExpiredToken({
+      provider: 'google-sheets',
+      refreshToken: 'google-refresh-token'
+    })
+
+    await Promise.all([refreshOAuthTokenIfExpired(dropboxToken), refreshOAuthTokenIfExpired(googleToken)])
+
+    // Different providers = separate API calls
+    expect(mockFetch).toHaveBeenCalledTimes(2)
+  })
+
+  it('should make separate fetch calls for different refresh tokens on the same provider', async () => {
+    const mockFetch = vi.fn().mockImplementation(() =>
+      Promise.resolve(
+        new Response(
+          JSON.stringify({
+            access_token: 'new-token',
+            refresh_token: 'new-refresh',
+            expires_in: 3600
+          }),
+          { status: 200 }
+        )
+      )
+    )
+    global.fetch = mockFetch
+
+    const token1 = makeExpiredToken({ refreshToken: 'user-a-refresh' })
+    const token2 = makeExpiredToken({ refreshToken: 'user-b-refresh' })
+
+    await Promise.all([refreshOAuthTokenIfExpired(token1), refreshOAuthTokenIfExpired(token2)])
+
+    // Different refresh tokens = different users = separate API calls
+    expect(mockFetch).toHaveBeenCalledTimes(2)
+  })
+
+  it('should propagate errors to all waiters when the refresh fails', async () => {
+    const mockFetch = vi.fn().mockResolvedValue(
+      new Response(
+        JSON.stringify({
+          error: 'invalid_grant',
+          error_description: 'Token revoked'
+        }),
+        { status: 400 }
+      )
+    )
+    global.fetch = mockFetch
+
+    const token = makeExpiredToken()
+
+    const promise1 = forceRefreshOAuthToken(token)
+    const promise2 = forceRefreshOAuthToken(token)
+
+    // Both should reject with the same error
+    await expect(promise1).rejects.toThrow('invalid_grant')
+    await expect(promise2).rejects.toThrow('invalid_grant')
+
+    // Only one API call was made
+    expect(mockFetch).toHaveBeenCalledTimes(1)
+
+    // Map is cleaned up even on failure
+    expect(_getInflightRefreshCount()).toBe(0)
+  })
+
+  it('should allow a new refresh after the previous one completes', async () => {
+    let callCount = 0
+    const mockFetch = vi.fn().mockImplementation(() => {
+      callCount++
+      return Promise.resolve(
+        new Response(
+          JSON.stringify({
+            access_token: `token-${callCount}`,
+            refresh_token: 'new-refresh',
+            expires_in: 3600
+          }),
+          { status: 200 }
+        )
+      )
+    })
+    global.fetch = mockFetch
+
+    const token = makeExpiredToken()
+
+    // First refresh
+    const result1 = await forceRefreshOAuthToken(token)
+    expect(result1.accessToken).toBe('token-1')
+
+    // Second refresh (after first completed)
+    const result2 = await forceRefreshOAuthToken(token)
+    expect(result2.accessToken).toBe('token-2')
+
+    // Two separate API calls (not deduplicated since they were sequential)
+    expect(mockFetch).toHaveBeenCalledTimes(2)
+  })
+})

package/src/integrations/oauth/server/__tests__/refresh.integration.test.ts

@@ -0,0 +1,257 @@
+import { describe, it, expect } from 'vitest'
+import { refreshOAuthTokenIfExpired } from '../refresh'
+import type { OAuthToken } from '../../types'
+
+/**
+ * Integration tests for OAuth token refresh with real provider APIs
+ *
+ * These tests use real credentials but manipulate the expiry date to force refresh.
+ * This allows testing the actual OAuth provider endpoints without waiting for token expiry.
+ *
+ * SETUP REQUIRED:
+ * 1. Ensure environment variables are set:
+ *    - NOTION_CLIENT_ID
+ *    - NOTION_CLIENT_SECRET
+ *    - GOOGLE_OAUTH_CLIENT_ID (optional)
+ *    - GOOGLE_OAUTH_CLIENT_SECRET (optional)
+ *
+ * 2. To get a real refresh token for testing:
+ *    a. Complete OAuth flow via the app (AI Studio → Settings → Credentials)
+ *    b. Retrieve the stored credential from the database
+ *    c. Decrypt and extract the refresh_token
+ *    d. Set it in the test below
+ *
+ * NOTE: These tests are skipped by default. Run with:
+ * pnpm test -- refresh.integration.test.ts
+ */
+
+describe('OAuth Token Refresh Integration Tests', () => {
+  // Skip these tests by default since they require real credentials
+  // To run: update the token below and run `pnpm test -- refresh.integration.test.ts`
+  const SKIP_INTEGRATION_TESTS = true
+
+  describe('Notion provider (basic-auth)', () => {
+    it.skipIf(SKIP_INTEGRATION_TESTS)(
+      'should refresh Notion token with real API',
+      async () => {
+        // SETUP: Replace with a real Notion refresh token
+        const realNotionToken: OAuthToken = {
+          provider: 'notion',
+          accessToken: 'expired-or-old-access-token', // Will be replaced after refresh
+          refreshToken: 'YOUR_REAL_NOTION_REFRESH_TOKEN_HERE', // <-- UPDATE THIS
+          expiresAt: new Date(Date.now() - 10 * 60 * 1000).toISOString(), // Force refresh (10 min ago)
+          tokenType: 'Bearer'
+        }
+
+        // This will make a real API call to Notion's token endpoint
+        const refreshedToken = await refreshOAuthTokenIfExpired(realNotionToken)
+
+        // Verify the refresh worked
+        expect(refreshedToken.provider).toBe('notion')
+        expect(refreshedToken.accessToken).not.toBe(realNotionToken.accessToken)
+        expect(refreshedToken.accessToken).toBeTruthy()
+        expect(refreshedToken.refreshToken).toBeTruthy()
+
+        // Verify new token will expire in the future
+        const expiresAt = new Date(refreshedToken.expiresAt).getTime()
+        const now = Date.now()
+        expect(expiresAt).toBeGreaterThan(now)
+
+        // Log result for debugging
+        console.log('✓ Notion token refreshed successfully')
+        console.log('  New access token (first 20 chars):', refreshedToken.accessToken.substring(0, 20) + '...')
+        console.log('  Expires at:', refreshedToken.expiresAt)
+        console.log('  Time until expiry:', Math.round((expiresAt - now) / 60000), 'minutes')
+      },
+      { timeout: 10000 } // 10 second timeout for API call
+    )
+
+    it.skipIf(SKIP_INTEGRATION_TESTS)(
+      'should handle Notion token that is still valid',
+      async () => {
+        // SETUP: Replace with a real Notion refresh token
+        const validNotionToken: OAuthToken = {
+          provider: 'notion',
+          accessToken: 'current-valid-access-token',
+          refreshToken: 'YOUR_REAL_NOTION_REFRESH_TOKEN_HERE', // <-- UPDATE THIS
+          expiresAt: new Date(Date.now() + 30 * 60 * 1000).toISOString(), // 30 min in future
+          tokenType: 'Bearer'
+        }
+
+        // Should return same token without API call (still valid)
+        const result = await refreshOAuthTokenIfExpired(validNotionToken)
+
+        expect(result).toBe(validNotionToken) // Same object reference
+        console.log('✓ Valid token returned unchanged (no API call made)')
+      }
+    )
+  })
+
+  describe('Google Sheets provider (form-encoded)', () => {
+    it.skipIf(SKIP_INTEGRATION_TESTS)(
+      'should refresh Google Sheets token with real API',
+      async () => {
+        // SETUP: Replace with a real Google Sheets refresh token
+        const realGoogleToken: OAuthToken = {
+          provider: 'google-sheets',
+          accessToken: 'expired-or-old-access-token',
+          refreshToken: 'YOUR_REAL_GOOGLE_REFRESH_TOKEN_HERE', // <-- UPDATE THIS
+          expiresAt: new Date(Date.now() - 10 * 60 * 1000).toISOString(), // Force refresh
+          tokenType: 'Bearer',
+          scope: 'https://www.googleapis.com/auth/spreadsheets'
+        }
+
+        const refreshedToken = await refreshOAuthTokenIfExpired(realGoogleToken)
+
+        expect(refreshedToken.provider).toBe('google-sheets')
+        expect(refreshedToken.accessToken).not.toBe(realGoogleToken.accessToken)
+        expect(refreshedToken.accessToken).toBeTruthy()
+        expect(refreshedToken.refreshToken).toBeTruthy()
+
+        // Verify scope is preserved
+        expect(refreshedToken.scope).toBe('https://www.googleapis.com/auth/spreadsheets')
+
+        console.log('✓ Google Sheets token refreshed successfully')
+        console.log('  New access token (first 20 chars):', refreshedToken.accessToken.substring(0, 20) + '...')
+        console.log('  Expires at:', refreshedToken.expiresAt)
+      },
+      { timeout: 10000 }
+    )
+  })
+
+  describe('Error scenarios with real API', () => {
+    it.skipIf(SKIP_INTEGRATION_TESTS)(
+      'should handle invalid refresh token with real Notion API',
+      async () => {
+        const tokenWithInvalidRefreshToken: OAuthToken = {
+          provider: 'notion',
+          accessToken: 'old-token',
+          refreshToken: 'completely-invalid-refresh-token-12345', // Invalid token
+          expiresAt: new Date(Date.now() - 10 * 60 * 1000).toISOString(),
+          tokenType: 'Bearer'
+        }
+
+        // Should throw error from Notion API
+        await expect(refreshOAuthTokenIfExpired(tokenWithInvalidRefreshToken)).rejects.toThrow()
+
+        console.log('✓ Invalid refresh token correctly rejected by Notion API')
+      },
+      { timeout: 10000 }
+    )
+  })
+})
+
+/**
+ * HELPER: Script to test with a credential from the database
+ *
+ * To use this with a real stored credential:
+ *
+ * 1. Get credential from database:
+ *    ```sql
+ *    SELECT * FROM credentials
+ *    WHERE name = 'notion-prod'
+ *    AND organization_id = 'your-org-id';
+ *    ```
+ *
+ * 2. Decrypt the encrypted_value using CredentialsService
+ *
+ * 3. Extract the token object
+ *
+ * 4. Manipulate the expiresAt field:
+ *    ```typescript
+ *    const token = decryptedCredential as OAuthToken
+ *    const expiredToken = {
+ *      ...token,
+ *      expiresAt: new Date(Date.now() - 10 * 60 * 1000).toISOString()
+ *    }
+ *    ```
+ *
+ * 5. Test refresh:
+ *    ```typescript
+ *    const refreshed = await refreshOAuthTokenIfExpired(expiredToken)
+ *    ```
+ *
+ * 6. Save refreshed token back to database:
+ *    ```typescript
+ *    await credentialsService.updateCredential(orgId, credentialName, refreshed)
+ *    ```
+ */
+
+describe('Real Credential Testing Pattern', () => {
+  it('demonstrates how to test with database credentials', async () => {
+    // This is a documentation test showing the pattern
+    // Not meant to run - just shows the workflow
+
+    // Step 1: Load credential from database (pseudo-code)
+    // const credential = await credentialsService.getCredential(orgId, 'notion-prod')
+    // const token = credential as OAuthToken
+
+    // Step 2: Manipulate expiry to force refresh
+    // const mockToken: OAuthToken = {
+    //   provider: 'notion',
+    //   accessToken: 'secret_abc123...', // Real token from DB
+    //   refreshToken: 'secret_refresh_xyz...', // Real refresh token from DB
+    //   expiresAt: new Date(Date.now() - 10 * 60 * 1000).toISOString(), // MANIPULATED: 10 min ago
+    //   tokenType: 'Bearer'
+    // }
+
+    // Step 3: Test refresh (would make real API call if not skipped)
+    // const refreshed = await refreshOAuthTokenIfExpired(mockToken)
+
+    // Step 4: Verify and optionally save back
+    // expect(refreshed.accessToken).not.toBe(mockToken.accessToken)
+    // await credentialsService.updateCredential(orgId, 'notion-prod', refreshed)
+
+    // This test is just documentation - always passes
+    expect(true).toBe(true)
+  })
+})
+
+/**
+ * MANUAL TESTING SCRIPT
+ *
+ * To manually test token refresh with a real credential:
+ *
+ * 1. Create a test file: packages/core/src/integrations/oauth/server/__tests__/manual-refresh-test.ts
+ *
+ * 2. Add this code:
+ *
+ * ```typescript
+ * import { refreshOAuthTokenIfExpired } from '../refresh'
+ * import type { OAuthToken } from '../../types'
+ *
+ * async function testRefresh() {
+ *   // Get a real token from your database
+ *   const realToken: OAuthToken = {
+ *     provider: 'notion',
+ *     accessToken: 'paste-real-access-token-here',
+ *     refreshToken: 'paste-real-refresh-token-here',
+ *     expiresAt: new Date(Date.now() - 10 * 60 * 1000).toISOString(), // Force refresh
+ *     tokenType: 'Bearer'
+ *   }
+ *
+ *   console.log('Original token:', {
+ *     accessToken: realToken.accessToken.substring(0, 20) + '...',
+ *     expiresAt: realToken.expiresAt
+ *   })
+ *
+ *   try {
+ *     const refreshed = await refreshOAuthTokenIfExpired(realToken)
+ *
+ *     console.log('Refreshed token:', {
+ *       accessToken: refreshed.accessToken.substring(0, 20) + '...',
+ *       expiresAt: refreshed.expiresAt,
+ *       changed: refreshed.accessToken !== realToken.accessToken
+ *     })
+ *
+ *     console.log('✓ Token refresh successful!')
+ *   } catch (error) {
+ *     console.error('✗ Token refresh failed:', error)
+ *   }
+ * }
+ *
+ * testRefresh()
+ * ```
+ *
+ * 3. Run with: pnpm tsx packages/core/src/integrations/oauth/server/__tests__/manual-refresh-test.ts
+ */