@nestjs/authentication 0.0.1 → 0.1.1

package/README.md

@@ -2,11 +2,6 @@
   <a href="http://nestjs.com/" target="blank"><img src="https://nestjs.com/img/logo-small.svg" width="120" alt="Nest Logo" /></a>
 </p>
 
-[travis-image]: https://api.travis-ci.org/nestjs/nest.svg?branch=master
-[travis-url]: https://travis-ci.org/nestjs/nest
-[linux-image]: https://img.shields.io/travis/nestjs/nest/master.svg?label=linux
-[linux-url]: https://travis-ci.org/nestjs/nest
-
   <p align="center">A progressive <a href="http://nodejs.org" target="blank">Node.js</a> framework for building efficient and scalable server-side applications.</p>
     <p align="center">
 <a href="https://www.npmjs.com/~nestjscore"><img src="https://img.shields.io/npm/v/@nestjs/core.svg" alt="NPM Version" /></a>
@@ -33,7 +28,70 @@ $ npm i --save @nestjs/authentication
 
 ## Quick Start
 
-[Overview & Tutorial](https://docs.nestjs.com/security/authentication)
+Import the module. Its global guard then requires a signed-in user on every route:
+
+```ts
+@Module({
+  imports: [
+    AuthenticationModule.forRoot({
+      accessToken: {
+        key: process.env.JWT_SECRET!,
+        issuer: 'https://api.example.com',
+        audience: 'web',
+        ttl: '15m',
+      },
+    }),
+  ],
+  providers: [JwtAuth],
+})
+export class AppModule {}
+```
+
+Credential providers are ordinary injectable classes that register themselves with `AuthenticationRegistry`:
+
+```ts
+@Injectable()
+export class JwtAuth extends JwtBearerProvider<User> {
+  constructor(
+    private readonly users: UsersRepository,
+    registry: AuthenticationRegistry,
+  ) {
+    super(); // verifies the tokens the module's `accessToken` option signs
+    registry.registerProvider(this);
+  }
+
+  validate({ sub }: JwtClaims) {
+    return sub ? this.users.findById(sub) : null;
+  }
+}
+```
+
+Then use `@Public()` to opt a route out, and `@Authenticate()` to change what a route requires:
+
+```ts
+@Controller()
+export class AppController {
+  @Public()
+  @Get('health')
+  health() {
+    return 'ok';
+  }
+
+  @Get('me')
+  me(@CurrentUser() user: User) {
+    return user;
+  }
+
+  // Anonymous callers get through too: `user` is then `null`.
+  @Authenticate({ optional: true })
+  @Get('greeting')
+  greeting(@CurrentUser() user: User | null) {
+    return user ? `Hello, ${user.email}` : 'Hello, guest';
+  }
+}
+```
+
+The in-memory stores are fine in development. In production, startup fails until you register real stores with `AuthenticationStorage.registerSource()` for everything your features use (a `SessionCookieProvider` uses the `sessions` store, `accessToken` the `refreshTokens` store unless `refreshToken: false`, and `mfa`, off unless configured, the `mfa` store), or you set `allowInMemoryStorage: true`. Read [Overview & Tutorial](https://docs.nestjs.com/security/authentication) for sessions, refresh tokens, TOTP, magic links, OIDC and account flows.
 
 ## Support
 

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

@@ -1,4 +1,5 @@
 import { type OnModuleDestroy } from '@nestjs/common';
+import { AuthenticationScope } from '../context/authentication-scope.service.js';
 import { AuthenticationRegistry } from '../services/authentication-registry.service.js';
 import { AuthenticationStorage } from '../storage/authentication.storage.js';
 import { AuthenticationEvents } from '../events/authentication-events.service.js';
@@ -35,13 +36,14 @@ export declare class PasswordResetService implements OnModuleDestroy {
     private readonly tokens;
     private readonly signInService;
     private readonly events;
+    private readonly scope;
     private static readonly logger;
     private readonly options?;
     private readonly ttl;
     private readonly inFlight;
     constructor(storage: AuthenticationStorage, registry: AuthenticationRegistry, hasher: PasswordHasher, sessions: SessionService, tokens: TokenService, signInService: SignInService, options?: {
         passwordReset?: PasswordResetOptions;
-    }, events?: AuthenticationEvents);
+    }, events?: AuthenticationEvents, scope?: AuthenticationScope);
     /**
      * Starts a reset for `email`, if it belongs to an account: the link goes
      * to `PasswordResetHandler.send()`. Returns at once, before the account is
@@ -56,12 +58,16 @@ export declare class PasswordResetService implements OnModuleDestroy {
      * changed its address or password since the link was sent. `null` too,
      * before the token is looked up (so the link still works), for a password
      * `PasswordHasher` refuses: not a string, empty, or over 4 KiB. Check your
-     * own password rules before calling it.
+     * own password rules before calling it. With `signIn`, 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 password stay as they were. Without `signIn`, the origin is not
+     * checked.
      */
     reset(token: string, password: string, { signIn }?: ResetPasswordOptions): Promise<PasswordResetResult | null>;
     onModuleDestroy(): Promise<void>;
     private issue;
-    /** Ends every session and refresh-token family of the user. */
+    /** 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. */
     private feature;

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

@@ -12,6 +12,7 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
 };
 var PasswordResetService_1;
 import { Inject, Injectable, Logger, Optional } from '@nestjs/common';
+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';
@@ -45,7 +46,7 @@ import { isMailableEmail, normalizeEmail } from './email.util.js';
  * the token: mail scanners and link previews follow GET links.
  */
 let PasswordResetService = PasswordResetService_1 = class PasswordResetService {
-    constructor(storage, registry, hasher, sessions, tokens, signInService, options, events = new AuthenticationEvents()) {
+    constructor(storage, registry, hasher, sessions, tokens, signInService, options, events = new AuthenticationEvents(), scope = new AuthenticationScope()) {
         this.storage = storage;
         this.registry = registry;
         this.hasher = hasher;
@@ -53,6 +54,7 @@ let PasswordResetService = PasswordResetService_1 = class PasswordResetService {
         this.tokens = tokens;
         this.signInService = signInService;
         this.events = events;
+        this.scope = scope;
         this.inFlight = new Set();
         this.options = options?.passwordReset;
         if (this.options) {
@@ -87,10 +89,19 @@ let PasswordResetService = PasswordResetService_1 = class PasswordResetService {
      * changed its address or password since the link was sent. `null` too,
      * before the token is looked up (so the link still works), for a password
      * `PasswordHasher` refuses: not a string, empty, or over 4 KiB. Check your
-     * own password rules before calling it.
+     * own password rules before calling it. With `signIn`, 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 password stay as they were. Without `signIn`, the origin is not
+     * checked.
      */
     async reset(token, password, { signIn = false } = {}) {
         const { handler } = this.feature();
+        // Signing in would refuse this request at the end, after the link is spent and the password
+        // changed: refuse it before, whatever the token is.
+        if (signIn) {
+            this.signInService.refuseCrossOrigin(this.scope.exchange()?.request);
+        }
         if (typeof token !== 'string' || !TOKEN_PATTERN.test(token) || !isHashablePassword(password)) {
             return null;
         }
@@ -150,7 +161,7 @@ let PasswordResetService = PasswordResetService_1 = class PasswordResetService {
         url.searchParams.set('token', token);
         await handler.send({ userId: account.id, email: account.email, url: url.toString(), expiresAt });
     }
-    /** Ends every session and refresh-token family of the user. */
+    /** Ends every session and refresh-token family (with refresh tokens on) of the user. */
     async revokeSignIns(userId) {
         await this.sessions.revokeAll(userId);
         await this.tokens.revokeAll(userId);
@@ -178,7 +189,8 @@ PasswordResetService = PasswordResetService_1 = __decorate([
         PasswordHasher,
         SessionService,
         TokenService,
-        SignInService, Object, AuthenticationEvents])
+        SignInService, Object, AuthenticationEvents,
+        AuthenticationScope])
 ], PasswordResetService);
 export { PasswordResetService };
 /**

package/dist/authentication.constants.d.ts

@@ -11,3 +11,12 @@ export declare const AUTHENTICATION_METADATA = "authentication:route";
  * so every copy of either package agrees on it.
  */
 export declare const AUTHENTICATION_GUARD_BRAND: unique symbol;
+/**
+ * @internal Whether a route is public, written next to the route metadata by
+ * `@Public()` (`true`) and `@Authenticate()` (`false`), on the class or the
+ * method: the method's value, when it has one, wins. `@nestjs/authorization`
+ * reads it, without importing this package, so that a `@Public()` route
+ * needs no `@Can.Anyone()`. A registry symbol, so every copy of either
+ * package agrees on it.
+ */
+export declare const AUTHENTICATION_PUBLIC: unique symbol;

package/dist/authentication.constants.js

@@ -11,3 +11,12 @@ export const AUTHENTICATION_METADATA = 'authentication:route';
  * so every copy of either package agrees on it.
  */
 export const AUTHENTICATION_GUARD_BRAND = Symbol.for('@nestjs/authentication:guard');
+/**
+ * @internal Whether a route is public, written next to the route metadata by
+ * `@Public()` (`true`) and `@Authenticate()` (`false`), on the class or the
+ * method: the method's value, when it has one, wins. `@nestjs/authorization`
+ * reads it, without importing this package, so that a `@Public()` route
+ * needs no `@Can.Anyone()`. A registry symbol, so every copy of either
+ * package agrees on it.
+ */
+export const AUTHENTICATION_PUBLIC = Symbol.for('@nestjs/authentication:public');

package/dist/authentication.module-definition.js

@@ -30,7 +30,9 @@ export const startupChecks = {
     useFactory: (resolved) => {
         const options = resolved ?? {};
         checkKeys(options);
-        warnShortLifetimes(options, new Logger('AuthenticationModule'));
+        const logger = new Logger('AuthenticationModule');
+        warnShortLifetimes(options, logger);
+        warnIdleSwitches(options, logger);
         return options;
     },
 };
@@ -49,7 +51,8 @@ export const storageRequirements = {
             registry[LOCK_REGISTRY]();
             const enabled = {
                 sessionCookie: registry.providers.some((provider) => provider instanceof SessionCookieProvider),
-                accessToken: options.accessToken !== undefined,
+                // With `accessToken`, unless turned off: they are what `issue()` stores.
+                refreshToken: options.accessToken !== undefined && options.refreshToken !== false,
                 mfa: options.mfa !== undefined,
                 // With their handlers: the registry refuses one without the other.
                 magicLink: options.magicLink !== undefined,
@@ -106,11 +109,17 @@ function checkKeys(options) {
             (hint ? `: ${hint}.` : `. The options are ${[...KNOWN_OPTIONS].join(', ')}.`));
     }
 }
+/** A switch that turns off what isn't on: harmless, and likely a forgotten option. */
+function warnIdleSwitches(options, logger) {
+    if (options.refreshToken === false && options.accessToken === undefined) {
+        logger.warn('`refreshToken: false` has no effect without `accessToken`: refresh tokens are only issued with access tokens.');
+    }
+}
 /** The lifetimes: what `@nestjs/jwt` and jsonwebtoken users are used to giving in seconds. */
 const LIFETIMES = [
     ['accessToken.ttl', (options) => options.accessToken?.ttl],
-    ['refreshToken.ttl', (options) => options.refreshToken?.ttl],
-    ['refreshToken.absoluteTtl', (options) => options.refreshToken?.absoluteTtl],
+    ['refreshToken.ttl', (options) => (options.refreshToken || undefined)?.ttl],
+    ['refreshToken.absoluteTtl', (options) => (options.refreshToken || undefined)?.absoluteTtl],
     ['session.absoluteTtl', (options) => options.session?.absoluteTtl],
     ['session.idleTtl', (options) => options.session?.idleTtl],
     ['mfa.pendingTtl', (options) => options.mfa?.pendingTtl],

package/dist/decorators/authenticate.decorator.js

@@ -1,4 +1,4 @@
-import { AUTHENTICATION_METADATA } from '../authentication.constants.js';
+import { AUTHENTICATION_METADATA, AUTHENTICATION_PUBLIC } from '../authentication.constants.js';
 /** Merges into the metadata already on the class or method, so decorators can be stacked. */
 export function route(value) {
     const defined = Object.fromEntries(Object.entries(value).filter(([, field]) => field !== undefined));
@@ -6,6 +6,9 @@ export function route(value) {
         const holder = descriptor ? descriptor.value : target;
         const existing = Reflect.getMetadata(AUTHENTICATION_METADATA, holder);
         Reflect.defineMetadata(AUTHENTICATION_METADATA, { ...existing, ...defined }, holder);
+        if (value.public !== undefined) {
+            Reflect.defineMetadata(AUTHENTICATION_PUBLIC, value.public, holder);
+        }
     };
     return decorator;
 }

package/dist/decorators/current-user.decorator.d.ts

@@ -1,6 +1,8 @@
+import { createParamDecorator } from '@nestjs/common';
+import type { AuthenticatedUser } from '../interfaces/authentication-result.interface.js';
 /**
  * The authenticated user, or `null` on `@Public()` and anonymous optional
  * calls. `@CurrentUser('email')` picks one property; the key is checked
  * against the `AuthenticationTypes` augmentation.
  */
-export declare const CurrentUser: (...dataOrPipes: (string | import("@nestjs/common").ParameterDecoratorOptions | import("@nestjs/common").PipeTransform<any, any> | import("@nestjs/common").Type<import("@nestjs/common").PipeTransform<any, any>> | undefined)[]) => ParameterDecorator;
+export declare const CurrentUser: ReturnType<typeof createParamDecorator<keyof AuthenticatedUser | undefined>>;

package/dist/decorators/current-user.decorator.js

@@ -5,6 +5,8 @@ import { resultOf } from '../utils/auth-state.util.js';
  * calls. `@CurrentUser('email')` picks one property; the key is checked
  * against the `AuthenticationTypes` augmentation.
  */
+// Annotated so the emitted .d.ts keeps `keyof AuthenticatedUser`: inferred, it
+// is resolved at build time against the unaugmented user and becomes `string`.
 export const CurrentUser = createParamDecorator((key, context) => {
     const user = resultOf(context)?.user ?? null;
     return key && user ? user[key] : user;

package/dist/decorators/public.decorator.d.ts

@@ -1,5 +1,8 @@
 /**
  * Skips authentication: no provider runs, and `@CurrentUser()` is `null`.
  * For health checks, the public catalog, and the routes that sign users in.
+ * To `@nestjs/authorization` it means `@Can.Anyone()`: a `@Public()` method
+ * lifts its class's `@Can()`, and a `@Can()` on the method itself still
+ * applies, to a guest.
  */
 export declare const Public: () => ClassDecorator & MethodDecorator;

package/dist/decorators/public.decorator.js

@@ -2,5 +2,8 @@ import { route } from './authenticate.decorator.js';
 /**
  * Skips authentication: no provider runs, and `@CurrentUser()` is `null`.
  * For health checks, the public catalog, and the routes that sign users in.
+ * To `@nestjs/authorization` it means `@Can.Anyone()`: a `@Public()` method
+ * lifts its class's `@Can()`, and a `@Can()` on the method itself still
+ * applies, to a guest.
  */
 export const Public = () => route({ public: true });

package/dist/errors/authentication.error.d.ts

@@ -10,7 +10,8 @@ import type { AuthenticationErrorOptions } from '../interfaces/authentication-er
  *   `TokenService.refresh()`), the module's interceptor turns it into the
  *   transport's error for its `status`: an HTTP 401 (409 for
  *   `MfaAlreadyEnrolledError`), GraphQL `UNAUTHENTICATED`, a `WsException`
- *   or an `RpcException`.
+ *   or an `RpcException`. Its `code` is sent as the body's `errorCode`
+ *   (and `error`), its `details` as `details`.
  * - Elsewhere (a queue worker), it is a plain `Error`.
  */
 export declare class AuthenticationError extends Error {
@@ -23,5 +24,6 @@ export declare class AuthenticationError extends Error {
     readonly status: 401 | 403 | 409;
     readonly challenge?: string;
     readonly code?: string;
-    constructor(message?: string, { challenge, code, cause }?: AuthenticationErrorOptions);
+    readonly details?: Record<string, unknown>;
+    constructor(message?: string, { challenge, code, details, cause }?: AuthenticationErrorOptions);
 }

package/dist/errors/authentication.error.js

@@ -9,11 +9,12 @@
  *   `TokenService.refresh()`), the module's interceptor turns it into the
  *   transport's error for its `status`: an HTTP 401 (409 for
  *   `MfaAlreadyEnrolledError`), GraphQL `UNAUTHENTICATED`, a `WsException`
- *   or an `RpcException`.
+ *   or an `RpcException`. Its `code` is sent as the body's `errorCode`
+ *   (and `error`), its `details` as `details`.
  * - Elsewhere (a queue worker), it is a plain `Error`.
  */
 export class AuthenticationError extends Error {
-    constructor(message = 'Unauthorized', { challenge, code, cause } = {}) {
+    constructor(message = 'Unauthorized', { challenge, code, details, cause } = {}) {
         super(message, cause === undefined ? undefined : { cause });
         /**
          * 401, or 409 for `MfaAlreadyEnrolledError`: the caller's fault, not an
@@ -29,5 +30,8 @@ export class AuthenticationError extends Error {
         if (code !== undefined) {
             this.code = code;
         }
+        if (details !== undefined) {
+            this.details = details;
+        }
     }
 }

package/dist/errors/magic-link.error.d.ts

@@ -1,14 +1,15 @@
 import { AuthenticationError } from './authentication.error.js';
 /**
  * A link was presented in a browser other than the one that requested it
- * (see `magicLink.bindToBrowser`). The one refusal `consume()` tells
- * apart: the customer can act on it (open the link where they asked for
- * it, or request a new one here), and it is decided before the link is
+ * (see `magicLink.bindToBrowser`), or in that browser after it requested
+ * five newer ones. The one refusal `consume()` tells apart: the customer
+ * can act on it (open the latest link where they asked for it, or request
+ * a new one here), and it is decided before the link is
  * looked up, so it reveals nothing about the token. Unknown, used, expired
  * and refused links share one answer, `null`.
  *
  * An `AuthenticationError`: a route that lets it escape answers 401 on any
- * transport, with `not_this_browser` as the body's `error`, the way
+ * transport, with `not_this_browser` as the body's `errorCode` (and `error`), the way
  * `TokenService.issue()` answers `mfa_required`.
  */
 export declare class MagicLinkError extends AuthenticationError {

package/dist/errors/magic-link.error.js

@@ -1,19 +1,20 @@
 import { AuthenticationError } from './authentication.error.js';
 /**
  * A link was presented in a browser other than the one that requested it
- * (see `magicLink.bindToBrowser`). The one refusal `consume()` tells
- * apart: the customer can act on it (open the link where they asked for
- * it, or request a new one here), and it is decided before the link is
+ * (see `magicLink.bindToBrowser`), or in that browser after it requested
+ * five newer ones. The one refusal `consume()` tells apart: the customer
+ * can act on it (open the latest link where they asked for it, or request
+ * a new one here), and it is decided before the link is
  * looked up, so it reveals nothing about the token. Unknown, used, expired
  * and refused links share one answer, `null`.
  *
  * An `AuthenticationError`: a route that lets it escape answers 401 on any
- * transport, with `not_this_browser` as the body's `error`, the way
+ * transport, with `not_this_browser` as the body's `errorCode` (and `error`), the way
  * `TokenService.issue()` answers `mfa_required`.
  */
 export class MagicLinkError extends AuthenticationError {
     constructor() {
-        super('Open the link in the browser you requested it from, or request a new one here', { code: 'not_this_browser' });
+        super('Open the latest link in the browser you requested it from, or request a new one here', { code: 'not_this_browser' });
         /** Why the link was refused: the only reason apps are told. */
         this.reason = 'not-this-browser';
         this.name = 'MagicLinkError';

package/dist/events/authentication-events.interface.d.ts

@@ -118,4 +118,19 @@ export interface AuthenticationMagicLinkRefusedEvent {
     /** The address the link was sent to, once the link was looked up (`expired`, `refused`). */
     email?: string;
 }
-export type AuthenticationEvent = AuthenticationSignInEvent | AuthenticationSignOutEvent | AuthenticationMfaVerifiedEvent | AuthenticationMfaFailedEvent | AuthenticationMfaEnabledEvent | AuthenticationMfaDisabledEvent | AuthenticationRecoveryCodesGeneratedEvent | AuthenticationRefreshTokenReusedEvent | AuthenticationPasswordResetRequestedEvent | AuthenticationPasswordResetEvent | AuthenticationEmailVerifiedEvent | AuthenticationMagicLinkRefusedEvent;
+/**
+ * A request's session was valid, but recording its activity
+ * (`SessionStore.touchSession()`) failed: a lock timeout, a read-only
+ * replica, an outage. The request went on with the session as read, and
+ * its idle timeout did not move: unless a later request records activity,
+ * the session ends at its previous idle deadline. Each request in a spell
+ * of failures publishes one, though `SessionService` logs only the first.
+ */
+export interface AuthenticationSessionTouchFailedEvent {
+    type: 'session-touch-failed';
+    userId: string;
+    sessionId: string;
+    /** What `touchSession()` rejected with. */
+    error: unknown;
+}
+export type AuthenticationEvent = AuthenticationSignInEvent | AuthenticationSignOutEvent | AuthenticationMfaVerifiedEvent | AuthenticationMfaFailedEvent | AuthenticationMfaEnabledEvent | AuthenticationMfaDisabledEvent | AuthenticationRecoveryCodesGeneratedEvent | AuthenticationRefreshTokenReusedEvent | AuthenticationPasswordResetRequestedEvent | AuthenticationPasswordResetEvent | AuthenticationEmailVerifiedEvent | AuthenticationMagicLinkRefusedEvent | AuthenticationSessionTouchFailedEvent;

package/dist/events/authentication-events.service.d.ts

@@ -3,7 +3,8 @@ import { type Observable } from 'rxjs';
 import type { AuthenticationEvent } from './authentication-events.interface.js';
 /**
  * The audit trail of sign-ins, sign-outs, second-factor changes, password
- * resets, email verifications and refused magic links. Each event is also
+ * resets, email verifications and refused magic links, and the session
+ * activity a store failed to record. Each event is also
  * published on its `node:diagnostics_channel` channel
  * (`nestjs:authentication:<type>`), for tooling that runs outside Nest.
  * Listeners cannot change the outcome: a throwing channel subscriber is

package/dist/events/authentication-events.service.js

@@ -9,7 +9,8 @@ import { Subject } from 'rxjs';
 import { channelFor } from './authentication.channels.js';
 /**
  * The audit trail of sign-ins, sign-outs, second-factor changes, password
- * resets, email verifications and refused magic links. Each event is also
+ * resets, email verifications and refused magic links, and the session
+ * activity a store failed to record. Each event is also
  * published on its `node:diagnostics_channel` channel
  * (`nestjs:authentication:<type>`), for tooling that runs outside Nest.
  * Listeners cannot change the outcome: a throwing channel subscriber is

package/dist/guards/authentication.guard.d.ts

@@ -8,14 +8,16 @@ import { AUTHENTICATION_GUARD_BRAND } from '../authentication.constants.js';
  *
  * | Route | No credentials | Valid | Invalid |
  * | --- | --- | --- | --- |
- * | default | 401 | pass | 401 |
+ * | default | 401 `missing_credentials` | pass | 401 |
  * | `@Authenticate({ optional: true })` | pass, user `null` | pass | 401 |
  * | `@Public()` | providers not called | not called | not called |
  *
  * A result with `mfa: 'pending'` (second factor outstanding) does not count
  * as signed in: 401 `mfa_required` where a user is required, anonymous on
  * optional routes. `@Authenticate({ mfa: true })` needs `mfa: 'verified'`,
- * and `@Authenticate({ verifiedEmail: true })` a verified address (403).
+ * and `@Authenticate({ verifiedEmail: true })` a verified address (403
+ * `email_unverified`). The code is Nest's `errorCode`; a provider's
+ * `AuthenticationError` is answered with its own `code` and `details`.
  *
  * Providers run once per call: the raw result is cached on the request, the
  * GraphQL operation's context, or per ws message. With

package/dist/guards/authentication.guard.js

@@ -15,25 +15,29 @@ import { getRawResult, setAuthState, setRawResult } from '../utils/auth-state.ut
 import { AuthenticationRegistry } from '../services/authentication-registry.service.js';
 import { AUTHENTICATION_GUARD_BRAND, AUTHENTICATION_METADATA } from '../authentication.constants.js';
 import { AuthenticationError } from '../errors/authentication.error.js';
-import { refusal } from '../utils/transport-errors.util.js';
+import { refusal, refusalOf } from '../utils/transport-errors.util.js';
 /** Which provider produced a result, for `@Authenticate({ providers })` on a cached result. */
 const producedBy = new WeakMap();
 const MFA_REQUIRED = { message: 'Second factor required', code: 'mfa_required' };
 const EMAIL_UNVERIFIED = { status: 403, message: 'Email address not verified', code: 'email_unverified' };
+/** No provider recognised any credentials: `new UnauthorizedException()`'s body, with an `errorCode`. */
+const MISSING_CREDENTIALS = { code: 'missing_credentials' };
 /**
  * Runs the registered providers in order and records the first result on
  * the call.
  *
  * | Route | No credentials | Valid | Invalid |
  * | --- | --- | --- | --- |
- * | default | 401 | pass | 401 |
+ * | default | 401 `missing_credentials` | pass | 401 |
  * | `@Authenticate({ optional: true })` | pass, user `null` | pass | 401 |
  * | `@Public()` | providers not called | not called | not called |
  *
  * A result with `mfa: 'pending'` (second factor outstanding) does not count
  * as signed in: 401 `mfa_required` where a user is required, anonymous on
  * optional routes. `@Authenticate({ mfa: true })` needs `mfa: 'verified'`,
- * and `@Authenticate({ verifiedEmail: true })` a verified address (403).
+ * and `@Authenticate({ verifiedEmail: true })` a verified address (403
+ * `email_unverified`). The code is Nest's `errorCode`; a provider's
+ * `AuthenticationError` is answered with its own `code` and `details`.
  *
  * Providers run once per call: the raw result is cached on the request, the
  * GraphQL operation's context, or per ws message. With
@@ -90,7 +94,7 @@ let AuthenticationGuard = class AuthenticationGuard {
             if (pending) {
                 return this.fail(context, MFA_REQUIRED);
             }
-            return this.fail(context, {}, this.challenges(context, providers));
+            return this.fail(context, MISSING_CREDENTIALS, this.challenges(context, providers));
         }
         if (route.mfa && result.mfa !== 'verified') {
             return this.fail(context, MFA_REQUIRED);
@@ -126,8 +130,7 @@ let AuthenticationGuard = class AuthenticationGuard {
                     if (everyProvider || error.status === 401) {
                         this.forgetConnection(context);
                     }
-                    const { status, message, code } = error;
-                    return this.fail(context, { status, message, code, cause: error }, error.challenge);
+                    return this.fail(context, refusalOf(error), error.challenge);
                 }
                 throw error; // a store outage is a 500, not a 401
             }

package/dist/index.d.ts

@@ -11,7 +11,7 @@ export { AuthenticationProvider } from './providers/index.js';
 export { ApiKeyProvider } from './providers/index.js';
 export { AuthenticationError, JwtError, MagicLinkError, MfaAlreadyEnrolledError, RefreshTokenError, } from './errors/index.js';
 export { AuthenticationEvents, type AuthenticationEmailVerifiedEvent, type AuthenticationEvent, type AuthenticationMagicLinkRefusedEvent, type AuthenticationMfaDisabledEvent, type AuthenticationMfaEnabledEvent, type AuthenticationMfaFailedEvent, type AuthenticationMfaVerifiedEvent, type AuthenticationPasswordResetEvent, type AuthenticationPasswordResetRequestedEvent, type AuthenticationRecoveryCodesGeneratedEvent, type AuthenticationRefreshTokenReusedEvent, type AuthenticationSignInEvent, type AuthenticationSignOutEvent, } from './events/index.js';
-export type { ApiKeyProviderOptions, ApiKeyRecord, ApiKeySession, AuthenticateOptions, AuthenticationErrorOptions, AuthenticationHandlerName, AuthenticationHandlers, AuthenticationModuleOptions, AuthenticationOptionsFactory, AuthenticationResult, AuthenticationStorageContract, AuthenticationStorageRegisterOptions, AuthenticationStorageSources, CreatedMagicLink, CredentialProvider, Duration, EmailTokenPurpose, EmailTokenRecord, EmailTokenStore, EmailVerificationLink, EmailVerificationOptions, GeneratedApiKey, IssuedSession, IssueTokensOptions, JwksClientOptions, JwsAlgorithm, JwtBearerProviderOptions, JwtClaims, JwtSignerOptions, JwtVerifierOptions, MagicLink, MagicLinkAccount, MagicLinkOptions, MagicLinkRecord, MagicLinkRequest, MagicLinkStore, MfaOptions, MfaState, MfaStore, OAuthTokens, OidcOptions, OidcProfile, OidcProviderConfig, OidcRedirect, OidcRequest, OidcResolveContext, OidcStartOptions, OidcStateStore, OidcTransaction, PasswordHasherOptions, PasswordResetAccount, PasswordResetLink, PasswordResetOptions, PasswordResetResult, RefreshTokenOptions, RefreshTokenRecord, RefreshTokenStore, RegisterHandlerOptions, RegisterProviderOptions, ResetPasswordOptions, SessionOptions, SessionRecord, SessionStore, SignInOptions, TokenPair, TotpRecord, } from './interfaces/index.js';
+export type { AccessTokenResult, ApiKeyProviderOptions, ApiKeyRecord, ApiKeySession, AuthenticateOptions, AuthenticationErrorOptions, AuthenticationHandlerName, AuthenticationHandlers, AuthenticationModuleOptions, AuthenticationOptionsFactory, AuthenticationResult, AuthenticationStorageContract, AuthenticationStorageRegisterOptions, AuthenticationStorageSources, CreatedMagicLink, CredentialProvider, Duration, EmailTokenPurpose, EmailTokenRecord, EmailTokenStore, EmailVerificationLink, EmailVerificationOptions, GeneratedApiKey, IssuedSession, IssuedTokens, IssueTokensOptions, JwksClientOptions, JwsAlgorithm, JwtBearerProviderOptions, JwtClaims, JwtSignerOptions, JwtVerifierOptions, MagicLink, MagicLinkAccount, MagicLinkOptions, MagicLinkRecord, MagicLinkRequest, MagicLinkStore, MfaOptions, MfaState, MfaStore, OAuthTokens, OidcOptions, OidcProfile, OidcProviderConfig, OidcRedirect, OidcRequest, OidcResolveContext, OidcStartOptions, OidcStateStore, OidcTransaction, PasswordHasherOptions, PasswordResetAccount, PasswordResetLink, PasswordResetOptions, PasswordResetResult, RefreshTokenOptions, RefreshTokenRecord, RefreshTokenStore, RegisterHandlerOptions, RegisterProviderOptions, ResetPasswordOptions, SessionExtra, SessionOptions, SessionRecord, SessionStore, SignInOptions, TokenPair, TotpRecord, } from './interfaces/index.js';
 export { SessionCookieProvider } from './session/session-cookie.provider.js';
 export { InMemorySessionStore } from './session/in-memory-session.store.js';
 export { SessionService } from './session/session.service.js';
@@ -39,12 +39,17 @@ export { InMemoryOidcStateStore } from './oidc/in-memory-oidc-state.store.js';
 export { github, google, microsoft } from './oidc/oidc.presets.js';
 /**
  * Augment once per app to type `@CurrentUser('key')`,
- * `AuthenticationContext.user` and `AuthenticationContext.session`:
+ * `AuthenticationContext.user` and `AuthenticationContext.session`,
+ * (`sessionExtra`) what a `SessionStore` reads with each session for
+ * `SessionCookieProvider.validate()` (`SessionRecord.extra`), and
+ * (`refreshTokens: false`, with the `refreshToken: false` option) that
+ * `TokenService.issue()` returns no refresh token ({@link IssuedTokens}):
  *
  * @example
  * declare module '@nestjs/authentication' {
  *   interface AuthenticationTypes {
  *     user: User;
+ *     sessionExtra: { user: User };
  *   }
  * }
  */

package/dist/interceptors/authentication-scope.interceptor.js

@@ -12,7 +12,7 @@ import { HttpAdapterHost } from '@nestjs/core';
 import { catchError, from, mergeMap, Observable, throwError } from 'rxjs';
 import { getAuthState } from '../utils/auth-state.util.js';
 import { AuthenticationError } from '../errors/authentication.error.js';
-import { refusal } from '../utils/transport-errors.util.js';
+import { refusal, refusalOf } from '../utils/transport-errors.util.js';
 import { AuthenticationScope, runCall } from '../context/authentication-scope.service.js';
 /**
  * @internal Opens the scope with what the guard recorded, around the
@@ -35,7 +35,7 @@ let AuthenticationScopeInterceptor = class AuthenticationScopeInterceptor {
             if (!(error instanceof AuthenticationError)) {
                 return throwError(() => error);
             }
-            const mapped = refusal(context, { status: error.status, message: error.message, code: error.code, cause: error }, { challenge: error.challenge, adapterHost: this.adapterHost });
+            const mapped = refusal(context, refusalOf(error), { challenge: error.challenge, adapterHost: this.adapterHost });
             return from(mapped).pipe(mergeMap((exception) => throwError(() => exception)));
         }));
     }

package/dist/interfaces/authentication-error-options.interface.d.ts

@@ -1,8 +1,18 @@
 export interface AuthenticationErrorOptions {
     /** `WWW-Authenticate` challenge sent with the 401 over HTTP, e.g. `ApiKey header="x-api-key"`. */
     challenge?: string;
-    /** Machine-readable reason, sent as the body's `error` field (`mfa_required`). */
+    /**
+     * Machine-readable reason (`mfa_required`), sent as Nest's `errorCode`
+     * (the HTTP exception's `errorCode`, and the body's on every transport),
+     * and as the body's `error` field, which carried it first.
+     */
     code?: string;
-    /** The error behind this one, for logs. */
+    /**
+     * Machine-readable data for the client, sent as the body's `details` field
+     * as is (`{ retryAfter: 30 }`): keep it JSON-serialisable, and leave out
+     * anything the caller should not see. Not sent unless set.
+     */
+    details?: Record<string, unknown>;
+    /** The error behind this one, for logs. Never sent. */
     cause?: unknown;
 }

package/dist/interfaces/authentication-module-options.interface.d.ts

@@ -26,7 +26,19 @@ export interface AuthenticationModuleOptions {
      * verifies unless it is given its own `key` or `jwks`.
      */
     accessToken?: JwtSignerOptions;
-    refreshToken?: RefreshTokenOptions;
+    /**
+     * The refresh tokens `TokenService` issues with each access token, on by
+     * default with `accessToken` (which then needs a `RefreshTokenStore`).
+     * `false` turns them off: `issue()` returns an access token alone and
+     * starts no family, `refresh()` and `revoke()` throw, `revokeAll()` does
+     * nothing, and no `RefreshTokenStore` is needed. For a service that signs
+     * its own short-lived access tokens, or one that only verifies them
+     * (which can also leave `accessToken` out and give its
+     * `JwtBearerProvider` the key: `super({ key })`). Declare
+     * `refreshTokens: false` on `AuthenticationTypes` to type `issue()`
+     * accordingly ({@link IssuedTokens}).
+     */
+    refreshToken?: RefreshTokenOptions | false;
     /** Goes with a registered `OidcAccountResolver` (`'oidc'`): each fails at startup without the other. */
     oidc?: OidcOptions;
     /** Goes with a registered `PasswordResetHandler` (`'passwordReset'`): each fails at startup without the other. */