@nestjs/authentication 0.0.1

package/dist/magic-link/magic-link.service.js

@@ -0,0 +1,215 @@
+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 { HttpAdapterHost } from '@nestjs/core';
+import { firstHeader } from '../utils/auth-state.util.js';
+import { AuthenticationScope } from '../context/authentication-scope.service.js';
+import { AuthenticationRegistry } from '../services/authentication-registry.service.js';
+import { AuthenticationStorage } from '../storage/authentication.storage.js';
+import { AUTHENTICATION_MODULE_OPTIONS } from '../authentication.constants.js';
+import { TOKEN_PATTERN, randomToken, safeEqual, safeRedirectPath, sha256 } from '../utils/crypto.util.js';
+import { durationOr, hasExpired } from '../utils/duration.util.js';
+import { AuthenticationEvents } from '../events/authentication-events.service.js';
+import { requireUrlOption } from '../utils/options.util.js';
+import { defaultCookieName, readCookie, serializeCookie } from '../session/cookies.util.js';
+import { SignInService } from '../session/sign-in.service.js';
+import { MagicLinkError } from '../errors/magic-link.error.js';
+import { isMailableEmail, normalizeEmail } from '../account/email.util.js';
+/**
+ * What the store keys a link by: the SHA-256 of its token, and of the secret
+ * that binds it to a browser when it is bound (`bindToBrowser`), so the link
+ * alone finds nothing.
+ */
+function linkId(token, binding) {
+    return sha256(binding === undefined ? token : `${token}.${binding}`);
+}
+/** Which link a browser's cookie is for: a public hint, computable from the link. */
+function hintOf(token) {
+    return sha256(`nestjs-authentication magic-link hint ${token}`).slice(0, 12);
+}
+/**
+ * Passwordless sign-in links: 256-bit single-use tokens, stored hashed,
+ * short-lived, and bound to the browser that requested them.
+ *
+ * Point the link at a page that POSTs the token back: mail scanners and
+ * link previews follow GET links, and would burn (or use) the token.
+ *
+ * Like `OidcService`, the service binds each link to the browser that
+ * requested it: `create()` refuses a request from another origin (another
+ * site's page must not start a link here), and sets an `HttpOnly`,
+ * `SameSite=Lax` cookie, `__Host-magic_link_tx`, holding a secret that no
+ * link carries; the store keys the link by the token and that secret
+ * together, so `consume()` finds it only with the cookie. The `__Host-`
+ * prefix keeps sibling subdomains from planting one. So the link's page
+ * must be on the same site as the API, as the session cookie requires
+ * anyway, and a link forwarded to another browser or device, or read from
+ * a log, is refused there while it stays usable where it was requested.
+ * See `magicLink.bindToBrowser`.
+ */
+let MagicLinkService = class MagicLinkService {
+    constructor(storage, registry, signIn, options, scope = new AuthenticationScope(), adapterHost, events = new AuthenticationEvents()) {
+        this.storage = storage;
+        this.registry = registry;
+        this.signIn = signIn;
+        this.scope = scope;
+        this.adapterHost = adapterHost;
+        this.events = events;
+        this.options = options?.magicLink;
+        if (this.options) {
+            requireUrlOption(this.options.url, 'magicLink.url', 'the page that receives the link');
+        }
+        this.ttl = durationOr(this.options?.ttl, '15m');
+        this.bindToBrowser = this.options?.bindToBrowser !== false;
+        this.txCookieName = defaultCookieName('magic_link_tx', this.options?.cookie);
+    }
+    /**
+     * Creates a link and hands it to `MagicLinkHandler.send()`. The token is
+     * not returned. Called from an HTTP handler, it sets the transaction
+     * cookie on the response (see `bindToBrowser`); the returned `cookie` is
+     * that `Set-Cookie` value, for callers outside HTTP. A request from another
+     * origin than the app's own and `session.trustedOrigins` gets a
+     * `ForbiddenException`, as `SignInService.signIn()` does. An `email` no
+     * mail should go to (missing, blank, without `@`, over 254 characters, or
+     * with whitespace or control characters) creates and sends nothing, and
+     * gets the same answer, like `PasswordResetService.request()`.
+     */
+    async create(email, { redirectTo } = {}) {
+        const { options, handler } = this.feature();
+        // The cookie binds the link to this browser: another site's page must not get one set here for
+        // an address its author reads (login CSRF), whatever the request asks for.
+        this.signIn.refuseCrossOrigin(this.scope.exchange()?.request);
+        const now = this.now();
+        const expiresAt = new Date(now + this.ttl);
+        const normalized = typeof email === 'string' ? normalizeEmail(email) : '';
+        if (!isMailableEmail(normalized)) {
+            return { expiresAt };
+        }
+        const token = randomToken();
+        const binding = this.bindToBrowser ? randomToken() : undefined;
+        const safe = safeRedirectPath(redirectTo);
+        await this.storage.magicLinks.saveMagicLink({
+            id: linkId(token, binding),
+            email: normalized,
+            createdAt: new Date(now),
+            expiresAt,
+            ...(safe && { redirectTo: safe }),
+        });
+        let cookie;
+        if (binding) {
+            cookie = this.txCookie(`${hintOf(token)}.${binding}`, this.ttl / 1000);
+            this.setCookie(cookie);
+        }
+        const url = new URL(options.url);
+        url.searchParams.set('token', token);
+        await handler.send({ email: normalized, url: url.toString(), expiresAt });
+        return { expiresAt, ...(cookie && { cookie }) };
+    }
+    /**
+     * Burns the token, asks `MagicLinkHandler.resolveUser()` for the user, and
+     * signs them in on this browser through `SignInService`, which sets the
+     * cookie. `null` for unknown, used or expired tokens and for addresses
+     * the handler refuses, one answer for all of them. A link this browser
+     * did not request (see `bindToBrowser`) throws {@link MagicLinkError}
+     * instead, before anything is looked up or burned: the module answers it
+     * with a 401 that tells the customer where to open the link. Each
+     * refusal is a `magic-link-refused` event with its reason. Outside an
+     * HTTP handler, pass the `request` that carries the cookie.
+     */
+    async consume(token, { request } = {}) {
+        const { handler } = this.feature();
+        if (typeof token !== 'string' || !TOKEN_PATTERN.test(token)) {
+            return this.refuse('unknown');
+        }
+        let binding;
+        if (this.bindToBrowser) {
+            const req = request ?? this.scope.exchange()?.request;
+            const [hint, secret] = (readCookie(firstHeader(req?.headers, 'cookie'), this.txCookieName) ?? '').split('.');
+            // The hint names the link this browser requested; anyone holding the link can compute it, so it
+            // only tells a link opened elsewhere from a bad one. The secret, which no link carries, is what
+            // the link is stored under: a leaked or forwarded link finds nothing without it. On a refusal
+            // here the cookie stays (it may be for a link this browser did request), and nothing is looked
+            // up: a link was presented, not proved.
+            if (!hint || !secret || !TOKEN_PATTERN.test(secret) || !safeEqual(hint, hintOf(token))) {
+                this.events.emit({ type: 'magic-link-refused', reason: 'not-this-browser' });
+                throw new MagicLinkError();
+            }
+            binding = secret;
+        }
+        const record = await this.storage.magicLinks.consumeMagicLink(linkId(token, binding));
+        // This browser's link is settled either way: the cookie goes.
+        this.setCookie(this.txCookie('', 0));
+        if (!record) {
+            return this.refuse('unknown');
+        }
+        if (hasExpired(record.expiresAt, this.now())) {
+            return this.refuse('expired', record.email);
+        }
+        const user = await handler.resolveUser(record.email);
+        if (!user) {
+            return this.refuse('refused', record.email);
+        }
+        // The link proved the address it was sent to, and signs in only the account whose address that
+        // is: a lookup that folds accents or ignores dots would otherwise hand `victim@exämple.com`'s
+        // mailbox the account of `victim@example.com`.
+        if (typeof user.email !== 'string') {
+            throw new TypeError('MagicLinkHandler.resolveUser() must return the account’s stored `email` with its `id`: the link signs in ' +
+                'only the account whose address it was sent to.');
+        }
+        if (normalizeEmail(user.email) !== record.email) {
+            return this.refuse('refused', record.email);
+        }
+        const issued = await this.signIn.signIn(user.id, { method: 'magic-link' });
+        return { ...issued, redirectTo: record.redirectTo };
+    }
+    /** The options and the handler; the module refuses to start with one and not the other. */
+    feature() {
+        const handler = this.registry.handler('magicLink');
+        if (!this.options || !handler) {
+            throw new Error('MagicLinkService: magic links are not enabled. Configure `magicLink` in the AuthenticationModule options, and ' +
+                "register a MagicLinkHandler: `registry.registerHandler('magicLink', this)`.");
+        }
+        return { options: this.options, handler };
+    }
+    /** The generic answer: which refusal it was is told only by the event. */
+    refuse(reason, email) {
+        this.events.emit({ type: 'magic-link-refused', reason, ...(email && { email }) });
+        return null;
+    }
+    txCookie(value, maxAge) {
+        return serializeCookie(this.txCookieName, value, { ...this.options?.cookie, sameSite: 'lax', maxAge });
+    }
+    setCookie(cookie) {
+        if (!this.bindToBrowser) {
+            return;
+        }
+        const response = this.scope.exchange()?.response;
+        if (response) {
+            this.adapterHost?.httpAdapter?.appendHeader(response, 'Set-Cookie', cookie);
+        }
+    }
+    now() {
+        return this.options?.now?.() ?? Date.now();
+    }
+};
+MagicLinkService = __decorate([
+    Injectable(),
+    __param(3, Optional()),
+    __param(3, Inject(AUTHENTICATION_MODULE_OPTIONS)),
+    __param(5, Optional()),
+    __metadata("design:paramtypes", [AuthenticationStorage,
+        AuthenticationRegistry,
+        SignInService, Object, AuthenticationScope,
+        HttpAdapterHost,
+        AuthenticationEvents])
+], MagicLinkService);
+export { MagicLinkService };

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

@@ -0,0 +1,25 @@
+import type { TotpRecord, MfaStore } from '../interfaces/mfa-store.interface.js';
+/**
+ * Process-local store: the default when no source is registered, and a
+ * test double. Atomic because it is synchronous.
+ */
+export declare class InMemoryMfaStore implements MfaStore {
+    private readonly totp;
+    private readonly codes;
+    private readonly failuresAt;
+    getTotp(userId: string): Promise<{
+        secret: string;
+        confirmed: boolean;
+        pendingSecret?: string;
+        lastUsedStep?: number;
+    } | undefined>;
+    saveTotp(userId: string, record: TotpRecord | null): Promise<void>;
+    claimTotpStep(userId: string, step: number): Promise<boolean>;
+    saveRecoveryCodes(userId: string, hashes: string[]): Promise<void>;
+    consumeRecoveryCode(userId: string, hash: string): Promise<boolean>;
+    countRecoveryCodes(userId: string): Promise<number>;
+    recordMfaFailure(userId: string, windowMs: number, now: number): Promise<number>;
+    countMfaFailures(userId: string, windowMs: number, now: number): Promise<number>;
+    clearMfaFailures(userId: string): Promise<void>;
+    private recent;
+}

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

@@ -0,0 +1,73 @@
+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. Atomic because it is synchronous.
+ */
+let InMemoryMfaStore = class InMemoryMfaStore {
+    constructor() {
+        this.totp = new Map();
+        this.codes = new Map();
+        this.failuresAt = new Map();
+    }
+    async getTotp(userId) {
+        const record = this.totp.get(userId);
+        return record && { ...record };
+    }
+    async saveTotp(userId, record) {
+        if (!record) {
+            this.totp.delete(userId);
+            return;
+        }
+        const claimed = this.totp.get(userId)?.lastUsedStep;
+        const lastUsedStep = Math.max(claimed ?? -Infinity, record.lastUsedStep ?? -Infinity);
+        const { lastUsedStep: _, ...rest } = record;
+        this.totp.set(userId, { ...rest, ...(Number.isFinite(lastUsedStep) && { lastUsedStep }) });
+    }
+    async claimTotpStep(userId, step) {
+        const record = this.totp.get(userId);
+        if (!record || (record.lastUsedStep !== undefined && step <= record.lastUsedStep)) {
+            return false;
+        }
+        record.lastUsedStep = step;
+        return true;
+    }
+    async saveRecoveryCodes(userId, hashes) {
+        if (hashes.length === 0) {
+            this.codes.delete(userId);
+        }
+        else {
+            this.codes.set(userId, new Set(hashes));
+        }
+    }
+    async consumeRecoveryCode(userId, hash) {
+        return this.codes.get(userId)?.delete(hash) ?? false;
+    }
+    async countRecoveryCodes(userId) {
+        return this.codes.get(userId)?.size ?? 0;
+    }
+    async recordMfaFailure(userId, windowMs, now) {
+        const recent = this.recent(userId, windowMs, now);
+        recent.push(now);
+        this.failuresAt.set(userId, recent);
+        return recent.length;
+    }
+    async countMfaFailures(userId, windowMs, now) {
+        return this.recent(userId, windowMs, now).length;
+    }
+    async clearMfaFailures(userId) {
+        this.failuresAt.delete(userId);
+    }
+    recent(userId, windowMs, now) {
+        return (this.failuresAt.get(userId) ?? []).filter((t) => t > now - windowMs);
+    }
+};
+InMemoryMfaStore = __decorate([
+    Injectable()
+], InMemoryMfaStore);
+export { InMemoryMfaStore };

package/dist/mfa/mfa.service.d.ts

@@ -0,0 +1,104 @@
+import { AuthenticationStorage } from '../storage/authentication.storage.js';
+import { AuthenticationEvents } from '../events/authentication-events.service.js';
+import type { MfaOptions } from '../interfaces/mfa-options.interface.js';
+/**
+ * TOTP second factor (RFC 6238 over RFC 4226 HOTP, SHA-1, 6 digits, 30 s:
+ * the parameters every authenticator app supports) plus recovery codes.
+ *
+ * - `enroll()` stores an unconfirmed 160-bit secret and returns the
+ *   `otpauth://` URI for the QR code; `confirm()` activates it once a
+ *   code verifies. It refuses to touch a confirmed authenticator
+ *   ({@link MfaAlreadyEnrolledError}): replacing one takes
+ *   `{ replace: true }`, which stages the new secret while the current one
+ *   keeps working until `confirm()`. Call that only from a route that
+ *   requires a verified second factor (`@Authenticate({ mfa: true })`), or
+ *   remove the authenticator with `disable()` first.
+ * - Secrets are encrypted before they reach the store (AES-256-GCM, bound to
+ *   the user id) and decrypted only to compute codes. A secret encrypted with
+ *   an older key is re-encrypted with the current one after its next
+ *   successful verification, or by `reencrypt(userId)`.
+ * - Each time step is accepted once per user (replay protection), across
+ *   the ±`window` range.
+ * - After `maxAttempts` failures in `lockoutWindow` every check fails;
+ *   6 digits are otherwise brute-forceable. Each attempt is counted before
+ *   it is checked, so a burst of parallel guesses cannot outrun the limit.
+ *   This is a per-account control on the verifier, not request rate
+ *   limiting.
+ * - Recovery codes are shown once, and stored under a slow hash salted
+ *   with the user id (~49 bits of entropy each, plus the attempt limit).
+ */
+export declare class MfaService {
+    private readonly storage;
+    private readonly events;
+    private static readonly logger;
+    private readonly options?;
+    private readonly cipher?;
+    private readonly lockoutWindow;
+    constructor(storage: AuthenticationStorage, options?: {
+        mfa?: MfaOptions;
+    }, events?: AuthenticationEvents);
+    isEnrolled(userId: string): Promise<boolean>;
+    /**
+     * Starts an enrollment. Throws {@link MfaAlreadyEnrolledError} when the user
+     * has a confirmed authenticator, unless `replace` is set: then the new
+     * secret is staged and the current authenticator stays active until
+     * `confirm()` succeeds with a code from the new one.
+     */
+    enroll(userId: string, accountName: string, { replace }?: {
+        replace?: boolean;
+    }): Promise<{
+        secret: string;
+        uri: string;
+    }>;
+    /**
+     * Activates a pending enrollment (or a staged replacement, which then
+     * takes the place of the current authenticator).
+     */
+    confirm(userId: string, code: string): Promise<boolean>;
+    verifyTotp(userId: string, code: string): Promise<boolean>;
+    /**
+     * Re-encrypts the stored secret with the current key if it was sealed
+     * with an older one (or is legacy plaintext under `migratePlaintext`).
+     * For key-rotation jobs; returns whether anything was rewritten.
+     */
+    reencrypt(userId: string): Promise<boolean>;
+    /**
+     * Returns fresh plaintext codes (show once); replaces any previous batch.
+     * Codes are a second factor: for a user with a confirmed authenticator,
+     * call it right after `confirm()` succeeded, or from a route that requires
+     * a verified second factor (`@Authenticate({ mfa: true })`). Otherwise an
+     * API key, or a token issued before the user enrolled, could mint codes
+     * that finish a sign-in with the password alone.
+     */
+    generateRecoveryCodes(userId: string): Promise<string[]>;
+    verifyRecoveryCode(userId: string, code: string): Promise<boolean>;
+    remainingRecoveryCodes(userId: string): Promise<number>;
+    /**
+     * Removes the authenticator and the recovery codes. Call it only from a
+     * route that requires a verified second factor
+     * (`@Authenticate({ mfa: true })`): an API key, or a token issued before
+     * the user enrolled, is no second factor.
+     */
+    disable(userId: string): Promise<void>;
+    keyUri(secret: string, accountName: string): string;
+    /** `opened` is undefined when the secret could not be decrypted: fail closed, not counted against the user. */
+    private check;
+    /**
+     * Counts an attempt before it is checked, and returns its number within
+     * the window, or `undefined` when it must be refused unchecked. Counting
+     * first is what stops a burst of parallel guesses: each one gets its own
+     * number from the store, and only the first `maxAttempts` are checked.
+     * An attempt made while already locked out is not counted, so the lockout
+     * ends `lockoutWindow` after it began.
+     */
+    private begin;
+    /** The attempt was already counted by {@link begin}; this reports it. */
+    private failed;
+    private seal;
+    private open;
+    private matchingStep;
+    /** Read at each call, never in the constructor: the registry locks once the module starts. */
+    private get store();
+    private get maxAttempts();
+    private now;
+}