@zeroxsolutions/server 0.3.2 → 0.3.3

package/CHANGELOG.md

@@ -1,3 +1,14 @@
+# @zeroxsolutions/server@0.3.3 (2026-09-18)
+
+### 🚀 Features
+
+- **server:** answer a guard's refusal from the one error handler ([d4ae306](https://github.com/zeroxsolutions/zeroxsolutions/commit/d4ae306))
+
+### ❤️ Thank You
+
+- Claude Opus 5 (1M context)
+- Lương Văn Tú
+
 ## 0.3.2 (2026-09-18)
 
 This was a version bump only for @zeroxsolutions/server to align it with other projects, there were no code changes.

package/dist/error-handler.d.ts

@@ -16,8 +16,8 @@ export interface ErrorHandlerOptions extends SurfaceVocabulary {
 }
 /**
  * The one central `onError` a transport installs, rendering every failure as one `application/vnd.api+json`
- * `errors[]` document. It asks, in order: `resolve`, then a request the validation hook rejected, then a
- * {@link JsonApiError} as thrown, then the HTTP status alone.
+ * `errors[]` document. It asks, in order: `resolve`, then a guard's own refusal, then a request the validation
+ * hook rejected, then a {@link JsonApiError} as thrown, then the HTTP status alone.
  *
  * Every answer is written to the log before it goes out, at the level its status class decides: a 5xx at error,
  * because this side went wrong, anything else at warn, because the request was refused. Without the line, a

package/dist/error-handler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"error-handler.d.ts","sourceRoot":"","sources":["../src/error-handler.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,MAAM,CAAC;AAGlD,OAAO,EAOL,KAAK,aAAa,EACnB,MAAM,0BAA0B,CAAC;AAElC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAkCjE,iGAAiG;AACjG,MAAM,WAAW,mBAAoB,SAAQ,iBAAiB;IAC5D;;;;OAIG;IACH,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,uGAAuG;IACvG,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,KAAK,aAAa,GAAG,SAAS,CAAC;IAChE,0GAA0G;IAC1G,SAAS,CAAC,EAAE,CAAC,CAAC,EAAE,OAAO,KAAK,MAAM,GAAG,SAAS,GAAG,IAAI,CAAC;CACvD;AAmBD;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,mBAAmB,GAAG,YAAY,CA+B7E"}
+{"version":3,"file":"error-handler.d.ts","sourceRoot":"","sources":["../src/error-handler.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,MAAM,CAAC;AAGlD,OAAO,EAOL,KAAK,aAAa,EACnB,MAAM,0BAA0B,CAAC;AAGlC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAqCjE,iGAAiG;AACjG,MAAM,WAAW,mBAAoB,SAAQ,iBAAiB;IAC5D;;;;OAIG;IACH,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,uGAAuG;IACvG,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,KAAK,aAAa,GAAG,SAAS,CAAC;IAChE,0GAA0G;IAC1G,SAAS,CAAC,EAAE,CAAC,CAAC,EAAE,OAAO,KAAK,MAAM,GAAG,SAAS,GAAG,IAAI,CAAC;CACvD;AA2BD;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,mBAAmB,GAAG,YAAY,CAiC7E"}

package/dist/error-handler.js

@@ -1,7 +1,9 @@
 import { getLogger } from '@logtape/logtape';
 import { HTTPException } from 'hono/http-exception';
 import { BASE_ERROR_CODES, JsonApiError, JSON_API_MEDIA_TYPE, toErrorDocument, toErrorObject, } from '@zeroxsolutions/response';
+import { PermissionRefused } from './permission-refused.js';
 import { RequestInvalid } from './request-invalid.js';
+import { Unauthenticated } from './unauthenticated.js';
 // The `code` and `title` each HTTP status is answered with, from the first entry the base registry gives it.
 const META_BY_STATUS = new Map();
 for (const [name, meta] of Object.entries(BASE_ERROR_CODES)) {
@@ -22,13 +24,21 @@ function errorObjectByStatus(err, status, namespace) {
         ...(detail && detail !== meta.title ? { detail } : {}),
     };
 }
-// Asks each step of the dispatch in turn: `resolve`, a request the validation hook rejected, a `JsonApiError` as
-// thrown, the HTTP status alone.
+// Asks each step of the dispatch in turn: `resolve`, a guard's refusal, a request the validation hook rejected, a
+// `JsonApiError` as thrown, the HTTP status alone.
 function claimError(err, c, options) {
     const resolved = options.resolve?.(err, c);
     if (resolved) {
         return { claimedBy: 'resolve', resolved };
     }
+    if (err instanceof Unauthenticated) {
+        const error = { status: '401', code: `${options.namespace}.unauthenticated`, title: 'Unauthenticated' };
+        return { claimedBy: 'auth', resolved: { status: 401, errors: [error] } };
+    }
+    if (err instanceof PermissionRefused) {
+        const error = { status: '403', code: `${options.namespace}.forbidden`, title: 'Forbidden' };
+        return { claimedBy: 'auth', resolved: { status: 403, errors: [error] }, logged: { permissions: err.permissions } };
+    }
     if (err instanceof RequestInvalid) {
         return { claimedBy: 'validation', resolved: { status: err.status, errors: err.errors } };
     }
@@ -40,8 +50,8 @@ function claimError(err, c, options) {
 }
 /**
  * The one central `onError` a transport installs, rendering every failure as one `application/vnd.api+json`
- * `errors[]` document. It asks, in order: `resolve`, then a request the validation hook rejected, then a
- * {@link JsonApiError} as thrown, then the HTTP status alone.
+ * `errors[]` document. It asks, in order: `resolve`, then a guard's own refusal, then a request the validation
+ * hook rejected, then a {@link JsonApiError} as thrown, then the HTTP status alone.
  *
  * Every answer is written to the log before it goes out, at the level its status class decides: a 5xx at error,
  * because this side went wrong, anything else at warn, because the request was refused. Without the line, a
@@ -52,8 +62,10 @@ export function createErrorHandler(options) {
     return (err, c) => {
         const requestId = options.requestId?.(c);
         const stamp = (e) => (requestId && !e.id ? { ...e, id: requestId } : e);
-        const { claimedBy, resolved } = claimError(err, c, options);
+        const { claimedBy, resolved, logged } = claimError(err, c, options);
         const line = {
+            // First, so a step's own facts can never take the place of the ones every line carries.
+            ...logged,
             // Undefined where a transport never mounted `requestId()` - minting one here is a second id for one request.
             requestId: requestId ?? c.get('requestId'),
             method: c.req.method,

package/dist/index.d.ts

@@ -5,5 +5,7 @@ export { createEnvironment, type EnvironmentOptions } from './environment.js';
 export type { SurfaceVocabulary } from './surface-vocabulary.js';
 export { jsonApiContentNegotiation } from './content-negotiation.js';
 export { createErrorHandler, type ErrorHandlerOptions } from './error-handler.js';
+export { PermissionRefused } from './permission-refused.js';
+export { Unauthenticated } from './unauthenticated.js';
 export { createValidationHook } from './validation-hook.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,iBAAiB,EAAE,KAAK,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAC9E,YAAY,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AACjE,OAAO,EAAE,yBAAyB,EAAE,MAAM,0BAA0B,CAAC;AACrE,OAAO,EAAE,kBAAkB,EAAE,KAAK,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAClF,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,iBAAiB,EAAE,KAAK,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAC9E,YAAY,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AACjE,OAAO,EAAE,yBAAyB,EAAE,MAAM,0BAA0B,CAAC;AACrE,OAAO,EAAE,kBAAkB,EAAE,KAAK,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAClF,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/index.js

@@ -4,4 +4,6 @@
 export { createEnvironment } from './environment.js';
 export { jsonApiContentNegotiation } from './content-negotiation.js';
 export { createErrorHandler } from './error-handler.js';
+export { PermissionRefused } from './permission-refused.js';
+export { Unauthenticated } from './unauthenticated.js';
 export { createValidationHook } from './validation-hook.js';

package/dist/permission-refused.d.ts

@@ -0,0 +1,13 @@
+/**
+ * A caller who is authenticated and may not perform what the route requires, thrown by the authorization
+ * guard so the app's one `onError` renders and logs it.
+ *
+ * `permissions` is what the route asked for, never who asked: the log needs it to say which guard refused,
+ * and the answer withholds it, because a 403 naming the resource draws the permission map for the caller
+ * who just failed it.
+ */
+export declare class PermissionRefused extends Error {
+    readonly permissions: Readonly<Record<string, readonly string[]>>;
+    constructor(permissions: Readonly<Record<string, readonly string[]>>);
+}
+//# sourceMappingURL=permission-refused.d.ts.map

package/dist/permission-refused.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permission-refused.d.ts","sourceRoot":"","sources":["../src/permission-refused.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;IAC9B,QAAQ,CAAC,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC;gBAAxD,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC;CAI9E"}

package/dist/permission-refused.js

@@ -0,0 +1,16 @@
+/**
+ * A caller who is authenticated and may not perform what the route requires, thrown by the authorization
+ * guard so the app's one `onError` renders and logs it.
+ *
+ * `permissions` is what the route asked for, never who asked: the log needs it to say which guard refused,
+ * and the answer withholds it, because a 403 naming the resource draws the permission map for the caller
+ * who just failed it.
+ */
+export class PermissionRefused extends Error {
+    permissions;
+    constructor(permissions) {
+        super('The caller may not perform every action this route requires');
+        this.permissions = permissions;
+        this.name = 'PermissionRefused';
+    }
+}

package/dist/unauthenticated.d.ts

@@ -0,0 +1,11 @@
+/**
+ * A request that resolved no caller, thrown by whatever guard establishes identity so the app's one
+ * `onError` renders and logs it.
+ *
+ * A guard that answers the request itself writes a second spelling of 401 per surface, and the two drift:
+ * one says `unauthenticated`, the next says `unauthorized`, for the same refusal.
+ */
+export declare class Unauthenticated extends Error {
+    constructor(message?: string);
+}
+//# sourceMappingURL=unauthenticated.d.ts.map

package/dist/unauthenticated.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unauthenticated.d.ts","sourceRoot":"","sources":["../src/unauthenticated.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,qBAAa,eAAgB,SAAQ,KAAK;gBAC5B,OAAO,SAAgD;CAIpE"}

package/dist/unauthenticated.js

@@ -0,0 +1,13 @@
+/**
+ * A request that resolved no caller, thrown by whatever guard establishes identity so the app's one
+ * `onError` renders and logs it.
+ *
+ * A guard that answers the request itself writes a second spelling of 401 per surface, and the two drift:
+ * one says `unauthenticated`, the next says `unauthorized`, for the same refusal.
+ */
+export class Unauthenticated extends Error {
+    constructor(message = 'The request carries no authenticated caller') {
+        super(message);
+        this.name = 'Unauthenticated';
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zeroxsolutions/server",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "private": false,
   "type": "module",
   "sideEffects": false,
@@ -21,8 +21,8 @@
   },
   "dependencies": {
     "tslib": "^2.3.0",
-    "@zeroxsolutions/response": "0.12.1",
-    "@zeroxsolutions/jsonapi": "0.11.1"
+    "@zeroxsolutions/jsonapi": "0.11.1",
+    "@zeroxsolutions/response": "0.12.1"
   },
   "peerDependencies": {
     "@hono/zod-openapi": "^1.0.0",