@flink-app/oidc-plugin 2.0.0-alpha.85 → 2.0.0-alpha.86

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @flink-app/oidc-plugin
 
+## 2.0.0-alpha.86
+
+### Patch Changes
+
+-   4219f07: Add `tokenDelivery` option to control how the JWT is attached to the post-callback redirect URL. Defaults to `"fragment"` (unchanged — `#token=...` is still appended for browser flows where URL fragments are not sent to the server). Set to `"query"` for native mobile flows where iOS `ASWebAuthenticationSession` strips fragments from custom-scheme callbacks, or pass a function `({ redirectUrl, provider, metadata }) => "fragment" | "query"` to decide per-request when one app serves both web and native clients. The plugin makes no scheme-based assumptions — policy lives in the host app.
+    -   @flink-app/flink@2.0.0-alpha.86
+    -   @flink-app/jwt-auth-plugin@2.0.0-alpha.86
+
 ## 2.0.0-alpha.85
 
 ### Patch Changes

package/dist/OidcPluginOptions.d.ts

@@ -1,6 +1,7 @@
 import OidcProfile from "./schemas/OidcProfile";
 import OidcTokenSet from "./schemas/OidcTokenSet";
 import { OidcProviderConfig } from "./OidcProviderConfig";
+import { TokenDeliveryMode } from "./utils/response-utils";
 /**
  * OIDC error information passed to onAuthError callback
  */
@@ -35,7 +36,9 @@ export interface AuthSuccessCallbackResponse {
     token: string;
     /**
      * Optional redirect URL after authentication
-     * Plugin will append #token=... to this URL
+     *
+     * The plugin will attach the JWT token to this URL according to the
+     * top-level `tokenDelivery` option (fragment by default, or query).
      */
     redirectUrl?: string;
 }
@@ -288,6 +291,36 @@ export interface OidcPluginOptions<TCtx = any> {
      * Example: process.env.OIDC_ENCRYPTION_KEY
      */
     encryptionKey?: string;
+    /**
+     * Controls how the JWT token is delivered back to the client on the
+     * post-callback redirect (ignored when the caller uses `?response_type=json`).
+     *
+     * - `"fragment"` (default): appends `#token=...` to the redirectUrl. Best
+     *   for web browsers — URL fragments are not sent to the server in HTTP
+     *   requests, which preserves a small but real security property.
+     * - `"query"`: appends `?token=...` (or `&token=...`). Required for native
+     *   mobile flows where the callback comes back via a custom URL scheme,
+     *   because iOS `ASWebAuthenticationSession` strips URL fragments before
+     *   delivering the URL to the app.
+     * - function: called once per callback to decide the delivery mode. Use
+     *   this when one app serves both web and native clients. The function
+     *   receives the resolved redirectUrl and the metadata bag from the
+     *   initiate request, so the host can route by URL scheme, by
+     *   `meta.intent`, or any other signal — the plugin makes no assumptions.
+     *
+     * Default: `"fragment"` (unchanged from prior versions).
+     *
+     * Example — route native (custom-scheme) clients to query, browsers to fragment:
+     * ```typescript
+     * tokenDelivery: ({ redirectUrl }) =>
+     *     /^https?:/i.test(redirectUrl) ? "fragment" : "query",
+     * ```
+     */
+    tokenDelivery?: TokenDeliveryMode | ((params: {
+        redirectUrl: string;
+        provider: string;
+        metadata: Record<string, string>;
+    }) => TokenDeliveryMode);
     /**
      * Whether to register OIDC routes automatically
      * If false, you must manually handle OIDC flow

package/dist/OidcPluginOptions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"OidcPluginOptions.d.ts","sourceRoot":"","sources":["../src/OidcPluginOptions.ts"],"names":[],"mappings":"AAAA,OAAO,WAAW,MAAM,uBAAuB,CAAC;AAChD,OAAO,YAAY,MAAM,wBAAwB,CAAC;AAClD,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE1D;;GAEG;AACH,MAAM,WAAW,SAAS;IACtB;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,OAAO,CAAC,EAAE,GAAG,CAAC;CACjB;AAED;;;GAGG;AACH,MAAM,WAAW,2BAA2B;IACxC;;;OAGG;IACH,IAAI,EAAE,GAAG,CAAC;IAEV;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACtC;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB,CAAC,IAAI,GAAG,GAAG;IACzC;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;IAE/C;;;;;;;;;;;OAWG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IAEtB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgDG;IACH,aAAa,EAAE,CACX,MAAM,EAAE;QACJ;;WAEG;QACH,OAAO,EAAE,WAAW,CAAC;QAErB;;;WAGG;QACH,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QAE5B;;WAEG;QACH,QAAQ,EAAE,MAAM,CAAC;QAEjB;;;;;;;;WAQG;QACH,WAAW,EAAE,MAAM,CAAC;QAEpB;;;;;;;;WAQG;QACH,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAEjC;;;WAGG;QACH,MAAM,CAAC,EAAE,YAAY,CAAC;KACzB,EACD,GAAG,EAAE,IAAI,KACR,OAAO,CAAC,2BAA2B,CAAC,CAAC;IAE1C;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE;QACnB,KAAK,EAAE,SAAS,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;QACjB;;;;WAIG;QACH,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB;;;WAGG;QACH,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;KACpC,KAAK,OAAO,CAAC,yBAAyB,CAAC,CAAC;IAEzC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACH,cAAc,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,KAAK,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAAC;IAEzF;;;OAGG;IACH,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAEhC;;;OAGG;IACH,yBAAyB,CAAC,EAAE,MAAM,CAAC;IAEnC;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;;;;;;;;OAUG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB;;;;;;;OAOG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CAC5B"}
+{"version":3,"file":"OidcPluginOptions.d.ts","sourceRoot":"","sources":["../src/OidcPluginOptions.ts"],"names":[],"mappings":"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"}

package/dist/handlers/CallbackOidc.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CallbackOidc.d.ts","sourceRoot":"","sources":["../../src/handlers/CallbackOidc.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,UAAU,EAAc,UAAU,EAAwC,MAAM,kBAAkB,CAAC;AAC5G,OAAO,eAAe,MAAM,4BAA4B,CAAC;AAOzD;;GAEG;AACH,UAAU,UAAU;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;CACzB;AAED;;;GAGG;AACH,eAAO,MAAM,KAAK,EAAE,UAGnB,CAAC;AAEF;;;;;;GAMG;AACH,QAAA,MAAM,YAAY,EAAE,UAAU,CAAC,GAAG,EAAE,GAAG,EAAE,UAAU,EAAE,eAAe,CAqQnE,CAAC;AAEF,eAAe,YAAY,CAAC"}
+{"version":3,"file":"CallbackOidc.d.ts","sourceRoot":"","sources":["../../src/handlers/CallbackOidc.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,UAAU,EAAc,UAAU,EAAwC,MAAM,kBAAkB,CAAC;AAC5G,OAAO,eAAe,MAAM,4BAA4B,CAAC;AAOzD;;GAEG;AACH,UAAU,UAAU;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;CACzB;AAED;;;GAGG;AACH,eAAO,MAAM,KAAK,EAAE,UAGnB,CAAC;AAEF;;;;;;GAMG;AACH,QAAA,MAAM,YAAY,EAAE,UAAU,CAAC,GAAG,EAAE,GAAG,EAAE,UAAU,EAAE,eAAe,CAiRnE,CAAC;AAEF,eAAe,YAAY,CAAC"}

package/dist/handlers/CallbackOidc.js

@@ -219,8 +219,18 @@ const CallbackOidc = async ({ ctx, req }) => {
         }
         const finalRedirectUrl = redirectUrl || session.redirectUri;
         log_1.oidcLog.debug(`Callback: auth complete, responding via ${response_type === "json" ? "JSON" : `redirect to "${finalRedirectUrl}"`}`);
+        // Resolve token delivery mode: literal, function, or default "fragment".
+        // The plugin stays a dumb transport — the host app makes the policy decision.
+        const tokenDeliverySetting = options.tokenDelivery ?? "fragment";
+        const resolvedTokenDelivery = typeof tokenDeliverySetting === "function"
+            ? tokenDeliverySetting({
+                redirectUrl: finalRedirectUrl,
+                provider,
+                metadata: sessionMetadata,
+            })
+            : tokenDeliverySetting;
         // Return JWT token in requested format
-        return (0, response_utils_1.formatTokenResponse)(token, user, finalRedirectUrl, response_type);
+        return (0, response_utils_1.formatTokenResponse)(token, user, finalRedirectUrl, response_type, resolvedTokenDelivery);
     }
     catch (error) {
         flink_1.log.error("OIDC callback error:", error);

package/dist/index.d.ts

@@ -22,6 +22,6 @@ export { ProviderRegistry } from "./providers/ProviderRegistry";
 export { generateState, generateSessionId, generateNonce, validateState } from "./utils/state-utils";
 export { encryptToken, decryptToken, validateEncryptionSecret } from "./utils/encryption-utils";
 export { mapClaimsToProfile, extractCustomClaims } from "./utils/claims-mapper";
-export { formatTokenResponse } from "./utils/response-utils";
+export { formatTokenResponse, TokenDeliveryMode } from "./utils/response-utils";
 export { createOidcError, validateProvider, handleProviderError, OidcErrorCodes } from "./utils/error-utils";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAG1C,OAAO,EAAE,iBAAiB,EAAE,SAAS,EAAE,2BAA2B,EAAE,yBAAyB,EAAE,MAAM,qBAAqB,CAAC;AAC3H,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAG1D,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAGxD,OAAO,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAC/D,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACjE,OAAO,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAC/D,OAAO,EAAE,OAAO,IAAI,cAAc,EAAE,MAAM,0BAA0B,CAAC;AACrE,OAAO,EAAE,OAAO,IAAI,eAAe,EAAE,MAAM,2BAA2B,CAAC;AACvE,OAAO,EAAE,OAAO,IAAI,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAGvE,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AACxD,OAAO,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAGhE,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACrG,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,wBAAwB,EAAE,MAAM,0BAA0B,CAAC;AAChG,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAChF,OAAO,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAC7D,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAG1C,OAAO,EAAE,iBAAiB,EAAE,SAAS,EAAE,2BAA2B,EAAE,yBAAyB,EAAE,MAAM,qBAAqB,CAAC;AAC3H,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAG1D,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAGxD,OAAO,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAC/D,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACjE,OAAO,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAC/D,OAAO,EAAE,OAAO,IAAI,cAAc,EAAE,MAAM,0BAA0B,CAAC;AACrE,OAAO,EAAE,OAAO,IAAI,eAAe,EAAE,MAAM,2BAA2B,CAAC;AACvE,OAAO,EAAE,OAAO,IAAI,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAGvE,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AACxD,OAAO,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAGhE,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACrG,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,wBAAwB,EAAE,MAAM,0BAA0B,CAAC;AAChG,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAChF,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAChF,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/utils/response-utils.d.ts

@@ -1,18 +1,29 @@
+/**
+ * Controls how the JWT token is delivered back to the client on the
+ * post-callback redirect.
+ *
+ * - "fragment": appends `#token=...` to the redirectUrl. Best for web
+ *   browsers — URL fragments are not sent to the server in HTTP requests
+ *   and are only accessible to client-side JavaScript.
+ * - "query": appends `?token=...` (or `&token=...`). Required for native
+ *   mobile flows where the callback comes back via a custom URL scheme,
+ *   because iOS `ASWebAuthenticationSession` strips URL fragments before
+ *   delivering the URL to the app.
+ */
+export type TokenDeliveryMode = "fragment" | "query";
 /**
  * Format token response for the client
  *
  * Supports two response formats:
  * 1. JSON response (for API clients)
- * 2. Redirect with token in URL fragment (for web browsers)
- *
- * URL fragments are used for security - they are NOT sent to the server
- * in HTTP requests and are only accessible to client-side JavaScript.
+ * 2. Redirect with token in URL fragment or query (for web/native clients)
  *
  * @param token - JWT token for the application
  * @param user - User object
  * @param redirectUrl - URL to redirect to
  * @param responseType - "json" or undefined (redirect)
+ * @param tokenDelivery - How to attach the token on redirect. Defaults to "fragment".
  * @returns Flink response object
  */
-export declare function formatTokenResponse(token: string, user: any, redirectUrl: string, responseType?: "json"): any;
+export declare function formatTokenResponse(token: string, user: any, redirectUrl: string, responseType?: "json", tokenDelivery?: TokenDeliveryMode): any;
 //# sourceMappingURL=response-utils.d.ts.map

package/dist/utils/response-utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"response-utils.d.ts","sourceRoot":"","sources":["../../src/utils/response-utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,WAAW,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,GAAG,CAwB7G"}
+{"version":3,"file":"response-utils.d.ts","sourceRoot":"","sources":["../../src/utils/response-utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,iBAAiB,GAAG,UAAU,GAAG,OAAO,CAAC;AAErD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CAC/B,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,GAAG,EACT,WAAW,EAAE,MAAM,EACnB,YAAY,CAAC,EAAE,MAAM,EACrB,aAAa,GAAE,iBAA8B,GAC9C,GAAG,CAqBL"}

package/dist/utils/response-utils.js

@@ -6,18 +6,16 @@ exports.formatTokenResponse = formatTokenResponse;
  *
  * Supports two response formats:
  * 1. JSON response (for API clients)
- * 2. Redirect with token in URL fragment (for web browsers)
- *
- * URL fragments are used for security - they are NOT sent to the server
- * in HTTP requests and are only accessible to client-side JavaScript.
+ * 2. Redirect with token in URL fragment or query (for web/native clients)
  *
  * @param token - JWT token for the application
  * @param user - User object
  * @param redirectUrl - URL to redirect to
  * @param responseType - "json" or undefined (redirect)
+ * @param tokenDelivery - How to attach the token on redirect. Defaults to "fragment".
  * @returns Flink response object
  */
-function formatTokenResponse(token, user, redirectUrl, responseType) {
+function formatTokenResponse(token, user, redirectUrl, responseType, tokenDelivery = "fragment") {
     // JSON response for API clients
     if (responseType === "json") {
         return {
@@ -27,11 +25,8 @@ function formatTokenResponse(token, user, redirectUrl, responseType) {
             },
         };
     }
-    // Redirect response for web browsers
-    // Token is in URL fragment (#token=...) for security
-    const separator = redirectUrl.includes("#") ? "&" : "#";
-    const tokenFragment = `token=${encodeURIComponent(token)}`;
-    const finalUrl = `${redirectUrl}${separator}${tokenFragment}`;
+    const tokenParam = `token=${encodeURIComponent(token)}`;
+    const finalUrl = appendToken(redirectUrl, tokenParam, tokenDelivery);
     return {
         status: 302,
         headers: {
@@ -40,3 +35,29 @@ function formatTokenResponse(token, user, redirectUrl, responseType) {
         data: {},
     };
 }
+/**
+ * Append a token parameter to a URL using the specified delivery mode.
+ *
+ * For "query" mode, any existing `#fragment` on the URL is preserved: the
+ * query parameter is spliced in *before* the fragment so the final URL is
+ * still well-formed.
+ *
+ * For "fragment" mode, a second token on an existing fragment is joined
+ * with `&` (same as the old behavior).
+ */
+function appendToken(redirectUrl, tokenParam, mode) {
+    if (mode === "query") {
+        const hashIdx = redirectUrl.indexOf("#");
+        if (hashIdx >= 0) {
+            const base = redirectUrl.slice(0, hashIdx);
+            const frag = redirectUrl.slice(hashIdx);
+            const sep = base.includes("?") ? "&" : "?";
+            return `${base}${sep}${tokenParam}${frag}`;
+        }
+        const sep = redirectUrl.includes("?") ? "&" : "?";
+        return `${redirectUrl}${sep}${tokenParam}`;
+    }
+    // fragment (default)
+    const sep = redirectUrl.includes("#") ? "&" : "#";
+    return `${redirectUrl}${sep}${tokenParam}`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flink-app/oidc-plugin",
-  "version": "2.0.0-alpha.85",
+  "version": "2.0.0-alpha.86",
   "description": "Flink plugin for OIDC authentication with generic IdP support",
   "author": "joel@frost.se",
   "license": "MIT",
@@ -11,10 +11,10 @@
   },
   "dependencies": {
     "openid-client": "^5.7.0",
-    "@flink-app/jwt-auth-plugin": "2.0.0-alpha.85"
+    "@flink-app/jwt-auth-plugin": "2.0.0-alpha.86"
   },
   "peerDependencies": {
-    "@flink-app/flink": ">=2.0.0-alpha.85",
+    "@flink-app/flink": ">=2.0.0-alpha.86",
     "mongodb": "^6.15.0"
   },
   "peerDependenciesMeta": {
@@ -27,9 +27,9 @@
     "@types/node": "22.13.10",
     "ts-node": "^10.9.2",
     "tsc-watch": "^4.2.9",
-    "@flink-app/jwt-auth-plugin": "2.0.0-alpha.85",
-    "@flink-app/flink": "2.0.0-alpha.85",
-    "@flink-app/test-utils": "2.0.0-alpha.85"
+    "@flink-app/flink": "2.0.0-alpha.86",
+    "@flink-app/jwt-auth-plugin": "2.0.0-alpha.86",
+    "@flink-app/test-utils": "2.0.0-alpha.86"
   },
   "scripts": {
     "test": "jasmine-ts --config=./spec/support/jasmine.json",

package/spec/utils/response-utils.spec.ts

@@ -0,0 +1,85 @@
+/**
+ * Tests for formatTokenResponse — covers JSON mode, fragment mode (default,
+ * backwards compatible), and query mode (including the tricky case where
+ * the redirectUrl already carries a fragment that must be preserved).
+ */
+
+import { formatTokenResponse } from "../../src/utils/response-utils";
+
+describe("response-utils", () => {
+    describe("formatTokenResponse", () => {
+        const token = "jwt.token.value";
+        const user = { id: "u1", email: "a@b.c" };
+
+        describe("JSON mode", () => {
+            it("returns { data: { user, token } } when response_type=json", () => {
+                const result = formatTokenResponse(token, user, "https://app/cb", "json");
+                expect(result).toEqual({ data: { user, token } });
+            });
+
+            it("ignores tokenDelivery when response_type=json", () => {
+                const result = formatTokenResponse(token, user, "https://app/cb", "json", "query");
+                expect(result).toEqual({ data: { user, token } });
+            });
+        });
+
+        describe("fragment mode (default)", () => {
+            it("appends #token=... to a plain URL", () => {
+                const result = formatTokenResponse(token, user, "https://app/cb");
+                expect(result.status).toBe(302);
+                expect(result.headers.Location).toBe(`https://app/cb#token=${encodeURIComponent(token)}`);
+            });
+
+            it("uses & when the URL already has a fragment", () => {
+                const result = formatTokenResponse(token, user, "https://app/cb#foo=bar");
+                expect(result.headers.Location).toBe(`https://app/cb#foo=bar&token=${encodeURIComponent(token)}`);
+            });
+
+            it("preserves existing query string", () => {
+                const result = formatTokenResponse(token, user, "https://app/cb?next=/dashboard");
+                expect(result.headers.Location).toBe(`https://app/cb?next=/dashboard#token=${encodeURIComponent(token)}`);
+            });
+
+            it("URL-encodes tokens with special characters", () => {
+                const weird = "a b+c/d=e";
+                const result = formatTokenResponse(weird, user, "https://app/cb");
+                expect(result.headers.Location).toBe(`https://app/cb#token=${encodeURIComponent(weird)}`);
+            });
+
+            it("is the default when tokenDelivery is omitted", () => {
+                const implicit = formatTokenResponse(token, user, "https://app/cb");
+                const explicit = formatTokenResponse(token, user, "https://app/cb", undefined, "fragment");
+                expect(implicit.headers.Location).toBe(explicit.headers.Location);
+            });
+        });
+
+        describe("query mode", () => {
+            it("appends ?token=... to a plain URL", () => {
+                const result = formatTokenResponse(token, user, "myapp://cb", undefined, "query");
+                expect(result.status).toBe(302);
+                expect(result.headers.Location).toBe(`myapp://cb?token=${encodeURIComponent(token)}`);
+            });
+
+            it("uses & when the URL already has a query string", () => {
+                const result = formatTokenResponse(token, user, "myapp://cb?foo=1", undefined, "query");
+                expect(result.headers.Location).toBe(`myapp://cb?foo=1&token=${encodeURIComponent(token)}`);
+            });
+
+            it("splices the query param BEFORE an existing fragment", () => {
+                const result = formatTokenResponse(token, user, "myapp://cb#state=xyz", undefined, "query");
+                expect(result.headers.Location).toBe(`myapp://cb?token=${encodeURIComponent(token)}#state=xyz`);
+            });
+
+            it("splices with & before fragment when query already present", () => {
+                const result = formatTokenResponse(token, user, "myapp://cb?foo=1#bar", undefined, "query");
+                expect(result.headers.Location).toBe(`myapp://cb?foo=1&token=${encodeURIComponent(token)}#bar`);
+            });
+
+            it("URL-encodes tokens with special characters", () => {
+                const weird = "a b+c/d=e";
+                const result = formatTokenResponse(weird, user, "myapp://cb", undefined, "query");
+                expect(result.headers.Location).toBe(`myapp://cb?token=${encodeURIComponent(weird)}`);
+            });
+        });
+    });
+});

package/src/OidcPluginOptions.ts

@@ -1,6 +1,7 @@
 import OidcProfile from "./schemas/OidcProfile";
 import OidcTokenSet from "./schemas/OidcTokenSet";
 import { OidcProviderConfig } from "./OidcProviderConfig";
+import { TokenDeliveryMode } from "./utils/response-utils";
 
 /**
  * OIDC error information passed to onAuthError callback
@@ -41,7 +42,9 @@ export interface AuthSuccessCallbackResponse {
 
     /**
      * Optional redirect URL after authentication
-     * Plugin will append #token=... to this URL
+     *
+     * The plugin will attach the JWT token to this URL according to the
+     * top-level `tokenDelivery` option (fragment by default, or query).
      */
     redirectUrl?: string;
 }
@@ -313,6 +316,39 @@ export interface OidcPluginOptions<TCtx = any> {
      */
     encryptionKey?: string;
 
+    /**
+     * Controls how the JWT token is delivered back to the client on the
+     * post-callback redirect (ignored when the caller uses `?response_type=json`).
+     *
+     * - `"fragment"` (default): appends `#token=...` to the redirectUrl. Best
+     *   for web browsers — URL fragments are not sent to the server in HTTP
+     *   requests, which preserves a small but real security property.
+     * - `"query"`: appends `?token=...` (or `&token=...`). Required for native
+     *   mobile flows where the callback comes back via a custom URL scheme,
+     *   because iOS `ASWebAuthenticationSession` strips URL fragments before
+     *   delivering the URL to the app.
+     * - function: called once per callback to decide the delivery mode. Use
+     *   this when one app serves both web and native clients. The function
+     *   receives the resolved redirectUrl and the metadata bag from the
+     *   initiate request, so the host can route by URL scheme, by
+     *   `meta.intent`, or any other signal — the plugin makes no assumptions.
+     *
+     * Default: `"fragment"` (unchanged from prior versions).
+     *
+     * Example — route native (custom-scheme) clients to query, browsers to fragment:
+     * ```typescript
+     * tokenDelivery: ({ redirectUrl }) =>
+     *     /^https?:/i.test(redirectUrl) ? "fragment" : "query",
+     * ```
+     */
+    tokenDelivery?:
+        | TokenDeliveryMode
+        | ((params: {
+              redirectUrl: string;
+              provider: string;
+              metadata: Record<string, string>;
+          }) => TokenDeliveryMode);
+
     /**
      * Whether to register OIDC routes automatically
      * If false, you must manually handle OIDC flow

package/src/handlers/CallbackOidc.ts

@@ -269,8 +269,20 @@ const CallbackOidc: GetHandler<any, any, PathParams, CallbackRequest> = async ({
         const finalRedirectUrl = redirectUrl || session.redirectUri;
         oidcLog.debug(`Callback: auth complete, responding via ${response_type === "json" ? "JSON" : `redirect to "${finalRedirectUrl}"`}`);
 
+        // Resolve token delivery mode: literal, function, or default "fragment".
+        // The plugin stays a dumb transport — the host app makes the policy decision.
+        const tokenDeliverySetting = options.tokenDelivery ?? "fragment";
+        const resolvedTokenDelivery =
+            typeof tokenDeliverySetting === "function"
+                ? tokenDeliverySetting({
+                      redirectUrl: finalRedirectUrl,
+                      provider,
+                      metadata: sessionMetadata,
+                  })
+                : tokenDeliverySetting;
+
         // Return JWT token in requested format
-        return formatTokenResponse(token, user, finalRedirectUrl, response_type);
+        return formatTokenResponse(token, user, finalRedirectUrl, response_type, resolvedTokenDelivery);
     } catch (error: any) {
         log.error("OIDC callback error:", error);
 

package/src/index.ts

@@ -34,5 +34,5 @@ export { ProviderRegistry } from "./providers/ProviderRegistry";
 export { generateState, generateSessionId, generateNonce, validateState } from "./utils/state-utils";
 export { encryptToken, decryptToken, validateEncryptionSecret } from "./utils/encryption-utils";
 export { mapClaimsToProfile, extractCustomClaims } from "./utils/claims-mapper";
-export { formatTokenResponse } from "./utils/response-utils";
+export { formatTokenResponse, TokenDeliveryMode } from "./utils/response-utils";
 export { createOidcError, validateProvider, handleProviderError, OidcErrorCodes } from "./utils/error-utils";

package/src/utils/response-utils.ts

@@ -1,20 +1,38 @@
+/**
+ * Controls how the JWT token is delivered back to the client on the
+ * post-callback redirect.
+ *
+ * - "fragment": appends `#token=...` to the redirectUrl. Best for web
+ *   browsers — URL fragments are not sent to the server in HTTP requests
+ *   and are only accessible to client-side JavaScript.
+ * - "query": appends `?token=...` (or `&token=...`). Required for native
+ *   mobile flows where the callback comes back via a custom URL scheme,
+ *   because iOS `ASWebAuthenticationSession` strips URL fragments before
+ *   delivering the URL to the app.
+ */
+export type TokenDeliveryMode = "fragment" | "query";
+
 /**
  * Format token response for the client
  *
  * Supports two response formats:
  * 1. JSON response (for API clients)
- * 2. Redirect with token in URL fragment (for web browsers)
- *
- * URL fragments are used for security - they are NOT sent to the server
- * in HTTP requests and are only accessible to client-side JavaScript.
+ * 2. Redirect with token in URL fragment or query (for web/native clients)
  *
  * @param token - JWT token for the application
  * @param user - User object
  * @param redirectUrl - URL to redirect to
  * @param responseType - "json" or undefined (redirect)
+ * @param tokenDelivery - How to attach the token on redirect. Defaults to "fragment".
  * @returns Flink response object
  */
-export function formatTokenResponse(token: string, user: any, redirectUrl: string, responseType?: "json"): any {
+export function formatTokenResponse(
+    token: string,
+    user: any,
+    redirectUrl: string,
+    responseType?: "json",
+    tokenDelivery: TokenDeliveryMode = "fragment"
+): any {
     // JSON response for API clients
     if (responseType === "json") {
         return {
@@ -25,11 +43,8 @@ export function formatTokenResponse(token: string, user: any, redirectUrl: strin
         };
     }
 
-    // Redirect response for web browsers
-    // Token is in URL fragment (#token=...) for security
-    const separator = redirectUrl.includes("#") ? "&" : "#";
-    const tokenFragment = `token=${encodeURIComponent(token)}`;
-    const finalUrl = `${redirectUrl}${separator}${tokenFragment}`;
+    const tokenParam = `token=${encodeURIComponent(token)}`;
+    const finalUrl = appendToken(redirectUrl, tokenParam, tokenDelivery);
 
     return {
         status: 302,
@@ -39,3 +54,31 @@ export function formatTokenResponse(token: string, user: any, redirectUrl: strin
         data: {},
     };
 }
+
+/**
+ * Append a token parameter to a URL using the specified delivery mode.
+ *
+ * For "query" mode, any existing `#fragment` on the URL is preserved: the
+ * query parameter is spliced in *before* the fragment so the final URL is
+ * still well-formed.
+ *
+ * For "fragment" mode, a second token on an existing fragment is joined
+ * with `&` (same as the old behavior).
+ */
+function appendToken(redirectUrl: string, tokenParam: string, mode: TokenDeliveryMode): string {
+    if (mode === "query") {
+        const hashIdx = redirectUrl.indexOf("#");
+        if (hashIdx >= 0) {
+            const base = redirectUrl.slice(0, hashIdx);
+            const frag = redirectUrl.slice(hashIdx);
+            const sep = base.includes("?") ? "&" : "?";
+            return `${base}${sep}${tokenParam}${frag}`;
+        }
+        const sep = redirectUrl.includes("?") ? "&" : "?";
+        return `${redirectUrl}${sep}${tokenParam}`;
+    }
+
+    // fragment (default)
+    const sep = redirectUrl.includes("#") ? "&" : "#";
+    return `${redirectUrl}${sep}${tokenParam}`;
+}