@flink-app/oauth-plugin 0.12.1-alpha.38 → 0.12.1-alpha.41

package/README.md

@@ -118,7 +118,7 @@ const app = new FlinkApp<Context>({
                 return {
                     user,
                     token,
-                    redirectUrl: "https://myapp.com/dashboard",
+                    redirectUrl: "https://myapp.com/dashboard", // Plugin will add: #token=...
                 };
             },
 
@@ -196,10 +196,12 @@ onAuthSuccess: async (
     Promise<{
         user: any;
         token: string; // JWT token from ctx.plugins.jwtAuth.createToken()
-        redirectUrl?: string;
+        redirectUrl?: string; // Plugin appends #token=... to this URL
     }>;
 ```
 
+**Important:** The `redirectUrl` should NOT include the token. The plugin automatically appends `#token=...` to the URL you return.
+
 **OAuth Profile Structure:**
 
 ```typescript
@@ -264,9 +266,53 @@ interface OAuthError {
 10. Plugin calls `onAuthSuccess` callback with profile and context
 11. App creates/links user account
 12. **App generates JWT token via `ctx.plugins.jwtAuth.createToken()`**
-13. **Plugin returns JWT token to client**
+13. **Plugin returns JWT token to client via URL fragment**
 14. Client stores JWT token and uses it for authenticated requests
 
+### How to Extract JWT Token in Frontend
+
+**IMPORTANT:** The plugin returns the JWT token as a **URL fragment** (`#token=...`), NOT as a query parameter (`?token=...`).
+
+URL fragments are more secure because they are:
+- NOT sent to the server in HTTP requests
+- NOT logged in server access logs
+- Only accessible to client-side JavaScript
+
+**Correct way to extract the token:**
+
+```javascript
+// ✅ CORRECT - Read from URL fragment (hash)
+const hash = window.location.hash.slice(1); // Remove leading #
+const params = new URLSearchParams(hash);
+const token = params.get("token");
+
+// ❌ WRONG - Reading from query parameters won't work
+const params = new URLSearchParams(window.location.search);
+const token = params.get("token"); // This returns null!
+```
+
+**In your `onAuthSuccess` callback:**
+
+```typescript
+// ✅ CORRECT - Just return the redirectUrl, plugin adds #token=...
+return {
+    user,
+    token,
+    redirectUrl: "https://myapp.com/dashboard",
+};
+// Result: https://myapp.com/dashboard#token=eyJ...
+
+// ❌ WRONG - Don't manually add the token
+return {
+    user,
+    token,
+    redirectUrl: `https://myapp.com/dashboard?token=${token}`,
+};
+// Plugin will add token again: ...?token=eyJ...#token=eyJ...
+```
+
+See [Client Integration Examples](#client-integration-examples) for complete frontend code.
+
 ### Initiate OAuth Flow
 
 ```
@@ -294,11 +340,45 @@ GET /oauth/:provider/callback?code={auth_code}&state={state}&response_type={json
 
 -   `code` - Authorization code from provider
 -   `state` - CSRF protection token
--   `response_type` - Optional response format (default: redirect with token in query)
+-   `response_type` - Optional response format: `json` for JSON response, otherwise redirect
 
 **Response Formats:**
 
-1. **JSON Response** (when `response_type=json`):
+1. **URL Fragment Redirect** (default):
+
+The plugin redirects to your `redirectUrl` with the JWT token appended as a **URL fragment** for enhanced security:
+
+```
+https://myapp.com/dashboard#token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+```
+
+**Why fragments?** URL fragments (`#token=...`) are NOT sent to the server in HTTP requests, making them more secure than query parameters. They're only accessible to client-side JavaScript.
+
+**Important:** Do NOT manually add the token to your `redirectUrl`. The plugin automatically appends it:
+
+```typescript
+// ❌ WRONG - Don't do this
+return {
+    user,
+    token,
+    redirectUrl: `${frontendUrl}/auth/callback?token=${token}`, // Plugin will add token again!
+};
+
+// ✅ CORRECT - Let plugin append the token
+return {
+    user,
+    token,
+    redirectUrl: `${frontendUrl}/auth/callback`, // Plugin adds: #token=...
+};
+```
+
+2. **JSON Response** (when `response_type=json`):
+
+Use `response_type=json` for API clients that need direct JSON response instead of redirect:
+
+```
+GET /oauth/github/callback?code=xxx&state=yyy&response_type=json
+```
 
 ```json
 {
@@ -311,18 +391,6 @@ GET /oauth/:provider/callback?code={auth_code}&state={state}&response_type={json
 }
 ```
 
-2. **URL Fragment** (when redirect URL supports fragments):
-
-```
-https://myapp.com/dashboard#token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
-```
-
-3. **Query Parameter** (default):
-
-```
-https://myapp.com/dashboard?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
-```
-
 ## Context API
 
 The plugin exposes methods via `ctx.plugins.oauth`:
@@ -531,15 +599,16 @@ function LoginPage() {
     };
 
     React.useEffect(() => {
-        // Check for token in URL after OAuth redirect
-        const urlParams = new URLSearchParams(window.location.search);
-        const token = urlParams.get("token");
+        // IMPORTANT: Token is in URL FRAGMENT (#token=...), not query parameter (?token=...)
+        const hash = window.location.hash.slice(1); // Remove the leading #
+        const params = new URLSearchParams(hash);
+        const token = params.get("token");
 
         if (token) {
             // Store JWT token
             localStorage.setItem("jwt_token", token);
 
-            // Clean URL
+            // Clean URL (remove fragment)
             window.history.replaceState({}, document.title, "/dashboard");
 
             // Redirect to dashboard
@@ -567,7 +636,10 @@ async function loginWithGitHub() {
 
     if (result.type === "success") {
         const url = result.url;
-        const token = new URL(url).searchParams.get("token");
+
+        // IMPORTANT: Token is in URL FRAGMENT (#token=...), not query parameter (?token=...)
+        const urlObj = new URL(url);
+        const token = new URLSearchParams(urlObj.hash.slice(1)).get("token");
 
         if (token) {
             await AsyncStorage.setItem("jwt_token", token);

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@flink-app/oauth-plugin",
-    "version": "0.12.1-alpha.38",
+    "version": "0.12.1-alpha.41",
     "description": "Flink plugin for OAuth 2.0 authentication with GitHub and Google providers",
     "scripts": {
         "test": "node --preserve-symlinks -r ts-node/register -- node_modules/jasmine/bin/jasmine --config=./spec/support/jasmine.json",
@@ -19,9 +19,9 @@
         "mongodb": "^6.15.0"
     },
     "devDependencies": {
-        "@flink-app/flink": "^0.12.1-alpha.35",
-        "@flink-app/jwt-auth-plugin": "^0.12.1-alpha.35",
-        "@flink-app/test-utils": "^0.12.1-alpha.38",
+        "@flink-app/flink": "^0.12.1-alpha.40",
+        "@flink-app/jwt-auth-plugin": "^0.12.1-alpha.41",
+        "@flink-app/test-utils": "^0.12.1-alpha.40",
         "@types/jasmine": "^3.7.1",
         "@types/jwt-simple": "^0.5.36",
         "@types/node": "22.13.10",
@@ -34,5 +34,5 @@
         "tsc-watch": "^4.2.9",
         "typescript": "5.4.5"
     },
-    "gitHead": "bba579788683fe0729399a56152eba4974f29bb6"
+    "gitHead": "76b54ee31f2c10c8c8f18af91facf5322b14ebf5"
 }