@nestjs/authentication 0.0.1

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

@@ -0,0 +1,209 @@
+import { scopedResult } from '../context/authentication-scope.service.js';
+const AUTH_STATE = Symbol.for('nestjs.authentication.state');
+/** The `session` this package last mirrored on a carrier, to tell it from another package's. */
+const MIRRORED_SESSION = Symbol.for('nestjs.authentication.mirrored-session');
+/**
+ * Where a ws client, or GraphQL's `context.req`, carries {@link userOf}, for other packages to call
+ * without importing this one (`@nestjs/authorization` does). A registry symbol, so every copy of
+ * either package agrees.
+ */
+const USER_OF = Symbol.for('nestjs.authentication.userOf');
+/**
+ * Per-call state. For HTTP and RPC the carrier below is already per call, and
+ * a GraphQL operation keeps its own on its context ({@link stateCarrierOf}). A
+ * WebSocket carrier is the socket, which outlives the message and is shared
+ * by concurrent messages, so ws calls are also keyed by their message payload
+ * (the same object reaches guards, interceptors and param decorators) or, for
+ * primitive payloads, by the args array (shared by guards and interceptors).
+ */
+const perCall = new WeakMap();
+function callKeys(context) {
+    if (context.getType() !== 'ws') {
+        return [];
+    }
+    const data = context.switchToWs().getData();
+    const keys = [context.getArgs()];
+    if (typeof data === 'object' && data !== null) {
+        keys.push(data);
+    }
+    return keys;
+}
+/**
+ * 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).
+ */
+function carrierOf(context) {
+    switch (context.getType()) {
+        case 'http':
+            return context.switchToHttp().getRequest();
+        case 'ws':
+            return context.switchToWs().getClient();
+        case 'rpc': {
+            const ctx = context.switchToRpc().getContext();
+            return typeof ctx === 'object' && ctx !== null ? ctx : undefined;
+        }
+        case 'graphql':
+            return context.getArgByIndex(2)?.req;
+        default:
+            return undefined;
+    }
+}
+/**
+ * Records what the handler sees (`@CurrentUser()`, `AuthContext`,
+ * `request.user`). `perCallOnly` skips the carrier mirror; used for ws
+ * `@Public()` messages, so they do not clear `client.user` under a
+ * concurrent message on the same socket.
+ */
+export function setAuthState(context, result, { perCallOnly = false } = {}) {
+    for (const key of callKeys(context)) {
+        perCall.set(key, result);
+    }
+    const carrier = carrierOf(context);
+    const type = context.getType();
+    if (carrier && (type === 'ws' || type === 'graphql')) {
+        // A function of the call, not a user: safe on a carrier that other calls share.
+        carrier[USER_OF] = userOf;
+    }
+    if (perCallOnly) {
+        return;
+    }
+    const own = stateCarrierOf(context);
+    if (own) {
+        own[AUTH_STATE] = result;
+    }
+    if (!carrier) {
+        return;
+    }
+    carrier.user = result?.user ?? null;
+    // `request.session` is often another package's (express-session, @fastify/session): mirrored only
+    // where it is free, or still holds what this package put there.
+    if (!('session' in carrier) || carrier.session === carrier[MIRRORED_SESSION]) {
+        carrier.session = result?.session ?? null;
+        carrier[MIRRORED_SESSION] = carrier.session;
+    }
+}
+/**
+ * `undefined` when authentication has not run for this call, `null` when it
+ * ran and the caller is anonymous.
+ */
+export function getAuthState(context) {
+    for (const key of callKeys(context)) {
+        if (perCall.has(key)) {
+            return perCall.get(key);
+        }
+    }
+    const own = stateCarrierOf(context);
+    return own && AUTH_STATE in own ? own[AUTH_STATE] : undefined;
+}
+/**
+ * @internal This call's result: the scope the interceptor opened for it, else what the guard
+ * recorded on the carrier. A ws message whose payload is a primitive shares nothing else with its
+ * guard but the socket, which outlives it, and would otherwise read another message's user.
+ */
+export function resultOf(context) {
+    const scoped = scopedResult(context);
+    return scoped !== undefined ? scoped : getAuthState(context);
+}
+/**
+ * The user of one ws message or GraphQL operation, for other packages: they call
+ * `carrier[USER_OF](context)` on a ws client, or on GraphQL's `context.req`, that this package
+ * has recorded a result on. Both outlive the call: the client is the connection, and over
+ * graphql-ws `context.req` is the socket's upgrade request. Their `user` is whatever the last
+ * authenticated call left, and a `@Public()` call leaves it alone. This answers what
+ * `@CurrentUser()` gets instead: the call's user, `null` when the call is anonymous (a `@Public()`
+ * one is), and `undefined` when nothing was recorded, for the message or its connection. A GraphQL
+ * operation records its own result, so one that recorded nothing authenticated nothing: `null`,
+ * never the `user` another operation left on the `req` they share.
+ */
+function userOf(context) {
+    const result = resultOf(context);
+    if (result === undefined) {
+        return context.getType() === 'graphql' ? null : undefined;
+    }
+    return result?.user ?? null;
+}
+const RAW = Symbol.for('nestjs.authentication.raw');
+const rawPerCall = new WeakMap();
+/**
+ * The providers' unfiltered answer, cached so a guard applied twice (global
+ * plus `@UseGuards`, or GraphQL root and field resolvers sharing one
+ * operation's context) authenticates once. Per message for ws, and per
+ * operation for GraphQL: over graphql-ws one upgrade request serves every
+ * operation of the socket, and each must see a revocation.
+ */
+export function setRawResult(context, result) {
+    if (context.getType() === 'ws') {
+        for (const key of callKeys(context)) {
+            rawPerCall.set(key, result);
+        }
+        return;
+    }
+    const own = stateCarrierOf(context);
+    if (own) {
+        own[RAW] = result;
+    }
+}
+export function getRawResult(context) {
+    if (context.getType() === 'ws') {
+        for (const key of callKeys(context)) {
+            if (rawPerCall.has(key)) {
+                return rawPerCall.get(key);
+            }
+        }
+        return undefined;
+    }
+    const own = stateCarrierOf(context);
+    return own && RAW in own ? own[RAW] : undefined;
+}
+/**
+ * Where a call's own state is kept, the providers' raw answer and the result
+ * recorded for the handler: the GraphQL operation's context, else the call's
+ * carrier. The context is built for each operation; its `req` is not, over
+ * graphql-ws.
+ */
+function stateCarrierOf(context) {
+    if (context.getType() === 'graphql') {
+        const operation = context.getArgByIndex(2);
+        return typeof operation === 'object' && operation !== null ? operation : undefined;
+    }
+    return carrierOf(context);
+}
+/**
+ * Request headers for the transports that have them:
+ * - `http`: `request.headers`
+ * - `ws`: socket.io's `client.handshake.headers`, else `client.request.headers`
+ *   (`WsAuthenticator.authenticateConnection()` stores the upgrade request
+ *   there for the `ws` library)
+ * - `graphql`: `context.req.headers`
+ * - `rpc`: `undefined`; metadata is transport specific
+ */
+export function getRequestHeaders(context) {
+    return requestOf(context)?.headers;
+}
+/**
+ * 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.
+ */
+export function requestOf(context) {
+    switch (context.getType()) {
+        case 'http':
+            return context.switchToHttp().getRequest();
+        case 'ws': {
+            const client = context.switchToWs().getClient();
+            const headers = client?.handshake?.headers ?? client?.request?.headers;
+            return headers ? { headers } : undefined;
+        }
+        case 'graphql':
+            return context.getArgByIndex(2)?.req;
+        default:
+            return undefined;
+    }
+}
+export function firstHeader(headers, name) {
+    const value = headers?.[name];
+    return Array.isArray(value) ? value[0] : value;
+}

package/dist/utils/bearer.util.d.ts

@@ -0,0 +1,9 @@
+import type { ExecutionContext } from '@nestjs/common';
+/**
+ * The token a bearer provider reads: the `Authorization: Bearer` header's,
+ * else, over socket.io, `handshake.auth.token`. `undefined` when there is
+ * none, or the header names another scheme (another provider's).
+ * `null` for a Bearer header without exactly one token (RFC 6750 §3.1
+ * `invalid_request`, answered as `invalid_token` like any bad credential).
+ */
+export declare function bearerToken(context: ExecutionContext, authorization: string | undefined): string | null | undefined;

package/dist/utils/bearer.util.js

@@ -0,0 +1,21 @@
+/**
+ * The token a bearer provider reads: the `Authorization: Bearer` header's,
+ * else, over socket.io, `handshake.auth.token`. `undefined` when there is
+ * none, or the header names another scheme (another provider's).
+ * `null` for a Bearer header without exactly one token (RFC 6750 §3.1
+ * `invalid_request`, answered as `invalid_token` like any bad credential).
+ */
+export function bearerToken(context, authorization) {
+    if (authorization) {
+        const [scheme, token, ...rest] = authorization.trim().split(/\s+/);
+        if (scheme.toLowerCase() !== 'bearer') {
+            return undefined;
+        }
+        return token && !rest.length ? token : null;
+    }
+    if (context.getType() === 'ws') {
+        const token = context.switchToWs().getClient()?.handshake?.auth?.token;
+        return typeof token === 'string' ? token : undefined;
+    }
+    return undefined;
+}

package/dist/utils/cross-origin.util.d.ts

@@ -0,0 +1,29 @@
+type Headers = Record<string, string | string[] | undefined>;
+/**
+ * Whether a request would change state from another origin. It is the
+ * decision `app.enableCsrfProtection()` makes from Nest 12.1 on (after Go's
+ * `net/http.CrossOriginProtection`), so the two never disagree:
+ *
+ * 1. `GET`, `HEAD` and `OPTIONS` never are.
+ * 2. With `Sec-Fetch-Site`, anything but `same-origin` and `none` is.
+ * 3. Without it, a request with no `Origin` is not: it comes from a
+ *    non-browser client.
+ * 4. Otherwise `Origin` must name the request's host (`:authority` on
+ *    HTTP/2, else `Host`), ignoring case and the scheme's default port.
+ *
+ * A request whose `Origin` is one of `trusted` never is. A WebSocket
+ * handshake (no method here, or a GET with `Upgrade: websocket`) opens a
+ * channel that carries writes, so steps 2 to 4 apply to it (cross-site
+ * WebSocket hijacking).
+ */
+export declare function isCrossOriginWrite(request: {
+    headers: Headers;
+    method?: string;
+}, trusted: ReadonlySet<string>): boolean;
+/**
+ * A trusted origin as browsers serialize `Origin`: lower-case scheme and
+ * host, no default port. Fails at startup, naming `option`, for anything
+ * that is not `scheme://host[:port]`.
+ */
+export declare function normalizeOrigin(origin: unknown, option: string): string;
+export {};

package/dist/utils/cross-origin.util.js

@@ -0,0 +1,90 @@
+const SAFE_METHODS = new Set(['GET', 'HEAD', 'OPTIONS']);
+const DEFAULT_PORTS = { 'http:': '80', 'https:': '443' };
+/**
+ * Whether a request would change state from another origin. It is the
+ * decision `app.enableCsrfProtection()` makes from Nest 12.1 on (after Go's
+ * `net/http.CrossOriginProtection`), so the two never disagree:
+ *
+ * 1. `GET`, `HEAD` and `OPTIONS` never are.
+ * 2. With `Sec-Fetch-Site`, anything but `same-origin` and `none` is.
+ * 3. Without it, a request with no `Origin` is not: it comes from a
+ *    non-browser client.
+ * 4. Otherwise `Origin` must name the request's host (`:authority` on
+ *    HTTP/2, else `Host`), ignoring case and the scheme's default port.
+ *
+ * A request whose `Origin` is one of `trusted` never is. A WebSocket
+ * handshake (no method here, or a GET with `Upgrade: websocket`) opens a
+ * channel that carries writes, so steps 2 to 4 apply to it (cross-site
+ * WebSocket hijacking).
+ */
+export function isCrossOriginWrite(request, trusted) {
+    // A GET that upgrades to a WebSocket (graphql-ws hands resolvers its upgrade request) opens a
+    // channel that carries writes: a handshake, not a safe request.
+    const upgrade = header(request.headers, 'upgrade')?.toLowerCase() === 'websocket';
+    if (request.method !== undefined && SAFE_METHODS.has(request.method) && !upgrade) {
+        return false;
+    }
+    const origin = header(request.headers, 'origin');
+    const site = header(request.headers, 'sec-fetch-site');
+    if (site !== undefined) {
+        if (site === 'same-origin' || site === 'none') {
+            return false;
+        }
+        return !(origin !== undefined && trusted.has(origin));
+    }
+    if (origin === undefined) {
+        return false;
+    }
+    const host = header(request.headers, ':authority') ?? header(request.headers, 'host');
+    if (host !== undefined && originMatchesHost(origin, host)) {
+        return false;
+    }
+    return !trusted.has(origin);
+}
+/**
+ * A trusted origin as browsers serialize `Origin`: lower-case scheme and
+ * host, no default port. Fails at startup, naming `option`, for anything
+ * that is not `scheme://host[:port]`.
+ */
+export function normalizeOrigin(origin, option) {
+    const fail = () => {
+        throw new TypeError(`${option}: ${JSON.stringify(origin)} is not an origin. Write it as scheme://host[:port], without a path.`);
+    };
+    if (typeof origin !== 'string' || !/^[a-z][a-z0-9+.-]*:\/\/[^/?#\\*]+$/i.test(origin)) {
+        return fail();
+    }
+    let url;
+    try {
+        url = new URL(origin);
+    }
+    catch {
+        return fail();
+    }
+    if (!url.host || url.username || url.password) {
+        fail();
+    }
+    return `${url.protocol}//${url.host}`;
+}
+function originMatchesHost(origin, host) {
+    let url;
+    try {
+        url = new URL(origin); // `null` (sandboxed frames) and non-URLs never match
+    }
+    catch {
+        return false;
+    }
+    if (!url.host) {
+        return false;
+    }
+    const authority = host.toLowerCase();
+    if (url.host === authority) {
+        return true;
+    }
+    const port = DEFAULT_PORTS[url.protocol];
+    return !url.port && port !== undefined && `${url.hostname}:${port}` === authority;
+}
+/** Repeated headers are joined, so conflicting values never equal `same-origin` or a trusted origin. */
+function header(headers, name) {
+    const value = headers[name];
+    return Array.isArray(value) ? value.join(', ') : value;
+}

package/dist/utils/crypto.util.d.ts

@@ -0,0 +1,19 @@
+/** 256 random bits, base64url (43 chars). */
+export declare function randomToken(bytes?: number): string;
+/** Pattern of a {@link randomToken} of 32 bytes. */
+export declare const TOKEN_PATTERN: RegExp;
+/**
+ * SHA-256, base64url. Used as the storage key for high-entropy bearer
+ * secrets (session ids, magic links, refresh tokens, recovery codes), so a
+ * leaked store cannot be replayed. A slow hash is unnecessary at 256 bits.
+ */
+export declare function sha256(value: string): string;
+/** Constant-time string comparison (length is not secret). */
+export declare function safeEqual(a: string, b: string): boolean;
+/**
+ * Accepts only same-origin relative paths (`/x`, not `//evil`, `/\evil`,
+ * or absolute URLs), to prevent open redirects, written only with the
+ * printable ASCII a `Location` header carries (anything else
+ * percent-encoded, as browsers send it), and at most 2,048 characters.
+ */
+export declare function safeRedirectPath(value: unknown): string | undefined;

package/dist/utils/crypto.util.js

@@ -0,0 +1,38 @@
+import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
+/** 256 random bits, base64url (43 chars). */
+export function randomToken(bytes = 32) {
+    return randomBytes(bytes).toString('base64url');
+}
+/** Pattern of a {@link randomToken} of 32 bytes. */
+export const TOKEN_PATTERN = /^[A-Za-z0-9_-]{43}$/;
+/**
+ * SHA-256, base64url. Used as the storage key for high-entropy bearer
+ * secrets (session ids, magic links, refresh tokens, recovery codes), so a
+ * leaked store cannot be replayed. A slow hash is unnecessary at 256 bits.
+ */
+export function sha256(value) {
+    return createHash('sha256').update(value).digest('base64url');
+}
+/** Constant-time string comparison (length is not secret). */
+export function safeEqual(a, b) {
+    const left = Buffer.from(a);
+    const right = Buffer.from(b);
+    return left.length === right.length && timingSafeEqual(left, right);
+}
+/** The longest return path kept: a login or a link stores it until used, and anyone can start one. */
+const MAX_REDIRECT_LENGTH = 2_048;
+/**
+ * Accepts only same-origin relative paths (`/x`, not `//evil`, `/\evil`,
+ * or absolute URLs), to prevent open redirects, written only with the
+ * printable ASCII a `Location` header carries (anything else
+ * percent-encoded, as browsers send it), and at most 2,048 characters.
+ */
+export function safeRedirectPath(value) {
+    if (typeof value !== 'string' || !value.startsWith('/') || value.length > MAX_REDIRECT_LENGTH) {
+        return undefined;
+    }
+    if (value.startsWith('//') || value.includes('\\') || !/^[\x21-\x7e]+$/.test(value)) {
+        return undefined;
+    }
+    return value;
+}

package/dist/utils/duration.util.d.ts

@@ -0,0 +1,9 @@
+import type { Duration } from '../interfaces/duration.interface.js';
+export declare function toMs(duration: Duration): number;
+export declare function durationOr(value: Duration | undefined, fallback: Duration): number;
+/**
+ * Whether `expiresAt` has passed at `now` (epoch milliseconds). Fails closed: a date that is not
+ * one (`Invalid Date`, from a store that lost or misnamed the column) has passed, where
+ * `now >= NaN`, which is always false, would keep a session, token or link alive forever.
+ */
+export declare function hasExpired(expiresAt: Date, now: number): boolean;

package/dist/utils/duration.util.js

@@ -0,0 +1,44 @@
+const UNITS = {
+    ms: 1,
+    s: 1_000,
+    m: 60_000,
+    h: 3_600_000,
+    d: 86_400_000,
+    w: 604_800_000,
+};
+/**
+ * The longest duration: 100 years. Longer, a lifetime added to the clock leaves the range of
+ * `Date` (an Invalid Date), and every token or session made with it would be born expired.
+ */
+const MAX_DURATION = 100 * 365.25 * 86_400_000;
+export function toMs(duration) {
+    let ms;
+    if (typeof duration === 'number') {
+        if (!Number.isFinite(duration) || duration < 0) {
+            throw new TypeError(`Invalid duration ${duration}. Use a non-negative number of milliseconds.`);
+        }
+        ms = duration;
+    }
+    else {
+        const match = /^(\d+(?:\.\d+)?)(ms|s|m|h|d|w)$/.exec(duration);
+        if (!match) {
+            throw new TypeError(`Invalid duration "${duration}". Use milliseconds or a string such as "15m" or "3d".`);
+        }
+        ms = Math.round(Number(match[1]) * UNITS[match[2]]);
+    }
+    if (ms > MAX_DURATION) {
+        throw new TypeError(`Invalid duration ${typeof duration === 'string' ? `"${duration}"` : duration}: longer than 100 years.`);
+    }
+    return ms;
+}
+export function durationOr(value, fallback) {
+    return toMs(value ?? fallback);
+}
+/**
+ * Whether `expiresAt` has passed at `now` (epoch milliseconds). Fails closed: a date that is not
+ * one (`Invalid Date`, from a store that lost or misnamed the column) has passed, where
+ * `now >= NaN`, which is always false, would keep a session, token or link alive forever.
+ */
+export function hasExpired(expiresAt, now) {
+    return !(now < expiresAt.getTime());
+}

package/dist/utils/index.d.ts

@@ -0,0 +1,8 @@
+export * from './api-key.util.js';
+export * from './auth-state.util.js';
+export * from './bearer.util.js';
+export * from './cross-origin.util.js';
+export * from './crypto.util.js';
+export * from './duration.util.js';
+export * from './options.util.js';
+export * from './transport-errors.util.js';

package/dist/utils/index.js

@@ -0,0 +1,8 @@
+export * from './api-key.util.js';
+export * from './auth-state.util.js';
+export * from './bearer.util.js';
+export * from './cross-origin.util.js';
+export * from './crypto.util.js';
+export * from './duration.util.js';
+export * from './options.util.js';
+export * from './transport-errors.util.js';

package/dist/utils/options.util.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Startup checks for values that must be there: a `process.env` variable
+ * that isn't set reaches the options as `undefined` (or as
+ * `"undefined/verify-email"` inside a template string), and would otherwise
+ * fail at the first request, or in a constructor with a message about
+ * `toString`. Each error names the option.
+ */
+/** `value` must be set and not empty. `what` describes it: `a secret of at least 32 bytes or a KeyObject`. */
+export declare function requireOption(value: unknown, option: string, what: string): void;
+/**
+ * `value`, when set, must be an integer from `min` to `max`. `Number(process.env.X)` of a variable
+ * that isn't set is `NaN`, and a comparison with `NaN` is always false: a limit set that way would
+ * silently stop limiting.
+ */
+export declare function requireIntegerOption(value: unknown, option: string, { min, max }: {
+    min: number;
+    max?: number;
+}): void;
+/** `value` must be an absolute http(s) URL. `what` describes it: `the page that receives the link`. */
+export declare function requireUrlOption(value: unknown, option: string, what: string): void;

package/dist/utils/options.util.js

@@ -0,0 +1,44 @@
+/**
+ * Startup checks for values that must be there: a `process.env` variable
+ * that isn't set reaches the options as `undefined` (or as
+ * `"undefined/verify-email"` inside a template string), and would otherwise
+ * fail at the first request, or in a constructor with a message about
+ * `toString`. Each error names the option.
+ */
+/** `value` must be set and not empty. `what` describes it: `a secret of at least 32 bytes or a KeyObject`. */
+export function requireOption(value, option, what) {
+    if (value !== undefined && value !== null && value !== '') {
+        return;
+    }
+    throw new TypeError(`AuthenticationModule: \`${option}\` is required (${what}), but it is ${value === '' ? 'empty' : 'undefined'}: ` +
+        'is the environment variable it reads set?');
+}
+/**
+ * `value`, when set, must be an integer from `min` to `max`. `Number(process.env.X)` of a variable
+ * that isn't set is `NaN`, and a comparison with `NaN` is always false: a limit set that way would
+ * silently stop limiting.
+ */
+export function requireIntegerOption(value, option, { min, max = Number.MAX_SAFE_INTEGER }) {
+    if (value === undefined || (Number.isSafeInteger(value) && value >= min && value <= max)) {
+        return;
+    }
+    const range = max === Number.MAX_SAFE_INTEGER ? `of at least ${min}` : `from ${min} to ${max}`;
+    throw new TypeError(`AuthenticationModule: \`${option}\` must be an integer ${range}, but it is ` +
+        `${typeof value === 'string' ? JSON.stringify(value) : String(value)}` +
+        (Number.isNaN(value) ? ': is the environment variable it reads set?' : '.'));
+}
+/** `value` must be an absolute http(s) URL. `what` describes it: `the page that receives the link`. */
+export function requireUrlOption(value, option, what) {
+    requireOption(value, option, what);
+    let url;
+    try {
+        url = typeof value === 'string' ? new URL(value) : undefined;
+    }
+    catch {
+        url = undefined;
+    }
+    if (!url || (url.protocol !== 'https:' && url.protocol !== 'http:')) {
+        throw new TypeError(`AuthenticationModule: \`${option}\` must be an absolute http(s) URL (${what}). Got ${JSON.stringify(value)}` +
+            (typeof value === 'string' && value.startsWith('undefined') ? ': is the environment variable it reads set?' : '.'));
+    }
+}

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

@@ -0,0 +1,33 @@
+import { type ExecutionContext } from '@nestjs/common';
+import type { HttpAdapterHost } from '@nestjs/core';
+export interface Refusal {
+    /** Default 401. 403 for a user the route refuses (an unverified address), 409 for a conflict (`MfaAlreadyEnrolledError`). */
+    status?: 401 | 403 | 409;
+    /** Default `Unauthorized`. */
+    message?: string;
+    /** Machine-readable reason (`mfa_required`), in the body's `error` field. */
+    code?: string;
+    /** The error behind the refusal, kept as the exception's `cause` for logs. */
+    cause?: unknown;
+}
+/**
+ * The one place this package's refusals become responses, for the guard and
+ * 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
+ *   `ForbiddenException` for a 403, `ConflictException` for a 409), so the body is Nest's own:
+ *   `{"message":"Unauthorized","statusCode":401}`, or with a message,
+ *   `{"message":"Refresh token reused","error":"Unauthorized","statusCode":401}`.
+ *   A `code` replaces `error`. Over HTTP, `challenge` becomes the
+ *   `WWW-Authenticate` header of a 401.
+ * - ws and rpc: a `WsException` / `RpcException` carrying
+ *   `{ statusCode, message }` (plus `status: 'error'` for ws, and `error`
+ *   with a `code`). Those filters report `HttpException`s as "Internal
+ *   server error", hence their own classes, loaded only when the packages
+ *   are installed.
+ */
+export declare function refusal(context: ExecutionContext, { status, message, code, cause }?: Refusal, { challenge, adapterHost }?: {
+    challenge?: string;
+    adapterHost?: HttpAdapterHost;
+}): Promise<Error>;

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

@@ -0,0 +1,70 @@
+import { ConflictException, ForbiddenException, UnauthorizedException } from '@nestjs/common';
+const loaded = new Map();
+/** Lazily loads an optional peer's exception class, once. */
+function load(pkg, name) {
+    let pending = loaded.get(pkg);
+    if (!pending) {
+        pending = import(pkg).then((mod) => mod[name], () => undefined);
+        loaded.set(pkg, pending);
+    }
+    return pending;
+}
+const DEFAULT_MESSAGE = 'Unauthorized';
+/**
+ * The one place this package's refusals become responses, for the guard and
+ * 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
+ *   `ForbiddenException` for a 403, `ConflictException` for a 409), so the body is Nest's own:
+ *   `{"message":"Unauthorized","statusCode":401}`, or with a message,
+ *   `{"message":"Refresh token reused","error":"Unauthorized","statusCode":401}`.
+ *   A `code` replaces `error`. Over HTTP, `challenge` becomes the
+ *   `WWW-Authenticate` header of a 401.
+ * - ws and rpc: a `WsException` / `RpcException` carrying
+ *   `{ statusCode, message }` (plus `status: 'error'` for ws, and `error`
+ *   with a `code`). Those filters report `HttpException`s as "Internal
+ *   server error", hence their own classes, loaded only when the packages
+ *   are installed.
+ */
+export async function refusal(context, { status = 401, message = DEFAULT_MESSAGE, code, cause } = {}, { challenge, adapterHost } = {}) {
+    const payload = { statusCode: status, ...(code && { error: code }), message };
+    switch (context.getType()) {
+        case 'ws': {
+            const WsException = await load('@nestjs/websockets', 'WsException');
+            if (WsException) {
+                return withCause(new WsException({ status: 'error', ...payload }), cause);
+            }
+            break;
+        }
+        case 'rpc': {
+            const RpcException = await load('@nestjs/microservices', 'RpcException');
+            if (RpcException) {
+                return withCause(new RpcException(payload), cause);
+            }
+            break;
+        }
+        case 'http':
+            if (challenge && status === 401) {
+                adapterHost?.httpAdapter?.setHeader(context.switchToHttp().getResponse(), 'WWW-Authenticate', challenge);
+            }
+            break;
+    }
+    const options = { cause, ...(code && { description: code }) };
+    if (status === 409) {
+        return new ConflictException(message, options);
+    }
+    if (status === 403) {
+        return new ForbiddenException(message, options);
+    }
+    // The default message gives the body of a bare `new UnauthorizedException()`.
+    return message === DEFAULT_MESSAGE && !code
+        ? new UnauthorizedException(undefined, options)
+        : new UnauthorizedException(message, options);
+}
+function withCause(error, cause) {
+    if (cause !== undefined) {
+        error.cause = cause;
+    }
+    return error;
+}