@dokebi/web 0.4.1 → 0.4.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/AI.md CHANGED
@@ -1,4 +1,4 @@
1
- # AI guide — @dokebi/web 0.4.1
1
+ # AI guide — @dokebi/web 0.4.2
2
2
 
3
3
  A plugin through which the app owns a Fastify 5 HTTP server. It blocks requests before the app is ready and while it shuts down (503), serves health routes, drains requests in progress, swaps cluster workers without downtime and handles trusted proxies. Routers, controllers, views and DBs are not required. Node >=24.0.0, core ^0.4.0. Details are in the [README](README.md).
4
4
 
@@ -160,7 +160,7 @@ Do not answer validation with your own `reply.code(422).send(…)`: template-ine
160
160
  | `isFormSubmission(headers)` | true for a body of `application/x-www-form-urlencoded` or `multipart/form-data` (a browser `<form method="post">`) |
161
161
  | `formFieldErrors(body)` | the `errors` (`{ field: message }`) of a 422 `VALIDATION_FAILED` body, else undefined |
162
162
  | `formOldInput(body)` | the request body's top-level strings, numbers, booleans and nulls without password-like fields (`password`, `token`, `secret`, `api_key`, `card`, `cvc`, `otp`, `pin`…); undefined when nothing is left or it is over 8 KB as JSON |
163
- | `formBackTarget(request, host, fallback?)` | the path and query of the `Referer` when it is `host` (`web.requestHost(request)`; another origin is never followed), else `fallback` for a POST/PUT/PATCH/DELETE, else undefined; a GET or HEAD never goes back to itself (no redirect loop) |
163
+ | `formBackTarget(request, host, fallback?)` | the path and query of the `Referer` when it is `host` (`web.requestHost(request)`; another origin is never followed) and the path stays on it (0.4.2: `//other.host/…`, `/\other.host` and their encoded forms such as `/%2F%2F…` are refused, so the target never resolves to another origin), else `fallback` for a POST/PUT/PATCH/DELETE, else undefined; a GET or HEAD never goes back to itself (no redirect loop) |
164
164
 
165
165
  dokebi-web knows no session: the caller flashes `errors` and `old` and answers `reply.redirect(target, 303)`.
166
166
 
@@ -182,6 +182,7 @@ dokebi-web knows no session: the caller flashes `errors` and `old` and answers `
182
182
  | `SEAL_PROVIDER_INVALID` | the provider has the wrong shape or was registered twice |
183
183
  | `SEAL_REQUIRED` | 415, a plain body on a sealed request (answered in plain text) |
184
184
  | `SEAL_BODY_REFUSED` | 400, a sealed body could not be opened (the reason is only in the warn log) |
185
+ | `SEAL_BUSY` | 503, the seal provider's replay nonce store is full of live nonces (fail closed, [D-0075](https://git.nyx-zone.com/dokebi/framework/-/blob/main/docs/decisions/D-0075-replay-capacity.md)); retryable, warn `SEAL_BODY_REFUSED` with `reason: capacity` |
185
186
  | `SEAL_BODY_NOT_JSON` | 400, the opened body is not JSON |
186
187
  | `SEAL_STREAM_UNSUPPORTED` | 500, JSON for a sealed request was sent as a stream (error log) |
187
188
  | `VALIDATION_FAILED` | 422, a refused body or query string schema, or `validationError()`; `fields` and `errors` in the body |
package/README.md CHANGED
@@ -1,4 +1,4 @@
1
- # @dokebi/web 0.4.1
1
+ # @dokebi/web 0.4.2
2
2
 
3
3
  An optional package for Node >=24.0.0 and core ^0.4.0 (public on npm). It owns an HTTP server built on Fastify 5.12.7; DBs, routers, controllers and views are not required.
4
4
 
@@ -71,7 +71,7 @@ Plugins with an entry file are left out of the generated code's manifest depende
71
71
  web owns the **slot** that seals HTTP data of seal hosts (@dokebi/app `domains.<host>.seal: true`) and of `seal: true` routes. @dokebi/seal fills in the algorithm with `sealCodec(provider)` (this package never imports seal). See [D-0062](https://git.nyx-zone.com/dokebi/framework/-/blob/main/docs/decisions/D-0062-http-seal.md).
72
72
 
73
73
  - The decision (once per request): health → plain, route `seal: false` → plain, `seal: true` or `seal(request)` → sealed, a `sealExclude` prefix (`/` boundary) → plain, any `sealRequests(predicate)` true → sealed. `seal` becomes `config.dokebiSeal` whether given to `route()`, a Fastify `register` scope or a router `mount`.
74
- - Bodies of sealed requests: when the content type is the provider's `contentType` (`application/vnd.dokebi-seal`), the parser opens it and puts the JSON into `request.body` (drift, replay and tampering are 400, with the reason only in warn `SEAL_BODY_REFUSED`). A body that is neither sealed nor `multipart/form-data` gets `415 { error: 'SEAL_REQUIRED', fix }` **before the parser** (warn `SEAL_REQUIRED`, once per route every 10 seconds).
74
+ - Bodies of sealed requests: when the content type is the provider's `contentType` (`application/vnd.dokebi-seal`), the parser opens it and puts the JSON into `request.body` (drift, replay and tampering are 400, with the reason only in warn `SEAL_BODY_REFUSED`; a full replay nonce store is a retryable 503 `SEAL_BUSY`, D-0075). A body that is neither sealed nor `multipart/form-data` gets `415 { error: 'SEAL_REQUIRED', fix }` **before the parser** (warn `SEAL_REQUIRED`, once per route every 10 seconds).
75
75
  - JSON responses of sealed requests (`application/json`, `+json`, 4xx and 5xx included) are sealed in `onSend` and get `Content-Type: application/vnd.dokebi-seal` and `x-dokebi-sealed-path` (the path used for sealing; the final path after redirects). HTML, file and hijacked responses stay as they are. Streamed JSON cannot be sealed and becomes a 500 (plain text is never sent).
76
76
  - Code that writes its own body (the Inertia first page, SSE) gets `{ path, encode }` from `sealOf(request)`.
77
77
  - When something wants sealing (a registered decision or a sealed route) but no provider exists, start fails with `SEAL_PROVIDER_MISSING`.
package/dist/errors.d.ts CHANGED
@@ -1,7 +1,7 @@
1
1
  import { DokebiError, type DokebiErrorOptions } from '@dokebi/core';
2
2
  import { type WebFieldError } from './responses.js';
3
3
  /** Codes of the errors this plugin throws or answers with (`WebError`, `plugin: 'dokebi-web'`). */
4
- export type WebErrorCode = 'INVALID_ENTRY' | 'INVALID_ROUTE' | 'INVALID_HOOK' | 'INVALID_ARGUMENT' | 'INVALID_EXTENSION_RESULT' | 'FROZEN' | 'CLOSED' | 'FORM_BODY_DISABLED' | 'FORM_BODY_TOO_MANY_FIELDS' | 'SEAL_PROVIDER_MISSING' | 'SEAL_PROVIDER_INVALID' | 'SEAL_REQUIRED' | 'SEAL_BODY_REFUSED' | 'SEAL_BODY_NOT_JSON' | 'SEAL_STREAM_UNSUPPORTED' | 'VALIDATION_FAILED' | 'NOT_FOUND';
4
+ export type WebErrorCode = 'INVALID_ENTRY' | 'INVALID_ROUTE' | 'INVALID_HOOK' | 'INVALID_ARGUMENT' | 'INVALID_EXTENSION_RESULT' | 'FROZEN' | 'CLOSED' | 'FORM_BODY_DISABLED' | 'FORM_BODY_TOO_MANY_FIELDS' | 'SEAL_PROVIDER_MISSING' | 'SEAL_PROVIDER_INVALID' | 'SEAL_REQUIRED' | 'SEAL_BODY_REFUSED' | 'SEAL_BUSY' | 'SEAL_BODY_NOT_JSON' | 'SEAL_STREAM_UNSUPPORTED' | 'VALIDATION_FAILED' | 'NOT_FOUND';
5
5
  /**
6
6
  * Errors of @dokebi/web; compare `code`, not the class (another installed copy may throw).
7
7
  * Request errors carry the HTTP `status` dokebi-web answers with, and a `hint` for the client.
package/dist/errors.js CHANGED
@@ -15,6 +15,7 @@ const FIX = {
15
15
  SEAL_PROVIDER_INVALID: 'Register one seal codec provider (the dokebi-seal plugin) with { contentType, forRequest }.',
16
16
  SEAL_REQUIRED: 'This route is sealed (a seal host): send the body sealed with @dokebi/seal (sealedFetch, or the Inertia bridge sealInertia). File uploads use multipart/form-data; webhooks and server-to-server routes set seal: false or are listed in dokebi-web sealExclude.',
17
17
  SEAL_BODY_REFUSED: 'Seal request bodies with @dokebi/seal for this host and path, once, within sealDriftMs of the server clock.',
18
+ SEAL_BUSY: 'The one-time nonce store of the seal provider is full of live nonces, so sealed bodies are refused until some expire (fail closed, D-0075): register @dokebi/websocket-hub with mode: cluster (Redis), or lower sealDriftMs.',
18
19
  SEAL_BODY_NOT_JSON: 'A sealed request body must be JSON text before sealing.',
19
20
  SEAL_STREAM_UNSUPPORTED: 'Send JSON of a sealed request as a string, object or Buffer, not a stream (or set seal: false on the route).',
20
21
  VALIDATION_FAILED: 'Correct the fields listed in `fields` (or `errors`): the route schema (schema.body, schema.querystring, schema.params) or the validationError() of the handler refused them.',
@@ -25,6 +26,7 @@ const HINT = {
25
26
  FORM_BODY_TOO_MANY_FIELDS: 'The form has too many fields.',
26
27
  SEAL_REQUIRED: 'This address only accepts sealed requests. Reload the page and try again.',
27
28
  SEAL_BODY_REFUSED: 'The request could not be opened. Reload the page and try again.',
29
+ SEAL_BUSY: 'The server is busy. Try again in a moment.',
28
30
  SEAL_BODY_NOT_JSON: 'The request could not be read. Reload the page and try again.',
29
31
  VALIDATION_FAILED: VALIDATION_HINT,
30
32
  NOT_FOUND: 'The page or resource does not exist.',
@@ -34,6 +36,7 @@ const STATUS = {
34
36
  FORM_BODY_TOO_MANY_FIELDS: 413,
35
37
  SEAL_REQUIRED: 415,
36
38
  SEAL_BODY_REFUSED: 400,
39
+ SEAL_BUSY: 503,
37
40
  SEAL_BODY_NOT_JSON: 400,
38
41
  SEAL_STREAM_UNSUPPORTED: 500,
39
42
  VALIDATION_FAILED: 422,
package/dist/forms.d.ts CHANGED
@@ -15,9 +15,10 @@ export type WebFormValue = string | number | boolean | null;
15
15
  export declare function isFormSubmission(headers: Readonly<Record<string, string | string[] | undefined>>): boolean;
16
16
  /**
17
17
  * Where a refused form goes back (D-0074 §3): the path and query of the `Referer` when it is
18
- * this host (`host` as `WebApi.requestHost` gives it; another origin is never followed).
19
- * Otherwise `fallback` for a POST, PUT, PATCH or DELETE (template-inertia passes `/`), or
20
- * undefined. A GET or HEAD whose referer is missing or is itself has no way back: a redirect to
18
+ * this host (`host` as `WebApi.requestHost` gives it; another origin is never followed) and the
19
+ * path stays on it (`//other.host/…`, `/\other.host` and their encoded forms are refused, so the
20
+ * answer never reads as another host). Otherwise `fallback` for a POST, PUT, PATCH or DELETE
21
+ * (template-inertia passes `/`), or undefined. A GET or HEAD whose referer is missing or is itself has no way back: a redirect to
21
22
  * itself would be refused again, forever.
22
23
  */
23
24
  export declare function formBackTarget(request: WebFormRequest, host: string, fallback?: string): string | undefined;
package/dist/forms.js CHANGED
@@ -19,9 +19,10 @@ export function isFormSubmission(headers) {
19
19
  }
20
20
  /**
21
21
  * Where a refused form goes back (D-0074 §3): the path and query of the `Referer` when it is
22
- * this host (`host` as `WebApi.requestHost` gives it; another origin is never followed).
23
- * Otherwise `fallback` for a POST, PUT, PATCH or DELETE (template-inertia passes `/`), or
24
- * undefined. A GET or HEAD whose referer is missing or is itself has no way back: a redirect to
22
+ * this host (`host` as `WebApi.requestHost` gives it; another origin is never followed) and the
23
+ * path stays on it (`//other.host/…`, `/\other.host` and their encoded forms are refused, so the
24
+ * answer never reads as another host). Otherwise `fallback` for a POST, PUT, PATCH or DELETE
25
+ * (template-inertia passes `/`), or undefined. A GET or HEAD whose referer is missing or is itself has no way back: a redirect to
25
26
  * itself would be refused again, forever.
26
27
  */
27
28
  export function formBackTarget(request, host, fallback) {
@@ -33,12 +34,29 @@ export function formBackTarget(request, host, fallback) {
33
34
  if ((url.protocol === 'http:' || url.protocol === 'https:') &&
34
35
  url.host.toLowerCase() === host.toLowerCase()) {
35
36
  const target = url.pathname + url.search;
36
- if (!(read && target === request.url))
37
+ if (sameOrigin(target, url.origin) && !(read && target === request.url))
37
38
  return target;
38
39
  }
39
40
  }
40
41
  return read ? undefined : fallback;
41
42
  }
43
+ /**
44
+ * A path a browser or a proxy could read as another host: `//host` (scheme-relative), `/\host`
45
+ * and their percent-encoded forms (`/%2F…`, `/%5C…`). The URL parser turns `\` and `/./` into
46
+ * `/`, so a same-host Referer such as `https://app.test//outside.test/x` has such a path.
47
+ */
48
+ const HOST_LIKE_PATH = /^\/(?:[/\\]|%2f|%5c)/i;
49
+ /**
50
+ * True when `target` (a path and query of a Referer whose origin is `origin`) is a redirect
51
+ * target that stays on `origin`: it is not host-like and resolves against `origin` to `origin`
52
+ * with the same path and query (ISSUE-0006 A02, an open redirect through `//host` paths).
53
+ */
54
+ function sameOrigin(target, origin) {
55
+ if (!target.startsWith('/') || HOST_LIKE_PATH.test(target))
56
+ return false;
57
+ const resolved = new URL(target, origin);
58
+ return resolved.origin === origin && resolved.pathname + resolved.search === target;
59
+ }
42
60
  /**
43
61
  * The old input of a refused form (D-0074 §3): the body's top-level strings, numbers, booleans
44
62
  * and nulls, without password-like fields (`password`, `token`, `secret`, `api_key`, `card`,
package/dist/index.js CHANGED
@@ -1065,7 +1065,7 @@ class WebRuntime {
1065
1065
  }
1066
1066
  export const createPlugin = definePlugin({
1067
1067
  name: 'dokebi-web',
1068
- version: '0.4.1',
1068
+ version: '0.4.2',
1069
1069
  core: '^0.4.0',
1070
1070
  options: declaration,
1071
1071
  entry: (input) => new WebEntryInput(input),
package/dist/seal.js CHANGED
@@ -219,6 +219,12 @@ export class WebSealing {
219
219
  ...(repeated ? { repeated } : {}),
220
220
  });
221
221
  this.#plain.add(request);
222
+ // A full replay nonce store (D-0075, fail closed) is the server's state, not the body's:
223
+ // 503, so the client may retry. It says nothing about drift or replay.
224
+ if (reason === 'capacity')
225
+ throw new WebError('SEAL_BUSY', 'Sealed request body refused: server busy', {
226
+ cause: error,
227
+ });
222
228
  throw new WebError('SEAL_BODY_REFUSED', 'Sealed request body refused', { cause: error });
223
229
  }
224
230
  if (plain === '')
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@dokebi/web",
3
- "version": "0.4.1",
3
+ "version": "0.4.2",
4
4
  "description": "Fastify 5 HTTP server owned by a Dokebi app: 503 before ready, health routes, drain and cluster handover.",
5
5
  "keywords": [
6
6
  "dokebi",