@nestjs/authentication 0.0.1

package/dist/oidc/oidc.service.js

@@ -0,0 +1,259 @@
+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 { BadGatewayException, BadRequestException, ForbiddenException, Inject, Injectable, NotFoundException, Optional, UnauthorizedException, } from '@nestjs/common';
+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 { AUTHENTICATION_MODULE_OPTIONS } from '../authentication.constants.js';
+import { safeEqual, safeRedirectPath, sha256 } from '../utils/crypto.util.js';
+import { durationOr, hasExpired } from '../utils/duration.util.js';
+import { requireOption } from '../utils/options.util.js';
+import { defaultCookieName, readCookie, serializeCookie } from '../session/cookies.util.js';
+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';
+const header = (headers, name) => {
+    const value = headers[name];
+    return Array.isArray(value) ? value[0] : value;
+};
+/**
+ * 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
+ * back to. Called from an HTTP handler, each method reads the request and
+ * sets its cookies on the response, on Express and Fastify alike:
+ *
+ * ```ts
+ * @Public()
+ * @Controller('auth/oidc')
+ * export class OidcController {
+ *   constructor(private readonly oidc: OidcService) {}
+ *
+ *   @Get(':provider/login')
+ *   @Redirect()
+ *   login(@Param('provider') provider: string, @Query('redirectTo') redirectTo?: string, @Query('link') link?: string) {
+ *     return this.oidc.start(provider, { redirectTo, link: link === 'true' });
+ *   }
+ *
+ *   @Get(':provider/callback')
+ *   @Redirect()
+ *   callback(@Param('provider') provider: string, @Query() query: Record<string, string>) {
+ *     return this.oidc.finish(provider, query);
+ *   }
+ * }
+ * ```
+ *
+ * The transaction (PKCE verifier, nonce, return path) stays server-side,
+ * keyed by `state`; the browser gets, in an `HttpOnly` cookie, the secret
+ * whose SHA-256 is the `state`. The callback must present both, which binds
+ * the response to the browser that started the login: another browser
+ * cannot finish it (login CSRF), nor can whoever reads the callback URL in a
+ * log or a history. `SameSite=Lax` lets the cookie through the IdP's
+ * top-level redirect, and the `__Host-` prefix keeps sibling subdomains from
+ * planting one.
+ *
+ * `start(provider, { link: true })` begins a link flow for the signed-in
+ * user instead of a sign-in: the callback re-checks that the same session is
+ * still live, hands `{ linkTo }` to the resolver, and keeps the session as
+ * it is.
+ */
+let OidcService = class OidcService {
+    constructor(storage, registry, signIn, sessions, options, scope = new AuthenticationScope(), adapterHost) {
+        this.storage = storage;
+        this.registry = registry;
+        this.signIn = signIn;
+        this.sessions = sessions;
+        this.scope = scope;
+        this.adapterHost = adapterHost;
+        this.clients = new Map();
+        this.options = options?.oidc;
+        if (this.options) {
+            assertCallbackUrl(this.options.callbackUrl);
+            assertProviderCredentials(this.options.providers);
+        }
+        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
+     * configured; 401 for a link flow without a signed-in session.
+     */
+    async start(provider, { redirectTo, link = false, request } = {}) {
+        const exchange = this.scope.exchange();
+        const req = request ?? exchange?.request ?? { headers: {} };
+        let linking;
+        if (link) {
+            // A link attaches whatever account the provider has signed in on this browser: never at the
+            // bidding of another site's page (a top-level navigation carries the Lax session cookie).
+            if (header(req.headers, 'sec-fetch-site') === 'cross-site') {
+                throw new ForbiddenException('Cross-site link refused');
+            }
+            const session = await this.currentSession(req);
+            if (!session) {
+                throw new UnauthorizedException('sign in to link an account');
+            }
+            linking = { userId: session.userId, sessionId: session.id };
+        }
+        const { url, transaction, binding } = await this.client(provider)
+            .authorizationRequest(this.callbackUrl(provider), safeRedirectPath(redirectTo), this.transactionTtl)
+            .catch(toHttp);
+        await this.storage.oidcStates.saveOidcState({ ...transaction, ...(linking && { link: linking }) });
+        return this.redirect(exchange?.response, url, [this.txCookie(binding, this.transactionTtl / 1000)]);
+    }
+    /**
+     * Completes a login on the callback route, and returns where to send the
+     * browser: the login's `redirectTo`, else `redirectAfterLogin`. A sign-in
+     * goes through `SignInService`, which sets the session cookie on the
+     * response; the transaction cookie is cleared.
+     */
+    async finish(provider, query, { request } = {}) {
+        const { options, resolver } = this.feature();
+        const exchange = this.scope.exchange();
+        const req = request ?? exchange?.request ?? { headers: {} };
+        // The cookie holds the secret whose SHA-256 is the state. The state travels in URLs, the
+        // secret never does: a callback URL read from a log is useless without this browser's cookie.
+        const state = query.state;
+        const bound = readCookie(header(req.headers, 'cookie'), this.txCookieName);
+        if (typeof state !== 'string' || !bound || !safeEqual(sha256(bound), state)) {
+            throw new BadRequestException('state mismatch');
+        }
+        const transaction = await this.storage.oidcStates.consumeOidcState(state);
+        if (!transaction || transaction.provider !== provider || hasExpired(transaction.expiresAt, this.now())) {
+            throw new BadRequestException('unknown or expired login');
+        }
+        const result = await this.client(provider).callback(query, transaction, this.callbackUrl(provider)).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.
+            const session = await this.currentSession(req);
+            if (session?.id !== transaction.link.sessionId) {
+                throw new UnauthorizedException('sign in to link an account');
+            }
+            const user = await resolver.resolveUser(result.profile, result.tokens, { linkTo: { id: session.userId } });
+            if (!user || user.id !== session.userId) {
+                throw new ForbiddenException('account not linked');
+            }
+            return this.redirect(exchange?.response, location, [this.txCookie('', 0)]);
+        }
+        const user = await resolver.resolveUser(result.profile, result.tokens, {});
+        if (!user) {
+            throw new ForbiddenException('account not allowed');
+        }
+        const issued = await this.signIn.signIn(user.id, { method: `oidc:${provider}` });
+        // `signIn()` set the session cookie on the response itself; the caller outside HTTP needs it too.
+        const { url } = this.redirect(exchange?.response, location, [this.txCookie('', 0)]);
+        return { url, cookies: [issued.cookie, this.txCookie('', 0)] };
+    }
+    /** Sets the cookies (and `no-store`) on the HTTP response, if there is one. */
+    redirect(response, url, cookies) {
+        const adapter = this.adapterHost?.httpAdapter;
+        if (response && adapter) {
+            for (const cookie of cookies) {
+                adapter.appendHeader(response, 'Set-Cookie', cookie);
+            }
+            adapter.setHeader(response, 'Cache-Control', 'no-store');
+        }
+        return { url, cookies };
+    }
+    /** The options and the resolver; the module refuses to start with one and not the other. */
+    feature() {
+        const resolver = this.registry.handler('oidc');
+        if (!this.options || !resolver) {
+            throw new Error('OidcService: OpenID Connect is not enabled. Configure `oidc` in the AuthenticationModule options, and register ' +
+                "an OidcAccountResolver: `registry.registerHandler('oidc', this)`.");
+        }
+        return { options: this.options, resolver };
+    }
+    /** A fully signed-in session (second factor done, if any) on this request. */
+    async currentSession(request) {
+        const session = await this.sessions.validate(this.sessions.tokenFrom(request));
+        return session && session.mfa !== 'pending' ? session : null;
+    }
+    callbackUrl(provider) {
+        return this.feature().options.callbackUrl.replaceAll(':provider', encodeURIComponent(provider));
+    }
+    txCookie(value, maxAge) {
+        return serializeCookie(this.txCookieName, value, { ...this.options?.cookie, sameSite: 'lax', maxAge });
+    }
+    now() {
+        return this.options?.now?.() ?? Date.now();
+    }
+};
+OidcService = __decorate([
+    Injectable(),
+    __param(4, Optional()),
+    __param(4, Inject(AUTHENTICATION_MODULE_OPTIONS)),
+    __param(6, Optional()),
+    __metadata("design:paramtypes", [AuthenticationStorage,
+        AuthenticationRegistry,
+        SignInService,
+        SessionService, Object, AuthenticationScope,
+        HttpAdapterHost])
+], OidcService);
+export { OidcService };
+/** `oidc.callbackUrl`, checked at startup: an absolute http(s) URL. */
+function assertCallbackUrl(value) {
+    let url;
+    try {
+        url = typeof value === 'string' ? new URL(value.replaceAll(':provider', 'provider')) : undefined;
+    }
+    catch {
+        url = undefined;
+    }
+    if (!url || (url.protocol !== 'https:' && url.protocol !== 'http:')) {
+        throw new Error('OidcService: `oidc.callbackUrl` must be the absolute URL of your callback route, with `:provider` where the ' +
+            `provider's name goes, e.g. 'https://app.example.com/auth/oidc/:provider/callback'. Got ${JSON.stringify(value)}.`);
+    }
+}
+/**
+ * `oidc.providers.<name>.clientId`, and `clientSecret` unless the provider
+ * is a public client (`tokenEndpointAuthMethod: 'none'`), checked at
+ * startup: an unset environment variable would otherwise turn a
+ * 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');
+    for (const [name, config] of Object.entries(providers)) {
+        requireOption(config?.clientId, `oidc.providers.${name}.clientId`, 'the client id the provider issued');
+        if (config.tokenEndpointAuthMethod !== 'none') {
+            requireOption(config.clientSecret, `oidc.providers.${name}.clientSecret`, "the client secret the provider issued; a public client sets `tokenEndpointAuthMethod: 'none'` instead");
+        }
+    }
+}
+/** An `OidcError` as the HTTP answer: 400 for a bad callback, 401 for a failed check, 502 for a provider that is down. */
+function toHttp(error) {
+    if (!(error instanceof OidcError)) {
+        throw error;
+    }
+    const Exception = {
+        request: BadRequestException,
+        verification: UnauthorizedException,
+        unavailable: BadGatewayException,
+    }[error.kind];
+    throw new Exception(error.message);
+}

package/dist/providers/api-key.provider.d.ts

@@ -0,0 +1,51 @@
+import type { ExecutionContext } from '@nestjs/common';
+import type { ApiKeyProviderOptions, ApiKeyRecord, ApiKeySession, GeneratedApiKey } from '../interfaces/api-key.interface.js';
+import type { AuthenticationResult } from '../interfaces/authentication-result.interface.js';
+import { AuthenticationProvider } from './authentication.provider.js';
+/**
+ * Base class for API keys: `Authorization: Bearer <prefix>_<id>_<secret>`,
+ * for scripts and partner systems. Extend it and look a key up by its id in
+ * your own table:
+ *
+ * ```ts
+ * @Injectable()
+ * export class ApiKeyAuth extends ApiKeyProvider<User> {
+ *   constructor(private readonly apiKeysRepository: ApiKeysRepository, registry: AuthenticationRegistry) {
+ *     super({ prefix: 'cat' });
+ *     registry.registerProvider(this, { order: 2 });
+ *   }
+ *   findKey(id: string) {
+ *     return this.apiKeysRepository.findWithUser(id); // { hash, user, expiresAt } or null
+ *   }
+ * }
+ * ```
+ *
+ * `generate()` makes a key: show the whole key once, and store its `id` and
+ * `hash`. Keys carry 256 random bits, so a SHA-256 of the key is all the
+ * store needs (a slow hash would only cost CPU on every request), and the
+ * hash is compared in constant time, with the same work for an unknown id.
+ *
+ * A key signs its user in on every route, but never counts as a second
+ * factor: `@Authenticate({ mfa: true })` refuses it. Keep keys to the routes
+ * meant for them with `@Authenticate({ providers })`. Permissions per key
+ * are authorization's job (`@nestjs/authorization`), with the key id from
+ * the session. Tokens without this provider's prefix are left to the other
+ * providers; a JWT never looks like a key, so `JwtBearerProvider` can run
+ * before or after this one.
+ */
+export declare abstract class ApiKeyProvider<TUser> extends AuthenticationProvider<TUser, ApiKeySession> {
+    private readonly prefix;
+    private readonly realm;
+    private readonly now;
+    constructor({ prefix, realm, now }: ApiKeyProviderOptions);
+    /**
+     * The key with this id, as stored, or `null` for none: unknown, revoked,
+     * or its user is gone. The provider checks the hash and `expiresAt`.
+     */
+    protected abstract findKey(id: string): ApiKeyRecord<TUser> | null | undefined | Promise<ApiKeyRecord<TUser> | null | undefined>;
+    /** A new key with this provider's prefix. */
+    generate(): GeneratedApiKey;
+    authenticate(context: ExecutionContext): Promise<AuthenticationResult<TUser, ApiKeySession> | null>;
+    challenge(): string;
+    private reject;
+}

package/dist/providers/api-key.provider.js

@@ -0,0 +1,93 @@
+import { randomBytes } from 'node:crypto';
+import { AuthenticationError } from '../errors/authentication.error.js';
+import { API_KEY_PATTERN, API_KEY_PREFIX_PATTERN } from '../utils/api-key.util.js';
+import { bearerToken } from '../utils/bearer.util.js';
+import { randomToken, safeEqual, sha256 } from '../utils/crypto.util.js';
+import { hasExpired } from '../utils/duration.util.js';
+import { AuthenticationProvider } from './authentication.provider.js';
+/** Compared against when the id is unknown, so every key costs the same hashing. */
+const NO_KEY = sha256('');
+/**
+ * Base class for API keys: `Authorization: Bearer <prefix>_<id>_<secret>`,
+ * for scripts and partner systems. Extend it and look a key up by its id in
+ * your own table:
+ *
+ * ```ts
+ * @Injectable()
+ * export class ApiKeyAuth extends ApiKeyProvider<User> {
+ *   constructor(private readonly apiKeysRepository: ApiKeysRepository, registry: AuthenticationRegistry) {
+ *     super({ prefix: 'cat' });
+ *     registry.registerProvider(this, { order: 2 });
+ *   }
+ *   findKey(id: string) {
+ *     return this.apiKeysRepository.findWithUser(id); // { hash, user, expiresAt } or null
+ *   }
+ * }
+ * ```
+ *
+ * `generate()` makes a key: show the whole key once, and store its `id` and
+ * `hash`. Keys carry 256 random bits, so a SHA-256 of the key is all the
+ * store needs (a slow hash would only cost CPU on every request), and the
+ * hash is compared in constant time, with the same work for an unknown id.
+ *
+ * A key signs its user in on every route, but never counts as a second
+ * factor: `@Authenticate({ mfa: true })` refuses it. Keep keys to the routes
+ * meant for them with `@Authenticate({ providers })`. Permissions per key
+ * are authorization's job (`@nestjs/authorization`), with the key id from
+ * the session. Tokens without this provider's prefix are left to the other
+ * providers; a JWT never looks like a key, so `JwtBearerProvider` can run
+ * before or after this one.
+ */
+export class ApiKeyProvider extends AuthenticationProvider {
+    constructor({ prefix, realm = 'api', now = Date.now }) {
+        super();
+        if (typeof prefix !== 'string' || !API_KEY_PREFIX_PATTERN.test(prefix)) {
+            throw new TypeError(`${new.target.name}: \`prefix\` must be 1-16 lowercase letters and digits, starting with a letter ` +
+                `(e.g. 'cat' for cat_<id>_<secret>), got ${JSON.stringify(prefix)}.`);
+        }
+        this.prefix = prefix;
+        this.realm = realm;
+        this.now = now;
+    }
+    /** A new key with this provider's prefix. */
+    generate() {
+        const id = randomBytes(8).toString('hex');
+        const key = `${this.prefix}_${id}_${randomToken()}`;
+        return { key, id, hash: sha256(key) };
+    }
+    async authenticate(context) {
+        const token = bearerToken(context, this.header(context, 'authorization'));
+        if (token === null) {
+            this.reject('malformed authorization header');
+        }
+        if (token === undefined || !token.startsWith(`${this.prefix}_`)) {
+            return null;
+        }
+        const match = API_KEY_PATTERN.exec(token);
+        if (!match) {
+            this.reject('malformed api key');
+        }
+        const id = match[2];
+        const record = await this.findKey(id);
+        // Hash and compare whether or not the id exists.
+        const matches = safeEqual(sha256(token), typeof record?.hash === 'string' ? record.hash : NO_KEY);
+        if (!record || !matches || record.user === null || record.user === undefined) {
+            this.reject('invalid api key');
+        }
+        const expiresAt = record.expiresAt ?? undefined;
+        if (expiresAt && hasExpired(expiresAt, this.now())) {
+            this.reject('api key expired');
+        }
+        const session = { method: 'api-key', keyId: id, ...(expiresAt && { expiresAt }) };
+        return { user: record.user, session };
+    }
+    challenge() {
+        return `Bearer realm="${this.realm}"`;
+    }
+    reject(description) {
+        // RFC 6750 §3.1, as JwtBearerProvider answers
+        throw new AuthenticationError(description, {
+            challenge: `Bearer realm="${this.realm}", error="invalid_token", error_description="${description}"`,
+        });
+    }
+}

package/dist/providers/authentication.provider.d.ts

@@ -0,0 +1,40 @@
+import type { ExecutionContext } from '@nestjs/common';
+import type { AuthenticatedSession, AuthenticatedUser, AuthenticationResult } from '../interfaces/authentication-result.interface.js';
+/**
+ * A credential source: the contract every provider meets, and the base
+ * class of `SessionCookieProvider` and `JwtBearerProvider`.
+ *
+ * - Resolve to `null` when the request carries no credentials this provider
+ *   understands; the guard tries the next provider.
+ * - Throw `AuthenticationError` when credentials are present but invalid;
+ *   the guard answers 401, even on `@Authenticate({ optional: true })`
+ *   routes.
+ *
+ * Subclasses are ordinary `@Injectable()` classes: they can live in any
+ * module and inject repositories, config, etc. The same class serves HTTP,
+ * GraphQL, WebSockets and RPC, because it receives the `ExecutionContext`.
+ */
+export declare abstract class AuthenticationProvider<TUser = AuthenticatedUser, TSession = AuthenticatedSession> {
+    abstract authenticate(context: ExecutionContext): Promise<AuthenticationResult<TUser, TSession> | null> | AuthenticationResult<TUser, TSession> | null;
+    /**
+     * A request header, whatever the transport: the HTTP request, GraphQL's
+     * `context.req`, or the WebSocket handshake. `undefined` over RPC, whose
+     * metadata is transport specific. A repeated header gives its first value.
+     */
+    protected header(context: ExecutionContext, name: string): string | undefined;
+}
+export interface AuthenticationProvider<TUser = AuthenticatedUser, TSession = AuthenticatedSession> {
+    /** `WWW-Authenticate` challenge sent with a 401 when no provider found credentials. */
+    challenge?(context: ExecutionContext): string | undefined;
+}
+/** A provider class, possibly abstract (`SessionCookieProvider`), for `@Authenticate({ providers })`. */
+export type ProviderClass = abstract new (...args: any[]) => AuthenticationProvider<any, any>;
+/**
+ * @internal Called by the module once the provider is resolved, before the
+ * first request, so a misconfigured provider fails at startup. `resolve`
+ * looks up the module's providers, for instances created with `new` (which
+ * Nest did not property-inject).
+ */
+export declare const PROVIDER_INIT: unique symbol;
+/** @internal */
+export type ProviderInit = (resolve: <T>(token: string | symbol | (abstract new (...args: any[]) => T)) => T) => void;

package/dist/providers/authentication.provider.js

@@ -0,0 +1,33 @@
+import { firstHeader, getRequestHeaders } from '../utils/auth-state.util.js';
+/**
+ * A credential source: the contract every provider meets, and the base
+ * class of `SessionCookieProvider` and `JwtBearerProvider`.
+ *
+ * - Resolve to `null` when the request carries no credentials this provider
+ *   understands; the guard tries the next provider.
+ * - Throw `AuthenticationError` when credentials are present but invalid;
+ *   the guard answers 401, even on `@Authenticate({ optional: true })`
+ *   routes.
+ *
+ * Subclasses are ordinary `@Injectable()` classes: they can live in any
+ * module and inject repositories, config, etc. The same class serves HTTP,
+ * GraphQL, WebSockets and RPC, because it receives the `ExecutionContext`.
+ */
+// oxlint-disable-next-line typescript/no-unsafe-declaration-merging -- see the interface below
+export class AuthenticationProvider {
+    /**
+     * A request header, whatever the transport: the HTTP request, GraphQL's
+     * `context.req`, or the WebSocket handshake. `undefined` over RPC, whose
+     * metadata is transport specific. A repeated header gives its first value.
+     */
+    header(context, name) {
+        return firstHeader(getRequestHeaders(context), name.toLowerCase());
+    }
+}
+/**
+ * @internal Called by the module once the provider is resolved, before the
+ * first request, so a misconfigured provider fails at startup. `resolve`
+ * looks up the module's providers, for instances created with `new` (which
+ * Nest did not property-inject).
+ */
+export const PROVIDER_INIT = Symbol('nestjs.authentication.provider-init');

package/dist/providers/index.d.ts

@@ -0,0 +1,2 @@
+export * from './authentication.provider.js';
+export * from './api-key.provider.js';

package/dist/providers/index.js

@@ -0,0 +1,2 @@
+export * from './authentication.provider.js';
+export * from './api-key.provider.js';

package/dist/services/authentication-registry.service.d.ts

@@ -0,0 +1,75 @@
+import { ModuleRef } from '@nestjs/core';
+import type { AuthenticationHandlers, AuthenticationHandlerName, RegisterProviderOptions, RegisterHandlerOptions, CredentialProvider } from '../interfaces/authentication-registry.interface.js';
+/** @internal Locks the registry. `AuthenticationModule.onModuleInit()` and the first read call it. */
+export declare const LOCK_REGISTRY: unique symbol;
+/**
+ * Where the app's credential providers and feature handlers register, from
+ * their own constructors, as stores do with `AuthenticationStorage`. They
+ * are ordinary providers of the app's modules, so they inject whatever
+ * those modules provide:
+ *
+ * ```ts
+ * @Injectable()
+ * export class SessionAuth extends SessionCookieProvider<User> {
+ *   constructor(private readonly users: UsersRepository, registry: AuthenticationRegistry) {
+ *     super();
+ *     registry.registerProvider(this);
+ *   }
+ *   // ...
+ * }
+ *
+ * @Injectable()
+ * export class PasswordResetMailer extends PasswordResetHandler {
+ *   constructor(private readonly users: UsersRepository, registry: AuthenticationRegistry) {
+ *     super();
+ *     registry.registerHandler('passwordReset', this);
+ *   }
+ *   // ...
+ * }
+ * ```
+ *
+ * The registry locks in `AuthenticationModule`'s `onModuleInit` (every
+ * provider constructor has run by then), or at the first read if that is
+ * earlier. At the lock it fails when a feature has its option without its
+ * handler, or the reverse, and it logs the chain and the handlers.
+ */
+export declare class AuthenticationRegistry {
+    private readonly options?;
+    private readonly moduleRef?;
+    private static readonly logger;
+    private readonly registered;
+    private readonly handlers;
+    private chain;
+    private locked;
+    constructor(options?: Record<string, unknown> | undefined, moduleRef?: ModuleRef | undefined);
+    /**
+     * Adds a credential provider to the chain the guard runs, in ascending
+     * `order` (default `0`). Call it from the constructor of a singleton
+     * provider. Throws, registering nothing, for an object without
+     * `authenticate()`, an order another provider has (unless `replace` is
+     * set), a provider registered twice, and once the registry has locked.
+     */
+    registerProvider(provider: CredentialProvider, { order, replace }?: RegisterProviderOptions): void;
+    /**
+     * Registers the handler of a feature: `registerHandler('passwordReset', this)`.
+     * The feature also needs its module option. Throws, registering nothing,
+     * for an unknown feature, a handler missing one of its methods, a feature
+     * that already has one (unless `replace` is set), and once the registry
+     * has locked.
+     */
+    registerHandler<K extends AuthenticationHandlerName>(feature: K, handler: AuthenticationHandlers[K], { replace }?: RegisterHandlerOptions): void;
+    /** The credential providers, in the order the guard runs them. Reading them locks the registry. */
+    get providers(): readonly CredentialProvider<unknown, unknown>[];
+    /** The handler registered for a feature, or `undefined`. Reading it locks the registry. */
+    handler<K extends AuthenticationHandlerName>(feature: K): AuthenticationHandlers[K] | undefined;
+    /**
+     * @internal Checks every feature has both its option and its handler,
+     * orders the chain, lets the providers check their configuration, and
+     * logs what registered. `log: false` for registries built outside a
+     * module (tests, the contract suite).
+     */
+    [LOCK_REGISTRY]({ log }?: {
+        log?: boolean;
+    }): void;
+    private assertOpen;
+}