@nestjs/authentication 0.0.1 → 0.1.0

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

@@ -1,33 +1,44 @@
 import { type ExecutionContext } from '@nestjs/common';
 import type { HttpAdapterHost } from '@nestjs/core';
+import type { AuthenticationError } from '../errors/authentication.error.js';
 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`. */
+    /**
+     * Without one, Nest's bare body (`new UnauthorizedException()`): the status
+     * phrase as `message`, and no `error`.
+     */
     message?: string;
-    /** Machine-readable reason (`mfa_required`), in the body's `error` field. */
+    /** Machine-readable reason (`mfa_required`): Nest's `errorCode`, and the body's `error` when there is a message. */
     code?: string;
+    /** Machine-readable data the app chose to send (`AuthenticationError`'s `details`): the body's `details`. */
+    details?: Record<string, unknown>;
     /** The error behind the refusal, kept as the exception's `cause` for logs. */
     cause?: unknown;
 }
+/** The refusal for an `AuthenticationError` a provider or a handler threw. */
+export declare function refusalOf(error: AuthenticationError): Refusal;
 /**
  * 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.
+ *   `ForbiddenException` for a 403, `ConflictException` for a 409), with
+ *   Nest's own body: `{"message":"Unauthorized","statusCode":401}`, or with a
+ *   message, `{"message":"Refresh token reused","error":"Unauthorized","statusCode":401}`.
+ *   A `code` is Nest's `errorCode` (on the exception, and in the body), and
+ *   the description in `error` when there is a message; `details` follow.
+ *   Over HTTP, `challenge` becomes the `WWW-Authenticate` header of a 401.
  * - 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.
+ *   `{ statusCode, message }` (plus `status: 'error'` for ws, and `error`,
+ *   `errorCode` and `details` as above). Those filters report
+ *   `HttpException`s as "Internal server error", hence their own classes,
+ *   loaded only when the packages are installed.
+ *
+ * Nothing else reaches the body: `cause` stays on the exception, for logs.
  */
-export declare function refusal(context: ExecutionContext, { status, message, code, cause }?: Refusal, { challenge, adapterHost }?: {
+export declare function refusal(context: ExecutionContext, { status, message, code, details, cause }?: Refusal, { challenge, adapterHost }?: {
     challenge?: string;
     adapterHost?: HttpAdapterHost;
 }): Promise<Error>;

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

@@ -10,25 +10,42 @@ function load(pkg, name) {
     return pending;
 }
 const DEFAULT_MESSAGE = 'Unauthorized';
+const PHRASES = { 401: 'Unauthorized', 403: 'Forbidden', 409: 'Conflict' };
+/** The refusal for an `AuthenticationError` a provider or a handler threw. */
+export function refusalOf(error) {
+    const { status, message, code, details } = error;
+    return { status, message, code, details, cause: error };
+}
 /**
  * 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.
+ *   `ForbiddenException` for a 403, `ConflictException` for a 409), with
+ *   Nest's own body: `{"message":"Unauthorized","statusCode":401}`, or with a
+ *   message, `{"message":"Refresh token reused","error":"Unauthorized","statusCode":401}`.
+ *   A `code` is Nest's `errorCode` (on the exception, and in the body), and
+ *   the description in `error` when there is a message; `details` follow.
+ *   Over HTTP, `challenge` becomes the `WWW-Authenticate` header of a 401.
  * - 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.
+ *   `{ statusCode, message }` (plus `status: 'error'` for ws, and `error`,
+ *   `errorCode` and `details` as above). Those filters report
+ *   `HttpException`s as "Internal server error", hence their own classes,
+ *   loaded only when the packages are installed.
+ *
+ * Nothing else reaches the body: `cause` stays on the exception, for logs.
  */
-export async function refusal(context, { status = 401, message = DEFAULT_MESSAGE, code, cause } = {}, { challenge, adapterHost } = {}) {
-    const payload = { statusCode: status, ...(code && { error: code }), message };
+export async function refusal(context, { status = 401, message, code, details, cause } = {}, { challenge, adapterHost } = {}) {
+    // The default message without a code gives the body of a bare `new UnauthorizedException()`.
+    const bare = message === undefined || (status === 401 && message === DEFAULT_MESSAGE && !code);
+    const payload = {
+        statusCode: status,
+        ...(!bare && code && { error: code }),
+        message: message ?? PHRASES[status],
+        ...(code && { errorCode: code }),
+        ...(details !== undefined && { details }),
+    };
     switch (context.getType()) {
         case 'ws': {
             const WsException = await load('@nestjs/websockets', 'WsException');
@@ -50,17 +67,12 @@ export async function refusal(context, { status = 401, message = DEFAULT_MESSAGE
             }
             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);
+    const Exception = status === 409 ? ConflictException : status === 403 ? ForbiddenException : UnauthorizedException;
+    // Nest builds the body: `error` is the code (the description) or the status phrase, then `errorCode`.
+    const options = { cause, ...(code && { errorCode: code, ...(!bare && { description: code }) }) };
+    const exception = new Exception(bare ? undefined : message, options);
+    // `details` are not Nest's: its body, with them.
+    return details === undefined ? exception : new Exception({ ...exception.getResponse(), details }, options);
 }
 function withCause(error, cause) {
     if (cause !== undefined) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nestjs/authentication",
-  "version": "0.0.1",
+  "version": "0.1.0",
   "description": "Nest - modern, fast, powerful node.js web framework (@authentication)",
   "author": "Kamil Mysliwiec",
   "license": "MIT",
@@ -46,41 +46,41 @@
     "@electric-sql/pglite": "0.5.8",
     "@electric-sql/pglite-socket": "0.2.11",
     "@nestjs/apollo": "14.0.1",
-    "@nestjs/authorization": "file:../authorization/nestjs-authorization-0.0.1.tgz",
-    "@nestjs/common": "12.1.0",
-    "@nestjs/core": "12.1.0",
+    "@nestjs/authorization": "0.0.1",
+    "@nestjs/common": "12.1.2",
+    "@nestjs/core": "12.1.2",
     "@nestjs/drizzle": "0.0.1",
     "@nestjs/graphql": "14.0.1",
     "@nestjs/idempotency": "0.0.1",
-    "@nestjs/mail": "file:../mail/nestjs-mail-0.0.1.tgz",
-    "@nestjs/microservices": "12.1.0",
-    "@nestjs/platform-express": "12.1.0",
-    "@nestjs/platform-fastify": "12.1.0",
-    "@nestjs/platform-ws": "12.1.0",
+    "@nestjs/mail": "0.0.1",
+    "@nestjs/microservices": "12.1.2",
+    "@nestjs/platform-express": "12.1.2",
+    "@nestjs/platform-fastify": "12.1.2",
+    "@nestjs/platform-ws": "12.1.2",
     "@nestjs/resilience": "0.0.1",
-    "@nestjs/testing": "12.1.0",
-    "@nestjs/throttler": "6.7.0",
-    "@nestjs/websockets": "12.1.0",
-    "@types/node": "24.13.6",
+    "@nestjs/testing": "12.1.2",
+    "@nestjs/throttler": "6.7.1",
+    "@nestjs/websockets": "12.1.2",
+    "@types/node": "24.19.1",
     "@types/pg": "8.23.1",
-    "@types/supertest": "6.0.3",
-    "@types/ws": "8.18.1",
+    "@types/supertest": "7.2.1",
+    "@types/ws": "8.18.2",
     "drizzle-orm": "0.45.3",
     "graphql": "16.14.2",
     "husky": "9.1.7",
-    "lint-staged": "17.5.1",
-    "oxlint": "1.85.0",
-    "pg": "8.23.0",
-    "prettier": "3.9.8",
+    "lint-staged": "17.6.0",
+    "oxlint": "1.87.0",
+    "pg": "8.23.1",
+    "prettier": "3.9.9",
     "reflect-metadata": "0.2.2",
-    "release-it": "21.1.0",
+    "release-it": "21.1.1",
     "rxjs": "7.8.2",
-    "supertest": "7.2.2",
-    "typeorm": "1.1.1",
+    "supertest": "7.3.1",
+    "typeorm": "1.1.2",
     "typescript": "7.0.2",
-    "vite": "8.3.0",
-    "vitest": "5.0.1",
-    "ws": "8.21.3"
+    "vite": "8.3.3",
+    "vitest": "5.0.3",
+    "ws": "8.22.0"
   },
   "peerDependencies": {
     "@nestjs/common": "^12.0.0",