@zeroxsolutions/server 0.3.5 → 0.4.0

package/CHANGELOG.md

@@ -1,3 +1,39 @@
+## 0.4.0 (2026-09-28)
+
+### 🚀 Features
+
+- ⚠️  **server:** challenge a 401 and keep a thrown response's headers ([e252634](https://github.com/zeroxsolutions/zeroxsolutions/commit/e252634))
+- ⚠️  **server:** answer a refused query as 400 with its parameter ([61ffe94](https://github.com/zeroxsolutions/zeroxsolutions/commit/61ffe94))
+
+### 🩹 Fixes
+
+- **server:** name the challenge on every 401 ([0a0b2af](https://github.com/zeroxsolutions/zeroxsolutions/commit/0a0b2af))
+- ⚠️  **server:** point error sources at what exists, name unknown keys ([44d2116](https://github.com/zeroxsolutions/zeroxsolutions/commit/44d2116))
+- ⚠️  **server:** label only json:api bodies and answer unmatched routes ([a6d3a08](https://github.com/zeroxsolutions/zeroxsolutions/commit/a6d3a08))
+
+### ⚠️  Breaking Changes
+
+- **server:** point error sources at what exists, name unknown keys  ([44d2116](https://github.com/zeroxsolutions/zeroxsolutions/commit/44d2116))
+  a missing member points at its parent; a whole-target
+  issue carries pointer "" for a body and no source otherwise; an
+  unrecognized query key is its own 400.
+- **server:** label only json:api bodies and answer unmatched routes  ([a6d3a08](https://github.com/zeroxsolutions/zeroxsolutions/commit/a6d3a08))
+  a body with no Content-Type is 415, and a response of
+  another media type keeps its own header.
+- **server:** challenge a 401 and keep a thrown response's headers  ([e252634](https://github.com/zeroxsolutions/zeroxsolutions/commit/e252634))
+  createErrorHandler requires authenticationChallenge.
+- **server:** answer a refused query as 400 with its parameter  ([61ffe94](https://github.com/zeroxsolutions/zeroxsolutions/commit/61ffe94))
+  QueryNotPermitted is answered by the library before resolve, as <namespace>.query_not_permitted.
+
+### ❤️ Thank You
+
+- Claude Opus 5.5 (1M context)
+- Lương Văn Tú
+
+## 0.3.5 (2026-09-27)
+
+This was a version bump only for @zeroxsolutions/server to align it with other projects, there were no code changes.
+
 ## 0.3.4 (2026-09-27)
 
 ### 🚀 Features

package/README.md

@@ -28,8 +28,8 @@ pnpm add @zeroxsolutions/server
 ```
 
 `hono`, `zod` and `@logtape/logtape` are peers - the worker already declares them.
-`@zeroxsolutions/jsonapi` and `@zeroxsolutions/response` come with it, as dependencies: this package
-CALLS them rather than reading a host's instance.
+`@zeroxsolutions/jsonapi`, `@zeroxsolutions/query` and `@zeroxsolutions/response` come with it, as
+dependencies: this package CALLS them rather than reading a host's instance.
 
 ## Quickstart
 
@@ -78,11 +78,13 @@ why `Content-Type` is read on a write only, and why an empty `Accept` is refused
 `createErrorHandler` is the app's `onError`, and every failure renders through it as one
 `application/vnd.api+json` error document carrying `jsonapi: { version: '1.1' }`. It asks, in order:
 
-1. `resolve(err, c)` - where a surface's domain error map answers, through
+1. a query the permit-list refused (`QueryNotPermitted`), answered `400` as
+   `<namespace>.query_not_permitted`, naming the parameter in `source.parameter`, before `resolve` sees it;
+2. `resolve(err, c)` - where a surface's domain error map answers, through
    `@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.
+3. a request the validation hook rejected, one error object per issue;
+4. a `JsonApiError`, rendered as it was thrown;
+5. 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
@@ -107,10 +109,21 @@ app.onError(
     category: LOG_CATEGORY,
     resolve: createDomainErrorResolver(apiErrors),
     requestId: (c) => c.var.requestId,
+    authenticationChallenge: 'Bearer',
   }),
 );
 ```
 
+`jsonApiNotFound({ namespace })` is `app.notFound(...)` - the answer for a route nobody declared. hono
+runs `notFound` outside `onError`, so this renders the same 404 error document without writing an
+`http.error.answered` line or stamping a request id: there is no failure here for the log line to join
+to, since nothing was thrown.
+
+```ts
+// entrypoints/http/app.ts
+app.notFound(jsonApiNotFound({ namespace: 'api' }));
+```
+
 ## Why a binder rather than a ready middleware
 
 The schema and the log category are the package's, not the library's: the schema is what the transport

package/dist/content-negotiation.d.ts

@@ -2,18 +2,26 @@ import type { MiddlewareHandler } from 'hono';
 import type { SurfaceVocabulary } from './surface-vocabulary.js';
 /**
  * Hono adapter over {@link negotiateJsonApi}: rejects with 415/406 per JSON:API v1.1 content
- * negotiation, then stamps the JSON:API media type onto the response `Content-Type`.
+ * negotiation, then labels a JSON:API response body with the JSON:API media type.
  *
  * `Content-Type` is read only where the request carries content - a bodyless `Request` has `body === null`,
  * a write's is a stream - because a header describes a representation and a read route has none, so an
- * unconditional read would cost a client sending a blanket default the whole collection.
+ * unconditional read would cost a client sending a blanket default the whole collection. A write that does
+ * carry a body but sent no `Content-Type` reads as `''`, which the negotiator refuses (415): a wildcard never
+ * stands in for the one type this surface reads.
+ *
+ * The response side only labels a body `c.json` left as `application/json` (or with no `Content-Type` at all):
+ * a route that answers `c.text(...)` or `c.body(null, 204)` keeps its own header, since neither is a JSON:API
+ * document.
  *
  * @example
  * ```ts
  * app.use('*', jsonApiContentNegotiation({ namespace: 'api' })); // one middleware, before the routes
  * ```
  */
-export declare function jsonApiContentNegotiation(options: SurfaceVocabulary): MiddlewareHandler;
+export declare function jsonApiContentNegotiation(options: SurfaceVocabulary & {
+    supportedExtensions?: readonly string[];
+}): MiddlewareHandler;
 /**
  * The refusals {@link jsonApiContentNegotiation} answers with, for a route to spread into its declared
  * responses, so a status the gate gains is declared wherever it is mounted.
@@ -109,9 +117,11 @@ export declare const NEGOTIATION_RESPONSES: {
         }, import("zod/v4/core").$strip>>;
         jsonapi: import("zod").ZodOptional<import("zod").ZodObject<{
             version: import("zod").ZodOptional<import("zod").ZodString>;
+            ext: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString>>;
+            profile: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString>>;
             meta: import("zod").ZodOptional<import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodUnknown>>;
         }, import("zod/v4/core").$strip>>;
-    }, import("zod/v4/core").$strip>>;
+    }, import("zod/v4/core").$strict>>;
     readonly 415: import("@zeroxsolutions/response").JsonApiResponse<import("zod").ZodObject<{
         errors: import("zod").ZodArray<import("zod").ZodObject<{
             id: import("zod").ZodOptional<import("zod").ZodString>;
@@ -197,8 +207,10 @@ export declare const NEGOTIATION_RESPONSES: {
         }, import("zod/v4/core").$strip>>;
         jsonapi: import("zod").ZodOptional<import("zod").ZodObject<{
             version: import("zod").ZodOptional<import("zod").ZodString>;
+            ext: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString>>;
+            profile: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString>>;
             meta: import("zod").ZodOptional<import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodUnknown>>;
         }, import("zod/v4/core").$strip>>;
-    }, import("zod/v4/core").$strip>>;
+    }, import("zod/v4/core").$strict>>;
 };
 //# sourceMappingURL=content-negotiation.d.ts.map

package/dist/content-negotiation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"content-negotiation.d.ts","sourceRoot":"","sources":["../src/content-negotiation.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,MAAM,CAAC;AAC9C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAEjE;;;;;;;;;;;;GAYG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,iBAAiB,GAAG,iBAAiB,CAQvF;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAGxB,CAAC"}
+{"version":3,"file":"content-negotiation.d.ts","sourceRoot":"","sources":["../src/content-negotiation.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,MAAM,CAAC;AAC9C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAEjE;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,iBAAiB,GAAG;IAAE,mBAAmB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GACvE,iBAAiB,CAanB;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAGxB,CAAC"}

package/dist/content-negotiation.js

@@ -2,11 +2,17 @@ import { negotiateJsonApi } from '@zeroxsolutions/jsonapi';
 import { errorResponse, JSON_API_MEDIA_TYPE } from '@zeroxsolutions/response';
 /**
  * Hono adapter over {@link negotiateJsonApi}: rejects with 415/406 per JSON:API v1.1 content
- * negotiation, then stamps the JSON:API media type onto the response `Content-Type`.
+ * negotiation, then labels a JSON:API response body with the JSON:API media type.
  *
  * `Content-Type` is read only where the request carries content - a bodyless `Request` has `body === null`,
  * a write's is a stream - because a header describes a representation and a read route has none, so an
- * unconditional read would cost a client sending a blanket default the whole collection.
+ * unconditional read would cost a client sending a blanket default the whole collection. A write that does
+ * carry a body but sent no `Content-Type` reads as `''`, which the negotiator refuses (415): a wildcard never
+ * stands in for the one type this surface reads.
+ *
+ * The response side only labels a body `c.json` left as `application/json` (or with no `Content-Type` at all):
+ * a route that answers `c.text(...)` or `c.body(null, 204)` keeps its own header, since neither is a JSON:API
+ * document.
  *
  * @example
  * ```ts
@@ -14,13 +20,19 @@ import { errorResponse, JSON_API_MEDIA_TYPE } from '@zeroxsolutions/response';
  * ```
  */
 export function jsonApiContentNegotiation(options) {
+    const supported = new Set(options.supportedExtensions ?? []);
     return async (c, next) => {
-        const contentType = c.req.raw.body === null ? undefined : c.req.header('Content-Type');
-        const error = negotiateJsonApi(contentType, c.req.header('Accept'), options.namespace);
+        // A body sent without a Content-Type is judged as an empty one, which the negotiator refuses.
+        const contentType = c.req.raw.body === null ? undefined : (c.req.header('Content-Type') ?? '');
+        const error = negotiateJsonApi(contentType, c.req.header('Accept'), options.namespace, supported);
         if (error)
             throw error;
         await next();
-        c.header('Content-Type', JSON_API_MEDIA_TYPE);
+        // `c.json` writes application/json, which is how a document leaves a handler; any other type is not a document.
+        const current = c.res.headers.get('Content-Type');
+        const unlabelled = current === null || current.split(';')[0]?.trim().toLowerCase() === 'application/json';
+        if (c.res.body !== null && unlabelled)
+            c.header('Content-Type', JSON_API_MEDIA_TYPE);
     };
 }
 /**

package/dist/error-handler.d.ts

@@ -1,6 +1,7 @@
 import type { Context, ErrorHandler } from 'hono';
-import { type ResolvedError } from '@zeroxsolutions/response';
+import { type ErrorObject, type ResolvedError } from '@zeroxsolutions/response';
 import type { SurfaceVocabulary } from './surface-vocabulary.js';
+export declare function errorObjectByStatus(err: Error, status: number, namespace: string): ErrorObject;
 /** Tunes {@link createErrorHandler} for a specific transport (the edge gateway vs a service). */
 export interface ErrorHandlerOptions extends SurfaceVocabulary {
     /**
@@ -13,15 +14,24 @@ export interface ErrorHandlerOptions extends SurfaceVocabulary {
     resolve?: (err: Error, c: Context) => ResolvedError | undefined;
     /** A request id stamped onto each error object's `id` when it carries none, so a client can correlate. */
     requestId?: (c: Context) => string | undefined | null;
+    /**
+     * The challenge every 401 names in `WWW-Authenticate`, for example `Bearer`. Required: RFC 9110 makes a 401 without
+     * one a malformed answer, and a client then cannot tell which scheme to retry with.
+     */
+    authenticationChallenge: string;
 }
 /**
  * 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 guard's own refusal, then a request the validation
- * hook rejected, then a {@link JsonApiError} as thrown, then the HTTP status alone.
+ * `errors[]` document. It asks, in order: a query the permit-list refused, then `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
  * mapped 500 and a guard's 401 reach the client leaving no trace that the request arrived.
+ *
+ * Whichever step answers a 401, the response carries `WWW-Authenticate: {@link ErrorHandlerOptions.authenticationChallenge}`
+ * - unless a kept `HTTPException` response already names one, which is left as the more specific answer.
  */
 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;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"}
+{"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;AAIlD,OAAO,EAML,KAAK,WAAW,EAChB,KAAK,aAAa,EACnB,MAAM,0BAA0B,CAAC;AAGlC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AA4BjE,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,WAAW,CAS9F;AAED,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;IACtD;;;OAGG;IACH,uBAAuB,EAAE,MAAM,CAAC;CACjC;AAyDD;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,mBAAmB,GAAG,YAAY,CAkC7E"}

package/dist/error-handler.js

@@ -1,5 +1,6 @@
 import { getLogger } from '@logtape/logtape';
 import { HTTPException } from 'hono/http-exception';
+import { QueryNotPermitted } from '@zeroxsolutions/query';
 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';
@@ -14,7 +15,7 @@ for (const [name, meta] of Object.entries(BASE_ERROR_CODES)) {
 // 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, status, namespace) {
+export function errorObjectByStatus(err, status, namespace) {
     const meta = META_BY_STATUS.get(status) ?? { code: 'error', title: 'Error' };
     const detail = err instanceof HTTPException ? err.message : undefined;
     return {
@@ -24,9 +25,19 @@ function errorObjectByStatus(err, status, 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.
+// Asks each step of the dispatch in turn: a query the permit-list refused, `resolve`, a guard's refusal, a request
+// the validation hook rejected, a `JsonApiError` as thrown, the HTTP status alone.
 function claimError(err, c, options) {
+    if (err instanceof QueryNotPermitted) {
+        const error = {
+            status: '400',
+            code: `${options.namespace}.query_not_permitted`,
+            title: BASE_ERROR_CODES.BAD_REQUEST.title,
+            detail: err.message,
+            source: { parameter: err.parameter },
+        };
+        return { claimedBy: 'query', resolved: { status: 400, errors: [error] } };
+    }
     const resolved = options.resolve?.(err, c);
     if (resolved) {
         return { claimedBy: 'resolve', resolved };
@@ -46,23 +57,47 @@ function claimError(err, c, options) {
         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)] } };
+    // A thrown HTTPException can carry its own Response (e.g. a rate limiter's Retry-After); content-type and
+    // content-length are this render's own to set, not the thrown response's.
+    const kept = err instanceof HTTPException && err.res
+        ? Object.fromEntries([...err.res.headers].filter(([name]) => name !== 'content-type' && name !== 'content-length'))
+        : undefined;
+    return {
+        claimedBy: 'status',
+        resolved: { status, errors: [errorObjectByStatus(err, status, options.namespace)] },
+        headers: kept,
+    };
+}
+// Names the challenge on a 401 whichever step claimed it, since a step answers its own status rather than the
+// header RFC 9110 requires beside it. A kept HTTPException header already naming one is left alone: naming a
+// second challenge would tell the client to retry with THIS scheme, which may not be the one the response chose.
+function withChallenge(claimed, authenticationChallenge) {
+    if (claimed.resolved.status !== 401)
+        return claimed;
+    const named = Object.keys(claimed.headers ?? {}).some((name) => name.toLowerCase() === 'www-authenticate');
+    if (named)
+        return claimed;
+    return { ...claimed, headers: { ...claimed.headers, 'WWW-Authenticate': authenticationChallenge } };
 }
 /**
  * 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 guard's own refusal, then a request the validation
- * hook rejected, then a {@link JsonApiError} as thrown, then the HTTP status alone.
+ * `errors[]` document. It asks, in order: a query the permit-list refused, then `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
  * mapped 500 and a guard's 401 reach the client leaving no trace that the request arrived.
+ *
+ * Whichever step answers a 401, the response carries `WWW-Authenticate: {@link ErrorHandlerOptions.authenticationChallenge}`
+ * - unless a kept `HTTPException` response already names one, which is left as the more specific answer.
  */
 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 { claimedBy, resolved, logged } = claimError(err, c, options);
+        const { claimedBy, resolved, logged, headers } = withChallenge(claimError(err, c, options), options.authenticationChallenge);
         const line = {
             // First, so a step's own facts can never take the place of the ones every line carries.
             ...logged,
@@ -84,6 +119,7 @@ export function createErrorHandler(options) {
         }
         const doc = toErrorDocument(resolved.errors.map(stamp));
         return c.body(JSON.stringify(doc), resolved.status, {
+            ...headers,
             'Content-Type': JSON_API_MEDIA_TYPE,
         });
     };

package/dist/index.d.ts

@@ -5,6 +5,7 @@ export { createEnvironment, type EnvironmentOptions } from './environment.js';
 export type { SurfaceVocabulary } from './surface-vocabulary.js';
 export { jsonApiContentNegotiation, NEGOTIATION_RESPONSES } from './content-negotiation.js';
 export { createErrorHandler, type ErrorHandlerOptions } from './error-handler.js';
+export { jsonApiNotFound } from './not-found.js';
 export { PermissionRefused } from './permission-refused.js';
 export { Unauthenticated } from './unauthenticated.js';
 export { createValidationHook } from './validation-hook.js';

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,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAC5F,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"}
+{"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,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAC5F,OAAO,EAAE,kBAAkB,EAAE,KAAK,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAClF,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,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,6 +4,7 @@
 export { createEnvironment } from './environment.js';
 export { jsonApiContentNegotiation, NEGOTIATION_RESPONSES } from './content-negotiation.js';
 export { createErrorHandler } from './error-handler.js';
+export { jsonApiNotFound } from './not-found.js';
 export { PermissionRefused } from './permission-refused.js';
 export { Unauthenticated } from './unauthenticated.js';
 export { createValidationHook } from './validation-hook.js';

package/dist/not-found.d.ts

@@ -0,0 +1,5 @@
+import type { NotFoundHandler } from 'hono';
+import type { SurfaceVocabulary } from './surface-vocabulary.js';
+/** The `notFound` handler a JSON:API surface installs, so a route nobody declared answers an error document. */
+export declare function jsonApiNotFound(options: SurfaceVocabulary): NotFoundHandler;
+//# sourceMappingURL=not-found.d.ts.map

package/dist/not-found.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"not-found.d.ts","sourceRoot":"","sources":["../src/not-found.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,MAAM,CAAC;AAE5C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAEjE,gHAAgH;AAChH,wBAAgB,eAAe,CAAC,OAAO,EAAE,iBAAiB,GAAG,eAAe,CAK3E"}

package/dist/not-found.js

@@ -0,0 +1,8 @@
+import { JSON_API_MEDIA_TYPE, toErrorDocument } from '@zeroxsolutions/response';
+import { errorObjectByStatus } from './error-handler.js';
+/** The `notFound` handler a JSON:API surface installs, so a route nobody declared answers an error document. */
+export function jsonApiNotFound(options) {
+    return (c) => c.body(JSON.stringify(toErrorDocument(errorObjectByStatus(new Error('Not Found'), 404, options.namespace))), 404, {
+        'Content-Type': JSON_API_MEDIA_TYPE,
+    });
+}

package/dist/validation-hook.d.ts

@@ -9,6 +9,13 @@ import type { SurfaceVocabulary } from './surface-vocabulary.js';
  * failure, carrying the request id that handler stamps; an app without that handler answers the throw with hono's
  * text 500. @hono/zod-validator 0.9.0 lets a hook's throw through, and answers `c.json(result, 400)` itself unless a
  * hook answers or throws first - which is why the hook is still passed to the constructor.
+ *
+ * A body issue's `source.pointer` names the deepest object that exists in what the client sent, not the member the
+ * schema expected - a missing member has no member of its own to point at, so the pointer stops at its parent (`""`
+ * when nothing past the document root was sent). A query issue names its parameter; a route's query schema is a
+ * house query schema or a `z.strictObject`, and each key such a schema does not recognize answers as its own error
+ * object naming that key. A header issue names its header. A `param` or `cookie` issue carries no spec member for a
+ * path segment, so it goes in `meta` instead.
  */
 export declare function createValidationHook<E extends Env = Env>(options: SurfaceVocabulary): Hook<unknown, E, string, undefined>;
 //# sourceMappingURL=validation-hook.d.ts.map

package/dist/validation-hook.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validation-hook.d.ts","sourceRoot":"","sources":["../src/validation-hook.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAC;AAC9C,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,MAAM,CAAC;AAGhC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAoBjE;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,SAAS,GAAG,GAAG,GAAG,EACtD,OAAO,EAAE,iBAAiB,GACzB,IAAI,CAAC,OAAO,EAAE,CAAC,EAAE,MAAM,EAAE,SAAS,CAAC,CAoBrC"}
+{"version":3,"file":"validation-hook.d.ts","sourceRoot":"","sources":["../src/validation-hook.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAC;AAC9C,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,MAAM,CAAC;AAGhC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAqBjE;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,SAAS,GAAG,GAAG,GAAG,EACtD,OAAO,EAAE,iBAAiB,GACzB,IAAI,CAAC,OAAO,EAAE,CAAC,EAAE,MAAM,EAAE,SAAS,CAAC,CA+BrC"}

package/dist/validation-hook.js

@@ -1,22 +1,19 @@
 import { BASE_ERROR_CODES } from '@zeroxsolutions/response';
 import { RequestInvalid } from './request-invalid.js';
-/**
- * The error object's `source` for one issue, by the slot it was read from.
- *
- * The spec defines exactly three members, and a path segment matches none of them: `pointer` is a JSON
- * Pointer into the request DOCUMENT, `parameter` a URI query parameter, `header` a header name. So a
- * `param` or `cookie` issue names its slot in `meta` rather than borrowing a member that means
- * something else.
- */
-function sourceFor(target, path) {
-    if (target === 'json' || target === 'form')
-        return { source: { pointer: `/${path.split('.').join('/')}` } };
-    if (target === 'query')
-        return { source: { parameter: path } };
-    if (target === 'header')
-        return { source: { header: path } };
-    return { meta: { target, path } };
+/** The deepest prefix of `path` that exists in what the client sent, which is where a pointer may point. */
+function existingPrefix(data, path) {
+    const found = [];
+    let current = data;
+    for (const segment of path) {
+        if (typeof current !== 'object' || current === null || !Object.hasOwn(current, segment))
+            break;
+        current = current[segment];
+        found.push(segment);
+    }
+    return found;
 }
+/** A JSON Pointer to a path, `""` for the whole document (RFC 6901 escapes `~` and `/`). */
+const pointerTo = (path) => path.map((segment) => `/${String(segment).replaceAll('~', '~0').replaceAll('/', '~1')}`).join('');
 /**
  * The `defaultHook` an `OpenAPIHono` is constructed with, rejecting a request its own schema refuses as one error
  * object per issue - 422 for a `json` or `form` target, 400 otherwise.
@@ -25,6 +22,13 @@ function sourceFor(target, path) {
  * failure, carrying the request id that handler stamps; an app without that handler answers the throw with hono's
  * text 500. @hono/zod-validator 0.9.0 lets a hook's throw through, and answers `c.json(result, 400)` itself unless a
  * hook answers or throws first - which is why the hook is still passed to the constructor.
+ *
+ * A body issue's `source.pointer` names the deepest object that exists in what the client sent, not the member the
+ * schema expected - a missing member has no member of its own to point at, so the pointer stops at its parent (`""`
+ * when nothing past the document root was sent). A query issue names its parameter; a route's query schema is a
+ * house query schema or a `z.strictObject`, and each key such a schema does not recognize answers as its own error
+ * object naming that key. A header issue names its header. A `param` or `cookie` issue carries no spec member for a
+ * path segment, so it goes in `meta` instead.
  */
 export function createValidationHook(options) {
     return (result) => {
@@ -34,14 +38,29 @@ export function createValidationHook(options) {
         const body = target === 'json' || target === 'form';
         const { status, title } = body ? BASE_ERROR_CODES.UNPROCESSABLE_ENTITY : BASE_ERROR_CODES.BAD_REQUEST;
         const code = `${options.namespace}.${body ? 'unprocessable_entity' : 'bad_request'}`;
-        const errors = result.error.issues.map((issue) => ({
-            status: String(status),
-            code,
-            title,
-            detail: issue.message,
-            // A whole-object refinement carries an empty path, so the slot it was read from stands in.
-            ...sourceFor(target, issue.path.map(String).join('.') || target),
-        }));
+        // @hono/zod-validator 0.9.0 calls the hook with `data`, the value it validated; the `Hook` type this package
+        // takes from `@hono/zod-openapi` does not declare that member on a failed result, so it is read through a cast.
+        const data = result.data;
+        const errors = result.error.issues.flatMap((issue) => {
+            const base = { status: String(status), code, title, detail: issue.message };
+            if (target === 'query' && issue.code === 'unrecognized_keys') {
+                return issue.keys.map((key) => ({
+                    ...base,
+                    detail: `The query parameter "${key}" cannot be processed.`,
+                    source: { parameter: key },
+                }));
+            }
+            if (body)
+                return [{ ...base, source: { pointer: pointerTo(existingPrefix(data, issue.path)) } }];
+            const path = issue.path.map(String).join('.');
+            if (path === '')
+                return [base];
+            if (target === 'query')
+                return [{ ...base, source: { parameter: path } }];
+            if (target === 'header')
+                return [{ ...base, source: { header: path } }];
+            return [{ ...base, meta: { target, path } }];
+        });
         throw new RequestInvalid(status, errors);
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zeroxsolutions/server",
-  "version": "0.3.5",
+  "version": "0.4.0",
   "private": false,
   "type": "module",
   "sideEffects": false,
@@ -21,8 +21,9 @@
   },
   "dependencies": {
     "tslib": "^2.3.0",
-    "@zeroxsolutions/jsonapi": "0.11.3",
-    "@zeroxsolutions/response": "0.13.0"
+    "@zeroxsolutions/jsonapi": "0.12.0",
+    "@zeroxsolutions/query": "0.7.0",
+    "@zeroxsolutions/response": "0.14.0"
   },
   "peerDependencies": {
     "@hono/zod-openapi": "^1.0.0",