@flink-app/oauth-plugin 0.12.1-alpha.33

package/examples/api-client-auth.ts

@@ -0,0 +1,550 @@
+/**
+ * API Client Integration with response_type=json
+ *
+ * This example demonstrates:
+ * - Using OAuth plugin with mobile apps and SPAs
+ * - response_type=json for JSON responses instead of redirects
+ * - Handling OAuth flow in API clients
+ * - Storing and using JWT tokens in mobile/SPA context
+ */
+
+import { FlinkApp } from "@flink-app/flink";
+import { jwtAuthPlugin } from "@flink-app/jwt-auth-plugin";
+import { oauthPlugin } from "@flink-app/oauth-plugin";
+import { FlinkContext, FlinkRepo } from "@flink-app/flink";
+
+interface User {
+    _id?: string;
+    email: string;
+    name?: string;
+    avatarUrl?: string;
+    oauthProviders: Array<{
+        provider: "github" | "google";
+        providerId: string;
+    }>;
+    roles: string[];
+    createdAt: Date;
+    updatedAt: Date;
+}
+
+class UserRepo extends FlinkRepo<AppContext, User> {
+    async findByEmail(email: string) {
+        return this.getOne({ email });
+    }
+}
+
+interface AppContext extends FlinkContext {
+    repos: {
+        userRepo: UserRepo;
+    };
+    plugins: {
+        jwtAuth: any;
+        oauth: any;
+    };
+}
+
+async function start() {
+    const app = new FlinkApp<AppContext>({
+        name: "OAuth API Client Example",
+        port: 3336,
+
+        db: {
+            uri: process.env.MONGODB_URI || "mongodb://localhost:27017/oauth-api-client-example",
+        },
+
+        auth: jwtAuthPlugin({
+            secret: process.env.JWT_SECRET || "your-super-secret-jwt-key",
+            getUser: async (tokenData) => {
+                const user = await app.ctx.repos.userRepo.getById(tokenData.userId);
+                if (!user) throw new Error("User not found");
+                return {
+                    id: user._id,
+                    email: user.email,
+                    roles: user.roles,
+                };
+            },
+            rolePermissions: {
+                user: ["read:own", "write:own"],
+            },
+            expiresIn: "30d", // Longer expiration for mobile apps
+        }),
+
+        plugins: [
+            oauthPlugin({
+                providers: {
+                    github: {
+                        clientId: process.env.GITHUB_CLIENT_ID!,
+                        clientSecret: process.env.GITHUB_CLIENT_SECRET!,
+                        callbackUrl: process.env.GITHUB_CALLBACK_URL || "http://localhost:3336/oauth/github/callback",
+                    },
+                    google: {
+                        clientId: process.env.GOOGLE_CLIENT_ID!,
+                        clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
+                        callbackUrl: process.env.GOOGLE_CALLBACK_URL || "http://localhost:3336/oauth/google/callback",
+                    },
+                },
+
+                storeTokens: false,
+
+                onAuthSuccess: async ({ profile, provider }, ctx) => {
+                    console.log(`\nAPI Client OAuth Success: ${provider} - ${profile.email}`);
+
+                    let user = await ctx.repos.userRepo.findByEmail(profile.email);
+
+                    if (!user) {
+                        user = await ctx.repos.userRepo.create({
+                            email: profile.email,
+                            name: profile.name,
+                            avatarUrl: profile.avatarUrl,
+                            oauthProviders: [{ provider, providerId: profile.id }],
+                            roles: ["user"],
+                            createdAt: new Date(),
+                            updatedAt: new Date(),
+                        });
+                    }
+
+                    const token = await ctx.plugins.jwtAuth.createToken({ userId: user._id, email: user.email }, user.roles);
+
+                    console.log(`JWT token generated for API client`);
+                    console.log(`Token will be returned as JSON (not redirect)`);
+
+                    return {
+                        user: {
+                            _id: user._id,
+                            email: user.email,
+                            name: user.name,
+                            avatarUrl: user.avatarUrl,
+                            roles: user.roles,
+                        },
+                        token,
+                        // redirectUrl is ignored when response_type=json
+                        redirectUrl: "/dashboard",
+                    };
+                },
+
+                onAuthError: async ({ error, provider }) => {
+                    console.error(`OAuth error for ${provider}:`, error);
+                    return {
+                        redirectUrl: `/login?error=${error.code}`,
+                    };
+                },
+            }),
+        ],
+
+        // IMPORTANT: Configure CORS for API clients
+        cors: {
+            origin: [
+                "http://localhost:3000", // React/Vue dev server
+                "http://localhost:19006", // Expo dev server
+                "capacitor://localhost", // Capacitor iOS/Android
+                "ionic://localhost", // Ionic
+                /\.myapp\.com$/, // Production domains
+            ],
+            credentials: true,
+            allowedHeaders: ["Authorization", "Content-Type"],
+        },
+    });
+
+    await app.start();
+
+    console.log("\n===========================================");
+    console.log("OAuth API Client Integration Example");
+    console.log("===========================================");
+    console.log(`Server: http://localhost:3336`);
+    console.log(`\nKey Feature: response_type=json`);
+    console.log(`  Add ?response_type=json to callback URL for JSON response`);
+    console.log(`  Perfect for mobile apps, SPAs, and API clients`);
+    console.log(`\nExample URLs:`);
+    console.log(`  Initiate: http://localhost:3336/oauth/github/initiate`);
+    console.log(`  Callback: http://localhost:3336/oauth/github/callback?code=xxx&state=yyy&response_type=json`);
+    console.log("===========================================\n");
+}
+
+start().catch((error) => {
+    console.error("Failed to start application:", error);
+    process.exit(1);
+});
+
+/**
+ * CLIENT INTEGRATION EXAMPLES
+ */
+
+/**
+ * Example 1: React SPA with Popup Window
+ */
+
+const ReactSPAExample = `
+import React, { useState } from 'react';
+
+function OAuthLogin() {
+  const [loading, setLoading] = useState(false);
+
+  const handleGitHubLogin = async () => {
+    setLoading(true);
+
+    // Open OAuth flow in popup window
+    const width = 600;
+    const height = 700;
+    const left = window.screen.width / 2 - width / 2;
+    const top = window.screen.height / 2 - height / 2;
+
+    const popup = window.open(
+      'http://localhost:3336/oauth/github/initiate',
+      'oauth_popup',
+      \`width=\${width},height=\${height},left=\${left},top=\${top}\`
+    );
+
+    // Listen for message from popup
+    window.addEventListener('message', async (event) => {
+      if (event.origin !== 'http://localhost:3336') return;
+
+      const { code, state } = event.data;
+
+      // Exchange code for token using response_type=json
+      const response = await fetch(
+        \`http://localhost:3336/oauth/github/callback?code=\${code}&state=\${state}&response_type=json\`,
+        {
+          credentials: 'include'
+        }
+      );
+
+      const data = await response.json();
+
+      if (data.token) {
+        // Store JWT token
+        localStorage.setItem('jwt_token', data.token);
+
+        // Store user data
+        localStorage.setItem('user', JSON.stringify(data.user));
+
+        // Close popup
+        popup?.close();
+
+        // Redirect to dashboard
+        window.location.href = '/dashboard';
+      }
+
+      setLoading(false);
+    });
+  };
+
+  return (
+    <div>
+      <button onClick={handleGitHubLogin} disabled={loading}>
+        {loading ? 'Logging in...' : 'Login with GitHub'}
+      </button>
+    </div>
+  );
+}
+`;
+
+/**
+ * Example 2: React Native with expo-auth-session
+ */
+
+const ReactNativeExample = `
+import React from 'react';
+import { Button, View, Text } from 'react-native';
+import * as WebBrowser from 'expo-web-browser';
+import * as AuthSession from 'expo-auth-session';
+import AsyncStorage from '@react-native-async-storage/async-storage';
+
+// Tell expo-auth-session to finish the session
+WebBrowser.maybeCompleteAuthSession();
+
+function OAuthLogin() {
+  const [user, setUser] = React.useState(null);
+
+  // Configure OAuth discovery
+  const discovery = {
+    authorizationEndpoint: 'http://localhost:3336/oauth/github/initiate',
+  };
+
+  // Create auth request
+  const [request, response, promptAsync] = AuthSession.useAuthRequest(
+    {
+      clientId: 'not-used-for-our-flow',
+      redirectUri: AuthSession.makeRedirectUri({
+        native: 'myapp://oauth/callback',
+      }),
+    },
+    discovery
+  );
+
+  React.useEffect(() => {
+    if (response?.type === 'success') {
+      const { code, state } = response.params;
+
+      // Exchange code for token with response_type=json
+      fetch(
+        \`http://localhost:3336/oauth/github/callback?code=\${code}&state=\${state}&response_type=json\`
+      )
+        .then(res => res.json())
+        .then(async (data) => {
+          // Store JWT token securely
+          await AsyncStorage.setItem('jwt_token', data.token);
+
+          // Store user data
+          await AsyncStorage.setItem('user', JSON.stringify(data.user));
+
+          setUser(data.user);
+        })
+        .catch(console.error);
+    }
+  }, [response]);
+
+  const handleLogin = () => {
+    promptAsync();
+  };
+
+  if (user) {
+    return (
+      <View>
+        <Text>Welcome, {user.name}!</Text>
+        <Text>Email: {user.email}</Text>
+      </View>
+    );
+  }
+
+  return (
+    <View>
+      <Button
+        title="Login with GitHub"
+        onPress={handleLogin}
+        disabled={!request}
+      />
+    </View>
+  );
+}
+`;
+
+/**
+ * Example 3: Mobile App with In-App Browser
+ */
+
+const MobileInAppBrowserExample = `
+import { InAppBrowser } from 'react-native-inappbrowser-reborn';
+import AsyncStorage from '@react-native-async-storage/async-storage';
+
+async function loginWithGitHub() {
+  try {
+    // Check if InAppBrowser is available
+    if (await InAppBrowser.isAvailable()) {
+      // Open OAuth URL in in-app browser
+      const result = await InAppBrowser.openAuth(
+        'http://localhost:3336/oauth/github/initiate',
+        'myapp://oauth/callback',
+        {
+          // iOS options
+          ephemeralWebSession: false,
+          // Android options
+          showTitle: false,
+          enableUrlBarHiding: true,
+          enableDefaultShare: false,
+        }
+      );
+
+      if (result.type === 'success') {
+        const url = new URL(result.url);
+        const code = url.searchParams.get('code');
+        const state = url.searchParams.get('state');
+
+        // Exchange code for token with response_type=json
+        const response = await fetch(
+          \`http://localhost:3336/oauth/github/callback?code=\${code}&state=\${state}&response_type=json\`
+        );
+
+        const data = await response.json();
+
+        // Store JWT token securely
+        await AsyncStorage.setItem('jwt_token', data.token);
+        await AsyncStorage.setItem('user', JSON.stringify(data.user));
+
+        return data;
+      }
+    }
+  } catch (error) {
+    console.error('OAuth error:', error);
+  }
+}
+
+// Usage in component
+const LoginScreen = () => {
+  const handleLogin = async () => {
+    const result = await loginWithGitHub();
+    if (result) {
+      // Navigate to home screen
+      navigation.navigate('Home');
+    }
+  };
+
+  return <Button title="Login with GitHub" onPress={handleLogin} />;
+};
+`;
+
+/**
+ * Example 4: Vue.js SPA
+ */
+
+const VueJSExample = `
+<template>
+  <div>
+    <button @click="loginWithGitHub" :disabled="loading">
+      {{ loading ? 'Logging in...' : 'Login with GitHub' }}
+    </button>
+  </div>
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      loading: false,
+    };
+  },
+  methods: {
+    async loginWithGitHub() {
+      this.loading = true;
+
+      // Open OAuth in popup
+      const popup = window.open(
+        'http://localhost:3336/oauth/github/initiate',
+        'oauth_popup',
+        'width=600,height=700'
+      );
+
+      // Poll for popup to close or message
+      const checkPopup = setInterval(async () => {
+        try {
+          if (popup.closed) {
+            clearInterval(checkPopup);
+            this.loading = false;
+            return;
+          }
+
+          // Check if popup has navigated to callback URL
+          const popupUrl = popup.location.href;
+          if (popupUrl.includes('/oauth/github/callback')) {
+            const url = new URL(popupUrl);
+            const code = url.searchParams.get('code');
+            const state = url.searchParams.get('state');
+
+            if (code && state) {
+              // Exchange for token with response_type=json
+              const response = await fetch(
+                \`http://localhost:3336/oauth/github/callback?code=\${code}&state=\${state}&response_type=json\`,
+                { credentials: 'include' }
+              );
+
+              const data = await response.json();
+
+              // Store JWT token
+              localStorage.setItem('jwt_token', data.token);
+              localStorage.setItem('user', JSON.stringify(data.user));
+
+              // Close popup
+              popup.close();
+              clearInterval(checkPopup);
+
+              // Redirect
+              this.$router.push('/dashboard');
+            }
+          }
+        } catch (e) {
+          // Cross-origin error - popup hasn't navigated yet
+        }
+      }, 500);
+    },
+  },
+};
+</script>
+`;
+
+/**
+ * Example 5: Using JWT Token for API Requests
+ */
+
+const UsingJWTTokenExample = `
+// After OAuth login, use JWT token for authenticated requests
+
+// Get stored token
+const token = localStorage.getItem('jwt_token');
+// or for React Native
+const token = await AsyncStorage.getItem('jwt_token');
+
+// Make authenticated request
+const response = await fetch('http://localhost:3336/api/profile', {
+  headers: {
+    'Authorization': \`Bearer \${token}\`,
+    'Content-Type': 'application/json'
+  }
+});
+
+const userData = await response.json();
+
+// Token refresh logic (if needed)
+if (response.status === 401) {
+  // Token expired - redirect to login
+  localStorage.removeItem('jwt_token');
+  window.location.href = '/login';
+}
+`;
+
+/**
+ * IMPORTANT NOTES
+ *
+ * Response Type Formats:
+ *
+ * 1. response_type=json (for API clients):
+ *    GET /oauth/github/callback?code=xxx&state=yyy&response_type=json
+ *
+ *    Response:
+ *    {
+ *      "user": { "_id": "...", "email": "...", ... },
+ *      "token": "eyJhbGc..."
+ *    }
+ *
+ * 2. Default (redirect with token in query):
+ *    GET /oauth/github/callback?code=xxx&state=yyy
+ *
+ *    Redirects to:
+ *    /dashboard?token=eyJhbGc...
+ *
+ * 3. URL fragment (if configured):
+ *    Redirects to:
+ *    /dashboard#token=eyJhbGc...
+ *
+ * Best Practices for API Clients:
+ *
+ * 1. Always use response_type=json for mobile apps and SPAs
+ * 2. Store JWT tokens in secure storage:
+ *    - Mobile: AsyncStorage, Keychain, SecureStore
+ *    - Web: localStorage (or sessionStorage for extra security)
+ * 3. Use HTTPS in production
+ * 4. Implement token refresh mechanism
+ * 5. Clear tokens on logout
+ * 6. Validate tokens on app startup
+ * 7. Handle token expiration gracefully
+ *
+ * Security Considerations:
+ *
+ * 1. NEVER store tokens in URL for long-term
+ * 2. Use HTTPS for all OAuth callbacks in production
+ * 3. Implement CORS properly for API clients
+ * 4. Validate redirect URIs on server
+ * 5. Use state parameter for CSRF protection
+ * 6. Implement rate limiting on OAuth endpoints
+ * 7. Log all OAuth attempts for security monitoring
+ */
+
+console.log("\n=== Client Integration Code Examples ===\n");
+console.log("1. React SPA with Popup:");
+console.log(ReactSPAExample);
+console.log("\n2. React Native with expo-auth-session:");
+console.log(ReactNativeExample);
+console.log("\n3. Mobile In-App Browser:");
+console.log(MobileInAppBrowserExample);
+console.log("\n4. Vue.js SPA:");
+console.log(VueJSExample);
+console.log("\n5. Using JWT Token:");
+console.log(UsingJWTTokenExample);