@zeroxsolutions/server 0.3.0 → 0.3.3

package/CHANGELOG.md

@@ -1,3 +1,29 @@
+# @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.
+
+## 0.3.1 (2026-09-18)
+
+### 🚀 Features
+
+- **server:** log every error the handler answers ([c003f8e](https://github.com/zeroxsolutions/zeroxsolutions/commit/c003f8e))
+
+### ❤️ Thank You
+
+- Claude Opus 5 (1M context)
+- Lương Văn Tú
+
 ## 0.3.0 (2026-09-13)
 
 ### 💅 Refactors

package/README.md

@@ -82,8 +82,13 @@ why `Content-Type` is read on a write only, and why an empty `Accept` is refused
    `@zeroxsolutions/response`'s `createDomainErrorResolver`;
 2. a request the validation hook rejected, one error object per issue;
 3. a `JsonApiError`, rendered as it was thrown;
-4. otherwise the status alone - a hono `HTTPException` at its own, anything else as a 500, written to
-   the log first because that 500 carries nothing of the error.
+4. otherwise the status alone - a hono `HTTPException` at its own, anything else as a 500.
+
+Whichever step answers, the handler writes one `http.error.answered` line under `category` before the
+document goes out, at the level the answered status class decides: a 5xx at error, anything else at
+warn. The line carries the request id, the method, the path, the answered status, the step that claimed
+the failure (`resolve`, `validation`, `jsonapi`, `status`) and the error's type and message. Without it
+a mapped 500 or a guard's 403 reaches the client with nothing in the log for an operator to join it to.
 
 The `requestId` option's value becomes the `id` of each error object that carries none, so a client
 quotes the id the request's log lines carry.

package/dist/error-handler.d.ts

@@ -4,7 +4,7 @@ import type { SurfaceVocabulary } from './surface-vocabulary.js';
 /** Tunes {@link createErrorHandler} for a specific transport (the edge gateway vs a service). */
 export interface ErrorHandlerOptions extends SurfaceVocabulary {
     /**
-     * The ISOLATE's own logging category, which the unhandled-500 line is written under. Required
+     * The ISOLATE's own logging category, which every answered failure's line is written under. Required
      * rather than defaulted: a category the isolate did not configure is silent, and silence here
      * looks the same as a request that never failed.
      */
@@ -16,11 +16,12 @@ 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.
  *
- * A failure none of those claimed is written to the log before it answers, because the generic 500 it renders
- * carries nothing of the error itself.
+ * 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
+ * mapped 500 and a guard's 401 reach the client leaving no trace that the request arrived.
  */
 export declare function createErrorHandler(options: ErrorHandlerOptions): ErrorHandler;
 //# sourceMappingURL=error-handler.d.ts.map

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;AAuBjE,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;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,mBAAmB,GAAG,YAAY,CAkC7E"}
+{"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)) {
@@ -9,9 +11,10 @@ for (const [name, meta] of Object.entries(BASE_ERROR_CODES)) {
         META_BY_STATUS.set(meta.status, { code: name.toLowerCase(), title: meta.title });
     }
 }
+// The message template both levels write, so one search finds every error this handler answered.
+const ANSWERED_LINE = 'http.error.answered {method} {path} {status} {claimedBy}';
 // Projects a failure hono raised - or one nothing claimed - onto a JSON:API error object by HTTP status.
-function errorObjectByStatus(err, namespace) {
-    const status = err instanceof HTTPException ? err.status : 500;
+function errorObjectByStatus(err, status, namespace) {
     const meta = META_BY_STATUS.get(status) ?? { code: 'error', title: 'Error' };
     const detail = err instanceof HTTPException ? err.message : 'Internal server error';
     return {
@@ -21,37 +24,64 @@ function errorObjectByStatus(err, namespace) {
         ...(detail && detail !== meta.title ? { detail } : {}),
     };
 }
+// 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 } };
+    }
+    if (err instanceof JsonApiError) {
+        return { claimedBy: 'jsonapi', resolved: { status: err.status, errors: [toErrorObject(err)] } };
+    }
+    const status = err instanceof HTTPException ? err.status : 500;
+    return { claimedBy: 'status', resolved: { status, errors: [errorObjectByStatus(err, status, options.namespace)] } };
+}
 /**
  * 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.
  *
- * A failure none of those claimed is written to the log before it answers, because the generic 500 it renders
- * carries nothing of the error itself.
+ * 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
+ * mapped 500 and a guard's 401 reach the client leaving no trace that the request arrived.
  */
 export function createErrorHandler(options) {
     const logger = getLogger(options.category);
     return (err, c) => {
         const requestId = options.requestId?.(c);
         const stamp = (e) => (requestId && !e.id ? { ...e, id: requestId } : e);
-        const claimed = options.resolve?.(err, c) ??
-            (err instanceof RequestInvalid ? { status: err.status, errors: err.errors } : undefined) ??
-            (err instanceof JsonApiError ? { status: err.status, errors: [toErrorObject(err)] } : undefined);
-        if (!claimed && !(err instanceof HTTPException)) {
-            logger.error('http.error.unhandled {method} {path} {type}', {
-                // 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,
-                // `path`, not `url`: a query string is where a caller puts a token, and a sink keeps what it is given.
-                path: c.req.path,
-                type: err.name,
-                message: err.message,
-            });
-        }
-        const resolved = claimed ?? {
-            status: err instanceof HTTPException ? err.status : 500,
-            errors: [errorObjectByStatus(err, options.namespace)],
+        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,
+            // `path`, not `url`: a query string is where a caller puts a token, and a sink keeps what it is given.
+            path: c.req.path,
+            status: resolved.status,
+            claimedBy,
+            type: err.name,
+            message: err.message,
         };
+        if (resolved.status >= 500) {
+            logger.error(ANSWERED_LINE, line);
+        }
+        else {
+            logger.warn(ANSWERED_LINE, line);
+        }
         const doc = toErrorDocument(resolved.errors.map(stamp));
         return c.body(JSON.stringify(doc), resolved.status, {
             'Content-Type': JSON_API_MEDIA_TYPE,

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.0",
+  "version": "0.3.3",
   "private": false,
   "type": "module",
   "sideEffects": false,
@@ -21,8 +21,8 @@
   },
   "dependencies": {
     "tslib": "^2.3.0",
-    "@zeroxsolutions/jsonapi": "0.11.0",
-    "@zeroxsolutions/response": "0.12.0"
+    "@zeroxsolutions/jsonapi": "0.11.1",
+    "@zeroxsolutions/response": "0.12.1"
   },
   "peerDependencies": {
     "@hono/zod-openapi": "^1.0.0",