@nestjs/authentication 0.0.1

package/dist/session/cookies.util.js

@@ -0,0 +1,82 @@
+/**
+ * Only the whitespace browsers strip around a cookie's name and value (RFC
+ * 6265 §5.2): space and tab. `String.prototype.trim()` would also strip
+ * U+00A0 and U+FEFF, so a sibling subdomain could plant `\xA0__Host-sid`,
+ * which browsers store as an unprefixed name, and have it read as `__Host-sid`.
+ */
+const trimSpaces = (text) => text.replace(/^[ \t]+|[ \t]+$/g, '');
+/**
+ * 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 function readCookie(header, name) {
+    if (!header) {
+        return undefined;
+    }
+    for (const pair of header.split(';')) {
+        const eq = pair.indexOf('=');
+        if (eq === -1) {
+            continue;
+        }
+        if (trimSpaces(pair.slice(0, eq)) !== name) {
+            continue;
+        }
+        let value = trimSpaces(pair.slice(eq + 1));
+        if (value.length >= 2 && value.startsWith('"') && value.endsWith('"')) {
+            value = value.slice(1, -1);
+        }
+        try {
+            return decodeURIComponent(value);
+        }
+        catch {
+            return value;
+        }
+    }
+    return undefined;
+}
+/**
+ * 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 function allowsHostPrefix(attributes = {}) {
+    return (attributes.secure ?? true) && (attributes.path ?? '/') === '/' && !attributes.domain;
+}
+/** `__Host-<name>` when the attributes allow it, `<name>` otherwise. */
+export function defaultCookieName(name, attributes = {}) {
+    return allowsHostPrefix(attributes) ? `__Host-${name}` : name;
+}
+/**
+ * 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 function assertCookieAttributes(name, attributes = {}, option) {
+    if (name.startsWith('__Host-') && !allowsHostPrefix(attributes)) {
+        throw new TypeError(`${option}.cookieName: browsers drop a __Host- cookie unless it is Secure, with Path=/ and no Domain.`);
+    }
+    if (name.startsWith('__Secure-') && !(attributes.secure ?? true)) {
+        throw new TypeError(`${option}.cookieName: browsers drop a __Secure- cookie unless it is Secure.`);
+    }
+    if (attributes.sameSite === 'none' && !(attributes.secure ?? true)) {
+        throw new TypeError(`${option}.cookie: browsers drop a SameSite=None cookie unless it is Secure. Keep \`secure\` on (the default), or ` +
+            "use sameSite 'lax' for plain-HTTP development.");
+    }
+}
+export function serializeCookie(name, value, attributes) {
+    const parts = [`${name}=${encodeURIComponent(value)}`, `Max-Age=${Math.max(0, Math.floor(attributes.maxAge))}`];
+    parts.push(`Path=${attributes.path ?? '/'}`);
+    if (attributes.domain) {
+        parts.push(`Domain=${attributes.domain}`);
+    }
+    parts.push('HttpOnly');
+    if (attributes.secure ?? true) {
+        parts.push('Secure');
+    }
+    const sameSite = attributes.sameSite ?? 'lax';
+    parts.push(`SameSite=${sameSite[0].toUpperCase()}${sameSite.slice(1)}`);
+    return parts.join('; ');
+}

package/dist/session/in-memory-session.store.d.ts

@@ -0,0 +1,33 @@
+import type { SessionRecord, SessionStore } from '../interfaces/session-store.interface.js';
+/**
+ * Process-local store: the default when no source is registered, and a
+ * test double. Sessions past their absolute expiry are dropped as new ones
+ * are written, so an app that runs for months does not grow without bound.
+ */
+export declare class InMemorySessionStore implements SessionStore {
+    private readonly sessions;
+    private sweepAt;
+    getSession(id: string): Promise<{
+        id: string;
+        userId: string;
+        createdAt: Date;
+        expiresAt: Date;
+        lastActiveAt: Date;
+        mfa?: import("../index.js").MfaState;
+        metadata?: Record<string, unknown>;
+    } | undefined>;
+    createSession(record: SessionRecord): Promise<void>;
+    touchSession(id: string, lastActiveAt: Date): Promise<void>;
+    deleteSession(id: string): Promise<boolean>;
+    listUserSessions(userId: string): Promise<{
+        id: string;
+        userId: string;
+        createdAt: Date;
+        expiresAt: Date;
+        lastActiveAt: Date;
+        mfa?: import("../index.js").MfaState;
+        metadata?: Record<string, unknown>;
+    }[]>;
+    deleteUserSessions(userId: string): Promise<void>;
+    private sweep;
+}

package/dist/session/in-memory-session.store.js

@@ -0,0 +1,60 @@
+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;
+};
+import { Injectable } from '@nestjs/common';
+/**
+ * Process-local store: the default when no source is registered, and a
+ * test double. Sessions past their absolute expiry are dropped as new ones
+ * are written, so an app that runs for months does not grow without bound.
+ */
+let InMemorySessionStore = class InMemorySessionStore {
+    constructor() {
+        this.sessions = new Map();
+        this.sweepAt = 1_024;
+    }
+    async getSession(id) {
+        const record = this.sessions.get(id);
+        return record && { ...record };
+    }
+    async createSession(record) {
+        this.sessions.set(record.id, { ...record });
+        // The new session's own clock, so tests with a fake one agree.
+        if (this.sessions.size >= this.sweepAt) {
+            this.sweep(record.lastActiveAt.getTime());
+        }
+    }
+    async touchSession(id, lastActiveAt) {
+        const record = this.sessions.get(id);
+        if (record && record.lastActiveAt < lastActiveAt) {
+            this.sessions.set(id, { ...record, lastActiveAt });
+        }
+    }
+    async deleteSession(id) {
+        return this.sessions.delete(id);
+    }
+    async listUserSessions(userId) {
+        return [...this.sessions.values()].filter((s) => s.userId === userId).map((s) => ({ ...s }));
+    }
+    async deleteUserSessions(userId) {
+        for (const [id, s] of this.sessions) {
+            if (s.userId === userId) {
+                this.sessions.delete(id);
+            }
+        }
+    }
+    sweep(now) {
+        for (const [id, s] of this.sessions) {
+            if (s.expiresAt.getTime() <= now) {
+                this.sessions.delete(id);
+            }
+        }
+        this.sweepAt = Math.max(1_024, this.sessions.size * 2);
+    }
+};
+InMemorySessionStore = __decorate([
+    Injectable()
+], InMemorySessionStore);
+export { InMemorySessionStore };

package/dist/session/session-cookie.provider.d.ts

@@ -0,0 +1,36 @@
+import { type ExecutionContext } from '@nestjs/common';
+import { AuthenticationProvider, PROVIDER_INIT, type ProviderInit } from '../providers/authentication.provider.js';
+import type { AuthenticationResult } from '../interfaces/authentication-result.interface.js';
+import type { SessionRecord } from '../interfaces/session-store.interface.js';
+import { SessionService } from './session.service.js';
+/**
+ * Base class for cookie-session authentication. Extend it and load the
+ * user; `SessionService` is property-injected, so the subclass constructor
+ * only lists its own dependencies:
+ *
+ * ```ts
+ * @Injectable()
+ * export class SessionAuth extends SessionCookieProvider<User> {
+ *   constructor(private readonly users: UsersRepository) { super(); }
+ *   validate(session: SessionRecord) {
+ *     return this.users.findById(session.userId);
+ *   }
+ * }
+ * ```
+ *
+ * A missing, stale or unknown cookie counts as "no credentials" rather than
+ * a 401: browsers keep sending them, and optional routes should keep
+ * working. So does the cookie on a cross-origin POST, PUT, PATCH or DELETE
+ * (CSRF defence on top of `SameSite=Lax`; see `session.trustedOrigins`).
+ * Works on socket.io handshakes and `ws` upgrade requests too; check
+ * `Origin` in the gateway against cross-site WebSocket hijacking, since
+ * browsers send cookies on cross-site upgrades.
+ */
+export declare abstract class SessionCookieProvider<TUser> extends AuthenticationProvider<TUser, SessionRecord> {
+    protected readonly sessions: SessionService;
+    /** Loads the user for a live session; `null` for deleted or banned users, which ends the session. */
+    protected abstract validate(session: SessionRecord): TUser | null | undefined | Promise<TUser | null | undefined>;
+    authenticate(context: ExecutionContext): Promise<AuthenticationResult<TUser, SessionRecord> | null>;
+    /** @internal An instance created with `new` was not property-injected. */
+    [PROVIDER_INIT](resolve: Parameters<ProviderInit>[0]): void;
+}

package/dist/session/session-cookie.provider.js

@@ -0,0 +1,58 @@
+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);
+};
+import { Inject } from '@nestjs/common';
+import { requestOf } from '../utils/auth-state.util.js';
+import { AuthenticationProvider, PROVIDER_INIT } from '../providers/authentication.provider.js';
+import { SessionService } from './session.service.js';
+/**
+ * Base class for cookie-session authentication. Extend it and load the
+ * user; `SessionService` is property-injected, so the subclass constructor
+ * only lists its own dependencies:
+ *
+ * ```ts
+ * @Injectable()
+ * export class SessionAuth extends SessionCookieProvider<User> {
+ *   constructor(private readonly users: UsersRepository) { super(); }
+ *   validate(session: SessionRecord) {
+ *     return this.users.findById(session.userId);
+ *   }
+ * }
+ * ```
+ *
+ * A missing, stale or unknown cookie counts as "no credentials" rather than
+ * a 401: browsers keep sending them, and optional routes should keep
+ * working. So does the cookie on a cross-origin POST, PUT, PATCH or DELETE
+ * (CSRF defence on top of `SameSite=Lax`; see `session.trustedOrigins`).
+ * Works on socket.io handshakes and `ws` upgrade requests too; check
+ * `Origin` in the gateway against cross-site WebSocket hijacking, since
+ * browsers send cookies on cross-site upgrades.
+ */
+export class SessionCookieProvider extends AuthenticationProvider {
+    async authenticate(context) {
+        const session = await this.sessions.validate(this.sessions.tokenFrom(requestOf(context)));
+        if (!session) {
+            return null;
+        }
+        const user = await this.validate(session);
+        if (user === null || user === undefined) {
+            await this.sessions.discard(session.id);
+            return null;
+        }
+        return { user, session, mfa: session.mfa };
+    }
+    /** @internal An instance created with `new` was not property-injected. */
+    [PROVIDER_INIT](resolve) {
+        this.sessions ??= resolve(SessionService);
+    }
+}
+__decorate([
+    Inject(SessionService),
+    __metadata("design:type", SessionService)
+], SessionCookieProvider.prototype, "sessions", void 0);

package/dist/session/session.service.d.ts

@@ -0,0 +1,97 @@
+import type { Duration } from '../interfaces/duration.interface.js';
+import { AuthenticationEvents } from '../events/authentication-events.service.js';
+import type { MfaState } from '../interfaces/authentication-result.interface.js';
+import { AuthenticationStorage } from '../storage/authentication.storage.js';
+import type { SessionRecord } from '../interfaces/session-store.interface.js';
+import type { SessionRequest, SessionOptions, IssuedSession } from '../interfaces/session.interface.js';
+type RequestHeaders = Record<string, string | string[] | undefined>;
+/**
+ * Server-side sessions: opaque 256-bit tokens in an `HttpOnly` cookie,
+ * stored by their SHA-256.
+ *
+ * - Absolute expiry plus an idle (sliding) timeout.
+ * - `list()`, `revoke()` and `revokeAll()` for "your devices" pages and
+ *   "sign out everywhere".
+ * - `create()`, `validate()` and `rotate()` are the low-level operations
+ *   behind `SignInService`, which also reads and writes the cookie.
+ */
+export declare class SessionService {
+    private readonly storage;
+    private readonly events;
+    private readonly options;
+    private readonly absoluteTtl;
+    private readonly pendingTtl;
+    private readonly idleTtl;
+    private readonly touchInterval;
+    private readonly cookieName;
+    private readonly trustedOrigins;
+    constructor(storage: AuthenticationStorage, options?: {
+        session?: SessionOptions;
+        mfa?: {
+            pendingTtl?: Duration;
+        };
+    }, events?: AuthenticationEvents);
+    /**
+     * Starts a session. `replacing` is the token of the session this client
+     * had before; it is deleted (session fixation defence). An `mfa: 'pending'`
+     * session expires after `mfa.pendingTtl` (default `'10m'`) instead of
+     * `absoluteTtl`: `rotate()` to `mfa: 'verified'` gives it the full
+     * lifetime, counted from its creation.
+     */
+    create(userId: string, { mfa, metadata, replacing }?: {
+        mfa?: MfaState;
+        metadata?: Record<string, unknown>;
+        replacing?: string;
+    }): Promise<IssuedSession>;
+    /** The live session for a token, sliding its idle timeout. */
+    validate(token: string | undefined): Promise<SessionRecord | null>;
+    /**
+     * Replaces the session id, keeping its user and absolute expiry. For
+     * privilege changes; `SignInService.rotateSession()` does it for the
+     * current browser and updates its cookie. A pending session rotated to
+     * `mfa: 'verified'` gets the absolute lifetime a verified sign-in has,
+     * `absoluteTtl` from its creation, in place of its `mfa.pendingTtl`.
+     * Resolves `null` when the session was gone by the time it was replaced:
+     * revoked (a sign-out everywhere, a password reset) or rotated by another
+     * request, which leaves no new session behind.
+     */
+    rotate(session: SessionRecord, changes?: Pick<Partial<SessionRecord>, 'mfa' | 'metadata'>): Promise<IssuedSession | null>;
+    /**
+     * Ends one of `userId`'s sessions. Resolves `false` when the id is unknown
+     * or belongs to another user, so a route can pass an id from the URL
+     * without checking ownership first.
+     */
+    revoke(sessionId: string, { userId }: {
+        userId: string;
+    }): Promise<boolean>;
+    /** Ends every session of a user, optionally keeping one (`except`: its id). */
+    revokeAll(userId: string, { except }?: {
+        except?: string;
+    }): Promise<void>;
+    /** Live sessions of a user: not past their absolute expiry or their idle timeout. */
+    list(userId: string): Promise<SessionRecord[]>;
+    /**
+     * @internal The session token a request carries. The cookie is ignored on
+     * unsafe requests (and WebSocket handshakes) from another origin: see
+     * {@link isCrossOriginWrite}.
+     */
+    tokenFrom(request: {
+        headers: RequestHeaders;
+        method?: string;
+    } | undefined): string | undefined;
+    /** @internal Whether `request` changes state from another origin than the app's own and `trustedOrigins`. */
+    isCrossOriginWrite(request: {
+        headers: RequestHeaders;
+        method?: string;
+    }): boolean;
+    /** @internal */
+    metadataFor(request: SessionRequest | undefined): Record<string, unknown> | undefined;
+    /** @internal */
+    clearCookie(): string;
+    /** @internal Deletes a session by id, for sessions whose user is gone. */
+    discard(sessionId: string): Promise<void>;
+    private isLive;
+    private issue;
+    private now;
+}
+export {};

package/dist/session/session.service.js

@@ -0,0 +1,208 @@
+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); }
+};
+import { Inject, Injectable, Optional } from '@nestjs/common';
+import { firstHeader } from '../utils/auth-state.util.js';
+import { AUTHENTICATION_MODULE_OPTIONS } from '../authentication.constants.js';
+import { isCrossOriginWrite, normalizeOrigin } from '../utils/cross-origin.util.js';
+import { TOKEN_PATTERN, randomToken, sha256 } from '../utils/crypto.util.js';
+import { durationOr, hasExpired } from '../utils/duration.util.js';
+import { AuthenticationEvents } from '../events/authentication-events.service.js';
+import { AuthenticationStorage } from '../storage/authentication.storage.js';
+import { assertCookieAttributes, defaultCookieName, readCookie, serializeCookie } from './cookies.util.js';
+/**
+ * Server-side sessions: opaque 256-bit tokens in an `HttpOnly` cookie,
+ * stored by their SHA-256.
+ *
+ * - Absolute expiry plus an idle (sliding) timeout.
+ * - `list()`, `revoke()` and `revokeAll()` for "your devices" pages and
+ *   "sign out everywhere".
+ * - `create()`, `validate()` and `rotate()` are the low-level operations
+ *   behind `SignInService`, which also reads and writes the cookie.
+ */
+let SessionService = class SessionService {
+    constructor(storage, options, events = new AuthenticationEvents()) {
+        this.storage = storage;
+        this.events = events;
+        this.options = options?.session ?? {};
+        this.absoluteTtl = durationOr(this.options.absoluteTtl, '7d');
+        // A pending session never outlives a verified one would.
+        this.pendingTtl = Math.min(durationOr(options?.mfa?.pendingTtl, '10m'), this.absoluteTtl);
+        this.idleTtl = durationOr(this.options.idleTtl, '1d');
+        this.touchInterval = durationOr(this.options.touchInterval, '1m');
+        // Activity is recorded at most once per touchInterval: at or past idleTtl, a user active all
+        // along would be signed out as idle.
+        if (this.idleTtl > 0 && this.touchInterval >= this.idleTtl) {
+            throw new TypeError(`session.touchInterval (${this.touchInterval} ms) must be shorter than session.idleTtl (${this.idleTtl} ms): ` +
+                'activity is recorded at most once per touchInterval, so active users would be signed out as idle.');
+        }
+        this.cookieName = this.options.cookieName ?? defaultCookieName('sid', this.options.cookie);
+        assertCookieAttributes(this.cookieName, this.options.cookie, 'session');
+        this.trustedOrigins = new Set((this.options.trustedOrigins ?? []).map((origin) => normalizeOrigin(origin, 'session.trustedOrigins')));
+    }
+    /**
+     * Starts a session. `replacing` is the token of the session this client
+     * had before; it is deleted (session fixation defence). An `mfa: 'pending'`
+     * session expires after `mfa.pendingTtl` (default `'10m'`) instead of
+     * `absoluteTtl`: `rotate()` to `mfa: 'verified'` gives it the full
+     * lifetime, counted from its creation.
+     */
+    async create(userId, { mfa, metadata, replacing } = {}) {
+        if (replacing && TOKEN_PATTERN.test(replacing)) {
+            await this.storage.sessions.deleteSession(sha256(replacing));
+        }
+        const now = this.now();
+        return this.issue({
+            userId,
+            createdAt: new Date(now),
+            expiresAt: new Date(now + (mfa === 'pending' ? this.pendingTtl : this.absoluteTtl)),
+            lastActiveAt: new Date(now),
+            ...(mfa && { mfa }),
+            ...(metadata && { metadata }),
+        });
+    }
+    /** The live session for a token, sliding its idle timeout. */
+    async validate(token) {
+        if (!token || !TOKEN_PATTERN.test(token)) {
+            return null;
+        }
+        const record = await this.storage.sessions.getSession(sha256(token));
+        if (!record) {
+            return null;
+        }
+        const now = this.now();
+        if (!this.isLive(record, now)) {
+            // Past its absolute expiry, nothing can revive it. Idle, it is only idle as this read saw
+            // it: another request (another instance's clock) may have touched it since, so it stays;
+            // the store prunes it once its absolute expiry passes.
+            if (hasExpired(record.expiresAt, now)) {
+                await this.storage.sessions.deleteSession(record.id);
+            }
+            return null;
+        }
+        if (now - record.lastActiveAt.getTime() >= this.touchInterval) {
+            record.lastActiveAt = new Date(now);
+            await this.storage.sessions.touchSession(record.id, record.lastActiveAt);
+        }
+        return record;
+    }
+    /**
+     * Replaces the session id, keeping its user and absolute expiry. For
+     * privilege changes; `SignInService.rotateSession()` does it for the
+     * current browser and updates its cookie. A pending session rotated to
+     * `mfa: 'verified'` gets the absolute lifetime a verified sign-in has,
+     * `absoluteTtl` from its creation, in place of its `mfa.pendingTtl`.
+     * Resolves `null` when the session was gone by the time it was replaced:
+     * revoked (a sign-out everywhere, a password reset) or rotated by another
+     * request, which leaves no new session behind.
+     */
+    async rotate(session, changes = {}) {
+        const { id: _, ...rest } = session;
+        const verifying = session.mfa === 'pending' && changes.mfa === 'verified';
+        // The new session first, then the old one, which must still be there to delete: if a revocation
+        // took it meanwhile (deleting the user's sessions, this new one included, or not yet), or another
+        // rotation did, this one lost, and its new session must not outlive the old.
+        const issued = await this.issue({
+            ...rest,
+            ...changes,
+            lastActiveAt: new Date(this.now()),
+            ...(verifying && { expiresAt: new Date(session.createdAt.getTime() + this.absoluteTtl) }),
+        });
+        if (!(await this.storage.sessions.deleteSession(session.id))) {
+            await this.storage.sessions.deleteSession(issued.session.id);
+            return null;
+        }
+        return issued;
+    }
+    /**
+     * Ends one of `userId`'s sessions. Resolves `false` when the id is unknown
+     * or belongs to another user, so a route can pass an id from the URL
+     * without checking ownership first.
+     */
+    async revoke(sessionId, { userId }) {
+        const record = typeof sessionId === 'string' ? await this.storage.sessions.getSession(sessionId) : undefined;
+        if (!record || record.userId !== userId) {
+            return false;
+        }
+        await this.storage.sessions.deleteSession(record.id);
+        this.events.emit({ type: 'sign-out', userId, sessionId: record.id });
+        return true;
+    }
+    /** Ends every session of a user, optionally keeping one (`except`: its id). */
+    async revokeAll(userId, { except } = {}) {
+        const store = this.storage.sessions;
+        if (!except) {
+            return store.deleteUserSessions(userId);
+        }
+        for (const session of await store.listUserSessions(userId)) {
+            if (session.id !== except) {
+                await store.deleteSession(session.id);
+            }
+        }
+    }
+    /** Live sessions of a user: not past their absolute expiry or their idle timeout. */
+    async list(userId) {
+        const now = this.now();
+        return (await this.storage.sessions.listUserSessions(userId)).filter((s) => this.isLive(s, now));
+    }
+    /**
+     * @internal The session token a request carries. The cookie is ignored on
+     * unsafe requests (and WebSocket handshakes) from another origin: see
+     * {@link isCrossOriginWrite}.
+     */
+    tokenFrom(request) {
+        if (!request || this.isCrossOriginWrite(request)) {
+            return undefined;
+        }
+        const token = readCookie(firstHeader(request.headers, 'cookie'), this.cookieName);
+        return token && TOKEN_PATTERN.test(token) ? token : undefined;
+    }
+    /** @internal Whether `request` changes state from another origin than the app's own and `trustedOrigins`. */
+    isCrossOriginWrite(request) {
+        return isCrossOriginWrite(request, this.trustedOrigins);
+    }
+    /** @internal */
+    metadataFor(request) {
+        return request && this.options.metadata ? this.options.metadata(request) : undefined;
+    }
+    /** @internal */
+    clearCookie() {
+        return serializeCookie(this.cookieName, '', { ...this.options.cookie, maxAge: 0 });
+    }
+    /** @internal Deletes a session by id, for sessions whose user is gone. */
+    async discard(sessionId) {
+        await this.storage.sessions.deleteSession(sessionId);
+    }
+    isLive(record, now) {
+        if (hasExpired(record.expiresAt, now)) {
+            return false;
+        }
+        return this.idleTtl === 0 || now < record.lastActiveAt.getTime() + this.idleTtl;
+    }
+    async issue(fields) {
+        const token = randomToken();
+        const session = { id: sha256(token), ...fields };
+        await this.storage.sessions.createSession(session);
+        const maxAge = Math.round((session.expiresAt.getTime() - this.now()) / 1000);
+        return { session, token, cookie: serializeCookie(this.cookieName, token, { ...this.options.cookie, maxAge }) };
+    }
+    now() {
+        return this.options.now?.() ?? Date.now();
+    }
+};
+SessionService = __decorate([
+    Injectable(),
+    __param(1, Optional()),
+    __param(1, Inject(AUTHENTICATION_MODULE_OPTIONS)),
+    __metadata("design:paramtypes", [AuthenticationStorage, Object, AuthenticationEvents])
+], SessionService);
+export { SessionService };

package/dist/session/sign-in.service.d.ts

@@ -0,0 +1,87 @@
+import { HttpAdapterHost } from '@nestjs/core';
+import { AuthenticationScope, type HttpExchange } from '../context/authentication-scope.service.js';
+import { AuthenticationEvents } from '../events/authentication-events.service.js';
+import { TokenService } from '../jwt/token.service.js';
+import { MfaService } from '../mfa/mfa.service.js';
+import type { IssuedSession } from '../interfaces/session.interface.js';
+import type { SignInOptions } from '../interfaces/sign-in-options.interface.js';
+import { SessionService } from './session.service.js';
+/**
+ * The browser's side of signing in. Called from an HTTP handler (or a
+ * GraphQL resolver whose context has `req` and `res`), each method reads
+ * this browser's session cookie from the request and sets the new one on
+ * the response, on Express and Fastify alike. Elsewhere, nothing is read or
+ * set: send the returned `cookie` yourself.
+ *
+ * `signIn()` is the one place a first factor (password, magic link, OIDC)
+ * turns into a session:
+ * - a sign-in posted from another origin's page is refused with a 403
+ *   (login CSRF: signing the victim's browser in to the attacker's
+ *   account), by the same rule as `app.enableCsrfProtection()`;
+ * - the browser's previous session is deleted (session fixation defence);
+ * - users with a confirmed authenticator get an `mfa: 'pending'` session,
+ *   which is not signed in anywhere until `completeMfa()` verifies a code.
+ */
+export declare class SignInService {
+    private readonly sessions;
+    private readonly mfa;
+    private readonly tokens;
+    private readonly scope;
+    private readonly adapterHost?;
+    private readonly events;
+    constructor(sessions: SessionService, mfa: MfaService, tokens: TokenService, scope?: AuthenticationScope, adapterHost?: HttpAdapterHost | undefined, events?: AuthenticationEvents);
+    /**
+     * Signs the user in on this browser. Throws a `ForbiddenException` for a
+     * request that changes state from another origin than the app's own and
+     * `session.trustedOrigins`.
+     */
+    signIn(userId: string, { method, metadata }?: SignInOptions): Promise<IssuedSession>;
+    /**
+     * Completes the second factor of this browser's session with a TOTP code
+     * or a recovery code, and rotates the session to `mfa: 'verified'` under a
+     * new id. `null` when the browser has no session or the code is wrong. A
+     * request with neither counts nothing against the user's lockout, as
+     * `TokenService.issue()` without a `secondFactor` doesn't.
+     */
+    completeMfa({ code, recoveryCode }: {
+        code?: string;
+        recoveryCode?: string;
+    }): Promise<IssuedSession | null>;
+    /**
+     * Confirms the user's new authenticator with a code from it
+     * (`MfaService.confirm()`), and, when this browser holds a session of the
+     * user, rotates it to `mfa: 'verified'` under a new id: the code proved
+     * this browser has the authenticator, so the user isn't asked for another
+     * code until their next sign-in. Without such a session (a token client,
+     * another user's session), it only confirms. `false` when the code is
+     * wrong, and nothing changes.
+     */
+    confirmMfa(userId: string, code: string): Promise<boolean>;
+    /**
+     * Gives this browser's session a new id, keeping its user, expiry and
+     * second factor, and updates the cookie. Call it on privilege changes: a
+     * new password, a new role. `null` when the browser has no session, or
+     * lost it meanwhile (revoked, or rotated by another request).
+     */
+    rotateSession(): Promise<IssuedSession | null>;
+    /**
+     * Ends this browser's session, pending or not, and clears its cookie.
+     * `false` when the browser had no live session (a bearer-token client, an
+     * expired cookie).
+     */
+    signOut(): Promise<boolean>;
+    /**
+     * Ends every session and refresh-token family of the user, and clears
+     * this browser's cookie if it was one of them. API keys live in your own
+     * table: revoke those yourself.
+     */
+    signOutEverywhere(userId: string): Promise<void>;
+    /**
+     * @internal The 403 `signIn()` answers a request that changes state from
+     * another origin than the app's own and `session.trustedOrigins` with.
+     * What binds a sign-in to a browser (a magic link's `create()`) checks it
+     * too: another site's page must not start one in the victim's browser.
+     */
+    refuseCrossOrigin(request: HttpExchange['request'] | undefined): void;
+    private setCookie;
+}