@react-foundry/fastify-auth 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (C) 2019-2025 Crown Copyright
+Copyright (C) 2019-2026 Daniel A.C. Martin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,117 @@
+React Foundry - Fastify-Auth
+============================
+
+Authentication plugin for Fastify. Allows you to authenticate uses by a variety
+of methods and obtain identity information and roles for use on each request.
+Also provides a session when requested or when required by the authentication
+method.
+
+
+Using this package
+------------------
+
+First install the package into your project:
+
+```shell
+npm install -S @react-foundry/fastify-auth
+```
+
+Then use it in your code as follows:
+
+```ts
+import Fastify from 'fastify';
+import { AuthMethod, fastifyAuth } from '@react-foundry/fastify-auth';
+
+const httpd = Fastify();
+
+httpd.register(fastifyAuth, {
+  privacy: false,
+  session: {
+    cookies: {
+      secret: 'changeme' // Change this to a secret string that is shared across instances of your application
+    }
+  },
+  method: AuthMethod.OIDC,
+  issuer: 'https://keycloak/realms/my-realm/', // Change this to the URL for your OIDC provider
+  clientId: 'my-client',                       // Change this to your client ID
+  clientSecret: 'my-client-secret',            // Change this to your client secret
+  redirectUri: 'https://my-website/'           // Change this to the base URL that the OIDC provider should redirect back to
+});
+
+httpd.get('/', async (req, _reply) => {
+  const user = req.user.username || 'guest';
+  const message = `Hello ${user}`;
+
+  return message;
+});
+
+await httpd.listen({
+  host: '::'
+  port: 8080
+});
+```
+
+
+### `fastifyAuth`
+
+A Fastify plugin which can be 'registered' with the following options.
+
+Options object:
+
+- **`method: 'none' | 'dummy' | 'headers' | 'basic' | 'oidc'`**
+  The method to use to authenticate users.
+  - `'none'`: No authentication (you might want this if you just want a
+              session).
+  - `'dummy'`: Dummy authentication; useful for testing.
+  - `'headers'`: Trusts auth information provided on HTTP headers (such as by a
+                 reverse proxy). **WARNING:** This is insecure when not behind a
+                 reverse authentication proxy.
+  - `'basic'`: HTTP [Basic authentication].
+  - `'oidc'`: [OpenID Connect]. (Such as [Keycloak] etc.)
+- **`privacy: boolean`**
+  When `true`, user must be authenticated to access any part of the website.
+  When `false`, users can still access the website but may not have access to
+  all features when those features require certain roles. Users can typically
+  choose to log-in to acquire extra permissions.
+- **`session: object`**
+  See: https://www.npmjs.com/package/@react-foundry/fastify-session
+
+
+### `req.user: object`
+
+An object representing the user data. Includes the `username` and `roles`. When
+using OIDC, it should also contain the `accessToken` for making requests to
+other services on behalf of the user.
+
+
+Working on this package
+-----------------------
+
+Before working on this package you must install its dependencies using
+the following command:
+
+```shell
+pnpm install
+```
+
+
+### Building
+
+Build the package by compiling the source code.
+
+```shell
+npm run build
+```
+
+
+### Clean-up
+
+Remove any previously built files.
+
+```shell
+npm run clean
+```
+
+[Basic authentication]: https://en.wikipedia.org/wiki/Basic_access_authentication
+[OpenID Connect]: https://en.wikipedia.org/wiki/OpenID#OpenID_Connect_(OIDC)
+[Keycloak]: https://www.keycloak.org/

package/dist/basic.d.ts

@@ -0,0 +1,10 @@
+import { AuthBagger } from './common';
+export type Options = {
+    username: string;
+    password: string;
+    roles?: string[];
+    realm?: string;
+    charset?: BufferEncoding;
+};
+export declare const basic: AuthBagger<Options>;
+export default basic;

package/dist/basic.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.basic = void 0;
+const error_1 = require("@fastify/error");
+const authPrefix = 'Basic ';
+const BadHeader = (0, error_1.createError)('FST_BAD_HEADER', 'Malformed Authorization header', 400);
+const AuthFailed = (0, error_1.createError)('FST_BASIC_AUTH_FAILED', 'Incorrect or missing authentication details', 401);
+const basic = ({ password, roles = [], username, realm = 'members', charset = 'utf-8' }, _fullSessions) => {
+    const base64Decode = (s) => Buffer.from(s, 'base64').toString(charset);
+    const decodeHeader = (s) => {
+        try {
+            return base64Decode(s.substring(authPrefix.length)).split(':');
+        }
+        catch (_err) {
+            throw new BadHeader();
+        }
+    };
+    return {
+        authenticate: (req, reply) => {
+            const authHeader = req.headers['authorization'] || '';
+            const [suppliedUsername, suppliedPassword] = (authHeader.startsWith(authPrefix)
+                ? decodeHeader(authHeader)
+                : []);
+            if (suppliedUsername === username && suppliedPassword === password) {
+                const user = {
+                    username,
+                    roles
+                };
+                req.user = user;
+            }
+            else {
+                reply.header('WWW-Authenticate', `Basic realm="${realm}", charset="${charset}"`);
+                throw new AuthFailed();
+            }
+        },
+        wantSession: false
+    };
+};
+exports.basic = basic;
+exports.default = exports.basic;

package/dist/basic.mjs

@@ -0,0 +1,36 @@
+import { createError } from '@fastify/error';
+const authPrefix = 'Basic ';
+const BadHeader = createError('FST_BAD_HEADER', 'Malformed Authorization header', 400);
+const AuthFailed = createError('FST_BASIC_AUTH_FAILED', 'Incorrect or missing authentication details', 401);
+export const basic = ({ password, roles = [], username, realm = 'members', charset = 'utf-8' }, _fullSessions) => {
+    const base64Decode = (s) => Buffer.from(s, 'base64').toString(charset);
+    const decodeHeader = (s) => {
+        try {
+            return base64Decode(s.substring(authPrefix.length)).split(':');
+        }
+        catch (_err) {
+            throw new BadHeader();
+        }
+    };
+    return {
+        authenticate: (req, reply) => {
+            const authHeader = req.headers['authorization'] || '';
+            const [suppliedUsername, suppliedPassword] = (authHeader.startsWith(authPrefix)
+                ? decodeHeader(authHeader)
+                : []);
+            if (suppliedUsername === username && suppliedPassword === password) {
+                const user = {
+                    username,
+                    roles
+                };
+                req.user = user;
+            }
+            else {
+                reply.header('WWW-Authenticate', `Basic realm="${realm}", charset="${charset}"`);
+                throw new AuthFailed();
+            }
+        },
+        wantSession: false
+    };
+};
+export default basic;

package/dist/common.d.ts

@@ -0,0 +1,48 @@
+import type { FastifyInstance } from 'fastify';
+import type { Request as _Request, RequestFull as _RequestFull, Reply, ReplyFull } from '@react-foundry/fastify-session';
+export type Promised<T> = T | Promise<T>;
+export type Maybe<T> = T | undefined;
+export type UserProfile = {
+    provider?: string;
+    id?: string;
+    displayName?: string;
+    name?: {
+        familyName?: string;
+        givenName?: string;
+        middleName?: string;
+    };
+    emails?: Array<{
+        value: string;
+        type?: string;
+    }>;
+    photos?: Array<{
+        value: string;
+    }>;
+    username: string;
+    groups?: string[];
+    roles: string[];
+    expiry?: Date;
+};
+type RequestExtras = {
+    user?: UserProfile;
+};
+export type Request = _Request & Partial<RequestExtras>;
+export type RequestFull = _RequestFull & RequestExtras;
+export type SubRouteHandlerMethod = (request: RequestFull, reply: Reply) => Promised<unknown | void>;
+export type RouteHandlerMethod = (this: FastifyInstance, request: Request, reply: Reply) => Promised<unknown | void>;
+type UserExtractor = (req: _Request) => Maybe<UserProfile>;
+export declare const fromExtractor: (extractor: UserExtractor) => SubRouteHandlerMethod;
+export type Serialize<A extends UserProfile = UserProfile, B = Partial<A>> = (user: A, req: Request) => Promised<B>;
+export type Deserialize<A extends UserProfile = UserProfile, B = Partial<A>> = (data: B, req: Request) => Promised<Maybe<A>>;
+export type SerDes<T = UserProfile> = (data: T, req: Request) => Promised<T>;
+export type AuthBag = {
+    authenticate: SubRouteHandlerMethod;
+    callback?: SubRouteHandlerMethod;
+    serialize?: Serialize;
+    deserialize?: Deserialize;
+    terminate?: SubRouteHandlerMethod;
+    wantSession: boolean;
+};
+export type AuthBagger<T> = (config: T, fullSessions: boolean) => Promised<AuthBag>;
+export declare const id: <T>(x: T) => T;
+export type { Reply, ReplyFull };

package/dist/common.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.id = exports.fromExtractor = void 0;
+const fromExtractor = (extractor) => (req, _reply) => {
+    req.user = extractor(req);
+};
+exports.fromExtractor = fromExtractor;
+const id = (x) => x;
+exports.id = id;

package/dist/common.mjs

@@ -0,0 +1,4 @@
+export const fromExtractor = (extractor) => (req, _reply) => {
+    req.user = extractor(req);
+};
+export const id = (x) => x;

package/dist/dummy.d.ts

@@ -0,0 +1,8 @@
+import type { AuthBagger } from './common';
+export type Options = {
+    username: string;
+    groups?: string[];
+    roles?: string[];
+};
+export declare const dummy: AuthBagger<Options>;
+export default dummy;

package/dist/dummy.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dummy = void 0;
+const common_1 = require("./common");
+const dummy = ({ username, groups = [], roles = [], }, _fullSessions) => ({
+    authenticate: (0, common_1.fromExtractor)((_) => ({
+        username,
+        groups,
+        roles
+    })),
+    wantSession: false
+});
+exports.dummy = dummy;
+exports.default = exports.dummy;

package/dist/dummy.mjs

@@ -0,0 +1,10 @@
+import { fromExtractor } from './common';
+export const dummy = ({ username, groups = [], roles = [], }, _fullSessions) => ({
+    authenticate: fromExtractor((_) => ({
+        username,
+        groups,
+        roles
+    })),
+    wantSession: false
+});
+export default dummy;

package/dist/headers.d.ts

@@ -0,0 +1,8 @@
+import type { AuthBagger } from './common';
+export type Options = {
+    usernameHeader?: string;
+    groupsHeader?: string;
+    rolesHeader?: string;
+};
+export declare const headers: AuthBagger<Options>;
+export default headers;

package/dist/headers.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.headers = void 0;
+const common_1 = require("./common");
+const valueFromHeader = (header) => (Array.isArray(header)
+    ? header[0]
+    : header);
+const headers = ({ groupsHeader = 'x-auth-groups', rolesHeader = 'x-auth-roles', usernameHeader = 'x-auth-username' }, _fullSessions) => ({
+    authenticate: (0, common_1.fromExtractor)((req) => {
+        const username = valueFromHeader(req.headers[usernameHeader]);
+        const groups = valueFromHeader(req.headers[groupsHeader]);
+        const roles = valueFromHeader(req.headers[rolesHeader]);
+        return (username && roles
+            ? {
+                username: username,
+                groups: groups?.split(',') || [],
+                roles: roles?.split(',') || []
+            }
+            : undefined);
+    }),
+    wantSession: false
+});
+exports.headers = headers;
+exports.default = exports.headers;

package/dist/headers.mjs

@@ -0,0 +1,20 @@
+import { fromExtractor } from './common';
+const valueFromHeader = (header) => (Array.isArray(header)
+    ? header[0]
+    : header);
+export const headers = ({ groupsHeader = 'x-auth-groups', rolesHeader = 'x-auth-roles', usernameHeader = 'x-auth-username' }, _fullSessions) => ({
+    authenticate: fromExtractor((req) => {
+        const username = valueFromHeader(req.headers[usernameHeader]);
+        const groups = valueFromHeader(req.headers[groupsHeader]);
+        const roles = valueFromHeader(req.headers[rolesHeader]);
+        return (username && roles
+            ? {
+                username: username,
+                groups: groups?.split(',') || [],
+                roles: roles?.split(',') || []
+            }
+            : undefined);
+    }),
+    wantSession: false
+});
+export default headers;

package/dist/index.d.ts

@@ -0,0 +1,42 @@
+import type { FastifyPluginCallback } from 'fastify';
+import type { RateLimitOptions, RateLimitPluginOptions } from '@fastify/rate-limit';
+import type { FastifySessionOptions } from '@react-foundry/fastify-session';
+import type { Options as _BasicOptions } from './basic';
+import type { Options as _DummyOptions } from './dummy';
+import type { Options as _HeadersOptions } from './headers';
+import type { Options as _OIDCOptions } from './oidc';
+import type { Reply, Request, RequestFull } from './common';
+export declare enum AuthMethod {
+    None = "none",
+    Dummy = "dummy",
+    Headers = "headers",
+    Basic = "basic",
+    OIDC = "oidc"
+}
+type Method<T> = {
+    method: T;
+};
+type NoneOptions = Method<AuthMethod.None> | {
+    method?: undefined;
+};
+type DummyOptions = Method<AuthMethod.Dummy> & _DummyOptions;
+type HeadersOptions = Method<AuthMethod.Headers> & _HeadersOptions;
+type BasicOptions = Method<AuthMethod.Basic> & _BasicOptions;
+type OIDCOptions = Method<AuthMethod.OIDC> & _OIDCOptions;
+type MethodOptions = NoneOptions | DummyOptions | HeadersOptions | BasicOptions | OIDCOptions;
+export type FastifyAuthPluginOptions = MethodOptions & {
+    privacy?: boolean;
+    pathPrefix?: string;
+    session?: FastifySessionOptions;
+    signInPath?: string;
+    signOutPath?: string;
+    callbackPath?: string;
+    redirectPath?: string;
+    rateLimit?: Omit<RateLimitPluginOptions, 'global'>;
+    authRateLimit?: RateLimitOptions;
+};
+export declare const fastifyAuth: FastifyPluginCallback<FastifyAuthPluginOptions>;
+export default fastifyAuth;
+export type { FastifyAuthPluginOptions as FastifyAuthOptions, Reply, Request, RequestFull, };
+export type { ReplyFull, RouteHandlerMethod } from './common';
+export { SessionStore } from '@react-foundry/fastify-session';

package/dist/index.js

@@ -0,0 +1,188 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SessionStore = exports.fastifyAuth = exports.AuthMethod = void 0;
+const fastify_plugin_1 = __importDefault(require("fastify-plugin"));
+const rate_limit_1 = __importDefault(require("@fastify/rate-limit"));
+const fastify_session_1 = __importStar(require("@react-foundry/fastify-session"));
+const basic_1 = require("./basic");
+const dummy_1 = require("./dummy");
+const headers_1 = require("./headers");
+const oidc_1 = require("./oidc");
+var AuthMethod;
+(function (AuthMethod) {
+    AuthMethod["None"] = "none";
+    AuthMethod["Dummy"] = "dummy";
+    AuthMethod["Headers"] = "headers";
+    AuthMethod["Basic"] = "basic";
+    AuthMethod["OIDC"] = "oidc";
+})(AuthMethod || (exports.AuthMethod = AuthMethod = {}));
+;
+const isNone = (v) => v.method === AuthMethod.None || v.method === undefined;
+const isDummy = (v) => v.method === AuthMethod.Dummy;
+const isHeaders = (v) => v.method === AuthMethod.Headers;
+const isBasic = (v) => v.method === AuthMethod.Basic;
+const isOIDC = (v) => v.method === AuthMethod.OIDC;
+const fastifyAuthPlugin = async (fastify, { privacy = true, pathPrefix = '/auth/', session = {}, signInPath = 'sign-in', signOutPath = 'sign-out', callbackPath = 'callback', redirectPath = '/', rateLimit: _rateLimit = {
+    max: 60,
+    timeWindow: 60000,
+}, authRateLimit = {
+    max: 100,
+    timeWindow: 15 * 60000
+}, ...methodOptions }) => {
+    const fullSessions = !!(session.store && session.store !== fastify_session_1.SessionStore.Cookie);
+    const serDes = (user, _req) => user;
+    const redact = (user, _req) => ({
+        username: user.username,
+        roles: user.roles
+    });
+    const _serialize = (fullSessions
+        ? serDes
+        : redact);
+    const redirect = async (_req, reply) => {
+        return reply.redirect(redirectPath, 302);
+    };
+    const rateLimit = _rateLimit && {
+        ..._rateLimit,
+        global: privacy
+    };
+    const authConfig = {
+        config: {
+            rateLimit: authRateLimit
+        }
+    };
+    const { authenticate, callback, deserialize = serDes, serialize = _serialize, terminate, wantSession } = await (isDummy(methodOptions) ? (0, dummy_1.dummy)(methodOptions, fullSessions)
+        : isHeaders(methodOptions) ? (0, headers_1.headers)(methodOptions, fullSessions)
+            : isBasic(methodOptions) ? (0, basic_1.basic)(methodOptions, fullSessions)
+                : isOIDC(methodOptions) ? (0, oidc_1.oidc)(methodOptions, fullSessions)
+                    : {});
+    const useSession = wantSession || !privacy;
+    const whitelist = (callback
+        ? [pathPrefix + callbackPath, pathPrefix + signOutPath]
+        : [pathPrefix + signOutPath]);
+    fastify.decorateRequest('user', null);
+    if (!fastify.hasDecorator('rateLimit') && (authenticate || callback)) {
+        fastify.register(rate_limit_1.default, rateLimit);
+    }
+    if (authenticate) {
+        if (useSession) {
+            fastify.addHook('onSend', async (req, _reply, _payload) => {
+                if (req.user) {
+                    if (req.session) {
+                        req.session.user = await serialize(req.user, req);
+                    }
+                    else {
+                        req.log.error('Unable to store session');
+                    }
+                }
+            });
+        }
+    }
+    if (useSession || session.store) {
+        if (!session.store) {
+            fastify.log.info('Session required for authentication; registering plugin...');
+        }
+        fastify.register(fastify_session_1.default, session);
+    }
+    if (authenticate) {
+        if (useSession) {
+            fastify.addHook('preHandler', async (req, _reply) => {
+                if (req.session?.user) {
+                    req.user = await deserialize(req.session.user, req);
+                    if (req.user) {
+                        req.log.debug(`User, '${req.user.username}', authenticated from session`);
+                    }
+                    else {
+                        req.log.info('Failed to authenticate from session; ending session...');
+                        delete req.session.user;
+                    }
+                }
+            });
+        }
+        if (privacy) {
+            fastify.addHook('preHandler', async (req, reply) => {
+                if (!req.user && !whitelist.includes(req.url)) {
+                    const r = await authenticate(req, reply);
+                    if (!callback) {
+                        const username = req.user?.username;
+                        req.log.debug(`User, '${username}', authenticated`);
+                    }
+                    return r;
+                }
+            });
+        }
+        else {
+            fastify.get(pathPrefix + signInPath, authConfig, async (req, reply) => {
+                const r = await authenticate(req, reply);
+                if (!callback) {
+                    req.log.debug(`User, '${req.user?.username}', authenticated`);
+                }
+                return (reply.sent
+                    ? r
+                    : redirect(req, reply));
+            });
+        }
+        if (callback) {
+            fastify.get(pathPrefix + callbackPath, authConfig, async (req, reply) => {
+                const r = await callback(req, reply);
+                req.log.debug(`User, '${req.user?.username}', authenticated`);
+                return (reply.sent
+                    ? r
+                    : redirect(req, reply));
+            });
+        }
+        fastify.get(pathPrefix + signOutPath, async (req, reply) => {
+            if (useSession && req.session?.user) {
+                delete req.user;
+                delete req.session.user;
+            }
+            const r = await terminate?.(req, reply);
+            req.log.debug('User logged out');
+            return (reply.sent
+                ? r
+                : redirect(req, reply));
+        });
+    }
+};
+exports.fastifyAuth = (0, fastify_plugin_1.default)(fastifyAuthPlugin, {
+    fastify: '5.x',
+    name: 'auth',
+});
+exports.default = exports.fastifyAuth;
+var fastify_session_2 = require("@react-foundry/fastify-session");
+Object.defineProperty(exports, "SessionStore", { enumerable: true, get: function () { return fastify_session_2.SessionStore; } });

package/dist/index.mjs

@@ -0,0 +1,148 @@
+import fp from 'fastify-plugin';
+import fastifyRateLimit from '@fastify/rate-limit';
+import fastifySession, { SessionStore } from '@react-foundry/fastify-session';
+import { basic } from './basic';
+import { dummy } from './dummy';
+import { headers } from './headers';
+import { oidc } from './oidc';
+export var AuthMethod;
+(function (AuthMethod) {
+    AuthMethod["None"] = "none";
+    AuthMethod["Dummy"] = "dummy";
+    AuthMethod["Headers"] = "headers";
+    AuthMethod["Basic"] = "basic";
+    AuthMethod["OIDC"] = "oidc";
+})(AuthMethod || (AuthMethod = {}));
+;
+const isNone = (v) => v.method === AuthMethod.None || v.method === undefined;
+const isDummy = (v) => v.method === AuthMethod.Dummy;
+const isHeaders = (v) => v.method === AuthMethod.Headers;
+const isBasic = (v) => v.method === AuthMethod.Basic;
+const isOIDC = (v) => v.method === AuthMethod.OIDC;
+const fastifyAuthPlugin = async (fastify, { privacy = true, pathPrefix = '/auth/', session = {}, signInPath = 'sign-in', signOutPath = 'sign-out', callbackPath = 'callback', redirectPath = '/', rateLimit: _rateLimit = {
+    max: 60,
+    timeWindow: 60000,
+}, authRateLimit = {
+    max: 100,
+    timeWindow: 15 * 60000
+}, ...methodOptions }) => {
+    const fullSessions = !!(session.store && session.store !== SessionStore.Cookie);
+    const serDes = (user, _req) => user;
+    const redact = (user, _req) => ({
+        username: user.username,
+        roles: user.roles
+    });
+    const _serialize = (fullSessions
+        ? serDes
+        : redact);
+    const redirect = async (_req, reply) => {
+        return reply.redirect(redirectPath, 302);
+    };
+    const rateLimit = _rateLimit && {
+        ..._rateLimit,
+        global: privacy
+    };
+    const authConfig = {
+        config: {
+            rateLimit: authRateLimit
+        }
+    };
+    const { authenticate, callback, deserialize = serDes, serialize = _serialize, terminate, wantSession } = await (isDummy(methodOptions) ? dummy(methodOptions, fullSessions)
+        : isHeaders(methodOptions) ? headers(methodOptions, fullSessions)
+            : isBasic(methodOptions) ? basic(methodOptions, fullSessions)
+                : isOIDC(methodOptions) ? oidc(methodOptions, fullSessions)
+                    : {});
+    const useSession = wantSession || !privacy;
+    const whitelist = (callback
+        ? [pathPrefix + callbackPath, pathPrefix + signOutPath]
+        : [pathPrefix + signOutPath]);
+    fastify.decorateRequest('user', null);
+    if (!fastify.hasDecorator('rateLimit') && (authenticate || callback)) {
+        fastify.register(fastifyRateLimit, rateLimit);
+    }
+    if (authenticate) {
+        if (useSession) {
+            fastify.addHook('onSend', async (req, _reply, _payload) => {
+                if (req.user) {
+                    if (req.session) {
+                        req.session.user = await serialize(req.user, req);
+                    }
+                    else {
+                        req.log.error('Unable to store session');
+                    }
+                }
+            });
+        }
+    }
+    if (useSession || session.store) {
+        if (!session.store) {
+            fastify.log.info('Session required for authentication; registering plugin...');
+        }
+        fastify.register(fastifySession, session);
+    }
+    if (authenticate) {
+        if (useSession) {
+            fastify.addHook('preHandler', async (req, _reply) => {
+                if (req.session?.user) {
+                    req.user = await deserialize(req.session.user, req);
+                    if (req.user) {
+                        req.log.debug(`User, '${req.user.username}', authenticated from session`);
+                    }
+                    else {
+                        req.log.info('Failed to authenticate from session; ending session...');
+                        delete req.session.user;
+                    }
+                }
+            });
+        }
+        if (privacy) {
+            fastify.addHook('preHandler', async (req, reply) => {
+                if (!req.user && !whitelist.includes(req.url)) {
+                    const r = await authenticate(req, reply);
+                    if (!callback) {
+                        const username = req.user?.username;
+                        req.log.debug(`User, '${username}', authenticated`);
+                    }
+                    return r;
+                }
+            });
+        }
+        else {
+            fastify.get(pathPrefix + signInPath, authConfig, async (req, reply) => {
+                const r = await authenticate(req, reply);
+                if (!callback) {
+                    req.log.debug(`User, '${req.user?.username}', authenticated`);
+                }
+                return (reply.sent
+                    ? r
+                    : redirect(req, reply));
+            });
+        }
+        if (callback) {
+            fastify.get(pathPrefix + callbackPath, authConfig, async (req, reply) => {
+                const r = await callback(req, reply);
+                req.log.debug(`User, '${req.user?.username}', authenticated`);
+                return (reply.sent
+                    ? r
+                    : redirect(req, reply));
+            });
+        }
+        fastify.get(pathPrefix + signOutPath, async (req, reply) => {
+            if (useSession && req.session?.user) {
+                delete req.user;
+                delete req.session.user;
+            }
+            const r = await terminate?.(req, reply);
+            req.log.debug('User logged out');
+            return (reply.sent
+                ? r
+                : redirect(req, reply));
+        });
+    }
+};
+export const fastifyAuth = fp(fastifyAuthPlugin, {
+    fastify: '5.x',
+    name: 'auth',
+});
+export default fastifyAuth;
+export { SessionStore } from '@react-foundry/fastify-session';

package/dist/oidc.d.ts

@@ -0,0 +1,18 @@
+import type { AuthBagger, UserProfile } from './common';
+export type Options = {
+    issuer: string;
+    clientId: string;
+    clientSecret?: string;
+    redirectUri: string;
+};
+export type AuthInfo = UserProfile & {
+    accessToken?: string;
+    accessTokenValid?: boolean;
+    refreshToken?: string;
+    refreshTokenValid?: boolean;
+    idToken?: string;
+    idTokenValid?: boolean;
+    userinfo?: object;
+};
+export declare const oidc: AuthBagger<Options>;
+export default oidc;

package/dist/oidc.js

@@ -0,0 +1,198 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.oidc = void 0;
+const base64url_1 = __importDefault(require("base64url"));
+const openid_client_1 = require("openid-client");
+const error_1 = require("@fastify/error");
+const common_1 = require("./common");
+const resourceToRoles = (acc, [x, y]) => ([
+    ...acc,
+    ...(y.roles?.map((e) => `${x}:${e}`) || [])
+]);
+const BadSession = (0, error_1.createError)('FST_BAD_SESSION', 'Unable to verify session', 409);
+const oidc = async ({ clientId, clientSecret, issuer, redirectUri: _redirectUri }, fullSessions) => {
+    openid_client_1.custom.setHttpOptionsDefaults({
+        timeout: 5000,
+    });
+    const redirectUri = _redirectUri + '/auth/callback';
+    const iss = await openid_client_1.Issuer.discover(issuer);
+    const client = new iss.Client({
+        client_id: clientId,
+        client_secret: clientSecret,
+        redirect_uris: [redirectUri],
+        token_endpoint_auth_method: (clientSecret
+            ? 'client_secret_basic'
+            : 'none')
+    });
+    const authInfo = (accessToken, refreshToken, idToken, userinfo = {}) => {
+        const extractJWTClaims = (token) => token && JSON.parse(base64url_1.default.decode(token.split('.')[1])) || {};
+        const accessClaims = extractJWTClaims(accessToken);
+        const idClaims = extractJWTClaims(idToken);
+        const refreshClaims = extractJWTClaims(refreshToken);
+        const data = {
+            ...accessClaims,
+            ...idClaims,
+            ...userinfo,
+            accessToken,
+            refreshToken,
+            idToken,
+            userinfo
+        };
+        const expiry = new Date((refreshClaims.exp || accessClaims.exp) * 1000);
+        const now = Math.floor(Date.now() / 1000);
+        const isValid = ({ nbf = 0, exp = 0 }) => ((nbf <= now) && (now < exp));
+        const accessTokenValid = isValid(accessClaims);
+        const refreshTokenValid = isValid(refreshClaims);
+        const idTokenValid = isValid(idClaims);
+        return {
+            provider: 'oidc',
+            id: data.sub,
+            displayName: data.displayName || data.name,
+            name: {
+                familyName: data.familyName || data.family_name,
+                givenName: data.givenName || data.given_name,
+                middleName: data.middleName || data.middle_name
+            },
+            emails: (data.email
+                ? [{ value: data.email }]
+                : undefined),
+            photos: (data.photo
+                ? [{ value: data.photo }]
+                : undefined),
+            username: data.username || data.preferred_username,
+            groups: data.groups,
+            roles: [
+                ...(data.roles || []),
+                ...(data.realm_access?.roles || []),
+                ...(Object.entries(data.resource_access || {}).reduce(resourceToRoles, []))
+            ].filter(common_1.id),
+            accessToken: data.accessToken,
+            accessTokenValid,
+            refreshToken: data.refreshToken,
+            refreshTokenValid,
+            idToken: data.idToken,
+            idTokenValid,
+            userinfo: data.userinfo,
+            expiry
+        };
+    };
+    const serialize = (user, req) => {
+        if (fullSessions) {
+            return user;
+        }
+        else {
+            const cookieLimit = 4096;
+            const encryptionCost = 1.5;
+            const smallEnough = (v) => (JSON.stringify(v).length * encryptionCost <= cookieLimit);
+            const payload = {
+                accessToken: user.accessToken,
+                refreshToken: user.refreshToken,
+                idToken: user.idToken,
+                userinfo: user.userinfo
+            };
+            if (smallEnough(payload)) {
+                return payload;
+            }
+            else {
+                delete payload.userinfo;
+                if (smallEnough(payload)) {
+                    return payload;
+                }
+                else {
+                    delete payload.idToken;
+                    if (smallEnough(payload)) {
+                        return payload;
+                    }
+                    else {
+                        delete payload.refreshToken;
+                        req.log.warn('Cannot fit refresh token in session; session will expire early');
+                        return payload;
+                    }
+                }
+            }
+        }
+    };
+    const deserialize = async ({ accessToken, refreshToken, idToken, userinfo }, req) => {
+        const user = authInfo(accessToken, refreshToken, idToken, userinfo || {});
+        if (user.username && user.accessTokenValid) {
+            return user;
+        }
+        else if (!user.accessTokenValid && refreshToken && user.refreshTokenValid) {
+            try {
+                const tokenSet = await client.refresh(refreshToken);
+                req.log.info('Obtained new access token');
+                const newUser = authInfo(tokenSet.access_token, tokenSet.refresh_token, tokenSet.id_token, userinfo || {});
+                if (newUser.username && newUser.accessTokenValid) {
+                    return newUser;
+                }
+                else {
+                    req.log.error('Access token was invalid');
+                    return undefined;
+                }
+            }
+            catch (_err) {
+                req.log.error('Failed to obtain new access token');
+                return undefined;
+            }
+        }
+        else {
+            req.log.info('Access token has expired and cannot renew');
+            return undefined;
+        }
+    };
+    const authenticate = async (req, reply) => {
+        const codeVerifier = openid_client_1.generators.codeVerifier();
+        const codeChallenge = openid_client_1.generators.codeChallenge(codeVerifier);
+        const state = openid_client_1.generators.state();
+        const redirectTo = client.authorizationUrl({
+            scope: 'openid',
+            state,
+            code_challenge: codeChallenge,
+            code_challenge_method: 'S256'
+        });
+        const sessionObj = {
+            codeVerifier,
+            state
+        };
+        req.session.oidc = sessionObj;
+        return reply.redirect(redirectTo);
+    };
+    const callback = async (req, reply) => {
+        const sessionObj = (req.session.oidc || {});
+        delete req.session.oidc;
+        const { codeVerifier, state } = sessionObj;
+        if (!(codeVerifier && state)) {
+            throw new BadSession();
+        }
+        const checks = {
+            code_verifier: codeVerifier,
+            state
+        };
+        const params = client.callbackParams(req.raw);
+        const tokenSet = await client.callback(redirectUri, params, checks);
+        const userinfo = await client.userinfo(tokenSet);
+        const user = authInfo(tokenSet.access_token, tokenSet.refresh_token, tokenSet.id_token, userinfo);
+        if (user.username) {
+            req.user = user;
+        }
+    };
+    const terminate = async (req, reply) => {
+        const redirectTo = client.endSessionUrl({
+            post_logout_redirect_uri: _redirectUri
+        });
+        return reply.redirect(redirectTo);
+    };
+    return {
+        authenticate,
+        callback,
+        deserialize,
+        serialize,
+        terminate,
+        wantSession: true
+    };
+};
+exports.oidc = oidc;
+exports.default = exports.oidc;

package/dist/oidc.mjs

@@ -0,0 +1,191 @@
+import base64url from 'base64url';
+import { Issuer, custom, generators } from 'openid-client';
+import { createError } from '@fastify/error';
+import { id } from './common';
+const resourceToRoles = (acc, [x, y]) => ([
+    ...acc,
+    ...(y.roles?.map((e) => `${x}:${e}`) || [])
+]);
+const BadSession = createError('FST_BAD_SESSION', 'Unable to verify session', 409);
+export const oidc = async ({ clientId, clientSecret, issuer, redirectUri: _redirectUri }, fullSessions) => {
+    custom.setHttpOptionsDefaults({
+        timeout: 5000,
+    });
+    const redirectUri = _redirectUri + '/auth/callback';
+    const iss = await Issuer.discover(issuer);
+    const client = new iss.Client({
+        client_id: clientId,
+        client_secret: clientSecret,
+        redirect_uris: [redirectUri],
+        token_endpoint_auth_method: (clientSecret
+            ? 'client_secret_basic'
+            : 'none')
+    });
+    const authInfo = (accessToken, refreshToken, idToken, userinfo = {}) => {
+        const extractJWTClaims = (token) => token && JSON.parse(base64url.decode(token.split('.')[1])) || {};
+        const accessClaims = extractJWTClaims(accessToken);
+        const idClaims = extractJWTClaims(idToken);
+        const refreshClaims = extractJWTClaims(refreshToken);
+        const data = {
+            ...accessClaims,
+            ...idClaims,
+            ...userinfo,
+            accessToken,
+            refreshToken,
+            idToken,
+            userinfo
+        };
+        const expiry = new Date((refreshClaims.exp || accessClaims.exp) * 1000);
+        const now = Math.floor(Date.now() / 1000);
+        const isValid = ({ nbf = 0, exp = 0 }) => ((nbf <= now) && (now < exp));
+        const accessTokenValid = isValid(accessClaims);
+        const refreshTokenValid = isValid(refreshClaims);
+        const idTokenValid = isValid(idClaims);
+        return {
+            provider: 'oidc',
+            id: data.sub,
+            displayName: data.displayName || data.name,
+            name: {
+                familyName: data.familyName || data.family_name,
+                givenName: data.givenName || data.given_name,
+                middleName: data.middleName || data.middle_name
+            },
+            emails: (data.email
+                ? [{ value: data.email }]
+                : undefined),
+            photos: (data.photo
+                ? [{ value: data.photo }]
+                : undefined),
+            username: data.username || data.preferred_username,
+            groups: data.groups,
+            roles: [
+                ...(data.roles || []),
+                ...(data.realm_access?.roles || []),
+                ...(Object.entries(data.resource_access || {}).reduce(resourceToRoles, []))
+            ].filter(id),
+            accessToken: data.accessToken,
+            accessTokenValid,
+            refreshToken: data.refreshToken,
+            refreshTokenValid,
+            idToken: data.idToken,
+            idTokenValid,
+            userinfo: data.userinfo,
+            expiry
+        };
+    };
+    const serialize = (user, req) => {
+        if (fullSessions) {
+            return user;
+        }
+        else {
+            const cookieLimit = 4096;
+            const encryptionCost = 1.5;
+            const smallEnough = (v) => (JSON.stringify(v).length * encryptionCost <= cookieLimit);
+            const payload = {
+                accessToken: user.accessToken,
+                refreshToken: user.refreshToken,
+                idToken: user.idToken,
+                userinfo: user.userinfo
+            };
+            if (smallEnough(payload)) {
+                return payload;
+            }
+            else {
+                delete payload.userinfo;
+                if (smallEnough(payload)) {
+                    return payload;
+                }
+                else {
+                    delete payload.idToken;
+                    if (smallEnough(payload)) {
+                        return payload;
+                    }
+                    else {
+                        delete payload.refreshToken;
+                        req.log.warn('Cannot fit refresh token in session; session will expire early');
+                        return payload;
+                    }
+                }
+            }
+        }
+    };
+    const deserialize = async ({ accessToken, refreshToken, idToken, userinfo }, req) => {
+        const user = authInfo(accessToken, refreshToken, idToken, userinfo || {});
+        if (user.username && user.accessTokenValid) {
+            return user;
+        }
+        else if (!user.accessTokenValid && refreshToken && user.refreshTokenValid) {
+            try {
+                const tokenSet = await client.refresh(refreshToken);
+                req.log.info('Obtained new access token');
+                const newUser = authInfo(tokenSet.access_token, tokenSet.refresh_token, tokenSet.id_token, userinfo || {});
+                if (newUser.username && newUser.accessTokenValid) {
+                    return newUser;
+                }
+                else {
+                    req.log.error('Access token was invalid');
+                    return undefined;
+                }
+            }
+            catch (_err) {
+                req.log.error('Failed to obtain new access token');
+                return undefined;
+            }
+        }
+        else {
+            req.log.info('Access token has expired and cannot renew');
+            return undefined;
+        }
+    };
+    const authenticate = async (req, reply) => {
+        const codeVerifier = generators.codeVerifier();
+        const codeChallenge = generators.codeChallenge(codeVerifier);
+        const state = generators.state();
+        const redirectTo = client.authorizationUrl({
+            scope: 'openid',
+            state,
+            code_challenge: codeChallenge,
+            code_challenge_method: 'S256'
+        });
+        const sessionObj = {
+            codeVerifier,
+            state
+        };
+        req.session.oidc = sessionObj;
+        return reply.redirect(redirectTo);
+    };
+    const callback = async (req, reply) => {
+        const sessionObj = (req.session.oidc || {});
+        delete req.session.oidc;
+        const { codeVerifier, state } = sessionObj;
+        if (!(codeVerifier && state)) {
+            throw new BadSession();
+        }
+        const checks = {
+            code_verifier: codeVerifier,
+            state
+        };
+        const params = client.callbackParams(req.raw);
+        const tokenSet = await client.callback(redirectUri, params, checks);
+        const userinfo = await client.userinfo(tokenSet);
+        const user = authInfo(tokenSet.access_token, tokenSet.refresh_token, tokenSet.id_token, userinfo);
+        if (user.username) {
+            req.user = user;
+        }
+    };
+    const terminate = async (req, reply) => {
+        const redirectTo = client.endSessionUrl({
+            post_logout_redirect_uri: _redirectUri
+        });
+        return reply.redirect(redirectTo);
+    };
+    return {
+        authenticate,
+        callback,
+        deserialize,
+        serialize,
+        terminate,
+        wantSession: true
+    };
+};
+export default oidc;

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@react-foundry/fastify-auth",
+  "version": "0.1.0",
+  "description": "Authentication plugin for Fastify.",
+  "main": "dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "files": [
+    "/dist"
+  ],
+  "author": "Daniel A.C. Martin <npm@daniel-martin.co.uk> (http://daniel-martin.co.uk/)",
+  "license": "MIT",
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "dependencies": {
+    "@fastify/error": "^4.2.0",
+    "@fastify/rate-limit": "^10.3.0",
+    "base64url": "^3.0.1",
+    "fastify-plugin": "^5.1.0",
+    "openid-client": "^5.7.1",
+    "@react-foundry/fastify-session": "^0.1.0"
+  },
+  "devDependencies": {
+    "fastify": "5.7.1",
+    "jest": "30.2.0",
+    "jest-environment-jsdom": "30.2.0",
+    "ts-jest": "29.4.6",
+    "typescript": "5.9.3"
+  },
+  "scripts": {
+    "test": "NODE_OPTIONS=--experimental-vm-modules jest",
+    "build": "npm run build:esm && npm run build:cjs",
+    "build:esm": "tsc -m es2022 && find dist -name '*.js' -exec sh -c 'mv \"$0\" \"${0%.js}.mjs\"' {} \\;",
+    "build:cjs": "tsc",
+    "clean": "rm -rf dist tsconfig.tsbuildinfo"
+  },
+  "module": "dist/index.mjs",
+  "typings": "dist/index.d.ts"
+}