@nestjs/authentication 0.0.1

package/dist/services/authentication-registry.service.js

@@ -0,0 +1,235 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+var AuthenticationRegistry_1;
+import { Inject, Injectable, Logger, Optional } from '@nestjs/common';
+import { ModuleRef } from '@nestjs/core';
+import { PROVIDER_INIT } from '../providers/authentication.provider.js';
+import { AUTHENTICATION_MODULE_OPTIONS } from '../authentication.constants.js';
+const HANDLERS = {
+    emailVerification: {
+        className: 'EmailVerificationHandler',
+        methods: ['send', 'markVerified'],
+        option: "emailVerification: { url: 'https://app.example.com/verify-email' }",
+    },
+    passwordReset: {
+        className: 'PasswordResetHandler',
+        methods: ['findUser', 'send', 'updatePassword'],
+        option: "passwordReset: { url: 'https://app.example.com/reset-password' }",
+    },
+    magicLink: {
+        className: 'MagicLinkHandler',
+        methods: ['send', 'resolveUser'],
+        option: "magicLink: { url: 'https://app.example.com/sign-in/magic' }",
+    },
+    oidc: {
+        className: 'OidcAccountResolver',
+        methods: ['resolveUser'],
+        option: "oidc: { callbackUrl: 'https://app.example.com/auth/oidc/:provider/callback', providers: { … } }",
+    },
+};
+const HANDLER_NAMES = Object.keys(HANDLERS);
+/** @internal Locks the registry. `AuthenticationModule.onModuleInit()` and the first read call it. */
+export const LOCK_REGISTRY = Symbol('AuthenticationRegistry.lock');
+/**
+ * Where the app's credential providers and feature handlers register, from
+ * their own constructors, as stores do with `AuthenticationStorage`. They
+ * are ordinary providers of the app's modules, so they inject whatever
+ * those modules provide:
+ *
+ * ```ts
+ * @Injectable()
+ * export class SessionAuth extends SessionCookieProvider<User> {
+ *   constructor(private readonly users: UsersRepository, registry: AuthenticationRegistry) {
+ *     super();
+ *     registry.registerProvider(this);
+ *   }
+ *   // ...
+ * }
+ *
+ * @Injectable()
+ * export class PasswordResetMailer extends PasswordResetHandler {
+ *   constructor(private readonly users: UsersRepository, registry: AuthenticationRegistry) {
+ *     super();
+ *     registry.registerHandler('passwordReset', this);
+ *   }
+ *   // ...
+ * }
+ * ```
+ *
+ * The registry locks in `AuthenticationModule`'s `onModuleInit` (every
+ * provider constructor has run by then), or at the first read if that is
+ * earlier. At the lock it fails when a feature has its option without its
+ * handler, or the reverse, and it logs the chain and the handlers.
+ */
+let AuthenticationRegistry = AuthenticationRegistry_1 = class AuthenticationRegistry {
+    constructor(options, moduleRef) {
+        this.options = options;
+        this.moduleRef = moduleRef;
+        this.registered = [];
+        this.handlers = new Map();
+        this.chain = [];
+        this.locked = false;
+    }
+    /**
+     * Adds a credential provider to the chain the guard runs, in ascending
+     * `order` (default `0`). Call it from the constructor of a singleton
+     * provider. Throws, registering nothing, for an object without
+     * `authenticate()`, an order another provider has (unless `replace` is
+     * set), a provider registered twice, and once the registry has locked.
+     */
+    registerProvider(provider, { order = 0, replace = false } = {}) {
+        const where = 'AuthenticationRegistry.registerProvider()';
+        if (provider === null || typeof provider !== 'object' || typeof provider.authenticate !== 'function') {
+            throw new TypeError(`${where}: expected a credential provider with an authenticate() method, got ${nameOf(provider)}.`);
+        }
+        if (typeof order !== 'number' || !Number.isFinite(order)) {
+            throw new TypeError(`${where}: \`order\` must be a finite number, got ${String(order)}.`);
+        }
+        this.assertOpen(where, nameOf(provider));
+        if (this.registered.some((entry) => entry.provider === provider)) {
+            throw new Error(`${where}: ${nameOf(provider)} is already registered (the same instance, twice).`);
+        }
+        const taken = this.registered.find((entry) => entry.order === order);
+        if (taken && !replace) {
+            if (taken.provider.constructor === provider.constructor && provider.constructor !== Object) {
+                throw new Error(`${where}: another ${nameOf(provider)} is already registered at order ${order}. Is the class provided in ` +
+                    'two modules? Provide it once, in the module that owns it.');
+            }
+            throw new Error(`${where}: ${nameOf(provider)} can't take order ${order}, ${nameOf(taken.provider)} has it. Providers run in ` +
+                'ascending `order` and the first that returns a user wins, so each needs its own: ' +
+                `\`registerProvider(this, { order: ${Math.max(...this.registered.map((entry) => entry.order)) + 1} })\`.`);
+        }
+        if (taken) {
+            this.registered.splice(this.registered.indexOf(taken), 1);
+        }
+        this.registered.push({ provider: provider, order });
+    }
+    /**
+     * Registers the handler of a feature: `registerHandler('passwordReset', this)`.
+     * The feature also needs its module option. Throws, registering nothing,
+     * for an unknown feature, a handler missing one of its methods, a feature
+     * that already has one (unless `replace` is set), and once the registry
+     * has locked.
+     */
+    registerHandler(feature, handler, { replace = false } = {}) {
+        const where = 'AuthenticationRegistry.registerHandler()';
+        if (!Object.hasOwn(HANDLERS, feature)) {
+            throw new TypeError(`${where}: unknown feature \`${String(feature)}\`. The features are ` +
+                `${HANDLER_NAMES.map((name) => `${name} (${HANDLERS[name].className})`).join(', ')}.`);
+        }
+        const { className, methods } = HANDLERS[feature];
+        if (handler === null || typeof handler !== 'object') {
+            throw new TypeError(`${where}: expected a ${className} as \`${feature}\`, got ${nameOf(handler)}.`);
+        }
+        const missing = methods.filter((method) => typeof handler[method] !== 'function');
+        if (missing.length > 0) {
+            throw new TypeError(`${where}: ${nameOf(handler)} doesn't implement ${className} for \`${feature}\`: ` +
+                `${missing.map((method) => `${method}()`).join(', ')} ${missing.length === 1 ? 'is' : 'are'} missing.`);
+        }
+        this.assertOpen(where, nameOf(handler));
+        const previous = this.handlers.get(feature);
+        if (previous && !replace) {
+            throw new Error(`${where}: ${nameOf(handler)} can't register \`${feature}\`, ` +
+                `${previous === handler ? 'it already did (the same instance, twice)' : `${nameOf(previous)} already did`}. ` +
+                'Register each feature once, or pass { replace: true } to replace it on purpose (tests, wrappers).');
+        }
+        this.handlers.set(feature, handler);
+    }
+    /** The credential providers, in the order the guard runs them. Reading them locks the registry. */
+    get providers() {
+        this[LOCK_REGISTRY]();
+        return this.chain;
+    }
+    /** The handler registered for a feature, or `undefined`. Reading it locks the registry. */
+    handler(feature) {
+        this[LOCK_REGISTRY]();
+        return this.handlers.get(feature);
+    }
+    /**
+     * @internal Checks every feature has both its option and its handler,
+     * orders the chain, lets the providers check their configuration, and
+     * logs what registered. `log: false` for registries built outside a
+     * module (tests, the contract suite).
+     */
+    [LOCK_REGISTRY]({ log = true } = {}) {
+        if (this.locked) {
+            return;
+        }
+        const options = this.options ?? {};
+        for (const feature of HANDLER_NAMES) {
+            const { className, option } = HANDLERS[feature];
+            const handler = this.handlers.get(feature);
+            if (options[feature] !== undefined && !handler) {
+                throw new Error(`AuthenticationModule: \`${feature}\` is configured, but no ${className} is registered. Write an ` +
+                    `@Injectable() class that extends ${className}, provide it in one of your modules, and register it from ` +
+                    `its constructor: \`registry.registerHandler('${feature}', this)\`, with \`registry: AuthenticationRegistry\` injected.`);
+            }
+            if (handler && options[feature] === undefined) {
+                throw new Error(`AuthenticationModule: ${nameOf(handler)} is registered as the \`${feature}\` handler, but the \`${feature}\` ` +
+                    `option is missing. Configure it in the AuthenticationModule options: \`${option}\`.`);
+            }
+        }
+        const chain = [...this.registered].sort((a, b) => a.order - b.order).map((entry) => entry.provider);
+        // Providers that read module options check them now, not at the first request.
+        const resolve = (token) => {
+            if (!this.moduleRef) {
+                throw new Error(`AuthenticationRegistry: no module to resolve ${String(token?.name ?? token)} from`);
+            }
+            return this.moduleRef.get(token, { strict: false });
+        };
+        for (const provider of chain) {
+            provider[PROVIDER_INIT]?.(resolve);
+        }
+        this.chain = Object.freeze(chain);
+        this.locked = true;
+        if (!log) {
+            return;
+        }
+        const logger = AuthenticationRegistry_1.logger;
+        const handlers = HANDLER_NAMES.filter((feature) => this.handlers.has(feature)).map((feature) => `${nameOf(this.handlers.get(feature))} (${feature})`);
+        if (chain.length === 0) {
+            logger.warn('AuthenticationRegistry: no credential provider is registered, so every route that is not @Public() answers ' +
+                '401. Register one from its constructor: `registry.registerProvider(this)`.');
+        }
+        logger.log(`AuthenticationRegistry: ${chain.length > 0 ? `providers ${chain.map(nameOf).join(', ')}` : 'no providers'}` +
+            (handlers.length > 0 ? `; handlers ${handlers.join(', ')}` : ''));
+    }
+    assertOpen(where, name) {
+        if (!this.locked) {
+            return;
+        }
+        throw new Error(`${where}: ${name} registered after AuthenticationModule initialized (or after the registry was first read). ` +
+            'Register from the constructor of a singleton provider: providers of lazy-loaded modules, request-scoped and ' +
+            'transient providers, and lifecycle hooks run too late.');
+    }
+};
+AuthenticationRegistry.logger = new Logger('AuthenticationModule');
+AuthenticationRegistry = AuthenticationRegistry_1 = __decorate([
+    Injectable(),
+    __param(0, Optional()),
+    __param(0, Inject(AUTHENTICATION_MODULE_OPTIONS)),
+    __param(1, Optional()),
+    __metadata("design:paramtypes", [Object, ModuleRef])
+], AuthenticationRegistry);
+export { AuthenticationRegistry };
+/** How a message names a value: its class, or what it is instead of an instance. */
+function nameOf(value) {
+    if (typeof value === 'function') {
+        return `the class ${value.name || '(anonymous)'} (pass an instance: \`this\`)`;
+    }
+    if (value === null || typeof value !== 'object') {
+        return String(value);
+    }
+    const name = value.constructor?.name;
+    return name && name !== 'Object' ? name : 'an object';
+}

package/dist/services/index.d.ts

@@ -0,0 +1,3 @@
+export * from './authentication-registry.service.js';
+export * from './password-hasher.service.js';
+export * from './ws-authenticator.service.js';

package/dist/services/index.js

@@ -0,0 +1,3 @@
+export * from './authentication-registry.service.js';
+export * from './password-hasher.service.js';
+export * from './ws-authenticator.service.js';

package/dist/services/password-hasher.service.d.ts

@@ -0,0 +1,47 @@
+import type { PasswordHasherOptions } from '../interfaces/password-hasher-options.interface.js';
+/**
+ * @internal The bytes `PasswordHasher` derives from: the password NFKC-normalised, as UTF-8. Throws
+ * for anything but a string, for an empty one (which no account should have), and past 4 KiB,
+ * which caps what a request can make scrypt read.
+ */
+export declare function encodePassword(password: unknown): Buffer;
+/** @internal Whether `PasswordHasher.hash()` takes `password` (see {@link encodePassword}). */
+export declare function isHashablePassword(password: unknown): password is string;
+/**
+ * scrypt password hashing (Node's `crypto.scrypt`, run on the libuv
+ * threadpool so it does not block the event loop).
+ *
+ * The encoded hash is self-describing (`$scrypt$ln=17,r=8,p=1$salt$hash`),
+ * so parameters can be raised later: `verify()` reads the parameters from
+ * the stored hash and `needsRehash()` tells the sign-in code to store a
+ * fresh hash while it has the plaintext.
+ *
+ * Passwords are NFKC-normalised (NIST SP 800-63B §5.1.1.2) so the same
+ * password typed on different keyboards verifies. `hash()` refuses an empty
+ * password and one over 4 KiB (a `RangeError`), and `verify()` answers
+ * `false` for them without any work; length and strength rules beyond that
+ * are the app's to check.
+ *
+ * The module provides one built from its `password` option. Tests replace
+ * it with a cheaper one: `new PasswordHasher({ logN: 10 })`.
+ */
+export declare class PasswordHasher {
+    private readonly params;
+    private readonly keyLength;
+    private readonly saltLength;
+    private dummy?;
+    constructor(options?: PasswordHasherOptions);
+    hash(password: string): Promise<string>;
+    /**
+     * Constant-time check. Pass `undefined` for an unknown user: a dummy hash
+     * is checked instead, so response time does not reveal which accounts
+     * exist. The first such call makes the dummy hash, which costs the same
+     * one derivation as every later check.
+     */
+    verify(password: string, encoded: string | null | undefined): Promise<boolean>;
+    /** `true` when the stored hash uses weaker or different parameters than configured. */
+    needsRehash(encoded: string): boolean;
+    /** The one expensive step: scrypt on the libuv threadpool. */
+    private derive;
+    private encodeInput;
+}

package/dist/services/password-hasher.service.js

@@ -0,0 +1,170 @@
+import { randomBytes, scrypt as scryptCb, timingSafeEqual } from 'node:crypto';
+// $scrypt$ln=17,r=8,p=1$<salt>$<hash>, unpadded standard base64 as in the PHC string format.
+const FORMAT = /^\$scrypt\$ln=(\d{1,2}),r=(\d{1,3}),p=(\d{1,3})\$([A-Za-z0-9+/]{16,})\$([A-Za-z0-9+/]{16,})$/;
+const MAX_PASSWORD_BYTES = 4096;
+function scrypt(password, salt, keyLength, { logN, r, p }) {
+    const N = 2 ** logN;
+    const options = { N, r, p, maxmem: 256 * N * r + 1024 * 1024 };
+    return new Promise((resolve, reject) => scryptCb(password, salt, keyLength, options, (err, key) => (err ? reject(err) : resolve(key))));
+}
+const b64 = (buf) => buf.toString('base64').replace(/=+$/, '');
+/**
+ * @internal The bytes `PasswordHasher` derives from: the password NFKC-normalised, as UTF-8. Throws
+ * for anything but a string, for an empty one (which no account should have), and past 4 KiB,
+ * which caps what a request can make scrypt read.
+ */
+export function encodePassword(password) {
+    if (typeof password !== 'string') {
+        throw new TypeError('password must be a string');
+    }
+    // Before normalising, which can multiply the length (U+FDFA is 18 characters in NFKC): a string
+    // longer than the limit in UTF-16 units is longer in UTF-8 bytes too.
+    if (password.length > MAX_PASSWORD_BYTES) {
+        throw new RangeError('password too long');
+    }
+    const input = Buffer.from(password.normalize('NFKC'), 'utf8');
+    if (input.length === 0) {
+        throw new RangeError('password is empty');
+    }
+    if (input.length > MAX_PASSWORD_BYTES) {
+        throw new RangeError('password too long');
+    }
+    return input;
+}
+/** @internal Whether `PasswordHasher.hash()` takes `password` (see {@link encodePassword}). */
+export function isHashablePassword(password) {
+    try {
+        encodePassword(password);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * scrypt password hashing (Node's `crypto.scrypt`, run on the libuv
+ * threadpool so it does not block the event loop).
+ *
+ * The encoded hash is self-describing (`$scrypt$ln=17,r=8,p=1$salt$hash`),
+ * so parameters can be raised later: `verify()` reads the parameters from
+ * the stored hash and `needsRehash()` tells the sign-in code to store a
+ * fresh hash while it has the plaintext.
+ *
+ * Passwords are NFKC-normalised (NIST SP 800-63B §5.1.1.2) so the same
+ * password typed on different keyboards verifies. `hash()` refuses an empty
+ * password and one over 4 KiB (a `RangeError`), and `verify()` answers
+ * `false` for them without any work; length and strength rules beyond that
+ * are the app's to check.
+ *
+ * The module provides one built from its `password` option. Tests replace
+ * it with a cheaper one: `new PasswordHasher({ logN: 10 })`.
+ */
+export class PasswordHasher {
+    constructor(options = {}) {
+        this.params = { logN: options.logN ?? 17, r: options.r ?? 8, p: options.p ?? 1 };
+        this.keyLength = options.keyLength ?? 32;
+        this.saltLength = options.saltLength ?? 16;
+        if (!isSane(this.params)) {
+            throw new RangeError('PasswordHasher: unsupported scrypt parameters');
+        }
+        // What `parse()` reads back: a hash made with anything else would never verify.
+        for (const [name, value] of [['keyLength', this.keyLength], ['saltLength', this.saltLength]]) {
+            if (!Number.isInteger(value) || value < 16 || value > 64) {
+                throw new RangeError(`PasswordHasher: \`${name}\` must be an integer from 16 to 64 bytes, got ${String(value)}`);
+            }
+        }
+    }
+    async hash(password) {
+        const input = this.encodeInput(password);
+        const salt = randomBytes(this.saltLength);
+        const key = await this.derive(input, salt, this.keyLength, this.params);
+        const { logN, r, p } = this.params;
+        return `$scrypt$ln=${logN},r=${r},p=${p}$${b64(salt)}$${b64(key)}`;
+    }
+    /**
+     * Constant-time check. Pass `undefined` for an unknown user: a dummy hash
+     * is checked instead, so response time does not reveal which accounts
+     * exist. The first such call makes the dummy hash, which costs the same
+     * one derivation as every later check.
+     */
+    async verify(password, encoded) {
+        if (!encoded) {
+            if (!this.dummy) {
+                // A failure (a cancelled worker, memory) is not kept: the next unknown user tries again.
+                this.dummy = this.hash('dummy password for timing equalisation').catch((error) => {
+                    this.dummy = undefined;
+                    throw error;
+                });
+                await this.dummy;
+            }
+            else {
+                await this.verify(password, await this.dummy);
+            }
+            return false;
+        }
+        const parsed = parse(encoded);
+        if (!parsed) {
+            // A disabled account (`!`), a hash from another scheme: the same work as an unknown user, so
+            // the answer's timing does not single these accounts out.
+            return this.verify(password, undefined);
+        }
+        let input;
+        try {
+            input = this.encodeInput(password);
+        }
+        catch {
+            return false;
+        }
+        const actual = await this.derive(input, parsed.salt, parsed.hash.length, parsed.params);
+        return timingSafeEqual(actual, parsed.hash);
+    }
+    /** `true` when the stored hash uses weaker or different parameters than configured. */
+    needsRehash(encoded) {
+        const parsed = parse(encoded);
+        if (!parsed) {
+            return true;
+        }
+        const { logN, r, p } = parsed.params;
+        return (logN !== this.params.logN ||
+            r !== this.params.r ||
+            p !== this.params.p ||
+            parsed.hash.length !== this.keyLength ||
+            parsed.salt.length < this.saltLength);
+    }
+    /** The one expensive step: scrypt on the libuv threadpool. */
+    derive(input, salt, keyLength, params) {
+        return scrypt(input, salt, keyLength, params);
+    }
+    encodeInput(password) {
+        return encodePassword(password);
+    }
+}
+function isSane({ logN, r, p }) {
+    // Bounds also cap what a tampered stored hash can make us compute: 1 GiB of memory (128·N·r),
+    // and 16 times the work of the default parameters (N·r·p).
+    return ([logN, r, p].every(Number.isInteger) &&
+        logN >= 10 &&
+        logN <= 22 &&
+        r >= 1 &&
+        r <= 32 &&
+        p >= 1 &&
+        p <= 16 &&
+        2 ** logN * r <= 2 ** 23 &&
+        2 ** logN * r * p <= 2 ** 24);
+}
+function parse(encoded) {
+    const match = FORMAT.exec(encoded);
+    if (!match) {
+        return undefined;
+    }
+    const params = { logN: Number(match[1]), r: Number(match[2]), p: Number(match[3]) };
+    if (!isSane(params)) {
+        return undefined;
+    }
+    const salt = Buffer.from(match[4], 'base64');
+    const hash = Buffer.from(match[5], 'base64');
+    if (hash.length < 16 || hash.length > 64 || salt.length > 64) {
+        return undefined;
+    }
+    return { params, salt, hash };
+}

package/dist/services/ws-authenticator.service.d.ts

@@ -0,0 +1,38 @@
+import type { IncomingMessage } from 'node:http';
+import type { AuthenticationResult } from '../interfaces/authentication-result.interface.js';
+import { AuthenticationRegistry } from './authentication-registry.service.js';
+interface ClosableClient {
+    close?(code?: number, reason?: string): void;
+    disconnect?(close?: boolean): void;
+    [key: PropertyKey]: any;
+}
+/**
+ * Handshake authentication for gateways. Nest does not run guards on
+ * `handleConnection`, so the gateway calls this:
+ *
+ * ```ts
+ * async handleConnection(client: WebSocket, request: IncomingMessage) {
+ *   await this.wsAuth.authenticateConnection(client, request);
+ * }
+ * ```
+ *
+ * It stores the upgrade request on `client.request` (the `ws` library does
+ * not), so providers can read headers again for each message; the global
+ * guard re-authenticates every message, so a revoked session stops working
+ * mid-connection.
+ *
+ * It never rejects: Nest drops the promise `handleConnection` returns, so a
+ * rejection would be unhandled, which ends the Node.js process. A provider
+ * or store that fails (a Redis outage) is logged, and the connection is
+ * closed with 1011.
+ */
+export declare class WsAuthenticator {
+    private readonly registry;
+    private static readonly logger;
+    constructor(registry: AuthenticationRegistry);
+    authenticateConnection(client: ClosableClient, request?: IncomingMessage, { required }?: {
+        required?: boolean;
+    }): Promise<AuthenticationResult<unknown, unknown> | null>;
+    private run;
+}
+export {};

package/dist/services/ws-authenticator.service.js

@@ -0,0 +1,92 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var WsAuthenticator_1;
+import { Injectable, Logger } from '@nestjs/common';
+import { ExecutionContextHost } from '@nestjs/core/internal';
+import { setAuthState } from '../utils/auth-state.util.js';
+import { AuthenticationError } from '../errors/authentication.error.js';
+import { AuthenticationRegistry } from './authentication-registry.service.js';
+class WsHandshake {
+    handleConnection() { }
+}
+/**
+ * Handshake authentication for gateways. Nest does not run guards on
+ * `handleConnection`, so the gateway calls this:
+ *
+ * ```ts
+ * async handleConnection(client: WebSocket, request: IncomingMessage) {
+ *   await this.wsAuth.authenticateConnection(client, request);
+ * }
+ * ```
+ *
+ * It stores the upgrade request on `client.request` (the `ws` library does
+ * not), so providers can read headers again for each message; the global
+ * guard re-authenticates every message, so a revoked session stops working
+ * mid-connection.
+ *
+ * It never rejects: Nest drops the promise `handleConnection` returns, so a
+ * rejection would be unhandled, which ends the Node.js process. A provider
+ * or store that fails (a Redis outage) is logged, and the connection is
+ * closed with 1011.
+ */
+let WsAuthenticator = WsAuthenticator_1 = class WsAuthenticator {
+    constructor(registry) {
+        this.registry = registry;
+    }
+    async authenticateConnection(client, request, { required = true } = {}) {
+        if (request && !client.handshake) {
+            client.request = request;
+        }
+        const context = new ExecutionContextHost([client, undefined], WsHandshake, WsHandshake.prototype.handleConnection);
+        context.setType('ws');
+        let result = null;
+        try {
+            result = await this.run(context);
+        }
+        catch (error) {
+            if (!(error instanceof AuthenticationError)) {
+                WsAuthenticator_1.logger.error('Authenticating a WebSocket connection failed', error?.stack);
+                close(client, 1011, 'Internal Error'); // RFC 6455 §7.4.1
+                return null;
+            }
+        }
+        if (result?.mfa === 'pending') {
+            result = null;
+        }
+        setAuthState(context, result);
+        if (!result && required) {
+            close(client, 1008, 'Unauthorized'); // policy violation
+        }
+        return result;
+    }
+    async run(context) {
+        for (const provider of this.registry.providers) {
+            const result = await provider.authenticate(context);
+            if (result?.user) {
+                return result;
+            }
+        }
+        return null;
+    }
+};
+WsAuthenticator.logger = new Logger('WsAuthenticator');
+WsAuthenticator = WsAuthenticator_1 = __decorate([
+    Injectable(),
+    __metadata("design:paramtypes", [AuthenticationRegistry])
+], WsAuthenticator);
+export { WsAuthenticator };
+function close(client, code, reason) {
+    if (client.close) {
+        client.close(code, reason);
+    }
+    else {
+        client.disconnect?.(true); // socket.io
+    }
+}

package/dist/session/cookies.util.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Reads one cookie from a raw `Cookie` header (RFC 6265 §5.4), so neither
+ * `cookie-parser` nor `@fastify/cookie` is needed. The first occurrence
+ * wins, as browsers send the most specific path first.
+ */
+export declare function readCookie(header: string | undefined, name: string): string | undefined;
+export interface CookieAttributes {
+    /** Defaults to `true`. Turn off only for plain-HTTP development on a host other than `localhost`. */
+    secure?: boolean;
+    /** Defaults to `lax`. */
+    sameSite?: 'lax' | 'strict' | 'none';
+    /** Defaults to `/`. */
+    path?: string;
+    domain?: string;
+}
+/**
+ * Whether browsers accept a `__Host-` cookie with these attributes: Secure,
+ * `Path=/` and no `Domain`. Such a cookie can only be set by the host
+ * itself, so a sibling subdomain cannot plant one (cookie tossing).
+ */
+export declare function allowsHostPrefix(attributes?: CookieAttributes): boolean;
+/** `__Host-<name>` when the attributes allow it, `<name>` otherwise. */
+export declare function defaultCookieName(name: string, attributes?: CookieAttributes): string;
+/**
+ * Fails at startup on a cookie browsers would silently drop: a prefixed name
+ * its attributes break, or `SameSite=None` without `Secure` (rejected by
+ * every browser: the cookie is never stored, so every sign-in looks like it
+ * worked and nothing stays signed in). `option` is the options object the
+ * message names (`session`).
+ */
+export declare function assertCookieAttributes(name: string, attributes: CookieAttributes | undefined, option: string): void;
+export declare function serializeCookie(name: string, value: string, attributes: CookieAttributes & {
+    maxAge: number;
+}): string;