@nestjs/authentication 0.0.1

package/dist/storage/authentication.storage.js

@@ -0,0 +1,350 @@
+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 AuthenticationStorage_1;
+import { Inject, Injectable, Logger, Optional } from '@nestjs/common';
+import { InMemoryEmailTokenStore } from '../account/in-memory-email-token.store.js';
+import { InMemoryRefreshTokenStore } from '../jwt/in-memory-refresh-token.store.js';
+import { InMemoryMagicLinkStore } from '../magic-link/in-memory-magic-link.store.js';
+import { InMemoryMfaStore } from '../mfa/in-memory-mfa.store.js';
+import { InMemoryOidcStateStore } from '../oidc/in-memory-oidc-state.store.js';
+import { InMemorySessionStore } from '../session/in-memory-session.store.js';
+import { AUTHENTICATION_STORAGE_REQUIREMENTS } from '../authentication.constants.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 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.
+     */
+    sessionCookie: ['sessions', 'refreshTokens', 'mfa'],
+    /** `accessToken`: `TokenService` (refresh-token families), whose `issue()` checks for an authenticator. */
+    accessToken: ['refreshTokens', 'mfa'],
+    /** `mfa`: enrollment, codes, recovery codes and the lockout. */
+    mfa: ['mfa'],
+    /** `magicLinkHandler`: pending links, then `SignInService.signIn()`. */
+    magicLink: ['sessions', 'mfa', 'magicLinks'],
+    /** `oidcAccountResolver`: logins in progress, the session that links an account, then `SignInService.signIn()`. */
+    oidc: ['sessions', 'mfa', 'oidcStates'],
+    /**
+     * `passwordResetHandler`: the links; `reset()` revokes every session and
+     * refresh-token family of the user, and with `signIn: true` signs in.
+     */
+    passwordReset: ['sessions', 'refreshTokens', 'mfa', 'emailTokens'],
+    /** `emailVerificationHandler`: the links. */
+    emailVerification: ['emailTokens'],
+};
+/** @internal The contracts the features use, in the order messages list them. */
+export function contractsUsedBy(features) {
+    const used = new Set();
+    for (const feature of features) {
+        for (const contract of CONTRACTS_BY_FEATURE[feature]) {
+            used.add(contract);
+        }
+    }
+    return CONTRACT_NAMES.filter((contract) => used.has(contract));
+}
+/** @internal Every contract, in the order they are listed in messages. */
+export const STORAGE_CONTRACTS = {
+    sessions: {
+        interfaceName: 'SessionStore',
+        holds: 'sessions',
+        methods: ['getSession', 'createSession', 'touchSession', 'deleteSession', 'listUserSessions', 'deleteUserSessions'],
+        inMemory: () => new InMemorySessionStore(),
+    },
+    refreshTokens: {
+        interfaceName: 'RefreshTokenStore',
+        holds: 'refresh tokens',
+        methods: [
+            'getRefreshToken',
+            'saveRefreshToken',
+            'markRefreshTokenUsed',
+            'revokeRefreshTokenFamily',
+            'isRefreshTokenFamilyRevoked',
+            'revokeUserRefreshTokens',
+        ],
+        inMemory: () => new InMemoryRefreshTokenStore(),
+    },
+    mfa: {
+        interfaceName: 'MfaStore',
+        holds: 'authenticators and recovery codes',
+        methods: [
+            'getTotp',
+            'saveTotp',
+            'claimTotpStep',
+            'saveRecoveryCodes',
+            'consumeRecoveryCode',
+            'countRecoveryCodes',
+            'recordMfaFailure',
+            'countMfaFailures',
+            'clearMfaFailures',
+        ],
+        inMemory: () => new InMemoryMfaStore(),
+    },
+    magicLinks: {
+        interfaceName: 'MagicLinkStore',
+        holds: 'pending magic links',
+        methods: ['saveMagicLink', 'consumeMagicLink'],
+        inMemory: () => new InMemoryMagicLinkStore(),
+    },
+    oidcStates: {
+        interfaceName: 'OidcStateStore',
+        holds: 'OIDC logins in progress',
+        methods: ['saveOidcState', 'consumeOidcState'],
+        inMemory: () => new InMemoryOidcStateStore(),
+    },
+    emailTokens: {
+        interfaceName: 'EmailTokenStore',
+        holds: 'password reset and verification links',
+        methods: ['saveEmailToken', 'consumeEmailToken', 'deleteUserEmailTokens'],
+        inMemory: () => new InMemoryEmailTokenStore(),
+    },
+};
+const CONTRACT_NAMES = Object.keys(STORAGE_CONTRACTS);
+const KNOWN = CONTRACT_NAMES.map((name) => `${name} (${STORAGE_CONTRACTS[name].interfaceName})`).join(', ');
+const DEFAULT = 'in-memory stores (the default: state is lost on restart and not shared between instances)';
+/** @internal Locks the registry. `AuthenticationModule.onModuleInit()` and the first read call it. */
+export const LOCK_STORAGE = Symbol('AuthenticationStorage.lock');
+/**
+ * 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.
+ */
+let AuthenticationStorage = AuthenticationStorage_1 = class AuthenticationStorage {
+    constructor(requirements) {
+        this.requirements = requirements;
+        this.registered = new Map();
+        this.active = new Map();
+        this.locked = false;
+    }
+    /**
+     * 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, options = {}) {
+        const entries = validate(sources);
+        if (this.locked) {
+            throw new Error(`AuthenticationStorage.registerSource(): ${describe(entries)} registered after AuthenticationModule initialized ` +
+                `(or after its storage was first read), which already uses ${this.summary(CONTRACT_NAMES)}. Register from ` +
+                'the constructor of a singleton provider: providers of lazy-loaded modules, request-scoped and transient ' +
+                'providers, and lifecycle hooks run too late.');
+        }
+        if (!options.replace) {
+            for (const [contract, source] of entries) {
+                const previous = this.registered.get(contract);
+                if (previous) {
+                    throw new Error(`AuthenticationStorage.registerSource(): ${nameOf(source)} can't register \`${contract}\`, ` +
+                        `${previous === source ? 'it already did (the same instance, twice)' : `${nameOf(previous)} already did`}. ` +
+                        'Register each contract once, or pass { replace: true } to replace it on purpose (tests, wrappers).');
+                }
+            }
+        }
+        for (const [contract, source] of entries) {
+            this.registered.set(contract, source);
+        }
+    }
+    /** The active session store: the registered one, else the in-memory default. Reading it locks the registry. */
+    get sessions() {
+        return this.source('sessions');
+    }
+    get refreshTokens() {
+        return this.source('refreshTokens');
+    }
+    get mfa() {
+        return this.source('mfa');
+    }
+    get magicLinks() {
+        return this.source('magicLinks');
+    }
+    get oidcStates() {
+        return this.source('oidcStates');
+    }
+    get emailTokens() {
+        return this.source('emailTokens');
+    }
+    /**
+     * @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 = true } = {}) {
+        if (this.locked) {
+            return;
+        }
+        const inUse = this.requirements?.contracts ?? [];
+        const missing = inUse.filter((contract) => !this.registered.has(contract));
+        if (missing.length > 0 && this.refusesInMemory()) {
+            throw new Error(productionError(missing));
+        }
+        this.locked = true;
+        for (const [contract, source] of this.registered) {
+            this.active.set(contract, source);
+        }
+        if (log) {
+            AuthenticationStorage_1.logger.log(`AuthenticationStorage: ${this.summary(inUse)}`);
+        }
+    }
+    source(contract) {
+        this[LOCK_STORAGE]();
+        let source = this.active.get(contract);
+        if (!source) {
+            // A contract no configured feature showed as used: never in memory in production either.
+            if (this.refusesInMemory()) {
+                throw new Error(productionError([contract]));
+            }
+            source = STORAGE_CONTRACTS[contract].inMemory();
+            this.active.set(contract, source);
+        }
+        return source;
+    }
+    /**
+     * In production, unless `allowInMemoryStorage` is set. A registry built
+     * with `new`, outside the module, has no options: it refuses too.
+     */
+    refusesInMemory() {
+        // `Production` and `production ` (a stray space in a .env file) are production too.
+        return process.env.NODE_ENV?.trim().toLowerCase() === 'production' && !this.requirements?.allowInMemoryStorage;
+    }
+    /**
+     * 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)`.
+     */
+    summary(inUse) {
+        const sources = new Set(this.registered.values());
+        if (sources.size === 0) {
+            return DEFAULT;
+        }
+        if (sources.size === 1 && this.registered.size === CONTRACT_NAMES.length) {
+            return nameOf([...sources][0]);
+        }
+        const listed = CONTRACT_NAMES.filter((contract) => inUse.includes(contract) || this.registered.has(contract));
+        const groups = new Map();
+        // The registered sources first, then what runs in memory.
+        for (const contract of [...listed.filter((c) => this.registered.has(c)), ...listed.filter((c) => !this.registered.has(c))]) {
+            const source = this.registered.get(contract);
+            const name = source ? nameOf(source) : 'in-memory';
+            groups.set(name, [...(groups.get(name) ?? []), contract]);
+        }
+        return [...groups].map(([name, contracts]) => `${name} (${contracts.join(', ')})`).join('; ');
+    }
+};
+AuthenticationStorage.logger = new Logger('AuthenticationModule');
+AuthenticationStorage = AuthenticationStorage_1 = __decorate([
+    Injectable(),
+    __param(0, Optional()),
+    __param(0, Inject(AUTHENTICATION_STORAGE_REQUIREMENTS)),
+    __metadata("design:paramtypes", [Object])
+], AuthenticationStorage);
+export { AuthenticationStorage };
+/** The `[contract, store]` pairs of a `registerSource()` argument, after checking every one. */
+function validate(sources) {
+    if (sources === null || typeof sources !== 'object') {
+        throw new TypeError(`AuthenticationStorage.registerSource(): the contracts go by name, and got ${nameOf(sources)}. ${usage()}`);
+    }
+    // A store passed as itself (`registerSource(this)`): say which call it meant.
+    const implemented = CONTRACT_NAMES.filter((contract) => STORAGE_CONTRACTS[contract].methods.some((method) => typeof sources[method] === 'function'));
+    if (implemented.length > 0) {
+        throw new TypeError(`AuthenticationStorage.registerSource(): the contracts go by name, and ${nameOf(sources)} was passed as itself. ` +
+            `Name what it implements: \`registerSource({ ${implemented.map((contract) => `${contract}: this`).join(', ')} })\`.`);
+    }
+    const keys = Object.keys(sources);
+    if (keys.length === 0) {
+        throw new TypeError(`AuthenticationStorage.registerSource(): the contracts go by name, and got none. ${usage()}`);
+    }
+    const unknown = keys.filter((key) => !Object.hasOwn(STORAGE_CONTRACTS, key));
+    if (unknown.length > 0) {
+        throw new TypeError(`AuthenticationStorage.registerSource(): unknown contract ${unknown.map((key) => `\`${key}\``).join(', ')}. ` +
+            `The contracts are ${KNOWN}.`);
+    }
+    return keys.map((contract) => {
+        const source = sources[contract];
+        const { interfaceName, methods } = STORAGE_CONTRACTS[contract];
+        if (source === null || typeof source !== 'object') {
+            throw new TypeError(`AuthenticationStorage.registerSource(): expected an object implementing ${interfaceName} as \`${contract}\`, ` +
+                `got ${nameOf(source)}.`);
+        }
+        const missing = methods.filter((method) => typeof source[method] !== 'function');
+        if (missing.length > 0) {
+            throw new TypeError(`AuthenticationStorage.registerSource(): ${nameOf(source)} doesn't implement ${interfaceName} for \`${contract}\`: ` +
+                `${missing.map((method) => `${method}()`).join(', ')} ${missing.length === 1 ? 'is' : 'are'} missing.`);
+        }
+        return [contract, source];
+    });
+}
+function usage() {
+    return `Pass the stores a provider implements: \`registerSource({ sessions: this, refreshTokens: this })\`. The contracts are ${KNOWN}.`;
+}
+function productionError(missing) {
+    const specs = missing.map((contract) => STORAGE_CONTRACTS[contract]);
+    const example = missing.map((contract) => `${contract}: this`).join(', ');
+    return (`AuthenticationStorage: no store is registered for ${and(missing.map((contract, i) => `\`${contract}\` (${specs[i].interfaceName})`))}, ` +
+        `and NODE_ENV is "production": in memory, ${and(specs.map((spec) => spec.holds))} would be lost on restart and not ` +
+        `shared between instances. Implement ${and(specs.map((spec) => spec.interfaceName))} in a provider that injects ` +
+        `AuthenticationStorage and calls \`storage.registerSource({ ${example} })\` in its constructor, or set ` +
+        '`allowInMemoryStorage: true` in the AuthenticationModule options to run in memory anyway.');
+}
+/** `a`, `a and b`, `a, b, and c`. */
+function and(items) {
+    if (items.length <= 2) {
+        return items.join(' and ');
+    }
+    return `${items.slice(0, -1).join(', ')}, and ${items.at(-1)}`;
+}
+/** 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)`;
+    }
+    if (value === null || typeof value !== 'object') {
+        return String(value);
+    }
+    const name = value.constructor?.name;
+    return name && name !== 'Object' ? name : 'an object';
+}
+/** `DrizzleAuthenticationStore (sessions, mfa)`: the sources of a `registerSource()` call. */
+function describe(entries) {
+    const names = [...new Set(entries.map(([, source]) => nameOf(source)))].join(', ');
+    return `${names} (${entries.map(([contract]) => contract).join(', ')})`;
+}

package/dist/storage/index.d.ts

@@ -0,0 +1 @@
+export * from './authentication.storage.js';

package/dist/storage/index.js

@@ -0,0 +1 @@
+export * from './authentication.storage.js';

package/dist/testing/index.d.ts

@@ -0,0 +1,39 @@
+import { type AuthenticationStorageContract, type AuthenticationStorageSources } from '../interfaces/authentication-storage.interface.js';
+export interface AuthenticationStoreContractOptions {
+    /**
+     * The contracts to check, which `create()` must return. Default: all six.
+     * An app that splits storage runs the suite once per provider:
+     * `{ contracts: ['sessions'] }` for its Redis store, the rest for its SQL one.
+     */
+    contracts?: AuthenticationStorageContract[];
+    /**
+     * Adds the concurrency cases: parallel calls on one token, one code, one
+     * link, which a store that reads and then writes (instead of one
+     * conditional write) fails. Set it for every store you run in production,
+     * on a pooled connection where you can, so the calls really race.
+     */
+    concurrent?: boolean;
+    /**
+     * The most pending magic links, OIDC logins and email tokens your store
+     * keeps (per kind). When set, a case per kind saves `maxPending + 2` and
+     * checks the two that expire first are gone: configure your store with a
+     * small cap in the test.
+     */
+    maxPending?: number;
+}
+/** One case: `run()` resolves, or rejects with an assertion error. */
+export interface AuthenticationStoreContractCase {
+    /** `<contract>: <what it checks>`. */
+    name: string;
+    contract: AuthenticationStorageContract;
+    run(): Promise<void>;
+}
+/** Stores on fresh state: `create()` is called once per case. */
+export type AuthenticationStoreFactory = () => AuthenticationStorageSources | Promise<AuthenticationStorageSources>;
+/**
+ * The cases every implementation of the given contracts must pass. Ids and
+ * user ids are unique per case, so a store on a shared database works, but
+ * the `maxPending` cases need the pending tables empty: return stores on
+ * fresh state (new tables, or truncated ones) from `create()`.
+ */
+export declare function authenticationStoreContract(create: AuthenticationStoreFactory, options?: AuthenticationStoreContractOptions): AuthenticationStoreContractCase[];