@pikku/core 0.6.12 → 0.6.14

package/dist/http/http-route-runner.js

@@ -1,43 +1,106 @@
-import { getErrorResponse } from '../errors/error-handler.js';
 import { verifyPermissions } from '../permissions.js';
 import { match } from 'path-to-regexp';
 import { PikkuHTTPAbstractRequest } from './pikku-http-abstract-request.js';
 import { PikkuHTTPAbstractResponse } from './pikku-http-abstract-response.js';
-import { ForbiddenError, NotFoundError, NotImplementedError, } from '../errors/errors.js';
+import { ForbiddenError, MissingSessionError, NotFoundError, } from '../errors/errors.js';
 import crypto from 'crypto';
 import { closeSessionServices } from '../utils.js';
-import { getSchema, validateAndCoerce } from '../schema.js';
+import { coerceQueryStringToArray, validateSchema } from '../schema.js';
+import { LocalUserSessionService } from '../services/user-session-service.js';
+import { runMiddleware } from '../middleware-runner.js';
+import { handleError } from '../handle-error.js';
+/**
+ * Initialize global state for HTTP routes and middleware if not already available
+ */
 if (!globalThis.pikku?.httpRoutes) {
     globalThis.pikku = globalThis.pikku || {};
+    globalThis.pikku.httpMiddleware = [];
     globalThis.pikku.httpRoutes = [];
     globalThis.pikku.httpRoutesMeta = [];
 }
+/**
+ * Get or set the global HTTP routes
+ *
+ * @param {CoreHTTPFunctionRoute<any, any, any>[]} [data] - Optional routes data to set
+ * @returns {CoreHTTPFunctionRoute<any, any, any>[]} Current routes
+ */
 const httpRoutes = (data) => {
     if (data) {
         globalThis.pikku.httpRoutes = data;
     }
     return globalThis.pikku.httpRoutes;
 };
+/**
+ * Get or set the global HTTP route metadata
+ *
+ * @param {HTTPRoutesMeta} [data] - Optional route metadata to set
+ * @returns {HTTPRoutesMeta} Current route metadata
+ */
 const httpRoutesMeta = (data) => {
     if (data) {
         globalThis.pikku.httpRoutesMeta = data;
     }
     return globalThis.pikku.httpRoutesMeta;
 };
+/**
+ * Get or set the global HTTP middleware
+ *
+ * @param {HTTPRouteMiddleware[]} [data] - Optional middleware to set
+ * @returns {HTTPRouteMiddleware[]} Current middleware
+ */
+const httpMiddleware = (data) => {
+    if (data) {
+        globalThis.pikku.httpMiddleware = data;
+    }
+    return globalThis.pikku.httpMiddleware;
+};
+/**
+ * Add middleware to a specific route or globally
+ *
+ * @param {APIMiddleware[] | string} routeOrMiddleware - Route pattern to match or middleware array
+ * @param {APIMiddleware} [middleware] - Middleware to add (required if first param is a string)
+ */
+export const addMiddleware = (routeOrMiddleware, middleware) => {
+    if (typeof routeOrMiddleware === 'string') {
+        globalThis.pikku.httpMiddleware.push({
+            route: routeOrMiddleware,
+            middleware: middleware,
+        });
+    }
+    else {
+        globalThis.pikku.httpMiddleware.push({
+            route: '*',
+            middleware: routeOrMiddleware,
+        });
+    }
+};
+/**
+ * Add a route to the global routes registry
+ *
+ * @param {CoreHTTPFunctionRoute} route - Route configuration to add
+ */
 export const addRoute = (route) => {
     httpRoutes().push(route);
 };
+/**
+ * Remove all routes from the global registry
+ */
 export const clearRoutes = () => {
     httpRoutes([]);
 };
 /**
+ * Set the HTTP routes metadata
+ *
+ * @param {HTTPRoutesMeta} routeMeta - Metadata for routes
  * @ignore
  */
-export const setHTTPRoutesMeta = (_routeMeta) => {
-    httpRoutesMeta(_routeMeta);
+export const setHTTPRoutesMeta = (routeMeta) => {
+    httpRoutesMeta(routeMeta);
 };
 /**
- * Returns all the registered routes and associated metadata.
+ * Returns all the registered routes and associated metadata
+ *
+ * @returns {Object} Object containing routes and routesMeta
  * @internal
  */
 export const getRoutes = () => {
@@ -46,69 +109,51 @@ export const getRoutes = () => {
         routesMeta: httpRoutesMeta(),
     };
 };
-const getMatchingRoute = (schemaService, requestType, requestPath) => {
+/**
+ * Find a route that matches the given request type and path
+ *
+ * @param {string} requestType - HTTP method (GET, POST, etc.)
+ * @param {string} requestPath - URL path to match
+ * @returns {Object | undefined} Matching route information or undefined if no match
+ */
+const getMatchingRoute = (requestType, requestPath) => {
     for (const route of httpRoutes()) {
-        // TODO: This is a performance improvement, but we could
-        // run against all routes if we want to return a 405 method.
-        // Probably want a cache to support.
+        // Skip routes that don't match the request method
         if (route.method !== requestType.toLowerCase()) {
             continue;
         }
+        // Create path matcher function
         const matchFunc = match(`/${route.route}`.replace(/^\/\//, '/'), {
             decode: decodeURIComponent,
         });
+        // Try to match the path
         const matchedPath = matchFunc(requestPath.replace(/^\/\//, '/'));
         if (matchedPath) {
-            // TODO: Cache this loop as a performance improvement
+            // Get all middleware for this route
+            const globalMiddleware = httpMiddleware()
+                .filter((m) => m.route === '*' || new RegExp(m.route).test(route.route))
+                .map((m) => m.middleware)
+                .flat();
+            // Find schema for this route
             const schemaName = httpRoutesMeta().find((routeMeta) => routeMeta.method === route.method && routeMeta.route === route.route)?.input;
-            if (schemaName && schemaService) {
-                const schema = getSchema(schemaName);
-                schemaService.compileSchema(schemaName, schema);
-            }
-            return { matchedPath, params: matchedPath.params, route, schemaName };
-        }
-    }
-    return undefined;
-};
-export const getUserSession = async (httpSessionService, auth, request) => {
-    if (httpSessionService) {
-        return (await httpSessionService.getUserSession(auth, request));
-    }
-    else if (auth) {
-        throw new NotImplementedError('Session service not implemented');
-    }
-    return undefined;
-};
-export const loadUserSession = async (skipUserSession, requiresSession, http, matchedPath, route, logger, httpSessionService) => {
-    if (skipUserSession && requiresSession) {
-        throw new Error("Can't skip trying to get user session if auth is required");
-    }
-    if (skipUserSession === false) {
-        try {
-            if (http?.request) {
-                return await getUserSession(httpSessionService, requiresSession, http.request);
-            }
-            else if (requiresSession) {
-                logger.error({
-                    action: 'Can only get user session with HTTP request',
-                    path: matchedPath,
-                    route,
-                });
-                throw new Error('Can only get user session with HTTP request');
-            }
-        }
-        catch (e) {
-            if (requiresSession) {
-                logger.info({
-                    action: 'Rejecting route (invalid session)',
-                    path: matchedPath,
-                });
-                throw e;
-            }
+            return {
+                matchedPath,
+                params: matchedPath.params,
+                route,
+                middleware: [...globalMiddleware, ...(route.middleware || [])],
+                schemaName,
+            };
         }
     }
     return undefined;
 };
+/**
+ * Create an HTTP interaction object from request and response
+ *
+ * @param {PikkuRequest | undefined} request - The HTTP request object
+ * @param {PikkuResponse | undefined} response - The HTTP response object
+ * @returns {PikkuHTTP | undefined} HTTP interaction object or undefined
+ */
 export const createHTTPInteraction = (request, response) => {
     let http = undefined;
     if (request instanceof PikkuHTTPAbstractRequest ||
@@ -123,70 +168,55 @@ export const createHTTPInteraction = (request, response) => {
     }
     return http;
 };
-export const handleError = (e, http, trackerId, logger, logWarningsForStatusCodes, respondWith404, bubbleError) => {
-    if (e instanceof NotFoundError && !respondWith404) {
-        return;
-    }
-    const errorResponse = getErrorResponse(e);
-    if (errorResponse != null) {
-        http?.response?.setStatus(errorResponse.status);
-        http?.response?.setJson({
-            message: errorResponse.message,
-            payload: e.payload,
-            traceId: trackerId,
-        });
-        if (logWarningsForStatusCodes.includes(errorResponse.status)) {
-            logger.warn(`Warning id: ${trackerId}`);
-            logger.warn(e);
-        }
-    }
-    else {
-        logger.warn(`Error id: ${trackerId}`);
-        logger.error(e);
-        http?.response?.setStatus(500);
-        http?.response?.setJson({ errorId: trackerId });
-    }
-    if (e instanceof NotFoundError) {
-        http?.response?.end();
-    }
-    if (bubbleError) {
-        throw e;
-    }
-};
 /**
- * @ignore
+ * Validate input data and execute route handler with appropriate middleware
+ *
+ * @param {Object} services - Available services
+ * @param {Object} matchedRoute - Information about the matched route
+ * @param {PikkuHTTP | undefined} http - HTTP interaction object
+ * @param {Object} options - Additional options
+ * @returns {Promise<any>} Result of the route handler
  */
-export const runHTTPRoute = async ({ singletonServices, request, response, createSessionServices, route: apiRoute, method: apiType, skipUserSession = false, respondWith404 = true, logWarningsForStatusCodes = [], coerceToArray = false, bubbleErrors = false, }) => {
+const executeRouteWithMiddleware = async (services, matchedRoute, http, options) => {
+    const { matchedPath, params, route, middleware, schemaName } = matchedRoute;
+    const { singletonServices, userSessionService, createSessionServices, skipUserSession, } = services;
+    const { coerceToArray } = options;
+    const requiresSession = route.auth !== false;
     let sessionServices;
-    const trackerId = crypto.randomUUID().toString();
-    const http = createHTTPInteraction(request, response);
-    const matchedRoute = getMatchingRoute(singletonServices.schemaService, apiType, apiRoute);
-    try {
-        if (!matchedRoute) {
+    let result;
+    http?.request?.setParams(params);
+    singletonServices.logger.info(`Matched route: ${route.route} | method: ${route.method.toUpperCase()} | auth: ${requiresSession.toString()}`);
+    // Main route execution function
+    const runMain = async () => {
+        const session = userSessionService.get();
+        // Validate session was set if needed
+        if (skipUserSession && requiresSession) {
+            throw new Error("Can't skip trying to get user session if auth is required");
+        }
+        if (requiresSession && !session) {
             singletonServices.logger.info({
-                message: 'Route not found',
-                apiRoute,
-                apiType,
+                action: 'Rejecting route (invalid session)',
+                path: matchedPath,
             });
-            throw new NotFoundError(`Route not found: ${apiRoute}`);
+            throw new MissingSessionError();
         }
-        const { matchedPath, params, route, schemaName } = matchedRoute;
-        const requiresSession = route.auth !== false;
-        http?.request?.setParams(params);
-        singletonServices.logger.info(`Matched route: ${route.route} | method: ${route.method.toUpperCase()} | auth: ${requiresSession.toString()}`);
-        const session = await loadUserSession(skipUserSession, requiresSession, http, matchedPath, route, singletonServices.logger, singletonServices.httpSessionService);
-        const data = await request.getData();
-        validateAndCoerce(singletonServices.logger, singletonServices.schemaService, schemaName, data, coerceToArray);
+        // Create session services
         sessionServices = await createSessionServices(singletonServices, { http }, session);
         const allServices = { ...singletonServices, ...sessionServices, http };
-        if (singletonServices.enforceHTTPAccess) {
-            await singletonServices.enforceHTTPAccess(route, session);
+        const data = await http?.request?.getData();
+        // Validate schema
+        validateSchema(singletonServices.logger, singletonServices.schemaService, schemaName, data);
+        if (coerceToArray && schemaName) {
+            coerceQueryStringToArray(schemaName, data);
         }
+        // Run permission checks
         const permissioned = await verifyPermissions(route.permissions, allServices, data, session);
         if (permissioned === false) {
             throw new ForbiddenError('Permission denied');
         }
-        const result = (await route.func(allServices, data, session));
+        // Execute the route handler
+        result = await route.func(allServices, data, session);
+        // Set the response
         if (route.returnsJSON === false) {
             http?.response?.setResponse(result);
         }
@@ -196,11 +226,52 @@ export const runHTTPRoute = async ({ singletonServices, request, response, creat
         http?.response?.setStatus(200);
         http?.response?.end();
         return result;
+    };
+    await runMiddleware({ ...singletonServices, userSessionService }, { http }, middleware, runMain);
+    return sessionServices ? { result, sessionServices } : { result };
+};
+/**
+ * Run an HTTP route with the given parameters
+ *
+ * @param {Object} options - Options for running the route
+ * @returns {Promise<Out | void>} Result of the route handler
+ * @ignore
+ */
+export const runHTTPRoute = async ({ singletonServices, request, response, createSessionServices, route: apiRoute, method: apiType, skipUserSession = false, respondWith404 = true, logWarningsForStatusCodes = [], coerceToArray = false, bubbleErrors = false, }) => {
+    const trackerId = crypto.randomUUID().toString();
+    const userSessionService = new LocalUserSessionService();
+    let sessionServices;
+    let result;
+    // Create HTTP interaction object
+    const http = createHTTPInteraction(request, response);
+    // Find matching route
+    const matchedRoute = getMatchingRoute(apiType, apiRoute);
+    try {
+        // Handle route not found
+        if (!matchedRoute) {
+            singletonServices.logger.info({
+                message: 'Route not found',
+                apiRoute,
+                apiType,
+            });
+            throw new NotFoundError(`Route not found: ${apiRoute}`);
+        }
+        // Execute route with middleware
+        ;
+        ({ result, sessionServices } = await executeRouteWithMiddleware({
+            singletonServices,
+            userSessionService,
+            createSessionServices,
+            skipUserSession,
+        }, matchedRoute, http, { coerceToArray }));
+        return result;
     }
     catch (e) {
+        // Handle and possibly bubble the error
         handleError(e, http, trackerId, singletonServices.logger, logWarningsForStatusCodes, respondWith404, bubbleErrors);
     }
     finally {
+        // Clean up session services
         if (sessionServices) {
             await closeSessionServices(singletonServices.logger, sessionServices);
         }

package/dist/http/http-routes.types.d.ts

@@ -1,5 +1,5 @@
 import { PikkuError } from '../errors/error-handler.js';
-import { APIDocs, CoreServices, CoreSingletonServices, CoreUserSession, CreateSessionServices } from '../types/core.types.js';
+import { APIDocs, CoreServices, CoreSingletonServices, CoreUserSession, CreateSessionServices, PikkuMiddleware } from '../types/core.types.js';
 import { CoreAPIFunction, CoreAPIFunctionSessionless, CoreAPIPermission } from '../types/functions.types.js';
 import { PikkuRequest } from '../pikku-request.js';
 import { PikkuResponse } from '../pikku-response.js';
@@ -65,18 +65,22 @@ export type PikkuQuery<T = Record<string, string | undefined>> = Record<string,
  * @template APIFunctionSessionless - The sessionless API function type, defaults to `CoreAPIFunctionSessionless`.
  * @template APIPermission - The permission function type, defaults to `CoreAPIPermission`.
  */
-export type CoreHTTPFunctionRoute<In, Out, R extends string, APIFunction = CoreAPIFunction<In, Out>, APIFunctionSessionless = CoreAPIFunctionSessionless<In, Out>, APIPermission = CoreAPIPermission<In>> = (CoreHTTPFunction & {
+export type CoreHTTPFunctionRoute<In, Out, R extends string, APIFunction = CoreAPIFunction<In, Out>, APIFunctionSessionless = CoreAPIFunctionSessionless<In, Out>, APIPermission = CoreAPIPermission<In>, APIMiddleware = PikkuMiddleware> = (CoreHTTPFunction & {
     route: R;
     method: HTTPMethod;
     func: APIFunction;
     permissions?: Record<string, APIPermission[] | APIPermission>;
     auth?: true;
+    tags?: string[];
+    middleware?: APIMiddleware[];
 }) | (CoreHTTPFunction & {
     route: R;
     method: HTTPMethod;
     func: APIFunctionSessionless;
     permissions?: undefined;
     auth?: false;
+    tags?: string[];
+    middleware?: APIMiddleware[];
 }) | (CoreHTTPFunction & {
     route: R;
     method: 'post';
@@ -84,6 +88,8 @@ export type CoreHTTPFunctionRoute<In, Out, R extends string, APIFunction = CoreA
     permissions?: Record<string, APIPermission[] | APIPermission>;
     auth?: true;
     query?: Array<keyof In>;
+    tags?: string[];
+    middleware?: APIMiddleware[];
 }) | (CoreHTTPFunction & {
     route: R;
     method: 'post';
@@ -91,6 +97,8 @@ export type CoreHTTPFunctionRoute<In, Out, R extends string, APIFunction = CoreA
     permissions?: undefined;
     auth?: false;
     query?: Array<keyof In>;
+    tags?: string[];
+    middleware?: APIMiddleware[];
 });
 /**
  * Represents an array of core API routes.
@@ -116,12 +124,10 @@ export type HTTPRoutesMeta = Array<{
     output: string | null;
     inputTypes?: HTTPFunctionMetaInputTypes;
     docs?: APIDocs;
+    tags?: string[];
 }>;
-/**
- * Verifies access to a route.
- * @param route - The route to verify access for.
- * @param session - The user session.
- * @returns A promise that resolves if access is granted.
- */
-export type enforceHTTPAccess = (route: CoreHTTPFunctionRoute<unknown, unknown, any>, session?: CoreUserSession) => Promise<void> | void;
+export type HTTPRouteMiddleware = {
+    route: string;
+    middleware: PikkuMiddleware[];
+};
 export {};

package/dist/http/index.d.ts

@@ -1,4 +1,3 @@
-export * from './pikku-http-session-service.js';
 export * from './pikku-http-abstract-request.js';
 export * from './pikku-http-abstract-response.js';
 export * from './log-http-routes.js';

package/dist/http/index.js

@@ -1,4 +1,3 @@
-export * from './pikku-http-session-service.js';
 export * from './pikku-http-abstract-request.js';
 export * from './pikku-http-abstract-response.js';
 export * from './log-http-routes.js';

package/dist/http/pikku-http-abstract-request.d.ts

@@ -1,12 +1,15 @@
 import { PikkuRequest } from '../pikku-request.js';
-import { PikkuQuery } from './http-routes.types.js';
+import { HTTPMethod, PikkuQuery } from './http-routes.types.js';
 /**
  * Abstract class representing a pikku request.
  * @template In - The type of the request body.
  * @group RequestResponse
  */
 export declare abstract class PikkuHTTPAbstractRequest<In = unknown> extends PikkuRequest<In> {
+    path: string;
+    method: HTTPMethod;
     private params;
+    constructor(path: string, method: HTTPMethod);
     /**
      * Retrieves the request body.
      * @returns A promise that resolves to the request body.

package/dist/http/pikku-http-abstract-request.js

@@ -6,7 +6,14 @@ import { PikkuRequest } from '../pikku-request.js';
  * @group RequestResponse
  */
 export class PikkuHTTPAbstractRequest extends PikkuRequest {
+    path;
+    method;
     params = {};
+    constructor(path, method) {
+        super();
+        this.path = path;
+        this.method = method;
+    }
     /**
      * Retrieves the raw request body as a Buffer.
      * @returns A promise that resolves to the raw request body.

package/dist/index.d.ts

@@ -9,6 +9,8 @@ export * from './services/index.js';
 export * from './http/index.js';
 export * from './channel/index.js';
 export * from './scheduler/index.js';
+export * from './errors/index.js';
+export * from './middleware/index.js';
 export { addRoute } from './http/http-route-runner.js';
 export { addChannel } from './channel/channel-runner.js';
 export { addScheduledTask } from './scheduler/scheduler-runner.js';

package/dist/index.js

@@ -9,6 +9,8 @@ export * from './services/index.js';
 export * from './http/index.js';
 export * from './channel/index.js';
 export * from './scheduler/index.js';
+export * from './errors/index.js';
+export * from './middleware/index.js';
 export { addRoute } from './http/http-route-runner.js';
 export { addChannel } from './channel/channel-runner.js';
 export { addScheduledTask } from './scheduler/scheduler-runner.js';

package/dist/middleware/auth-api-key.d.ts

@@ -0,0 +1,9 @@
+import { PikkuMiddleware } from '../types/core.types.js';
+/**
+ * API key middleware that retrieves a session from the 'x-api-key' header using a provided callback.
+ *
+ * @param options.getSessionForAPIKey - A function that returns a session when provided an API key.
+ */
+export declare const apiKeyMiddleware: (options?: {
+    getSessionForAPIKey?: (apiKey: string) => Promise<any>;
+}) => PikkuMiddleware;

package/dist/middleware/auth-api-key.js

@@ -0,0 +1,23 @@
+/**
+ * API key middleware that retrieves a session from the 'x-api-key' header using a provided callback.
+ *
+ * @param options.getSessionForAPIKey - A function that returns a session when provided an API key.
+ */
+export const apiKeyMiddleware = (options = {}) => {
+    const middleware = async ({ userSessionService }, { http }, next) => {
+        if (!http?.request || userSessionService.get()) {
+            return next();
+        }
+        if (options.getSessionForAPIKey) {
+            const apiKey = http.request.getHeader('x-api-key');
+            if (apiKey) {
+                const userSession = await options.getSessionForAPIKey(apiKey);
+                if (userSession) {
+                    await userSessionService.set(userSession);
+                }
+            }
+        }
+        return next();
+    };
+    return middleware;
+};

package/dist/middleware/auth-cookie-middleware.d.ts

@@ -0,0 +1,11 @@
+import { PikkuMiddleware } from '../types/core.types.js';
+/**
+ * Cookie middleware that extracts a session from cookies.
+ *
+ * @param options.cookieNames - List of cookie names to check.
+ * @param options.getSessionForCookieValue - Function to retrieve a session using a cookie value.
+ */
+export declare const cookieMiddleware: (options?: {
+    cookieNames?: string[];
+    getSessionForCookieValue?: (cookieValue: string, cookieName: string) => Promise<any>;
+}) => PikkuMiddleware;

package/dist/middleware/auth-cookie-middleware.js

@@ -0,0 +1,36 @@
+/**
+ * Cookie middleware that extracts a session from cookies.
+ *
+ * @param options.cookieNames - List of cookie names to check.
+ * @param options.getSessionForCookieValue - Function to retrieve a session using a cookie value.
+ */
+export const cookieMiddleware = (options = {}) => {
+    const middleware = async ({ userSessionService }, { http }, next) => {
+        if (!http?.request || userSessionService.get()) {
+            return next();
+        }
+        if (options.getSessionForCookieValue && options.cookieNames) {
+            const cookies = http.request.getCookies();
+            if (cookies) {
+                let cookieName;
+                for (const name of options.cookieNames) {
+                    if (cookies[name]) {
+                        cookieName = name;
+                        break;
+                    }
+                }
+                if (cookieName) {
+                    const cookieValue = cookies[cookieName];
+                    if (cookieValue) {
+                        const userSession = await options.getSessionForCookieValue(cookieValue, cookieName);
+                        if (userSession) {
+                            await userSessionService.set(userSession);
+                        }
+                    }
+                }
+            }
+        }
+        return next();
+    };
+    return middleware;
+};

package/dist/middleware/auth-jwt-middleware.d.ts

@@ -0,0 +1,10 @@
+import { PikkuMiddleware } from '../types/core.types.js';
+/**
+ * JWT middleware that extracts the Bearer token from the Authorization header,
+ * decodes it via the jwtService, and sets the session if found.
+ *
+ * @param options.debugJWTDecode - Optional flag for debugging the JWT decode process.
+ */
+export declare const jwtMiddleware: (options?: {
+    debugJWTDecode?: boolean;
+}) => PikkuMiddleware;

package/dist/middleware/auth-jwt-middleware.js

@@ -0,0 +1,32 @@
+import { InvalidSessionError } from '../errors/errors.js';
+/**
+ * JWT middleware that extracts the Bearer token from the Authorization header,
+ * decodes it via the jwtService, and sets the session if found.
+ *
+ * @param options.debugJWTDecode - Optional flag for debugging the JWT decode process.
+ */
+export const jwtMiddleware = (options = {}) => {
+    const middleware = async ({ jwt, userSessionService }, { http }, next) => {
+        if (!jwt) {
+            throw new Error('JWT service not found');
+        }
+        // Skip if session already exists.
+        if (!http?.request || userSessionService.get()) {
+            return next();
+        }
+        const authHeader = http.request.getHeader('authorization') ||
+            http.request.getHeader('Authorization');
+        if (authHeader) {
+            const [scheme, token] = authHeader.split(' ');
+            if (scheme !== 'Bearer' || !token) {
+                throw new InvalidSessionError();
+            }
+            const userSession = await jwt.decode(token, undefined, options.debugJWTDecode);
+            if (userSession) {
+                await userSessionService.set(userSession);
+            }
+        }
+        return next();
+    };
+    return middleware;
+};

package/dist/middleware/auth-query-middleware.d.ts

@@ -0,0 +1,10 @@
+import { PikkuQuery } from '../http/http-routes.types.js';
+import { PikkuMiddleware } from '../types/core.types.js';
+/**
+ * Query middleware that retrieves a session using query parameters.
+ *
+ * @param options.getSessionForQueryValue - A function that returns a session based on query parameters.
+ */
+export declare const queryMiddleware: (options?: {
+    getSessionForQueryValue?: (query: PikkuQuery) => Promise<any>;
+}) => PikkuMiddleware;

package/dist/middleware/auth-query-middleware.js

@@ -0,0 +1,21 @@
+/**
+ * Query middleware that retrieves a session using query parameters.
+ *
+ * @param options.getSessionForQueryValue - A function that returns a session based on query parameters.
+ */
+export const queryMiddleware = (options = {}) => {
+    const middleware = async ({ userSessionService }, { http }, next) => {
+        if (!http?.request || userSessionService.get()) {
+            return next();
+        }
+        if (options.getSessionForQueryValue) {
+            const query = http.request.getQuery();
+            const userSession = await options.getSessionForQueryValue(query);
+            if (userSession) {
+                await userSessionService.set(userSession);
+            }
+        }
+        return next();
+    };
+    return middleware;
+};