@nestjs/authentication 0.0.1

package/dist/jwt/jwt-signer.service.js

@@ -0,0 +1,36 @@
+import { randomToken } from '../utils/crypto.util.js';
+import { durationOr, toMs } from '../utils/duration.util.js';
+import { algorithmFor, assertSigningKey, signJws, toKeyObject } from './jws.util.js';
+/**
+ * Issues signed JWTs. Adds `iat`, `exp`, `jti` and the configured
+ * `iss`/`aud`; callers pass `sub` and custom claims. The module's
+ * `accessToken` option configures the one `TokenService` uses; construct
+ * others directly.
+ */
+export class JwtSigner {
+    /** Throws a `TypeError` for a key that cannot sign, or an invalid `ttl`. */
+    constructor(options) {
+        this.options = options;
+        this.key = toKeyObject(options.key);
+        const alg = options.alg ?? algorithmFor(this.key);
+        if (!alg) {
+            throw new TypeError(`JwtSigner: ${this.key.asymmetricKeyType} keys are not supported.`);
+        }
+        assertSigningKey(alg, this.key, 'JwtSigner');
+        this.alg = alg;
+        toMs(options.ttl ?? 0); // an invalid duration fails here, not at the first sign()
+    }
+    sign(claims, { ttl } = {}) {
+        const iat = Math.floor((this.options.now?.() ?? Date.now()) / 1000);
+        const lifetime = Math.floor(durationOr(ttl ?? this.options.ttl, '15m') / 1000);
+        const payload = {
+            ...(this.options.issuer !== undefined && { iss: this.options.issuer }),
+            ...(this.options.audience !== undefined && { aud: this.options.audience }),
+            jti: randomToken(16),
+            ...claims,
+            iat,
+            exp: iat + lifetime,
+        };
+        return signJws({ alg: this.alg, typ: this.options.type ?? 'JWT', ...(this.options.kid && { kid: this.options.kid }) }, payload, this.key);
+    }
+}

package/dist/jwt/jwt-verifier.service.d.ts

@@ -0,0 +1,22 @@
+import type { JwsAlgorithm, JwtClaims } from '../interfaces/jwt.interface.js';
+import type { JwtSignerOptions } from '../interfaces/jwt-options.interface.js';
+import type { JwtVerifierOptions } from '../interfaces/jwt-options.interface.js';
+/**
+ * Verifies compact JWS tokens and their registered claims. `verify()`
+ * throws {@link JwtError}; a configuration that could not verify anything
+ * throws a `TypeError` in the constructor.
+ */
+export declare class JwtVerifier {
+    private readonly options;
+    private readonly key?;
+    private readonly jwks?;
+    readonly algorithms: JwsAlgorithm[];
+    constructor(options: JwtVerifierOptions);
+    verify(token: string): Promise<JwtClaims>;
+}
+/**
+ * @internal A verifier for what a `JwtSigner` with these options issues:
+ * the same secret, or the public half of its private key, with its
+ * algorithm, issuer, audience and `typ`. `overrides` add rules (`maxAge`).
+ */
+export declare function verifierForSigner(signer: JwtSignerOptions, overrides?: Omit<JwtVerifierOptions, 'key' | 'jwks'>): JwtVerifier;

package/dist/jwt/jwt-verifier.service.js

@@ -0,0 +1,109 @@
+import { createPublicKey } from 'node:crypto';
+import { toMs } from '../utils/duration.util.js';
+import { JwtError } from '../errors/jwt.error.js';
+import { JwksClient } from './jwks.client.js';
+import { algorithmFor, assertKeyFits, decodeJws, toKeyObject, validateClaims, verifySignature } from './jws.util.js';
+/**
+ * Verifies compact JWS tokens and their registered claims. `verify()`
+ * throws {@link JwtError}; a configuration that could not verify anything
+ * throws a `TypeError` in the constructor.
+ */
+export class JwtVerifier {
+    constructor(options) {
+        this.options = options;
+        if (!!options.key === !!options.jwks) {
+            throw new TypeError('JwtVerifier: pass exactly one of `key` or `jwks`.');
+        }
+        let given;
+        if (options.key) {
+            given = toKeyObject(options.key);
+            // A private key verifies with its public half, derived once.
+            this.key = given.type === 'private' ? createPublicKey(given) : given;
+        }
+        if (options.jwks) {
+            this.jwks = typeof options.jwks === 'string' ? new JwksClient(options.jwks) : options.jwks;
+        }
+        if (this.key) {
+            const implied = algorithmFor(this.key);
+            if (!implied) {
+                throw new TypeError(`JwtVerifier: ${this.key.asymmetricKeyType} keys are not supported.`);
+            }
+            this.algorithms = options.algorithms ?? [implied];
+            for (const alg of this.algorithms) {
+                assertKeyFits(alg, this.key, 'JwtVerifier');
+            }
+            // A public key is someone else's, an identity provider's that signs every client's tokens with
+            // it, as with a JWKS. A secret or a private key is the app's own (`verifierForSigner()`).
+            if (given?.type === 'public') {
+                requireIssuerAndAudience(options, 'public `key`');
+            }
+        }
+        else {
+            this.algorithms = options.algorithms ?? ['RS256', 'ES256'];
+            if (this.algorithms.includes('HS256')) {
+                throw new TypeError('JwtVerifier: HS256 cannot be combined with a JWKS.');
+            }
+            requireIssuerAndAudience(options, '`jwks`');
+        }
+        // Invalid durations fail here, not at the first request.
+        toMs(options.clockTolerance ?? 0);
+        toMs(options.maxAge ?? 0);
+    }
+    async verify(token) {
+        const decoded = decodeJws(token);
+        const { header } = decoded;
+        const alg = header.alg;
+        if (!this.algorithms.includes(alg)) {
+            throw new JwtError('unsupported algorithm');
+        }
+        // RFC 7515 §4.1.11: extensions we do not understand must be rejected.
+        if (header.crit !== undefined) {
+            throw new JwtError('unsupported critical header');
+        }
+        if (this.options.type !== undefined && (typeof header.typ !== 'string' || mediaType(header.typ) !== mediaType(this.options.type))) {
+            throw new JwtError('unexpected token type');
+        }
+        const key = this.key ?? (await this.jwks.getKey(header));
+        verifySignature(alg, key, decoded);
+        validateClaims(decoded.payload, this.options);
+        return decoded.payload;
+    }
+}
+/** Throws unless the tokens of a key the app does not own are pinned to their issuer and to the app. */
+function requireIssuerAndAudience(options, what) {
+    if (typeof options.issuer === 'string' && options.audience !== undefined) {
+        return;
+    }
+    throw new TypeError(`JwtVerifier: a ${what} verifier needs \`issuer\` and \`audience\`. An identity provider signs tokens for ` +
+        'all of its clients with the same keys, so without them tokens issued to other applications verify ' +
+        'too. For tokens that carry no audience, pass `audience: false` and check the claim that names your ' +
+        'client in `validate()`.');
+}
+/**
+ * A `typ` as RFC 7515 §4.1.9 compares it: without regard to case, and with
+ * `application/` implied when it has no `/`, so `at+jwt` and
+ * `application/at+jwt` are one type (RFC 9068 §4 accepts both).
+ */
+function mediaType(typ) {
+    const lower = typ.toLowerCase();
+    return lower.includes('/') ? lower : `application/${lower}`;
+}
+/**
+ * @internal A verifier for what a `JwtSigner` with these options issues:
+ * the same secret, or the public half of its private key, with its
+ * algorithm, issuer, audience and `typ`. `overrides` add rules (`maxAge`).
+ */
+export function verifierForSigner(signer, overrides = {}) {
+    const key = toKeyObject(signer.key);
+    const alg = signer.alg ?? algorithmFor(key);
+    return new JwtVerifier({
+        issuer: signer.issuer,
+        audience: signer.audience,
+        type: signer.type,
+        now: signer.now,
+        ...(alg && { algorithms: [alg] }),
+        ...overrides,
+        // The signer's own key (a secret or a private key): its tokens are the app's.
+        key,
+    });
+}

package/dist/jwt/token.service.d.ts

@@ -0,0 +1,81 @@
+import { AuthenticationStorage } from '../storage/authentication.storage.js';
+import { AuthenticationEvents } from '../events/authentication-events.service.js';
+import { MfaService } from '../mfa/mfa.service.js';
+import type { JwtSignerOptions } from '../interfaces/jwt-options.interface.js';
+import type { RefreshTokenOptions } from '../interfaces/refresh-token-options.interface.js';
+import type { IssueTokensOptions, TokenPair } from '../interfaces/token.interface.js';
+/**
+ * Tokens for clients that do not keep cookies (mobile apps, CLIs): a
+ * short-lived JWT access token, and an opaque refresh token that renews it.
+ *
+ * - `issue()` is to token clients what `SignInService.signIn()` is to
+ *   browsers: a user with a confirmed authenticator gets no tokens without
+ *   a second factor.
+ * - Access tokens are signed with the module's `accessToken` options, the
+ *   same ones `JwtBearerProvider` verifies with by default.
+ * - Refresh tokens are single use and stored hashed. Each rotation stays in
+ *   the family of the original sign-in, which has an absolute lifetime.
+ * - Presenting a refresh token that was already rotated, including two
+ *   concurrent presentations (`markRefreshTokenUsed()` is a compare-and-set), means two
+ *   parties hold it: the whole family is revoked, and both have to sign in
+ *   again (OAuth 2.0 Security BCP §4.14.2).
+ */
+export declare class TokenService {
+    private readonly storage;
+    private readonly events;
+    private readonly mfa;
+    private static readonly logger;
+    /** The `amr` warning is a misconfiguration: once per process says enough. */
+    private static warnedAmr;
+    private readonly signer?;
+    private readonly expiresIn;
+    private readonly ttl;
+    private readonly absoluteTtl;
+    private readonly clock?;
+    constructor(storage: AuthenticationStorage, options?: {
+        accessToken?: JwtSignerOptions;
+        refreshToken?: RefreshTokenOptions;
+    }, events?: AuthenticationEvents, mfa?: MfaService);
+    /**
+     * At sign-in: signs an access token and starts a refresh-token family.
+     *
+     * A user with a confirmed authenticator must send a second factor
+     * (`secondFactor`). Without one, `issue()` throws an
+     * `AuthenticationError` whose body says `mfa_required`, and counts
+     * nothing against the user's lockout; with a wrong one, `Invalid code`.
+     * A verified second factor adds `mfa` to the `amr` claim, which
+     * `@Authenticate({ mfa: true })` accepts; `claims.amr` cannot (see
+     * {@link IssueTokensOptions.claims}).
+     */
+    issue(userId: string, { claims, method, secondFactor }?: IssueTokensOptions): Promise<TokenPair>;
+    /**
+     * Spends a refresh token: returns its successor, and an access token with
+     * the family's claims. Throws {@link RefreshTokenError} (`invalid`,
+     * `expired`, `reused`), which a route answers with 401.
+     */
+    refresh(refreshToken: string): Promise<TokenPair>;
+    /** Two parties hold the token: the family is revoked, and the theft reported. */
+    private reused;
+    /**
+     * Signs out the client holding `refreshToken` (one device): revokes its
+     * family. Spent tokens of the family work too. Resolves `false` for
+     * unknown or malformed tokens, which a route should not reveal (RFC 7009
+     * §2.2).
+     */
+    revoke(refreshToken: string): Promise<boolean>;
+    /** Signs the user out of every token client. Issued access tokens live until they expire. */
+    revokeAll(userId: string): Promise<void>;
+    /** `true` when a second factor was required and verified; throws when one is required and missing or wrong. */
+    private checkSecondFactor;
+    private pair;
+    private requireSigner;
+    private create;
+    /**
+     * The app's claims with `amr` deduplicated and stripped of the values that
+     * mean a second factor: `JwtBearerProvider` would take them as verified,
+     * and only `issue()` knows whether a code was. An `amr` left empty is
+     * dropped. The first token issued with such values logs a warning.
+     */
+    private ownClaims;
+    private now;
+}

package/dist/jwt/token.service.js

@@ -0,0 +1,230 @@
+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 TokenService_1;
+import { Inject, Injectable, Logger, Optional } from '@nestjs/common';
+import { AUTHENTICATION_MODULE_OPTIONS } from '../authentication.constants.js';
+import { TOKEN_PATTERN, randomToken, sha256 } from '../utils/crypto.util.js';
+import { durationOr, hasExpired } from '../utils/duration.util.js';
+import { AuthenticationStorage } from '../storage/authentication.storage.js';
+import { AuthenticationError } from '../errors/authentication.error.js';
+import { AuthenticationEvents } from '../events/authentication-events.service.js';
+import { requireOption } from '../utils/options.util.js';
+import { MfaService } from '../mfa/mfa.service.js';
+import { RefreshTokenError } from '../errors/refresh-token.error.js';
+import { MFA_AMR_VALUES } from './amr.util.js';
+import { JwtSigner } from './jwt-signer.service.js';
+/**
+ * Tokens for clients that do not keep cookies (mobile apps, CLIs): a
+ * short-lived JWT access token, and an opaque refresh token that renews it.
+ *
+ * - `issue()` is to token clients what `SignInService.signIn()` is to
+ *   browsers: a user with a confirmed authenticator gets no tokens without
+ *   a second factor.
+ * - Access tokens are signed with the module's `accessToken` options, the
+ *   same ones `JwtBearerProvider` verifies with by default.
+ * - Refresh tokens are single use and stored hashed. Each rotation stays in
+ *   the family of the original sign-in, which has an absolute lifetime.
+ * - Presenting a refresh token that was already rotated, including two
+ *   concurrent presentations (`markRefreshTokenUsed()` is a compare-and-set), means two
+ *   parties hold it: the whole family is revoked, and both have to sign in
+ *   again (OAuth 2.0 Security BCP §4.14.2).
+ */
+let TokenService = TokenService_1 = class TokenService {
+    constructor(storage, options, events = new AuthenticationEvents(), mfa = new MfaService(storage)) {
+        this.storage = storage;
+        this.events = events;
+        this.mfa = mfa;
+        const refresh = options?.refreshToken ?? {};
+        this.ttl = durationOr(refresh.ttl, '30d');
+        this.absoluteTtl = durationOr(refresh.absoluteTtl, '90d');
+        this.clock = refresh.now;
+        // A bad key fails at startup, not at the first sign-in.
+        if (options?.accessToken) {
+            requireOption(options.accessToken.key, 'accessToken.key', 'a secret of at least 32 bytes or a KeyObject');
+            try {
+                this.signer = new JwtSigner(options.accessToken);
+            }
+            catch (error) {
+                throw new TypeError(`AuthenticationModule: \`accessToken\`: ${error.message.replace(/^JwtSigner: /, '')}`);
+            }
+        }
+        this.expiresIn = Math.floor(durationOr(options?.accessToken?.ttl, '15m') / 1000);
+    }
+    /**
+     * At sign-in: signs an access token and starts a refresh-token family.
+     *
+     * A user with a confirmed authenticator must send a second factor
+     * (`secondFactor`). Without one, `issue()` throws an
+     * `AuthenticationError` whose body says `mfa_required`, and counts
+     * nothing against the user's lockout; with a wrong one, `Invalid code`.
+     * A verified second factor adds `mfa` to the `amr` claim, which
+     * `@Authenticate({ mfa: true })` accepts; `claims.amr` cannot (see
+     * {@link IssueTokensOptions.claims}).
+     */
+    async issue(userId, { claims, method, secondFactor } = {}) {
+        const signer = this.requireSigner();
+        const verified = await this.checkSecondFactor(userId, secondFactor);
+        const own = this.ownClaims(claims);
+        const familyClaims = verified ? { ...own, amr: [...(own?.amr ?? []), 'mfa'] } : own;
+        const familyExpiresAt = new Date(this.now() + this.absoluteTtl);
+        const { token, record } = await this.create(userId, randomToken(16), familyExpiresAt, familyClaims);
+        this.events.emit({
+            type: 'sign-in',
+            userId,
+            tokenFamilyId: record.familyId,
+            ...(method && { method }),
+            ...(verified && { mfa: 'verified' }),
+        });
+        return this.pair(signer, token, record);
+    }
+    /**
+     * Spends a refresh token: returns its successor, and an access token with
+     * the family's claims. Throws {@link RefreshTokenError} (`invalid`,
+     * `expired`, `reused`), which a route answers with 401.
+     */
+    async refresh(refreshToken) {
+        const signer = this.requireSigner();
+        if (typeof refreshToken !== 'string' || !TOKEN_PATTERN.test(refreshToken)) {
+            throw new RefreshTokenError('invalid');
+        }
+        const store = this.storage.refreshTokens;
+        const record = await store.getRefreshToken(sha256(refreshToken));
+        if (!record || (await store.isRefreshTokenFamilyRevoked(record.familyId))) {
+            throw new RefreshTokenError('invalid');
+        }
+        const now = new Date(this.now());
+        const expired = hasExpired(record.expiresAt, now.getTime()) || hasExpired(record.familyExpiresAt, now.getTime());
+        // An unspent token that expired is refused as such, and not spent: presenting it
+        // again is a client retrying, not theft. A spent one stays a reuse, expired or not.
+        if (expired && !record.usedAt) {
+            throw new RefreshTokenError('expired');
+        }
+        if (record.usedAt) {
+            throw await this.reused(record);
+        }
+        // The successor is saved before this token is spent: a store that fails in between leaves it
+        // unspent, so the client's retry is a retry, not a theft that signs the user out. If another
+        // request spent it first, revoking the family revokes this successor too.
+        const next = await this.create(record.userId, record.familyId, record.familyExpiresAt, record.claims);
+        if (!(await store.markRefreshTokenUsed(record.id, now))) {
+            throw await this.reused(record);
+        }
+        return this.pair(signer, next.token, next.record);
+    }
+    /** Two parties hold the token: the family is revoked, and the theft reported. */
+    async reused(record) {
+        await this.storage.refreshTokens.revokeRefreshTokenFamily(record.familyId);
+        this.events.emit({ type: 'refresh-token-reused', userId: record.userId, tokenFamilyId: record.familyId });
+        return new RefreshTokenError('reused');
+    }
+    /**
+     * Signs out the client holding `refreshToken` (one device): revokes its
+     * family. Spent tokens of the family work too. Resolves `false` for
+     * unknown or malformed tokens, which a route should not reveal (RFC 7009
+     * §2.2).
+     */
+    async revoke(refreshToken) {
+        if (typeof refreshToken !== 'string' || !TOKEN_PATTERN.test(refreshToken)) {
+            return false;
+        }
+        const store = this.storage.refreshTokens;
+        const record = await store.getRefreshToken(sha256(refreshToken));
+        if (!record) {
+            return false;
+        }
+        await store.revokeRefreshTokenFamily(record.familyId);
+        this.events.emit({ type: 'sign-out', userId: record.userId, tokenFamilyId: record.familyId });
+        return true;
+    }
+    /** Signs the user out of every token client. Issued access tokens live until they expire. */
+    revokeAll(userId) {
+        return this.storage.refreshTokens.revokeUserRefreshTokens(userId);
+    }
+    /** `true` when a second factor was required and verified; throws when one is required and missing or wrong. */
+    async checkSecondFactor(userId, secondFactor) {
+        if (!(await this.mfa.isEnrolled(userId))) {
+            return false;
+        }
+        const { code, recoveryCode } = secondFactor ?? {};
+        if (!code && !recoveryCode) {
+            throw new AuthenticationError('Second factor required', { code: 'mfa_required' });
+        }
+        const verified = recoveryCode
+            ? await this.mfa.verifyRecoveryCode(userId, recoveryCode)
+            : await this.mfa.verifyTotp(userId, code);
+        if (!verified) {
+            throw new AuthenticationError('Invalid code', { code: 'mfa_required' });
+        }
+        return true;
+    }
+    pair(signer, refreshToken, record) {
+        const accessToken = signer.sign({ ...record.claims, sub: record.userId });
+        return { accessToken, refreshToken, expiresIn: this.expiresIn };
+    }
+    requireSigner() {
+        if (!this.signer) {
+            throw new Error('TokenService: configure `accessToken` (the signing key) in the AuthenticationModule options');
+        }
+        return this.signer;
+    }
+    async create(userId, familyId, familyExpiresAt, claims) {
+        const token = randomToken();
+        const now = this.now();
+        const record = {
+            id: sha256(token),
+            familyId,
+            userId,
+            createdAt: new Date(now),
+            expiresAt: new Date(Math.min(now + this.ttl, familyExpiresAt.getTime())),
+            familyExpiresAt,
+            ...(claims && { claims }),
+        };
+        await this.storage.refreshTokens.saveRefreshToken(record);
+        return { token, record };
+    }
+    /**
+     * The app's claims with `amr` deduplicated and stripped of the values that
+     * mean a second factor: `JwtBearerProvider` would take them as verified,
+     * and only `issue()` knows whether a code was. An `amr` left empty is
+     * dropped. The first token issued with such values logs a warning.
+     */
+    ownClaims(claims) {
+        if (!claims || !Array.isArray(claims.amr)) {
+            return claims;
+        }
+        const { amr, ...rest } = claims;
+        const unique = [...new Set(amr)];
+        const stripped = unique.filter((method) => MFA_AMR_VALUES.includes(method));
+        if (stripped.length && !TokenService_1.warnedAmr) {
+            TokenService_1.warnedAmr = true;
+            TokenService_1.logger.warn(`issue() dropped ${stripped.map((m) => `'${m}'`).join(', ')} from \`claims.amr\`: those values mean a verified second ` +
+                'factor, which only the service records (`mfa`, once a code was verified). Remove them from the claims passed to issue().');
+        }
+        const kept = unique.filter((method) => !stripped.includes(method));
+        return kept.length ? { ...rest, amr: kept } : rest;
+    }
+    now() {
+        return this.clock?.() ?? Date.now();
+    }
+};
+TokenService.logger = new Logger('TokenService');
+/** The `amr` warning is a misconfiguration: once per process says enough. */
+TokenService.warnedAmr = false;
+TokenService = TokenService_1 = __decorate([
+    Injectable(),
+    __param(1, Optional()),
+    __param(1, Inject(AUTHENTICATION_MODULE_OPTIONS)),
+    __metadata("design:paramtypes", [AuthenticationStorage, Object, AuthenticationEvents,
+        MfaService])
+], TokenService);
+export { TokenService };

package/dist/magic-link/in-memory-magic-link.store.d.ts

@@ -0,0 +1,12 @@
+import type { MagicLinkRecord, MagicLinkStore } from '../interfaces/magic-link-store.interface.js';
+/**
+ * Process-local store: the default when no source is registered, and a
+ * test double. Drops expired links as new ones are saved, and holds at most
+ * 10,000, dropping the oldest: anyone can request links, so the store must
+ * not grow with them.
+ */
+export declare class InMemoryMagicLinkStore implements MagicLinkStore {
+    private readonly links;
+    saveMagicLink(record: MagicLinkRecord): Promise<void>;
+    consumeMagicLink(id: string): Promise<MagicLinkRecord | undefined>;
+}

package/dist/magic-link/in-memory-magic-link.store.js

@@ -0,0 +1,45 @@
+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';
+const MAX_PENDING = 10_000;
+/**
+ * Process-local store: the default when no source is registered, and a
+ * test double. Drops expired links as new ones are saved, and holds at most
+ * 10,000, dropping the oldest: anyone can request links, so the store must
+ * not grow with them.
+ */
+let InMemoryMagicLinkStore = class InMemoryMagicLinkStore {
+    constructor() {
+        this.links = new Map();
+    }
+    async saveMagicLink(record) {
+        const now = record.createdAt.getTime();
+        // Insertion order is expiry order (one lifetime per service): stop at the first live entry.
+        for (const [id, link] of this.links) {
+            if (link.expiresAt.getTime() > now) {
+                break;
+            }
+            this.links.delete(id);
+        }
+        this.links.set(record.id, { ...record });
+        for (const id of this.links.keys()) {
+            if (this.links.size <= MAX_PENDING) {
+                break;
+            }
+            this.links.delete(id); // insertion order: the oldest first
+        }
+    }
+    async consumeMagicLink(id) {
+        const record = this.links.get(id);
+        this.links.delete(id);
+        return record;
+    }
+};
+InMemoryMagicLinkStore = __decorate([
+    Injectable()
+], InMemoryMagicLinkStore);
+export { InMemoryMagicLinkStore };

package/dist/magic-link/magic-link.handler.d.ts

@@ -0,0 +1,25 @@
+import type { MagicLink, MagicLinkAccount } from '../interfaces/magic-link.interface.js';
+/**
+ * Implemented by the app: delivery (the module ships no mailer) and the
+ * email-to-user mapping (look up, or create for passwordless sign-up).
+ * An ordinary provider of one of your modules, which registers itself from
+ * its constructor: `registry.registerHandler('magicLink', this)`.
+ *
+ * The link proves the address, not that the account behind it was created
+ * by the same person: if accounts can be registered without verifying the
+ * email (password sign-up), refuse links to accounts whose address was
+ * never verified, or someone who registered the address first keeps access
+ * (account pre-hijacking).
+ */
+export declare abstract class MagicLinkHandler {
+    abstract send(link: MagicLink): void | Promise<void>;
+    /**
+     * The account for an address (trimmed, lowercased, NFC), with the
+     * address it has stored, or `null` to refuse. The link signs in only an
+     * account whose stored `email` is the link's address, compared trimmed
+     * and lowercased: a lookup that ignores accents or dots (MySQL's default
+     * collation does) would otherwise sign whoever reads `victim@exämple.com`
+     * in to `victim@example.com`'s account.
+     */
+    abstract resolveUser(email: string): MagicLinkAccount | null | Promise<MagicLinkAccount | null>;
+}

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

@@ -0,0 +1,14 @@
+/**
+ * Implemented by the app: delivery (the module ships no mailer) and the
+ * email-to-user mapping (look up, or create for passwordless sign-up).
+ * An ordinary provider of one of your modules, which registers itself from
+ * its constructor: `registry.registerHandler('magicLink', this)`.
+ *
+ * The link proves the address, not that the account behind it was created
+ * by the same person: if accounts can be registered without verifying the
+ * email (password sign-up), refuse links to accounts whose address was
+ * never verified, or someone who registered the address first keeps access
+ * (account pre-hijacking).
+ */
+export class MagicLinkHandler {
+}

package/dist/magic-link/magic-link.service.d.ts

@@ -0,0 +1,79 @@
+import { HttpAdapterHost } from '@nestjs/core';
+import { AuthenticationScope } from '../context/authentication-scope.service.js';
+import { AuthenticationRegistry } from '../services/authentication-registry.service.js';
+import { AuthenticationStorage } from '../storage/authentication.storage.js';
+import { AuthenticationEvents } from '../events/authentication-events.service.js';
+import type { IssuedSession } from '../interfaces/session.interface.js';
+import { SignInService } from '../session/sign-in.service.js';
+import type { MagicLinkOptions, MagicLinkRequest, CreatedMagicLink } from '../interfaces/magic-link.interface.js';
+/**
+ * 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`.
+ */
+export declare class MagicLinkService {
+    private readonly storage;
+    private readonly registry;
+    private readonly signIn;
+    private readonly scope;
+    private readonly adapterHost?;
+    private readonly events;
+    private readonly options?;
+    private readonly ttl;
+    private readonly bindToBrowser;
+    private readonly txCookieName;
+    constructor(storage: AuthenticationStorage, registry: AuthenticationRegistry, signIn: SignInService, options?: {
+        magicLink?: MagicLinkOptions;
+    }, scope?: AuthenticationScope, adapterHost?: HttpAdapterHost | undefined, events?: AuthenticationEvents);
+    /**
+     * 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()`.
+     */
+    create(email: string, { redirectTo }?: {
+        redirectTo?: string;
+    }): Promise<CreatedMagicLink>;
+    /**
+     * 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.
+     */
+    consume(token: string, { request }?: {
+        request?: MagicLinkRequest;
+    }): Promise<(IssuedSession & {
+        redirectTo?: string;
+    }) | null>;
+    /** The options and the handler; the module refuses to start with one and not the other. */
+    private feature;
+    /** The generic answer: which refusal it was is told only by the event. */
+    private refuse;
+    private txCookie;
+    private setCookie;
+    private now;
+}