@flink-app/oidc-plugin 2.0.0-alpha.81 → 2.0.0-alpha.82

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @flink-app/oidc-plugin
 
+## 2.0.0-alpha.82
+
+### Patch Changes
+
+-   Add metadata passthrough support. Any query parameters prefixed with `meta.` on the initiate endpoint (e.g. `?meta.intent=admin&meta.source=mobile`) are collected, stripped of the prefix, stored in the session, and delivered to both `onAuthSuccess` and `onAuthError` callbacks as `metadata: Record<string, string>`. Empty object when no meta params are provided.
+    -   @flink-app/flink@2.0.0-alpha.82
+    -   @flink-app/jwt-auth-plugin@2.0.0-alpha.82
+
 ## 2.0.0-alpha.81
 
 ### Patch Changes

package/dist/OidcPluginOptions.d.ts

@@ -110,7 +110,7 @@ export interface OidcPluginOptions<TCtx = any> {
      *
      * Example:
      * ```typescript
-     * onAuthSuccess: async ({ profile, claims, provider }, ctx) => {
+     * onAuthSuccess: async ({ profile, claims, provider, metadata }, ctx) => {
      *   // Find user by OIDC subject + issuer
      *   let user = await ctx.repos.userRepo.getOne({
      *     'oidcConnections.subject': claims.sub,
@@ -168,6 +168,16 @@ export interface OidcPluginOptions<TCtx = any> {
          * ```
          */
         redirectUri: string;
+        /**
+         * Arbitrary metadata collected from meta.* query parameters on the initiate request.
+         * Opaque to the plugin — it only transports these values.
+         *
+         * Example: GET /oidc/acme/initiate?meta.intent=admin&meta.source=mobile
+         * Produces: { intent: "admin", source: "mobile" }
+         *
+         * Empty object ({}) if no meta.* params were provided.
+         */
+        metadata: Record<string, string>;
         /**
          * OIDC tokens (only if storeTokens: true)
          * Includes accessToken, idToken, refreshToken
@@ -210,6 +220,11 @@ export interface OidcPluginOptions<TCtx = any> {
          * (e.g., IdP returns an error before we can retrieve the session)
          */
         redirectUri?: string;
+        /**
+         * Metadata from the initiate request (meta.* query params, prefix stripped).
+         * Empty object ({}) if no meta.* params were provided or session was not found.
+         */
+        metadata: Record<string, string>;
     }) => Promise<AuthErrorCallbackResponse>;
     /**
      * Dynamic provider loader callback

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;;;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;KACxB,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":"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"}

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,CA8PnE,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,CAqQnE,CAAC;AAEF,eAAe,YAAY,CAAC"}

package/dist/handlers/CallbackOidc.js

@@ -39,8 +39,9 @@ exports.Route = {
 const CallbackOidc = async ({ ctx, req }) => {
     const { provider } = req.params;
     const { code, state, error: oidcError, error_description, response_type } = req.query;
-    // Track session outside try/catch so redirectUri is available in error handling
+    // Track session outside try/catch so redirectUri and metadata are available in error handling
     let sessionRedirectUri;
+    let sessionMetadata = {};
     try {
         // Validate provider and response_type
         (0, error_utils_1.validateProvider)(provider);
@@ -54,6 +55,7 @@ const CallbackOidc = async ({ ctx, req }) => {
             if (state) {
                 const errorSession = await ctx.repos.oidcSessionRepo.getByState(state);
                 sessionRedirectUri = errorSession?.redirectUri;
+                sessionMetadata = errorSession?.metadata ?? {};
                 if (errorSession) {
                     await ctx.repos.oidcSessionRepo.deleteBySessionId(errorSession.sessionId);
                 }
@@ -65,6 +67,7 @@ const CallbackOidc = async ({ ctx, req }) => {
                     error,
                     provider,
                     redirectUri: sessionRedirectUri,
+                    metadata: sessionMetadata,
                 });
                 if (errorResult.redirectUrl) {
                     return {
@@ -96,8 +99,9 @@ const CallbackOidc = async ({ ctx, req }) => {
                 providedState: state.substring(0, 10) + "...",
             });
         }
-        // Track redirectUri for error handling
+        // Track redirectUri and metadata for error handling
         sessionRedirectUri = session.redirectUri;
+        sessionMetadata = session.metadata ?? {};
         // Delete session immediately after validation (one-time use)
         await ctx.repos.oidcSessionRepo.deleteBySessionId(session.sessionId);
         log_1.oidcLog.debug(`Callback: state validated, session deleted (one-time use)`);
@@ -129,6 +133,7 @@ const CallbackOidc = async ({ ctx, req }) => {
             claims: tokenSet.claims,
             provider,
             redirectUri: session.redirectUri,
+            metadata: sessionMetadata,
             ...(options.storeTokens ? { tokens: tokenSet } : {}),
         };
         let authResult;
@@ -147,6 +152,7 @@ const CallbackOidc = async ({ ctx, req }) => {
                     error: oidcError,
                     provider,
                     redirectUri: session.redirectUri,
+                    metadata: sessionMetadata,
                 });
                 if (errorResult.redirectUrl) {
                     return {
@@ -228,6 +234,7 @@ const CallbackOidc = async ({ ctx, req }) => {
                         error,
                         provider,
                         redirectUri: sessionRedirectUri,
+                        metadata: sessionMetadata,
                     });
                     if (errorResult.redirectUrl) {
                         return {

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

@@ -1 +1 @@
-{"version":3,"file":"InitiateOidc.d.ts","sourceRoot":"","sources":["../../src/handlers/InitiateOidc.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,UAAU,EAAc,UAAU,EAAmC,MAAM,kBAAkB,CAAC;AACvG,OAAO,eAAe,MAAM,4BAA4B,CAAC;AAMzD;;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;;;;;GAKG;AACH,QAAA,MAAM,YAAY,EAAE,UAAU,CAAC,GAAG,EAAE,GAAG,EAAE,UAAU,EAAE,eAAe,CAyEnE,CAAC;AAEF,eAAe,YAAY,CAAC"}
+{"version":3,"file":"InitiateOidc.d.ts","sourceRoot":"","sources":["../../src/handlers/InitiateOidc.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,UAAU,EAAc,UAAU,EAAmC,MAAM,kBAAkB,CAAC;AACvG,OAAO,eAAe,MAAM,4BAA4B,CAAC;AAMzD;;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;;;;;GAKG;AACH,QAAA,MAAM,YAAY,EAAE,UAAU,CAAC,GAAG,EAAE,GAAG,EAAE,UAAU,EAAE,eAAe,CAkFnE,CAAC;AAEF,eAAe,YAAY,CAAC"}

package/dist/handlers/InitiateOidc.js

@@ -51,6 +51,13 @@ const InitiateOidc = async ({ ctx, req }) => {
         // Determine redirect URI (use provided or default to callback URL)
         const staticProviderConfig = options.providers?.[provider];
         const finalRedirectUri = redirectUri || staticProviderConfig?.callbackUrl || `${req.protocol}://${req.get("host")}/oidc/${provider}/callback`;
+        // Collect meta.* query params as opaque metadata (prefix stripped)
+        const metadata = {};
+        for (const [key, value] of Object.entries(req.query)) {
+            if (key.startsWith("meta.") && typeof value === "string") {
+                metadata[key.slice(5)] = value;
+            }
+        }
         log_1.oidcLog.debug(`Initiate: resolved redirectUri="${finalRedirectUri}" (source: ${redirectUri ? "query param" : staticProviderConfig?.callbackUrl ? "provider config" : "auto-detected"})`);
         // Generate cryptographically secure parameters
         const state = (0, state_utils_1.generateState)();
@@ -65,6 +72,7 @@ const InitiateOidc = async ({ ctx, req }) => {
             nonce,
             provider,
             redirectUri: finalRedirectUri,
+            metadata,
             createdAt: new Date(),
         });
         log_1.oidcLog.debug(`Initiate: session created sessionId=${sessionId}`);

package/dist/schemas/OidcSession.d.ts

@@ -37,6 +37,11 @@ export default interface OidcSession {
      * Can be overridden by the client via query parameter
      */
     redirectUri: string;
+    /**
+     * Arbitrary metadata collected from meta.* query parameters on initiate
+     * Passed through to onAuthSuccess and onAuthError callbacks unchanged
+     */
+    metadata?: Record<string, string>;
     /**
      * Session creation timestamp
      * MongoDB TTL index will automatically delete expired sessions

package/dist/schemas/OidcSession.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"OidcSession.d.ts","sourceRoot":"","sources":["../../src/schemas/OidcSession.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,CAAC,OAAO,WAAW,WAAW;IAChC;;OAEG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;;OAGG;IACH,YAAY,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,SAAS,EAAE,IAAI,CAAC;CACnB"}
+{"version":3,"file":"OidcSession.d.ts","sourceRoot":"","sources":["../../src/schemas/OidcSession.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,CAAC,OAAO,WAAW,WAAW;IAChC;;OAEG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;;OAGG;IACH,YAAY,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAElC;;;OAGG;IACH,SAAS,EAAE,IAAI,CAAC;CACnB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flink-app/oidc-plugin",
-  "version": "2.0.0-alpha.81",
+  "version": "2.0.0-alpha.82",
   "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.81"
+    "@flink-app/jwt-auth-plugin": "2.0.0-alpha.82"
   },
   "peerDependencies": {
-    "@flink-app/flink": ">=2.0.0-alpha.81",
+    "@flink-app/flink": ">=2.0.0-alpha.82",
     "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/flink": "2.0.0-alpha.81",
-    "@flink-app/jwt-auth-plugin": "2.0.0-alpha.81",
-    "@flink-app/test-utils": "2.0.0-alpha.81"
+    "@flink-app/flink": "2.0.0-alpha.82",
+    "@flink-app/jwt-auth-plugin": "2.0.0-alpha.82",
+    "@flink-app/test-utils": "2.0.0-alpha.82"
   },
   "scripts": {
     "test": "jasmine-ts --config=./spec/support/jasmine.json",

package/src/OidcPluginOptions.ts

@@ -120,7 +120,7 @@ export interface OidcPluginOptions<TCtx = any> {
      *
      * Example:
      * ```typescript
-     * onAuthSuccess: async ({ profile, claims, provider }, ctx) => {
+     * onAuthSuccess: async ({ profile, claims, provider, metadata }, ctx) => {
      *   // Find user by OIDC subject + issuer
      *   let user = await ctx.repos.userRepo.getOne({
      *     'oidcConnections.subject': claims.sub,
@@ -183,6 +183,17 @@ export interface OidcPluginOptions<TCtx = any> {
              */
             redirectUri: string;
 
+            /**
+             * Arbitrary metadata collected from meta.* query parameters on the initiate request.
+             * Opaque to the plugin — it only transports these values.
+             *
+             * Example: GET /oidc/acme/initiate?meta.intent=admin&meta.source=mobile
+             * Produces: { intent: "admin", source: "mobile" }
+             *
+             * Empty object ({}) if no meta.* params were provided.
+             */
+            metadata: Record<string, string>;
+
             /**
              * OIDC tokens (only if storeTokens: true)
              * Includes accessToken, idToken, refreshToken
@@ -228,6 +239,11 @@ export interface OidcPluginOptions<TCtx = any> {
          * (e.g., IdP returns an error before we can retrieve the session)
          */
         redirectUri?: string;
+        /**
+         * Metadata from the initiate request (meta.* query params, prefix stripped).
+         * Empty object ({}) if no meta.* params were provided or session was not found.
+         */
+        metadata: Record<string, string>;
     }) => Promise<AuthErrorCallbackResponse>;
 
     /**

package/src/handlers/CallbackOidc.ts

@@ -49,8 +49,9 @@ const CallbackOidc: GetHandler<any, any, PathParams, CallbackRequest> = async ({
     const { provider } = req.params;
     const { code, state, error: oidcError, error_description, response_type } = req.query;
 
-    // Track session outside try/catch so redirectUri is available in error handling
+    // Track session outside try/catch so redirectUri and metadata are available in error handling
     let sessionRedirectUri: string | undefined;
+    let sessionMetadata: Record<string, string> = {};
 
     try {
         // Validate provider and response_type
@@ -68,6 +69,7 @@ const CallbackOidc: GetHandler<any, any, PathParams, CallbackRequest> = async ({
             if (state) {
                 const errorSession = await ctx.repos.oidcSessionRepo.getByState(state);
                 sessionRedirectUri = errorSession?.redirectUri;
+                sessionMetadata = errorSession?.metadata ?? {};
                 if (errorSession) {
                     await ctx.repos.oidcSessionRepo.deleteBySessionId(errorSession.sessionId);
                 }
@@ -80,6 +82,7 @@ const CallbackOidc: GetHandler<any, any, PathParams, CallbackRequest> = async ({
                     error,
                     provider,
                     redirectUri: sessionRedirectUri,
+                    metadata: sessionMetadata,
                 });
 
                 if (errorResult.redirectUrl) {
@@ -119,8 +122,9 @@ const CallbackOidc: GetHandler<any, any, PathParams, CallbackRequest> = async ({
             });
         }
 
-        // Track redirectUri for error handling
+        // Track redirectUri and metadata for error handling
         sessionRedirectUri = session.redirectUri;
+        sessionMetadata = session.metadata ?? {};
 
         // Delete session immediately after validation (one-time use)
         await ctx.repos.oidcSessionRepo.deleteBySessionId(session.sessionId);
@@ -167,6 +171,7 @@ const CallbackOidc: GetHandler<any, any, PathParams, CallbackRequest> = async ({
             claims: tokenSet.claims,
             provider,
             redirectUri: session.redirectUri,
+            metadata: sessionMetadata,
             ...(options.storeTokens ? { tokens: tokenSet } : {}),
         };
 
@@ -187,6 +192,7 @@ const CallbackOidc: GetHandler<any, any, PathParams, CallbackRequest> = async ({
                     error: oidcError,
                     provider,
                     redirectUri: session.redirectUri,
+                    metadata: sessionMetadata,
                 });
 
                 if (errorResult.redirectUrl) {
@@ -278,6 +284,7 @@ const CallbackOidc: GetHandler<any, any, PathParams, CallbackRequest> = async ({
                         error,
                         provider,
                         redirectUri: sessionRedirectUri,
+                        metadata: sessionMetadata,
                     });
 
                     if (errorResult.redirectUrl) {

package/src/handlers/InitiateOidc.ts

@@ -67,6 +67,14 @@ const InitiateOidc: GetHandler<any, any, PathParams, InitiateRequest> = async ({
         const staticProviderConfig = options.providers?.[provider];
         const finalRedirectUri = redirectUri || staticProviderConfig?.callbackUrl || `${req.protocol}://${req.get("host")}/oidc/${provider}/callback`;
 
+        // Collect meta.* query params as opaque metadata (prefix stripped)
+        const metadata: Record<string, string> = {};
+        for (const [key, value] of Object.entries(req.query)) {
+            if (key.startsWith("meta.") && typeof value === "string") {
+                metadata[key.slice(5)] = value;
+            }
+        }
+
         oidcLog.debug(`Initiate: resolved redirectUri="${finalRedirectUri}" (source: ${redirectUri ? "query param" : staticProviderConfig?.callbackUrl ? "provider config" : "auto-detected"})`);
 
         // Generate cryptographically secure parameters
@@ -83,6 +91,7 @@ const InitiateOidc: GetHandler<any, any, PathParams, InitiateRequest> = async ({
             nonce,
             provider,
             redirectUri: finalRedirectUri,
+            metadata,
             createdAt: new Date(),
         });
 

package/src/schemas/OidcSession.ts

@@ -44,6 +44,12 @@ export default interface OidcSession {
      */
     redirectUri: string;
 
+    /**
+     * Arbitrary metadata collected from meta.* query parameters on initiate
+     * Passed through to onAuthSuccess and onAuthError callbacks unchanged
+     */
+    metadata?: Record<string, string>;
+
     /**
      * Session creation timestamp
      * MongoDB TTL index will automatically delete expired sessions