@nestjs/authentication 0.0.1

package/dist/session/sign-in.service.js

@@ -0,0 +1,206 @@
+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 { ForbiddenException, Injectable, Optional } from '@nestjs/common';
+import { HttpAdapterHost } from '@nestjs/core';
+import { AuthenticationScope } 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 { sha256 } from '../utils/crypto.util.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.
+ */
+let SignInService = class SignInService {
+    constructor(sessions, mfa, tokens, scope = new AuthenticationScope(), adapterHost, events = new AuthenticationEvents()) {
+        this.sessions = sessions;
+        this.mfa = mfa;
+        this.tokens = tokens;
+        this.scope = scope;
+        this.adapterHost = adapterHost;
+        this.events = events;
+    }
+    /**
+     * 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`.
+     */
+    async signIn(userId, { method, metadata } = {}) {
+        const exchange = this.scope.exchange();
+        this.refuseCrossOrigin(exchange?.request);
+        const mfa = (await this.mfa.isEnrolled(userId)) ? 'pending' : undefined;
+        const stored = { ...this.sessions.metadataFor(exchange?.request), ...metadata };
+        const issued = await this.sessions.create(userId, {
+            mfa,
+            metadata: Object.keys(stored).length ? stored : undefined,
+            replacing: this.sessions.tokenFrom(exchange?.request),
+        });
+        this.setCookie(exchange, issued.cookie);
+        this.events.emit({
+            type: 'sign-in',
+            userId,
+            sessionId: issued.session.id,
+            ...(method && { method }),
+            ...(mfa && { mfa }),
+            ...(issued.session.metadata && { metadata: issued.session.metadata }),
+        });
+        return issued;
+    }
+    /**
+     * 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.
+     */
+    async completeMfa({ code, recoveryCode }) {
+        if (!code && !recoveryCode) {
+            return null;
+        }
+        const exchange = this.scope.exchange();
+        const session = await this.sessions.validate(this.sessions.tokenFrom(exchange?.request));
+        if (!session) {
+            return null;
+        }
+        const verified = recoveryCode
+            ? await this.mfa.verifyRecoveryCode(session.userId, recoveryCode)
+            : await this.mfa.verifyTotp(session.userId, code);
+        if (!verified) {
+            return null;
+        }
+        // A revocation that took the session meanwhile wins: no verified session comes of it.
+        const issued = await this.sessions.rotate(session, { mfa: 'verified' });
+        if (issued) {
+            this.setCookie(exchange, issued.cookie);
+        }
+        return issued;
+    }
+    /**
+     * 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.
+     */
+    async confirmMfa(userId, code) {
+        if (!(await this.mfa.confirm(userId, code))) {
+            return false;
+        }
+        const exchange = this.scope.exchange();
+        const session = await this.sessions.validate(this.sessions.tokenFrom(exchange?.request));
+        if (session?.userId === userId) {
+            const issued = await this.sessions.rotate(session, { mfa: 'verified' });
+            if (issued) {
+                this.setCookie(exchange, issued.cookie);
+            }
+        }
+        return true;
+    }
+    /**
+     * 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).
+     */
+    async rotateSession() {
+        const exchange = this.scope.exchange();
+        const session = await this.sessions.validate(this.sessions.tokenFrom(exchange?.request));
+        if (!session) {
+            return null;
+        }
+        const issued = await this.sessions.rotate(session);
+        if (issued) {
+            this.setCookie(exchange, issued.cookie);
+        }
+        return issued;
+    }
+    /**
+     * 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).
+     */
+    async signOut() {
+        const exchange = this.scope.exchange();
+        const token = this.sessions.tokenFrom(exchange?.request);
+        if (!token) {
+            return false;
+        }
+        const session = await this.sessions.validate(token);
+        this.setCookie(exchange, this.sessions.clearCookie());
+        // Deleted whatever this instance makes of it: idle here, it may still be live for another
+        // instance (its clock, or another idleTtl during a rolling deploy).
+        await this.sessions.discard(sha256(token));
+        if (!session) {
+            return false;
+        }
+        this.events.emit({ type: 'sign-out', userId: session.userId, sessionId: session.id });
+        return true;
+    }
+    /**
+     * 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.
+     */
+    async signOutEverywhere(userId) {
+        const exchange = this.scope.exchange();
+        const own = await this.sessions.validate(this.sessions.tokenFrom(exchange?.request));
+        await this.sessions.revokeAll(userId);
+        await this.tokens.revokeAll(userId);
+        if (own?.userId === userId) {
+            this.setCookie(exchange, this.sessions.clearCookie());
+        }
+        this.events.emit({ type: 'sign-out', userId, everywhere: true });
+    }
+    /**
+     * @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) {
+        if (request && this.sessions.isCrossOriginWrite(request)) {
+            throw new ForbiddenException('Cross-origin sign-in refused');
+        }
+    }
+    setCookie(exchange, cookie) {
+        if (exchange?.response) {
+            this.adapterHost?.httpAdapter?.appendHeader(exchange.response, 'Set-Cookie', cookie);
+        }
+    }
+};
+SignInService = __decorate([
+    Injectable(),
+    __param(4, Optional()),
+    __metadata("design:paramtypes", [SessionService,
+        MfaService,
+        TokenService,
+        AuthenticationScope,
+        HttpAdapterHost,
+        AuthenticationEvents])
+], SignInService);
+export { SignInService };

package/dist/storage/authentication.storage.d.ts

@@ -0,0 +1,130 @@
+import type { EmailTokenStore } from '../interfaces/email-token-store.interface.js';
+import type { RefreshTokenStore } from '../interfaces/refresh-token-store.interface.js';
+import type { MagicLinkStore } from '../interfaces/magic-link-store.interface.js';
+import type { MfaStore } from '../interfaces/mfa-store.interface.js';
+import type { OidcStateStore } from '../interfaces/oidc-state-store.interface.js';
+import type { SessionStore } from '../interfaces/session-store.interface.js';
+import type { AuthenticationStorageSources, AuthenticationStorageContract, AuthenticationStorageRegisterOptions } from '../interfaces/authentication-storage.interface.js';
+/**
+ * @internal What each feature reads or writes, audited against the code
+ * paths: the production guard's rule.
+ * Any feature that signs someone in reads `mfa`, configured or not: a user
+ * may have enrolled an authenticator through another instance, and
+ * `MfaService.isEnrolled()` is how a sign-in finds out. Any feature that
+ * revokes a user's sign-ins reaches both `sessions` and `refreshTokens`.
+ */
+export declare const CONTRACTS_BY_FEATURE: {
+    /**
+     * A `SessionCookieProvider` in `providers`: `SessionService` (every
+     * request), `SignInService.signIn()` (`isEnrolled()`), `completeMfa()`,
+     * and `signOutEverywhere()`, which also revokes the user's refresh-token
+     * families.
+     */
+    readonly sessionCookie: readonly ["sessions", "refreshTokens", "mfa"];
+    /** `accessToken`: `TokenService` (refresh-token families), whose `issue()` checks for an authenticator. */
+    readonly accessToken: readonly ["refreshTokens", "mfa"];
+    /** `mfa`: enrollment, codes, recovery codes and the lockout. */
+    readonly mfa: readonly ["mfa"];
+    /** `magicLinkHandler`: pending links, then `SignInService.signIn()`. */
+    readonly magicLink: readonly ["sessions", "mfa", "magicLinks"];
+    /** `oidcAccountResolver`: logins in progress, the session that links an account, then `SignInService.signIn()`. */
+    readonly oidc: readonly ["sessions", "mfa", "oidcStates"];
+    /**
+     * `passwordResetHandler`: the links; `reset()` revokes every session and
+     * refresh-token family of the user, and with `signIn: true` signs in.
+     */
+    readonly passwordReset: readonly ["sessions", "refreshTokens", "mfa", "emailTokens"];
+    /** `emailVerificationHandler`: the links. */
+    readonly emailVerification: readonly ["emailTokens"];
+};
+/** @internal */
+export type AuthenticationFeature = keyof typeof CONTRACTS_BY_FEATURE;
+/** @internal The contracts the features use, in the order messages list them. */
+export declare function contractsUsedBy(features: Iterable<AuthenticationFeature>): AuthenticationStorageContract[];
+/** @internal What the configured features need from storage, computed by the module from its options. */
+export interface AuthenticationStorageRequirements {
+    /** The contracts a configured feature uses ({@link contractsUsedBy}): the production guard checks these at startup. */
+    contracts: AuthenticationStorageContract[];
+    allowInMemoryStorage: boolean;
+}
+interface ContractSpec {
+    interfaceName: string;
+    /** What is lost with the in-memory default, for the production guard. */
+    holds: string;
+    methods: readonly string[];
+    inMemory: () => object;
+}
+/** @internal Every contract, in the order they are listed in messages. */
+export declare const STORAGE_CONTRACTS: Record<AuthenticationStorageContract, ContractSpec>;
+/** @internal Locks the registry. `AuthenticationModule.onModuleInit()` and the first read call it. */
+export declare const LOCK_STORAGE: unique symbol;
+/**
+ * Where the module keeps its state. The app registers its own stores here,
+ * from the constructor of an ordinary provider:
+ *
+ * ```ts
+ * @Injectable()
+ * export class DrizzleAuthenticationStore implements SessionStore, RefreshTokenStore, MfaStore {
+ *   constructor(@Inject(DRIZZLE) private readonly db: Database, storage: AuthenticationStorage) {
+ *     storage.registerSource({ sessions: this, refreshTokens: this, mfa: this });
+ *   }
+ *   // ...
+ * }
+ * ```
+ *
+ * A contract no source registered uses the in-memory store, so an app that
+ * imports the module boots with no storage configured. The registry locks
+ * in `AuthenticationModule`'s `onModuleInit` (every provider constructor has
+ * run by then), or at the first read of a store if that is earlier (another
+ * module's `onModuleInit`): it logs the active sources, and in production
+ * refuses to start while a contract a configured feature uses has no
+ * source, unless `allowInMemoryStorage` is set. In production, a read of
+ * any other contract without a source (an app calling a service outside
+ * the features it configured) fails the same way at that read, instead of
+ * running on the in-memory default.
+ */
+export declare class AuthenticationStorage {
+    private readonly requirements?;
+    private static readonly logger;
+    private readonly registered;
+    private readonly active;
+    private locked;
+    constructor(requirements?: AuthenticationStorageRequirements | undefined);
+    /**
+     * Registers stores by contract: `{ sessions: this, refreshTokens: this }`.
+     * Call it from the constructor of a singleton provider. Throws, registering
+     * nothing, when a store lacks one of its contract's methods, when a
+     * contract already has a source (unless `replace` is set: tests,
+     * wrappers), and once the registry has locked.
+     */
+    registerSource(sources: AuthenticationStorageSources, options?: AuthenticationStorageRegisterOptions): void;
+    /** The active session store: the registered one, else the in-memory default. Reading it locks the registry. */
+    get sessions(): SessionStore;
+    get refreshTokens(): RefreshTokenStore;
+    get mfa(): MfaStore;
+    get magicLinks(): MagicLinkStore;
+    get oidcStates(): OidcStateStore;
+    get emailTokens(): EmailTokenStore;
+    /**
+     * @internal Freezes the sources, logs them, and enforces the production
+     * guard (which leaves the registry open): in production, a contract in use
+     * with no source fails unless in-memory storage was allowed. `log: false`
+     * for the contract suite, which builds a registry per case.
+     */
+    [LOCK_STORAGE]({ log }?: {
+        log?: boolean;
+    }): void;
+    private source;
+    /**
+     * In production, unless `allowInMemoryStorage` is set. A registry built
+     * with `new`, outside the module, has no options: it refuses too.
+     */
+    private refusesInMemory;
+    /**
+     * The in-memory default, `DrizzleAuthenticationStore` (one source for every
+     * contract), or the contracts in use or registered, by source:
+     * `RedisSessionStore (sessions); DrizzleAuthenticationStore (mfa); in-memory (oidcStates)`.
+     */
+    private summary;
+}
+export {};