@nestjs/authentication 0.1.1 → 0.1.3

package/README.md

@@ -18,7 +18,7 @@
 
 ## Description
 
-Authentication module for [Nest](https://github.com/nestjs/nest): a global guard with `@Public()` and `@Authenticate()`, credential providers as ordinary injectable classes (bearer JWT, cookie sessions, your own), server-side sessions with rotation, refresh tokens, TOTP second factor, magic links, OIDC sign-in, email verification and password reset, across HTTP, GraphQL, WebSockets and microservices, with no third-party dependencies.
+Authentication module for [Nest](https://github.com/nestjs/nest): a global guard with `@Public()` and `@Authenticate()`, credential providers as ordinary injectable classes (bearer JWT, cookie sessions, your own), server-side sessions with rotation, refresh tokens, TOTP second factor, magic links, OIDC sign-in, email verification and password reset, across HTTP, GraphQL, WebSockets, microservices and MCP tool calls (`@nestjs/mcp`), with no third-party dependencies.
 
 ## Installation
 

package/SECURITY.md

@@ -0,0 +1,13 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+Please report security issues to `support@nestjs.com` rather than in a public issue or pull request.
+
+A good report includes:
+
+- the version of `@nestjs/authentication` you found it in, and of Node.js,
+- the steps or a short script that reproduce it,
+- what an attacker could do with it.
+
+Please give us a chance to release a fix before you disclose the issue publicly.

package/dist/account/email-verification.service.d.ts

@@ -14,6 +14,7 @@ export declare class EmailVerificationService {
     private readonly storage;
     private readonly registry;
     private readonly events;
+    private static readonly logger;
     private readonly options?;
     private readonly ttl;
     constructor(storage: AuthenticationStorage, registry: AuthenticationRegistry, options?: {
@@ -34,7 +35,8 @@ export declare class EmailVerificationService {
      * Burns the token and asks `EmailVerificationHandler.markVerified()` to
      * record the address, if it is still the user's. Resolves the verified
      * address, or `null` for unknown, used or expired tokens and for an
-     * address the user has since changed.
+     * address the user has since changed. When `markVerified()` throws, the
+     * link works again until it expires, and the error is rethrown.
      */
     verify(token: string): Promise<{
         userId: string;

package/dist/account/email-verification.service.js

@@ -10,7 +10,8 @@ var __metadata = (this && this.__metadata) || function (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';
+var EmailVerificationService_1;
+import { Inject, Injectable, Logger, Optional } from '@nestjs/common';
 import { AuthenticationRegistry } from '../services/authentication-registry.service.js';
 import { AuthenticationStorage } from '../storage/authentication.storage.js';
 import { AUTHENTICATION_MODULE_OPTIONS } from '../authentication.constants.js';
@@ -26,7 +27,7 @@ import { requireUrlOption } from '../utils/options.util.js';
  * Point the link at a page that POSTs the token back: mail scanners and link
  * previews follow GET links, and would use it up.
  */
-let EmailVerificationService = class EmailVerificationService {
+let EmailVerificationService = EmailVerificationService_1 = class EmailVerificationService {
     constructor(storage, registry, options, events = new AuthenticationEvents()) {
         this.storage = storage;
         this.registry = registry;
@@ -70,7 +71,8 @@ let EmailVerificationService = class EmailVerificationService {
      * Burns the token and asks `EmailVerificationHandler.markVerified()` to
      * record the address, if it is still the user's. Resolves the verified
      * address, or `null` for unknown, used or expired tokens and for an
-     * address the user has since changed.
+     * address the user has since changed. When `markVerified()` throws, the
+     * link works again until it expires, and the error is rethrown.
      */
     async verify(token) {
         const { handler } = this.feature();
@@ -81,7 +83,17 @@ let EmailVerificationService = class EmailVerificationService {
         if (!record || hasExpired(record.expiresAt, this.now())) {
             return null;
         }
-        if (!(await handler.markVerified(record.userId, record.email))) {
+        let verified;
+        try {
+            verified = await handler.markVerified(record.userId, record.email);
+        }
+        catch (error) {
+            // Give the link back, so the user can try it again rather than ask for another email. Marking
+            // an address verified twice changes nothing, and one the user changed since gets `false`.
+            await this.storage.emailTokens.saveEmailToken(record).catch((saveError) => EmailVerificationService_1.logger.error('Could not give back an email verification link', saveError instanceof Error ? saveError.stack : saveError));
+            throw error;
+        }
+        if (!verified) {
             return null;
         }
         await this.storage.emailTokens.deleteUserEmailTokens(record.userId, 'email-verification');
@@ -101,7 +113,8 @@ let EmailVerificationService = class EmailVerificationService {
         return this.options?.now?.() ?? Date.now();
     }
 };
-EmailVerificationService = __decorate([
+EmailVerificationService.logger = new Logger('EmailVerificationService');
+EmailVerificationService = EmailVerificationService_1 = __decorate([
     Injectable(),
     __param(2, Optional()),
     __param(2, Inject(AUTHENTICATION_MODULE_OPTIONS)),

package/dist/account/password-reset.service.d.ts

@@ -62,11 +62,18 @@ export declare class PasswordResetService implements OnModuleDestroy {
      * another origin than the app's own and `session.trustedOrigins` gets a
      * `ForbiddenException` first, as `SignInService.signIn()` does, so the link
      * and the password stay as they were. Without `signIn`, the origin is not
-     * checked.
+     * checked. When a step throws before the new password is stored (the
+     * lookup, the hash, ending sign-ins, `updatePassword()`), the link works
+     * again until it expires, and the error is rethrown.
      */
     reset(token: string, password: string, { signIn }?: ResetPasswordOptions): Promise<PasswordResetResult | null>;
     onModuleDestroy(): Promise<void>;
     private issue;
+    /**
+     * Checks the link's account and stores the new password's hash. `null` for an account that is gone
+     * or changed its address or password since the link was sent.
+     */
+    private setPassword;
     /** Ends every session and refresh-token family (with refresh tokens on) of the user. */
     private revokeSignIns;
     /** The options and the handler; the module refuses to start with one and not the other. */

package/dist/account/password-reset.service.js

@@ -93,7 +93,9 @@ let PasswordResetService = PasswordResetService_1 = class PasswordResetService {
      * another origin than the app's own and `session.trustedOrigins` gets a
      * `ForbiddenException` first, as `SignInService.signIn()` does, so the link
      * and the password stay as they were. Without `signIn`, the origin is not
-     * checked.
+     * checked. When a step throws before the new password is stored (the
+     * lookup, the hash, ending sign-ins, `updatePassword()`), the link works
+     * again until it expires, and the error is rethrown.
      */
     async reset(token, password, { signIn = false } = {}) {
         const { handler } = this.feature();
@@ -109,20 +111,21 @@ let PasswordResetService = PasswordResetService_1 = class PasswordResetService {
         if (!record || hasExpired(record.expiresAt, this.now())) {
             return null;
         }
-        const found = await handler.findUser(normalizeEmail(record.email));
-        const account = found && checked(found);
-        if (!account ||
-            account.id !== record.userId ||
-            account.email !== record.email ||
-            !safeEqual(fingerprint(account.passwordHash), record.fingerprint ?? '')) {
+        let account;
+        try {
+            account = await this.setPassword(handler, record, password);
+        }
+        catch (error) {
+            // A step failed before the new password was stored, as far as this request can tell: give the
+            // link back, so the customer can try it again rather than ask for another email. Safe even if
+            // updatePassword() stored the hash and then threw: the link is bound to the fingerprint of the
+            // password it replaces, so once that changed, it sets nothing.
+            await this.storage.emailTokens.saveEmailToken(record).catch((saveError) => PasswordResetService_1.logger.error('Could not give back a password reset link', saveError instanceof Error ? saveError.stack : saveError));
+            throw error;
+        }
+        if (!account) {
             return null;
         }
-        const passwordHash = await this.hasher.hash(password);
-        // Sign-ins end before the new password is stored, so a store that fails leaves the old password
-        // without its sessions rather than the new one next to them; and again after, for any sign-in
-        // that started in between.
-        await this.revokeSignIns(account.id);
-        await handler.updatePassword(account.id, passwordHash);
         await this.storage.emailTokens.deleteUserEmailTokens(account.id, 'password-reset');
         await this.revokeSignIns(account.id);
         // The link reached the address, and the password is the owner's now.
@@ -161,6 +164,27 @@ let PasswordResetService = PasswordResetService_1 = class PasswordResetService {
         url.searchParams.set('token', token);
         await handler.send({ userId: account.id, email: account.email, url: url.toString(), expiresAt });
     }
+    /**
+     * Checks the link's account and stores the new password's hash. `null` for an account that is gone
+     * or changed its address or password since the link was sent.
+     */
+    async setPassword(handler, record, password) {
+        const found = await handler.findUser(normalizeEmail(record.email));
+        const account = found && checked(found);
+        if (!account ||
+            account.id !== record.userId ||
+            account.email !== record.email ||
+            !safeEqual(fingerprint(account.passwordHash), record.fingerprint ?? '')) {
+            return null;
+        }
+        const passwordHash = await this.hasher.hash(password);
+        // Sign-ins end before the new password is stored, so a store that fails leaves the old password
+        // without its sessions rather than the new one next to them; and again after, for any sign-in
+        // that started in between.
+        await this.revokeSignIns(account.id);
+        await handler.updatePassword(account.id, passwordHash);
+        return account;
+    }
     /** Ends every session and refresh-token family (with refresh tokens on) of the user. */
     async revokeSignIns(userId) {
         await this.sessions.revokeAll(userId);

package/dist/context/authentication-scope.service.d.ts

@@ -32,8 +32,11 @@ export declare class AuthenticationScope {
     get current(): Scope | undefined;
     run<R>(scope: Scope, fn: () => R): R;
     /**
-     * The HTTP request and response of the current call: an HTTP handler, or
-     * a GraphQL resolver whose context carries `req` (and `res`).
+     * The HTTP request and response of the current call: an HTTP handler, a
+     * GraphQL resolver whose context carries `req` (and `res`), or an
+     * `@nestjs/mcp` call that arrived over HTTP (its context, the second of
+     * its arguments, carries `request`). An MCP call has no response of its own
+     * to set cookies on: the MCP SDK writes the HTTP response.
      */
     exchange(): HttpExchange | undefined;
 }

package/dist/context/authentication-scope.service.js

@@ -39,8 +39,11 @@ let AuthenticationScope = class AuthenticationScope {
         return this.storage.run(scope, fn);
     }
     /**
-     * The HTTP request and response of the current call: an HTTP handler, or
-     * a GraphQL resolver whose context carries `req` (and `res`).
+     * The HTTP request and response of the current call: an HTTP handler, a
+     * GraphQL resolver whose context carries `req` (and `res`), or an
+     * `@nestjs/mcp` call that arrived over HTTP (its context, the second of
+     * its arguments, carries `request`). An MCP call has no response of its own
+     * to set cookies on: the MCP SDK writes the HTTP response.
      */
     exchange() {
         const context = this.current?.context;
@@ -53,6 +56,10 @@ let AuthenticationScope = class AuthenticationScope {
                 const gql = context.getArgByIndex(2);
                 return gql?.req ? { request: gql.req, response: gql.res } : undefined;
             }
+            case 'mcp': {
+                const request = context.getArgByIndex(1)?.request;
+                return request?.headers ? { request } : undefined;
+            }
             default:
                 return undefined;
         }

package/dist/interfaces/email-token-store.interface.d.ts

@@ -37,7 +37,9 @@ export interface EmailTokenStore {
     /**
      * Saves a new token (a fresh random id: a plain insert), then keeps the
      * store bounded: deletes tokens whose `expiresAt` is at or before this
-     * one's `createdAt`, and past a cap, those that expire first.
+     * one's `createdAt`, and past a cap, those that expire first. The services
+     * also save back a record `consumeEmailToken()` just returned, when a step
+     * after it failed: its id is free again, so that is a plain insert too.
      */
     saveEmailToken(record: EmailTokenRecord): Promise<void>;
     /**

package/dist/interfaces/oidc.interface.d.ts

@@ -55,7 +55,27 @@ export interface OidcOptions extends OidcClientOptions {
      * domain where it started.
      */
     callbackUrl: string | ((request: OidcRequest) => string | Promise<string>);
-    providers: Record<string, OidcProviderConfig>;
+    /**
+     * The providers users can sign in with, by name: the `:provider` of your
+     * routes, and the `provider` of each profile they sign in with.
+     *
+     * Providers that aren't known at startup (one OIDC client per customer,
+     * created at runtime) come from a function of the name instead, called on
+     * the login and again on the callback: return the provider's config, or
+     * `undefined` (or `null`) for a name you don't serve, which answers 404.
+     * A rotated secret is used from the next call on. Each config it returns
+     * gets the checks the object form gets at startup. Caching your lookup is
+     * yours to do; discovery documents and key sets are cached by issuer and
+     * by URI, whatever the name.
+     *
+     * Identities are linked by (provider, subject), so a name must stand for
+     * one client of one provider: put the customer in the name (`acme`),
+     * rather than reusing one name for every customer's own provider. A
+     * provider a customer brings vouches for whatever addresses it likes, as
+     * verified ones too: link by email only to that customer's accounts, and
+     * check an issuer they enter against the providers you support.
+     */
+    providers: Record<string, OidcProviderConfig> | ((name: string) => OidcProviderConfig | null | undefined | Promise<OidcProviderConfig | null | undefined>);
     /** Where to land after sign-in when the login had no `redirectTo`. Default `/`. */
     redirectAfterLogin?: string;
     /** Lifetime of a login between the redirect to the provider and the callback. Default `'10m'`. */

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

@@ -64,7 +64,10 @@ export declare class MagicLinkService {
      * 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.
+     * HTTP handler, pass the `request` that carries the cookie. A request from
+     * another origin than the app's own and `session.trustedOrigins` gets a
+     * `ForbiddenException` first, as `SignInService.signIn()` does, so the
+     * link and the cookie stay as they were.
      */
     consume(token: string, { request }?: {
         request?: MagicLinkRequest;

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

@@ -146,10 +146,16 @@ let MagicLinkService = class MagicLinkService {
      * 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.
+     * HTTP handler, pass the `request` that carries the cookie. A request from
+     * another origin than the app's own and `session.trustedOrigins` gets a
+     * `ForbiddenException` first, as `SignInService.signIn()` does, so the
+     * link and the cookie stay as they were.
      */
     async consume(token, { request } = {}) {
         const { handler } = this.feature();
+        // Signing in would refuse this request at the end, after the link is spent and the cookie
+        // settled: refuse it before, whatever the token is.
+        this.signIn.refuseCrossOrigin(this.scope.exchange()?.request);
         if (typeof token !== 'string' || !TOKEN_PATTERN.test(token)) {
             return this.refuse('unknown');
         }

package/dist/oidc/oidc.client.d.ts

@@ -1,5 +1,32 @@
+import { JwksClient } from '../jwt/jwks.client.js';
 import type { OAuthTokens, OidcProfile, OidcProviderConfig } from '../interfaces/oidc-provider.interface.js';
 import type { OidcTransaction, OidcClientOptions } from '../interfaces/oidc.interface.js';
+interface Endpoints {
+    issuer?: string;
+    authorization_endpoint: string;
+    token_endpoint: string;
+    userinfo_endpoint?: string;
+    jwks_uri?: string;
+    authorization_response_iss_parameter_supported?: boolean;
+}
+/**
+ * What the clients of one `OidcService` share: discovery documents, by
+ * issuer, and key sets, by URI. Neither depends on the client id or secret,
+ * so a client made anew for each login (`oidc.providers` as a function)
+ * still fetches them once per TTL, and the key set's cooldown still holds.
+ */
+export declare class OidcMetadataCache {
+    private readonly options;
+    private readonly documents;
+    private readonly keySets;
+    constructor(options?: OidcClientOptions);
+    /** The discovery document of `issuer`, as published: the endpoints a config overrides are its own to merge. */
+    document(issuer: string): Promise<Endpoints>;
+    /** The key set at `uri`, an https URL. */
+    jwks(uri: string): JwksClient;
+    private discover;
+    private now;
+}
 /**
  * One OAuth 2.0 / OpenID Connect provider: authorization code flow with
  * PKCE (S256), `state` and `nonce`.
@@ -13,10 +40,9 @@ export declare class OidcClient {
     readonly name: string;
     private readonly config;
     private readonly options;
-    private discovery?;
-    private jwks?;
+    private readonly metadata;
     readonly kind: 'oidc' | 'oauth2';
-    constructor(name: string, config: OidcProviderConfig, options?: OidcClientOptions);
+    constructor(name: string, config: OidcProviderConfig, options?: OidcClientOptions, metadata?: OidcMetadataCache);
     /**
      * The provider's authorization URL, the transaction to store, and the
      * browser binding for the transaction cookie. `state` is the SHA-256 of
@@ -37,8 +63,8 @@ export declare class OidcClient {
     private verifyIdToken;
     private exchange;
     private endpoints;
-    private discover;
     private getJson;
     private request;
     private now;
 }
+export {};

package/dist/oidc/oidc.client.js

@@ -8,8 +8,10 @@ import { OidcError } from '../errors/oidc.error.js';
 const LOOPBACK = new Set(['localhost', '127.0.0.1', '[::1]']);
 /**
  * Only https, except loopback http (local IdPs and tests). The URLs come from the provider's
- * discovery document or the app's configuration, never from the user: a bad one is a
- * misconfiguration (`unavailable`, a 502), not a failed sign-in.
+ * discovery document or the app's configuration, never from the request: a bad one is a
+ * misconfiguration (`unavailable`, a 502), not a failed sign-in. Nor does this keep a fetch off
+ * the app's own network: an issuer that customers enter themselves is the app's to check
+ * against the providers it supports, before it stores it.
  */
 function assertSecureUrl(value, what) {
     let url;
@@ -24,6 +26,66 @@ function assertSecureUrl(value, what) {
     }
     return url.toString();
 }
+/** A request to the provider: no redirects, a 10 s timeout, and a network failure as an outage. */
+async function send(options, url, init) {
+    try {
+        return await (options.fetch ?? fetch)(url, { ...init, redirect: 'error', signal: AbortSignal.timeout(10_000) });
+    }
+    catch (error) {
+        throw new OidcError(`${new URL(url).host} is unreachable (${error.message})`, 'unavailable');
+    }
+}
+/**
+ * What the clients of one `OidcService` share: discovery documents, by
+ * issuer, and key sets, by URI. Neither depends on the client id or secret,
+ * so a client made anew for each login (`oidc.providers` as a function)
+ * still fetches them once per TTL, and the key set's cooldown still holds.
+ */
+export class OidcMetadataCache {
+    constructor(options = {}) {
+        this.options = options;
+        this.documents = new Map();
+        this.keySets = new Map();
+    }
+    /** The discovery document of `issuer`, as published: the endpoints a config overrides are its own to merge. */
+    document(issuer) {
+        const ttl = durationOr(this.options.discoveryTtl, '1h');
+        let cached = this.documents.get(issuer);
+        if (!cached || this.now() - cached.at >= ttl) {
+            const entry = { value: this.discover(issuer), at: this.now() };
+            this.documents.set(issuer, entry);
+            // Retry next time, unless a later fetch has taken its place.
+            entry.value.catch(() => this.documents.get(issuer) === entry && this.documents.delete(issuer));
+            cached = entry;
+        }
+        return cached.value;
+    }
+    /** The key set at `uri`, an https URL. */
+    jwks(uri) {
+        let jwks = this.keySets.get(uri);
+        if (!jwks) {
+            jwks = new JwksClient(uri, { ...this.options.jwks, fetch: this.options.fetch, now: this.options.now });
+            this.keySets.set(uri, jwks);
+        }
+        return jwks;
+    }
+    async discover(issuer) {
+        const url = `${issuer.replace(/\/$/, '')}/.well-known/openid-configuration`;
+        const response = await send(this.options, assertSecureUrl(url, 'issuer'), { headers: { accept: 'application/json' } });
+        if (!response.ok) {
+            throw new OidcError(`discovery failed (${response.status})`, 'unavailable');
+        }
+        const doc = (await response.json().catch(() => ({})));
+        // OIDC Discovery §4.3: the document must name exactly the issuer we asked.
+        if (doc.issuer !== issuer) {
+            throw new OidcError('discovery issuer mismatch', 'unavailable');
+        }
+        return doc;
+    }
+    now() {
+        return this.options.now?.() ?? Date.now();
+    }
+}
 /**
  * One OAuth 2.0 / OpenID Connect provider: authorization code flow with
  * PKCE (S256), `state` and `nonce`.
@@ -34,10 +96,11 @@ function assertSecureUrl(value, what) {
  * userinfo's `sub` matches the ID token's (OIDC Core §5.3.2).
  */
 export class OidcClient {
-    constructor(name, config, options = {}) {
+    constructor(name, config, options = {}, metadata = new OidcMetadataCache(options)) {
         this.name = name;
         this.config = config;
         this.options = options;
+        this.metadata = metadata;
         this.kind = config.kind ?? 'oidc';
         if (this.kind === 'oidc' && !config.issuer) {
             throw new Error(`OIDC provider '${name}' needs an issuer`);
@@ -138,13 +201,8 @@ export class OidcClient {
         };
     }
     async verifyIdToken(endpoints, idToken, nonce) {
-        this.jwks ??= new JwksClient(assertSecureUrl(endpoints.jwks_uri, 'jwks_uri'), {
-            ...this.options.jwks,
-            fetch: this.options.fetch,
-            now: this.options.now,
-        });
         const verifier = new JwtVerifier({
-            jwks: this.jwks,
+            jwks: this.metadata.jwks(assertSecureUrl(endpoints.jwks_uri, 'jwks_uri')),
             algorithms: this.config.idTokenAlgorithms ?? ['RS256', 'ES256'],
             issuer: endpoints.issuer,
             audience: this.config.clientId,
@@ -229,26 +287,7 @@ export class OidcClient {
                 }),
             };
         }
-        const ttl = durationOr(this.options.discoveryTtl, '1h');
-        if (!this.discovery || this.now() - this.discovery.at >= ttl) {
-            const value = this.discover();
-            this.discovery = { value, at: this.now() };
-            value.catch(() => (this.discovery = undefined)); // retry next time
-        }
-        return this.discovery.value;
-    }
-    async discover() {
-        const issuer = this.config.issuer;
-        const url = `${issuer.replace(/\/$/, '')}/.well-known/openid-configuration`;
-        const response = await this.request(assertSecureUrl(url, 'issuer'), { headers: { accept: 'application/json' } });
-        if (!response.ok) {
-            throw new OidcError(`discovery failed (${response.status})`, 'unavailable');
-        }
-        const doc = (await response.json().catch(() => ({})));
-        // OIDC Discovery §4.3: the document must name exactly the issuer we asked.
-        if (doc.issuer !== issuer) {
-            throw new OidcError('discovery issuer mismatch', 'unavailable');
-        }
+        const doc = await this.metadata.document(this.config.issuer);
         return {
             ...doc,
             authorization_endpoint: assertSecureUrl(this.config.authorizationEndpoint ?? doc.authorization_endpoint, 'authorization_endpoint'),
@@ -272,13 +311,8 @@ export class OidcClient {
         }
         return response.json();
     }
-    async request(url, init) {
-        try {
-            return await (this.options.fetch ?? fetch)(url, { ...init, redirect: 'error', signal: AbortSignal.timeout(10_000) });
-        }
-        catch (error) {
-            throw new OidcError(`${new URL(url).host} is unreachable (${error.message})`, 'unavailable');
-        }
+    request(url, init) {
+        return send(this.options, url, init);
     }
     now() {
         return this.options.now?.() ?? Date.now();

package/dist/oidc/oidc.service.d.ts

@@ -5,7 +5,6 @@ import { AuthenticationStorage } from '../storage/authentication.storage.js';
 import { SessionService } from '../session/session.service.js';
 import { SignInService } from '../session/sign-in.service.js';
 import type { OidcOptions, OidcRequest, OidcRedirect, OidcStartOptions } from '../interfaces/oidc.interface.js';
-import { OidcClient } from './oidc.client.js';
 /**
  * OpenID Connect sign-in, behind two routes of your own: a login route that
  * redirects to the provider, and the callback route it sends the browser
@@ -53,14 +52,13 @@ export declare class OidcService {
     private readonly sessions;
     private readonly scope;
     private readonly adapterHost?;
-    private readonly clients;
+    private readonly metadata;
     private readonly options?;
     private readonly transactionTtl;
     private readonly txCookieName;
     constructor(storage: AuthenticationStorage, registry: AuthenticationRegistry, signIn: SignInService, sessions: SessionService, options?: {
         oidc?: OidcOptions;
     }, scope?: AuthenticationScope, adapterHost?: HttpAdapterHost | undefined);
-    client(name: string): OidcClient;
     /**
      * Starts a login: stores the transaction, sets its cookie, and returns
      * the provider's authorization URL. 404 for a provider that isn't
@@ -82,6 +80,13 @@ export declare class OidcService {
     private feature;
     /** A fully signed-in session (second factor done, if any) on this request. */
     private currentSession;
+    /**
+     * The client of the provider named `name`, made for this call from its
+     * config: a secret the `oidc.providers` function rotates is the one the
+     * next call uses. 404 for a provider that isn't configured, or that the
+     * function doesn't serve.
+     */
+    private client;
     /** `oidc.callbackUrl` for this request, with the provider's name in it. */
     private callbackUrl;
     private txCookie;

package/dist/oidc/oidc.service.js

@@ -23,7 +23,7 @@ import { defaultCookieName, readCookie, serializeCookie } from '../session/cooki
 import { SessionService } from '../session/session.service.js';
 import { SignInService } from '../session/sign-in.service.js';
 import { OidcError } from '../errors/oidc.error.js';
-import { OidcClient } from './oidc.client.js';
+import { OidcClient, OidcMetadataCache } from './oidc.client.js';
 const header = (headers, name) => {
     const value = headers[name];
     return Array.isArray(value) ? value[0] : value;
@@ -76,30 +76,19 @@ let OidcService = class OidcService {
         this.sessions = sessions;
         this.scope = scope;
         this.adapterHost = adapterHost;
-        this.clients = new Map();
         this.options = options?.oidc;
         if (this.options) {
             if (typeof this.options.callbackUrl !== 'function') {
                 assertCallbackUrl(this.options.callbackUrl);
             }
-            assertProviderCredentials(this.options.providers);
+            if (typeof this.options.providers !== 'function') {
+                assertProviderCredentials(this.options.providers);
+            }
         }
+        this.metadata = new OidcMetadataCache(this.options);
         this.transactionTtl = durationOr(this.options?.transactionTtl, '10m');
         this.txCookieName = defaultCookieName('oidc_tx', this.options?.cookie);
     }
-    client(name) {
-        const { options } = this.feature();
-        const config = Object.hasOwn(options.providers, name) ? options.providers[name] : undefined;
-        if (!config) {
-            throw new NotFoundException();
-        }
-        let client = this.clients.get(name);
-        if (!client) {
-            client = new OidcClient(name, config, options);
-            this.clients.set(name, client);
-        }
-        return client;
-    }
     /**
      * Starts a login: stores the transaction, sets its cookie, and returns
      * the provider's authorization URL. 404 for a provider that isn't
@@ -121,7 +110,8 @@ let OidcService = class OidcService {
             }
             linking = { userId: session.userId, sessionId: session.id };
         }
-        const { url, transaction, binding } = await this.client(provider)
+        const client = await this.client(provider);
+        const { url, transaction, binding } = await client
             .authorizationRequest(await this.callbackUrl(provider, req), safeRedirectPath(redirectTo), this.transactionTtl)
             .catch(toHttp);
         await this.storage.oidcStates.saveOidcState({ ...transaction, ...(linking && { link: linking }) });
@@ -151,7 +141,8 @@ let OidcService = class OidcService {
         // Asked again rather than stored with the login: the cookie keeps the callback on the login's host,
         // and a function that answers otherwise gets the code refused by the provider, not accepted.
         const callbackUrl = await this.callbackUrl(provider, req);
-        const result = await this.client(provider).callback(query, transaction, callbackUrl).catch(toHttp);
+        const client = await this.client(provider);
+        const result = await client.callback(query, transaction, callbackUrl).catch(toHttp);
         const location = transaction.redirectTo ?? options.redirectAfterLogin ?? '/';
         if (transaction.link) {
             // The session that asked to link must still be the one on this browser.
@@ -199,6 +190,29 @@ let OidcService = class OidcService {
         const session = await this.sessions.validate(this.sessions.tokenFrom(request));
         return session && session.mfa !== 'pending' ? session : null;
     }
+    /**
+     * The client of the provider named `name`, made for this call from its
+     * config: a secret the `oidc.providers` function rotates is the one the
+     * next call uses. 404 for a provider that isn't configured, or that the
+     * function doesn't serve.
+     */
+    async client(name) {
+        const { providers } = this.feature().options;
+        let config;
+        if (typeof providers === 'function') {
+            config = await providers(name);
+            if (config) {
+                assertResolvedCredentials(name, config);
+            }
+        }
+        else {
+            config = Object.hasOwn(providers, name) ? providers[name] : undefined;
+        }
+        if (!config) {
+            throw new NotFoundException();
+        }
+        return new OidcClient(name, config, this.options, this.metadata);
+    }
     /** `oidc.callbackUrl` for this request, with the provider's name in it. */
     async callbackUrl(provider, request) {
         const { callbackUrl } = this.feature().options;
@@ -244,6 +258,10 @@ function assertCallbackUrl(value, must = '`oidc.callbackUrl` must be') {
             `provider's name goes, e.g. 'https://app.example.com/auth/oidc/:provider/callback'. Got ${JSON.stringify(value)}.`);
     }
 }
+const CREDENTIALS = {
+    clientId: 'the client id the provider issued',
+    clientSecret: "the client secret the provider issued; a public client sets `tokenEndpointAuthMethod: 'none'` instead",
+};
 /**
  * `oidc.providers.<name>.clientId`, and `clientSecret` unless the provider
  * is a public client (`tokenEndpointAuthMethod: 'none'`), checked at
@@ -251,11 +269,20 @@ function assertCallbackUrl(value, must = '`oidc.callbackUrl` must be') {
  * confidential client into a public one, and fail at the token exchange.
  */
 function assertProviderCredentials(providers) {
-    requireOption(providers, 'oidc.providers', 'the providers users can sign in with, by name');
+    requireOption(providers, 'oidc.providers', 'the providers users can sign in with, by name, or a function of the name');
     for (const [name, config] of Object.entries(providers)) {
-        requireOption(config?.clientId, `oidc.providers.${name}.clientId`, 'the client id the provider issued');
+        requireOption(config?.clientId, `oidc.providers.${name}.clientId`, CREDENTIALS.clientId);
         if (config.tokenEndpointAuthMethod !== 'none') {
-            requireOption(config.clientSecret, `oidc.providers.${name}.clientSecret`, "the client secret the provider issued; a public client sets `tokenEndpointAuthMethod: 'none'` instead");
+            requireOption(config.clientSecret, `oidc.providers.${name}.clientSecret`, CREDENTIALS.clientSecret);
+        }
+    }
+}
+/** The same checks, on each config the `oidc.providers` function returns. */
+function assertResolvedCredentials(name, config) {
+    for (const key of ['clientId', 'clientSecret']) {
+        if (!config[key] && (key === 'clientId' || config.tokenEndpointAuthMethod !== 'none')) {
+            throw new Error(`OidcService: the \`oidc.providers\` function returned the provider '${name}' without its \`${key}\` ` +
+                `(${CREDENTIALS[key]}).`);
         }
     }
 }

package/dist/services/password-hasher.service.d.ts

@@ -14,7 +14,9 @@ export declare function isHashablePassword(password: unknown): password is strin
  * The encoded hash is self-describing (`$scrypt$ln=17,r=8,p=1$salt$hash`),
  * so parameters can be raised later: `verify()` reads the parameters from
  * the stored hash and `needsRehash()` tells the sign-in code to store a
- * fresh hash while it has the plaintext.
+ * fresh hash while it has the plaintext. Until then, `verify()` makes up the
+ * work an older, cheaper hash saves, so it answers no sooner than for an
+ * unknown user.
  *
  * Passwords are NFKC-normalised (NIST SP 800-63B §5.1.1.2) so the same
  * password typed on different keyboards verifies. `hash()` refuses an empty
@@ -37,6 +39,11 @@ export declare class PasswordHasher {
      * is checked instead, so response time does not reveal which accounts
      * exist. The first such call makes the dummy hash, which costs the same
      * one derivation as every later check.
+     *
+     * A hash stored before the cost was raised is cheaper to check than the
+     * dummy, so its check is topped up to the configured work, right password
+     * or wrong. One stored before the cost was lowered takes its longer time
+     * until it is rehashed: that can't be hidden.
      */
     verify(password: string, encoded: string | null | undefined): Promise<boolean>;
     /** `true` when the stored hash uses weaker or different parameters than configured. */

package/dist/services/password-hasher.service.js

@@ -8,6 +8,8 @@ function scrypt(password, salt, keyLength, { logN, r, p }) {
     return new Promise((resolve, reject) => scryptCb(password, salt, keyLength, options, (err, key) => (err ? reject(err) : resolve(key))));
 }
 const b64 = (buf) => buf.toString('base64').replace(/=+$/, '');
+/** What a derivation costs: N·r·p, since OpenSSL runs the `p` lanes one after another. */
+const work = ({ logN, r, p }) => 2 ** logN * r * p;
 /**
  * @internal The bytes `PasswordHasher` derives from: the password NFKC-normalised, as UTF-8. Throws
  * for anything but a string, for an empty one (which no account should have), and past 4 KiB,
@@ -48,7 +50,9 @@ export function isHashablePassword(password) {
  * The encoded hash is self-describing (`$scrypt$ln=17,r=8,p=1$salt$hash`),
  * so parameters can be raised later: `verify()` reads the parameters from
  * the stored hash and `needsRehash()` tells the sign-in code to store a
- * fresh hash while it has the plaintext.
+ * fresh hash while it has the plaintext. Until then, `verify()` makes up the
+ * work an older, cheaper hash saves, so it answers no sooner than for an
+ * unknown user.
  *
  * Passwords are NFKC-normalised (NIST SP 800-63B §5.1.1.2) so the same
  * password typed on different keyboards verifies. `hash()` refuses an empty
@@ -86,6 +90,11 @@ export class PasswordHasher {
      * is checked instead, so response time does not reveal which accounts
      * exist. The first such call makes the dummy hash, which costs the same
      * one derivation as every later check.
+     *
+     * A hash stored before the cost was raised is cheaper to check than the
+     * dummy, so its check is topped up to the configured work, right password
+     * or wrong. One stored before the cost was lowered takes its longer time
+     * until it is rehashed: that can't be hidden.
      */
     async verify(password, encoded) {
         if (!encoded) {
@@ -116,6 +125,17 @@ export class PasswordHasher {
             return false;
         }
         const actual = await this.derive(input, parsed.salt, parsed.hash.length, parsed.params);
+        // A hash stored before the cost was raised takes less work than the dummy, which would tell an
+        // account from an unknown email: make up the difference in N·r·p with derivations at the
+        // configured r and p, halving N each time. Exact when only N changed, within 2·r·p otherwise.
+        let missing = work(this.params) - work(parsed.params);
+        for (let logN = this.params.logN - 1; logN >= 1 && missing > 0; logN--) {
+            const params = { ...this.params, logN };
+            if (work(params) <= missing) {
+                await this.derive(input, parsed.salt, this.keyLength, params);
+                missing -= work(params);
+            }
+        }
         return timingSafeEqual(actual, parsed.hash);
     }
     /** `true` when the stored hash uses weaker or different parameters than configured. */

package/dist/testing/index.js

@@ -113,16 +113,15 @@ export function authenticationStoreContract(create, options = {}) {
         // Two instances: one clock a little behind the other.
         const behind = new SessionService(storage, { session: { ...options, now: () => clock - 2_000 } });
         const ahead = new SessionService(storage, { session: { ...options, now: () => clock } });
-        for (let round = 0; round < 3; round++) {
-            const { token } = await ahead.create(uid());
-            clock += 61_000; // idle for 61 s on `ahead`, 59 s on `behind`
-            const [seenIdle, touched] = await Promise.all([ahead.validate(token), behind.validate(token)]);
-            same(seenIdle, null, 'the request that saw the session idle is refused');
-            assert.ok(touched, 'the other instance, within the idle timeout, touches the session');
-            clock += 1_000;
-            assert.ok(await ahead.validate(token), 'the touched session is still there');
-        }
-    }, concurrent);
+        const { token } = await ahead.create(uid());
+        clock += 61_000; // idle for 61 s on `ahead`, 59 s on `behind`
+        // One after the other: run together, `behind` may read and touch first, and then `ahead` rightly
+        // finds the session alive. In this order, a `validate()` that deleted what it saw idle fails below.
+        same(await ahead.validate(token), null, 'the request that saw the session idle is refused');
+        assert.ok(await behind.validate(token), 'the other instance, within the idle timeout, touches the session');
+        clock += 1_000;
+        assert.ok(await ahead.validate(token), 'the touched session is still there');
+    });
     add('sessions', 'a request racing a sign-out or a rotation never brings the session back (SessionService)', async (sources) => {
         let clock = T0;
         const sessions = new SessionService(storageOf(sources, 'sessions'), {
@@ -414,6 +413,9 @@ export function authenticationStoreContract(create, options = {}) {
         }
         same(await store.consumeEmailToken(reset.id, 'email-verification'), undefined, 'a token of another purpose is refused');
         same(await store.consumeEmailToken(reset.id, 'password-reset'), reset, '…and left in place');
+        // What the services do when a step after the consume fails.
+        await store.saveEmailToken(reset);
+        same(await store.consumeEmailToken(reset.id, 'password-reset'), reset, 'a consumed token can be saved back, and works once more');
         const second = emailToken({ userId: u1 });
         await store.saveEmailToken(second);
         await store.deleteUserEmailTokens(u1, 'password-reset');

package/dist/utils/auth-state.util.d.ts

@@ -38,13 +38,16 @@ export declare function getRawResult(context: ExecutionContext): State | undefin
  *   (`WsAuthenticator.authenticateConnection()` stores the upgrade request
  *   there for the `ws` library)
  * - `graphql`: `context.req.headers`
+ * - `mcp`: the headers of the HTTP request the call arrived in; `undefined`
+ *   over stdio, where the MCP spec takes credentials from the environment
  * - `rpc`: `undefined`; metadata is transport specific
  */
 export declare function getRequestHeaders(context: ExecutionContext): Headers | undefined;
 /**
  * The request behind a call, as far as authentication needs it: headers,
- * and the method for HTTP and GraphQL (a WebSocket handshake has none, so
- * it counts as a safe request). `undefined` for RPC.
+ * and the method for HTTP, GraphQL and MCP (a WebSocket handshake has none,
+ * so it counts as a safe request). `undefined` for RPC, and for MCP over
+ * stdio.
  */
 export declare function requestOf(context: ExecutionContext): {
     headers: Headers;

package/dist/utils/auth-state.util.js

@@ -28,12 +28,27 @@ function callKeys(context) {
     }
     return keys;
 }
+/**
+ * The context of an `@nestjs/mcp` call (a tool, resource or prompt), read from
+ * its arguments, `[input, context]`, so this package needs no `@nestjs/mcp`
+ * dependency. Its `request` is the HTTP platform's request (a plain
+ * `{ method, url, headers }` object for `@nestjs/mcp/testing`'s in-memory
+ * client), absent over stdio.
+ */
+function mcpCallOf(context) {
+    const call = context.getArgByIndex(1);
+    return typeof call === 'object' && call !== null ? call : undefined;
+}
 /**
  * The object that carries the result for one call, mirrored as `user` /
  * `session` where Passport-era code and `@nestjs/authorization` look:
  * the request (http), the client socket (ws), the transport context (rpc),
  * `context.req` (graphql; over graphql-ws, the socket's upgrade request, which
- * every operation of the socket shares).
+ * every operation of the socket shares), and for an MCP call (`mcp`) the HTTP
+ * request it arrived in, else (over stdio) its own context object. Each MCP
+ * request travels in an HTTP request of its own, so the request is per call,
+ * and it is the one the endpoint's route was authenticated on: a guard there
+ * and on the call authenticate once.
  */
 function carrierOf(context) {
     switch (context.getType()) {
@@ -47,6 +62,10 @@ function carrierOf(context) {
         }
         case 'graphql':
             return context.getArgByIndex(2)?.req;
+        case 'mcp': {
+            const call = mcpCallOf(context);
+            return call?.request ?? call;
+        }
         default:
             return undefined;
     }
@@ -178,6 +197,8 @@ function stateCarrierOf(context) {
  *   (`WsAuthenticator.authenticateConnection()` stores the upgrade request
  *   there for the `ws` library)
  * - `graphql`: `context.req.headers`
+ * - `mcp`: the headers of the HTTP request the call arrived in; `undefined`
+ *   over stdio, where the MCP spec takes credentials from the environment
  * - `rpc`: `undefined`; metadata is transport specific
  */
 export function getRequestHeaders(context) {
@@ -185,8 +206,9 @@ export function getRequestHeaders(context) {
 }
 /**
  * The request behind a call, as far as authentication needs it: headers,
- * and the method for HTTP and GraphQL (a WebSocket handshake has none, so
- * it counts as a safe request). `undefined` for RPC.
+ * and the method for HTTP, GraphQL and MCP (a WebSocket handshake has none,
+ * so it counts as a safe request). `undefined` for RPC, and for MCP over
+ * stdio.
  */
 export function requestOf(context) {
     switch (context.getType()) {
@@ -199,6 +221,10 @@ export function requestOf(context) {
         }
         case 'graphql':
             return context.getArgByIndex(2)?.req;
+        case 'mcp': {
+            const request = mcpCallOf(context)?.request;
+            return request?.headers ? request : undefined;
+        }
         default:
             return undefined;
     }

package/dist/utils/transport-errors.util.d.ts

@@ -23,13 +23,15 @@ export declare function refusalOf(error: AuthenticationError): Refusal;
  * for `AuthenticationError`s thrown by handlers: the error each transport's
  * exception filter understands, for the refusal's status.
  *
- * - HTTP and GraphQL: Nest's own `UnauthorizedException` (or
+ * - HTTP, GraphQL and MCP: Nest's own `UnauthorizedException` (or
  *   `ForbiddenException` for a 403, `ConflictException` for a 409), with
  *   Nest's own body: `{"message":"Unauthorized","statusCode":401}`, or with a
  *   message, `{"message":"Refresh token reused","error":"Unauthorized","statusCode":401}`.
  *   A `code` is Nest's `errorCode` (on the exception, and in the body), and
  *   the description in `error` when there is a message; `details` follow.
  *   Over HTTP, `challenge` becomes the `WWW-Authenticate` header of a 401.
+ *   `@nestjs/mcp` answers a tool call's exception with a tool error carrying
+ *   its message, and a resource's or prompt's with a JSON-RPC error.
  * - ws and rpc: a `WsException` / `RpcException` carrying
  *   `{ statusCode, message }` (plus `status: 'error'` for ws, and `error`,
  *   `errorCode` and `details` as above). Those filters report

package/dist/utils/transport-errors.util.js

@@ -21,13 +21,15 @@ export function refusalOf(error) {
  * for `AuthenticationError`s thrown by handlers: the error each transport's
  * exception filter understands, for the refusal's status.
  *
- * - HTTP and GraphQL: Nest's own `UnauthorizedException` (or
+ * - HTTP, GraphQL and MCP: Nest's own `UnauthorizedException` (or
  *   `ForbiddenException` for a 403, `ConflictException` for a 409), with
  *   Nest's own body: `{"message":"Unauthorized","statusCode":401}`, or with a
  *   message, `{"message":"Refresh token reused","error":"Unauthorized","statusCode":401}`.
  *   A `code` is Nest's `errorCode` (on the exception, and in the body), and
  *   the description in `error` when there is a message; `details` follow.
  *   Over HTTP, `challenge` becomes the `WWW-Authenticate` header of a 401.
+ *   `@nestjs/mcp` answers a tool call's exception with a tool error carrying
+ *   its message, and a resource's or prompt's with a JSON-RPC error.
  * - ws and rpc: a `WsException` / `RpcException` carrying
  *   `{ statusCode, message }` (plus `status: 'error'` for ws, and `error`,
  *   `errorCode` and `details` as above). Those filters report
@@ -66,6 +68,12 @@ export async function refusal(context, { status = 401, message, code, details, c
                 adapterHost?.httpAdapter?.setHeader(context.switchToHttp().getResponse(), 'WWW-Authenticate', challenge);
             }
             break;
+        case 'mcp':
+            // Nest's own exception, as for HTTP, which `@nestjs/mcp` answers with: a tool result with `isError: true` and
+            // the message, for a tool; a JSON-RPC error with the message and the status, for a resource or a prompt. The
+            // MCP SDK writes the HTTP response, so no challenge goes with it: an MCP client learns where to sign in from
+            // the endpoint's own 401 (`@nestjs/mcp`'s `auth` option).
+            break;
     }
     const Exception = status === 409 ? ConflictException : status === 403 ? ForbiddenException : UnauthorizedException;
     // Nest builds the body: `error` is the code (the description) or the status phrase, then `errorCode`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nestjs/authentication",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Nest - modern, fast, powerful node.js web framework (@authentication)",
   "author": "Kamil Mysliwiec",
   "license": "MIT",
@@ -41,26 +41,26 @@
   "devDependencies": {
     "@apollo/server": "5.5.1",
     "@as-integrations/express5": "1.1.2",
-    "@commitlint/cli": "21.2.3",
-    "@commitlint/config-angular": "21.2.3",
+    "@commitlint/cli": "21.2.4",
+    "@commitlint/config-angular": "21.2.4",
     "@electric-sql/pglite": "0.5.8",
     "@electric-sql/pglite-socket": "0.2.11",
     "@nestjs/apollo": "14.0.1",
     "@nestjs/authorization": "0.1.0",
-    "@nestjs/common": "12.1.2",
-    "@nestjs/core": "12.1.2",
-    "@nestjs/drizzle": "0.0.1",
+    "@nestjs/common": "12.3.2",
+    "@nestjs/core": "12.3.2",
+    "@nestjs/drizzle": "0.0.2",
     "@nestjs/graphql": "14.0.1",
-    "@nestjs/idempotency": "0.0.2",
+    "@nestjs/idempotency": "0.0.3",
     "@nestjs/mail": "0.0.1",
-    "@nestjs/microservices": "12.1.2",
-    "@nestjs/platform-express": "12.1.2",
-    "@nestjs/platform-fastify": "12.1.2",
-    "@nestjs/platform-ws": "12.1.2",
-    "@nestjs/resilience": "0.0.2",
-    "@nestjs/testing": "12.1.2",
+    "@nestjs/microservices": "12.3.2",
+    "@nestjs/platform-express": "12.3.2",
+    "@nestjs/platform-fastify": "12.3.2",
+    "@nestjs/platform-ws": "12.3.2",
+    "@nestjs/resilience": "0.0.3",
+    "@nestjs/testing": "12.3.2",
     "@nestjs/throttler": "6.7.1",
-    "@nestjs/websockets": "12.1.2",
+    "@nestjs/websockets": "12.3.2",
     "@types/node": "24.19.2",
     "@types/pg": "8.23.1",
     "@types/supertest": "7.2.1",
@@ -69,18 +69,18 @@
     "graphql": "16.14.2",
     "husky": "9.1.7",
     "lint-staged": "17.6.0",
-    "oxlint": "1.87.0",
+    "oxlint": "1.91.0",
     "pg": "8.23.1",
     "prettier": "3.9.10",
     "reflect-metadata": "0.2.2",
-    "release-it": "21.1.1",
+    "release-it": "21.1.2",
     "rxjs": "7.8.2",
     "supertest": "7.3.1",
     "typeorm": "1.1.2",
     "typescript": "7.0.2",
-    "vite": "8.3.4",
-    "vitest": "5.0.3",
-    "ws": "8.22.0"
+    "vite": "8.3.5",
+    "vitest": "5.1.0",
+    "ws": "8.22.1"
   },
   "peerDependencies": {
     "@nestjs/common": "^12.0.0",