@dokebi/web 0.4.2 → 0.4.4
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 +250 -39
- package/README.md +31 -10
- package/dist/app-routes.d.ts +20 -0
- package/dist/app-routes.js +137 -0
- package/dist/before-hijack.d.ts +24 -0
- package/dist/before-hijack.js +73 -0
- package/dist/body.d.ts +14 -0
- package/dist/body.js +30 -0
- package/dist/cluster-ready.d.ts +67 -0
- package/dist/cluster-ready.js +123 -0
- package/dist/compilers.d.ts +16 -0
- package/dist/compilers.js +25 -0
- package/dist/compression.d.ts +40 -0
- package/dist/compression.js +435 -0
- package/dist/connections.d.ts +44 -0
- package/dist/connections.js +282 -0
- package/dist/define-errors.d.ts +76 -0
- package/dist/define-errors.js +161 -0
- package/dist/describe.d.ts +37 -0
- package/dist/describe.js +96 -0
- package/dist/errors.d.ts +1 -1
- package/dist/errors.js +24 -3
- package/dist/forms.d.ts +23 -7
- package/dist/forms.js +53 -13
- package/dist/index.d.ts +134 -4
- package/dist/index.js +1552 -91
- package/dist/options.d.ts +56 -0
- package/dist/options.js +320 -1
- package/dist/points.d.ts +159 -0
- package/dist/points.js +162 -1
- package/dist/responses.d.ts +31 -6
- package/dist/responses.js +68 -6
- package/dist/route-config.d.ts +38 -0
- package/dist/route-config.js +222 -0
- package/dist/route-hooks.d.ts +75 -0
- package/dist/route-hooks.js +118 -0
- package/dist/route-table.d.ts +55 -0
- package/dist/route-table.js +142 -0
- package/dist/seal.d.ts +49 -1
- package/dist/seal.js +259 -24
- package/dist/security-headers.d.ts +121 -0
- package/dist/security-headers.js +298 -0
- package/dist/transient-log.d.ts +42 -0
- package/dist/transient-log.js +95 -0
- package/options.schema.json +488 -1
- package/package.json +22 -9
package/dist/options.d.ts
CHANGED
|
@@ -1,19 +1,75 @@
|
|
|
1
1
|
import { type OptionsOf } from '@dokebi/core';
|
|
2
2
|
export declare const options: import("@dokebi/core").OptionsDeclaration<{
|
|
3
|
+
readonly binaryBody: boolean;
|
|
4
|
+
readonly compression: {
|
|
5
|
+
readonly brotliQuality: number;
|
|
6
|
+
readonly enabled: boolean;
|
|
7
|
+
readonly encodings: readonly ("br" | "gzip")[];
|
|
8
|
+
readonly gzipLevel: number;
|
|
9
|
+
readonly maxBufferBytes: number;
|
|
10
|
+
readonly maxPending: number;
|
|
11
|
+
readonly thresholdBytes: number;
|
|
12
|
+
};
|
|
3
13
|
readonly developmentErrors: boolean;
|
|
14
|
+
readonly drainGraceMs: number;
|
|
15
|
+
readonly drainIdleMs: number;
|
|
4
16
|
readonly formBody: boolean;
|
|
5
17
|
readonly formMaxFields: number;
|
|
18
|
+
readonly formOldInputMaxChars: number;
|
|
19
|
+
readonly formRefererMaxLength: number;
|
|
6
20
|
readonly healthRoutes: false | {
|
|
7
21
|
readonly live: string;
|
|
8
22
|
readonly ready: string;
|
|
9
23
|
};
|
|
10
24
|
readonly host: string;
|
|
25
|
+
readonly linger: {
|
|
26
|
+
readonly maxBytes: number;
|
|
27
|
+
readonly ms: number;
|
|
28
|
+
};
|
|
29
|
+
readonly logRepeatWindowMs: number;
|
|
11
30
|
readonly maxBodyBytes: number;
|
|
31
|
+
readonly maxRouteBodyBytes: number;
|
|
32
|
+
readonly overload: {
|
|
33
|
+
readonly enabled: boolean;
|
|
34
|
+
readonly maxEventLoopDelayMs: number;
|
|
35
|
+
readonly maxEventLoopUtilization: number;
|
|
36
|
+
readonly maxHeapUsedBytes: number;
|
|
37
|
+
readonly maxRssBytes: number;
|
|
38
|
+
readonly retryAfterMs: number;
|
|
39
|
+
readonly sampleIntervalMs: number;
|
|
40
|
+
};
|
|
12
41
|
readonly port: number;
|
|
13
42
|
readonly requestTimeoutMs: number;
|
|
43
|
+
readonly routeIds?: {
|
|
44
|
+
readonly healthLive?: string;
|
|
45
|
+
readonly healthReady?: string;
|
|
46
|
+
};
|
|
14
47
|
readonly sealDriftMs: number;
|
|
15
48
|
readonly sealExclude: readonly string[];
|
|
49
|
+
readonly sealRetryAfterMs: number;
|
|
50
|
+
readonly securityHeaders: {
|
|
51
|
+
readonly contentSecurityPolicy: false | {
|
|
52
|
+
readonly directives: Readonly<Record<string, false | readonly string[]>>;
|
|
53
|
+
readonly reportOnly: boolean;
|
|
54
|
+
};
|
|
55
|
+
readonly contentTypeOptions: boolean;
|
|
56
|
+
readonly crossOriginOpenerPolicy: "same-origin" | "same-origin-allow-popups" | "unsafe-none" | false;
|
|
57
|
+
readonly crossOriginResourcePolicy: "cross-origin" | "same-origin" | "same-site" | false;
|
|
58
|
+
readonly enabled: boolean;
|
|
59
|
+
readonly frameOptions: "DENY" | "SAMEORIGIN" | false;
|
|
60
|
+
readonly referrerPolicy: "no-referrer" | "no-referrer-when-downgrade" | "origin" | "origin-when-cross-origin" | "same-origin" | "strict-origin" | "strict-origin-when-cross-origin" | "unsafe-url" | false;
|
|
61
|
+
readonly strictTransportSecurity: false | {
|
|
62
|
+
readonly includeSubDomains: boolean;
|
|
63
|
+
readonly maxAgeSec: number;
|
|
64
|
+
readonly preload: boolean;
|
|
65
|
+
};
|
|
66
|
+
};
|
|
67
|
+
readonly transientLogLevel: "error" | "warn";
|
|
68
|
+
readonly transientLogMaxKeys: number;
|
|
69
|
+
readonly transientLogWindowMs: number;
|
|
16
70
|
readonly trustProxy: readonly string[];
|
|
71
|
+
readonly unavailableRetryAfterMs: number;
|
|
72
|
+
readonly unknownFields: "refuse" | "remove";
|
|
17
73
|
}>;
|
|
18
74
|
/** The parsed options of dokebi-web (`options.dokebi-web`). */
|
|
19
75
|
export type WebOptions = OptionsOf<typeof options>;
|
package/dist/options.js
CHANGED
|
@@ -1,5 +1,7 @@
|
|
|
1
1
|
import { isIP } from 'node:net';
|
|
2
2
|
import { defineOptions, option as o } from '@dokebi/core';
|
|
3
|
+
import { routeIdsOption } from './points.js';
|
|
4
|
+
import { DIRECTIVE, SOURCE } from './security-headers.js';
|
|
3
5
|
/*
|
|
4
6
|
* Options of dokebi-web (D-0063 §3): one declaration is the parser and, at build time,
|
|
5
7
|
* options.schema.json. The rules are the hand parser's before wave B; what the old schema did
|
|
@@ -27,11 +29,38 @@ export const options = defineOptions({
|
|
|
27
29
|
description: 'Largest request body in bytes.',
|
|
28
30
|
}),
|
|
29
31
|
bodyLimit: o.alias('maxBodyBytes'),
|
|
32
|
+
maxRouteBodyBytes: o.integer({
|
|
33
|
+
minimum: 1,
|
|
34
|
+
maximum: 1073741824,
|
|
35
|
+
default: 67108864,
|
|
36
|
+
description: 'Largest bodyLimit one route may declare for itself, in bytes (D-0122); a larger one fails the start. At least maxBodyBytes.',
|
|
37
|
+
}),
|
|
38
|
+
linger: o.object({
|
|
39
|
+
ms: o.integer({
|
|
40
|
+
minimum: 0,
|
|
41
|
+
maximum: 60_000,
|
|
42
|
+
default: 5000,
|
|
43
|
+
description: 'After an answer sent before the request body was read (a 403, 413 or 415 refused early), how long the connection still reads and drops what the client keeps sending before it closes, so the client reads the answer instead of a connection reset. 0 closes at once.',
|
|
44
|
+
}),
|
|
45
|
+
maxBytes: o.integer({
|
|
46
|
+
minimum: 0,
|
|
47
|
+
maximum: 1_073_741_824,
|
|
48
|
+
default: 16_777_216,
|
|
49
|
+
description: 'At most this many bytes of such an unread body are read and dropped; past it the connection closes at once.',
|
|
50
|
+
}),
|
|
51
|
+
}, {
|
|
52
|
+
default: { ms: 5000, maxBytes: 16_777_216 },
|
|
53
|
+
description: 'Lingering close (AI-M47 flaky test): an early answer closes its connection only after the client stopped sending, within these limits.',
|
|
54
|
+
}),
|
|
55
|
+
binaryBody: o.boolean({
|
|
56
|
+
default: false,
|
|
57
|
+
description: 'Parse application/octet-stream bodies into request.body as a Buffer, up to the route bodyLimit or maxBodyBytes (D-0122). Off: such a request gets 415 as before. Seal hosts still refuse them (415 SEAL_REQUIRED) unless the route sets seal: false',
|
|
58
|
+
}),
|
|
30
59
|
requestTimeoutMs: o.integer({
|
|
31
60
|
minimum: 1,
|
|
32
61
|
maximum: 2147483647,
|
|
33
62
|
default: 30000,
|
|
34
|
-
description: 'Time to
|
|
63
|
+
description: 'Time a request body may take to arrive after its headers, in ms (408 REQUEST_TIMEOUT past it; a route may set its own config.requestTimeoutMs), and the bound of the headers themselves; not a limit on the work it starts.',
|
|
35
64
|
}),
|
|
36
65
|
requestTimeout: o.alias('requestTimeoutMs'),
|
|
37
66
|
healthRoutes: o.union([
|
|
@@ -52,6 +81,10 @@ export const options = defineOptions({
|
|
|
52
81
|
default: { live: '/health/live', ready: '/health/ready' },
|
|
53
82
|
description: 'Liveness and readiness routes (answered before ready and while draining); false registers none.',
|
|
54
83
|
}),
|
|
84
|
+
routeIds: routeIdsOption('dokebi-web', {
|
|
85
|
+
healthLive: 'the liveness route (healthRoutes.live)',
|
|
86
|
+
healthReady: 'the readiness route (healthRoutes.ready)',
|
|
87
|
+
}),
|
|
55
88
|
trustProxy: o.array(o.string({
|
|
56
89
|
minLength: 2,
|
|
57
90
|
maxLength: 45,
|
|
@@ -75,6 +108,10 @@ export const options = defineOptions({
|
|
|
75
108
|
default: [],
|
|
76
109
|
description: 'Seal hosts (D-0062): path prefixes that stay plain (webhooks, server-to-server), matched at a / boundary',
|
|
77
110
|
}),
|
|
111
|
+
unknownFields: o.enum(['remove', 'refuse'], {
|
|
112
|
+
default: 'remove',
|
|
113
|
+
description: "Fields a route schema does not allow (additionalProperties: false) in a body, query string or params: remove drops them before the handler (Fastify's default, Ajv removeAdditional); refuse answers an extra body or query field 422 VALIDATION_FAILED naming each field (is not allowed), an extra path parameter 400 INVALID_REQUEST like any refused params schema.",
|
|
114
|
+
}),
|
|
78
115
|
formBody: o.boolean({
|
|
79
116
|
default: false,
|
|
80
117
|
description: 'Parse HTML form bodies (application/x-www-form-urlencoded) into request.body (D-0068). Off: such a request gets 415 FORM_BODY_DISABLED. Seal hosts still refuse them (415 SEAL_REQUIRED)',
|
|
@@ -86,7 +123,289 @@ export const options = defineOptions({
|
|
|
86
123
|
description: 'Most fields one form body may carry; more is 413 FORM_BODY_TOO_MANY_FIELDS (maxBodyBytes also applies)',
|
|
87
124
|
}),
|
|
88
125
|
developmentErrors: o.boolean({
|
|
126
|
+
reloadable: true,
|
|
89
127
|
default: true,
|
|
90
128
|
description: 'Outside production (NODE_ENV is not production) error bodies also carry fix and details (D-0063). false: never, as in production. hint and data are always sent.',
|
|
91
129
|
}),
|
|
130
|
+
transientLogWindowMs: o.integer({
|
|
131
|
+
reloadable: true,
|
|
132
|
+
minimum: 1000,
|
|
133
|
+
maximum: 3600000,
|
|
134
|
+
default: 10000,
|
|
135
|
+
description: 'Retryable 503s (a translated error, or a 503 with Retry-After; D-0113): the first of each error code and route in a window is logged in full, the rest are counted into one WEB_TRANSIENT_REPEATED line when the window ends or the server closes. 500s are not affected.',
|
|
136
|
+
}),
|
|
137
|
+
transientLogMaxKeys: o.integer({
|
|
138
|
+
reloadable: true,
|
|
139
|
+
minimum: 1,
|
|
140
|
+
maximum: 65536,
|
|
141
|
+
default: 256,
|
|
142
|
+
description: 'Distinct error code and route pairs one transient window logs in full (D-0113); past it new pairs are only counted, in one WEB_TRANSIENT_REPEATED line with overflow: true.',
|
|
143
|
+
}),
|
|
144
|
+
logRepeatWindowMs: o.integer({
|
|
145
|
+
minimum: 1000,
|
|
146
|
+
maximum: 3600000,
|
|
147
|
+
default: 10000,
|
|
148
|
+
description: 'Window of every other repeated web log (D-0047, D-0114): a 500 of the same route, error name and code, a refused form body, a refused or failed sealed body, a failed response hook, translator or responder is logged in full once per window; the next one says how many were held back (repeated).',
|
|
149
|
+
}),
|
|
150
|
+
formOldInputMaxChars: o.integer({
|
|
151
|
+
minimum: 256,
|
|
152
|
+
maximum: 1048576,
|
|
153
|
+
default: 8192,
|
|
154
|
+
description: 'Largest old input (as JSON text) a refused form goes back with (D-0074, D-0114); a larger body goes back without its old input, so the user retypes it. Raise it for forms with long text areas.',
|
|
155
|
+
}),
|
|
156
|
+
formRefererMaxLength: o.integer({
|
|
157
|
+
minimum: 256,
|
|
158
|
+
maximum: 65536,
|
|
159
|
+
default: 4096,
|
|
160
|
+
description: 'Longest Referer a refused form goes back to (D-0074, D-0114); a longer one is not followed (POST: back to the fallback). Raise it for pages with long query strings.',
|
|
161
|
+
}),
|
|
162
|
+
drainGraceMs: o.integer({
|
|
163
|
+
reloadable: true,
|
|
164
|
+
minimum: 0,
|
|
165
|
+
maximum: 60000,
|
|
166
|
+
default: 100,
|
|
167
|
+
description: 'How long a draining node:cluster worker stays up after it stops listening, so a connection the primary was already handing it is answered "not accepted" and passed on (D-0036, D-0114).',
|
|
168
|
+
}),
|
|
169
|
+
drainIdleMs: o.integer({
|
|
170
|
+
reloadable: true,
|
|
171
|
+
minimum: 0,
|
|
172
|
+
maximum: 60000,
|
|
173
|
+
default: 2000,
|
|
174
|
+
description: 'How long a draining node:cluster worker keeps its idle keep-alive connections open (D-0036): a request a client sends on one is served with Connection: close instead of being lost to a closed socket (ECONNRESET), and the drain goes on as soon as none is left. Connections still idle then are closed. The wait ends 100 ms before the drain deadline (core drainDeadline) whatever this says, so it never causes DRAIN_TIMEOUT.',
|
|
175
|
+
}),
|
|
176
|
+
unavailableRetryAfterMs: o.integer({
|
|
177
|
+
reloadable: true,
|
|
178
|
+
minimum: 1000,
|
|
179
|
+
maximum: 600000,
|
|
180
|
+
default: 5000,
|
|
181
|
+
description: 'Retry-After of the 503 SERVICE_UNAVAILABLE refusals before the app is ready, while a required health check is not ready (a Redis or database outage) and while it drains (rounded up to seconds). The default matches the 5 s of a lost Redis connection (dokebi-redis unavailableRetryAfterMs), the usual cause of an unready worker.',
|
|
182
|
+
}),
|
|
183
|
+
sealRetryAfterMs: o.integer({
|
|
184
|
+
minimum: 1,
|
|
185
|
+
maximum: 60000,
|
|
186
|
+
default: 1000,
|
|
187
|
+
description: 'Retry-After of the 503s SEAL_BUSY (a full replay nonce store) and SEAL_NONCE_STORE_UNAVAILABLE (a failing or slow one) (D-0114).',
|
|
188
|
+
}),
|
|
189
|
+
transientLogLevel: o.enum(['error', 'warn'], {
|
|
190
|
+
reloadable: true,
|
|
191
|
+
default: 'error',
|
|
192
|
+
description: 'Level of the transient 503 records and their WEB_TRANSIENT_REPEATED summaries (D-0113). 500s stay at error.',
|
|
193
|
+
}),
|
|
194
|
+
compression: o.object({
|
|
195
|
+
enabled: o.boolean({
|
|
196
|
+
default: true,
|
|
197
|
+
description: 'Compress responses with br or gzip when the client accepts it (D-0125). false: every answer goes out as the handler wrote it (a front proxy compresses).',
|
|
198
|
+
}),
|
|
199
|
+
thresholdBytes: o.integer({
|
|
200
|
+
minimum: 0,
|
|
201
|
+
maximum: 1048576,
|
|
202
|
+
default: 1024,
|
|
203
|
+
description: 'Smallest body in bytes that is compressed; a smaller one (or a stream with a smaller Content-Length) goes out as is.',
|
|
204
|
+
}),
|
|
205
|
+
brotliQuality: o.integer({
|
|
206
|
+
minimum: 0,
|
|
207
|
+
maximum: 11,
|
|
208
|
+
default: 4,
|
|
209
|
+
description: 'Brotli quality, 0 (fastest) to 11 (smallest, far too slow for answers made per request).',
|
|
210
|
+
}),
|
|
211
|
+
gzipLevel: o.integer({
|
|
212
|
+
minimum: 1,
|
|
213
|
+
maximum: 9,
|
|
214
|
+
default: 6,
|
|
215
|
+
description: 'gzip level, 1 (fastest) to 9 (smallest).',
|
|
216
|
+
}),
|
|
217
|
+
encodings: o.array(o.enum(['br', 'gzip']), {
|
|
218
|
+
minItems: 1,
|
|
219
|
+
maxItems: 2,
|
|
220
|
+
uniqueItems: true,
|
|
221
|
+
default: ['br', 'gzip'],
|
|
222
|
+
description: 'Codings offered, in the order that wins when the client gives them the same q-value.',
|
|
223
|
+
}),
|
|
224
|
+
maxBufferBytes: o.integer({
|
|
225
|
+
minimum: 1024,
|
|
226
|
+
maximum: 67108864,
|
|
227
|
+
default: 1048576,
|
|
228
|
+
description: 'Largest buffered body compressed in one call (sent with Content-Length); a larger one is compressed as a stream, chunk by chunk, so its compressed copy is never held whole.',
|
|
229
|
+
}),
|
|
230
|
+
maxPending: o.integer({
|
|
231
|
+
minimum: 1,
|
|
232
|
+
maximum: 4096,
|
|
233
|
+
default: 64,
|
|
234
|
+
description: 'Compressions under way at once (one-shot jobs and streams); past it answers go out uncompressed with a WEB_COMPRESSION_BUSY warning, instead of queueing more CPU work.',
|
|
235
|
+
}),
|
|
236
|
+
}, {
|
|
237
|
+
default: {
|
|
238
|
+
enabled: true,
|
|
239
|
+
thresholdBytes: 1024,
|
|
240
|
+
brotliQuality: 4,
|
|
241
|
+
gzipLevel: 6,
|
|
242
|
+
encodings: ['br', 'gzip'],
|
|
243
|
+
maxBufferBytes: 1048576,
|
|
244
|
+
maxPending: 64,
|
|
245
|
+
},
|
|
246
|
+
description: 'Response compression (D-0125): br or gzip by Accept-Encoding for text, JSON, JS, CSS, SVG and XML bodies; never for 206, 304, SSE, sealed bodies, Cache-Control: no-transform or a body that already has a Content-Encoding.',
|
|
247
|
+
}),
|
|
248
|
+
overload: o.object({
|
|
249
|
+
enabled: o.boolean({
|
|
250
|
+
default: true,
|
|
251
|
+
description: 'Shed load (D-0150, @fastify/under-pressure): above a limit below, requests are answered 503 OVERLOADED with Retry-After before any handler runs; health routes and routes with config.overload false are served. false: never',
|
|
252
|
+
}),
|
|
253
|
+
maxEventLoopDelayMs: o.integer({
|
|
254
|
+
reloadable: true,
|
|
255
|
+
minimum: 0,
|
|
256
|
+
maximum: 600000,
|
|
257
|
+
default: 200,
|
|
258
|
+
description: 'Mean event loop delay over the last sample above which requests are refused (a saturated but healthy loop measured a mean of 11 ms, at most 24 ms; D-0150 §2); 0: not checked',
|
|
259
|
+
}),
|
|
260
|
+
maxEventLoopUtilization: o.number({
|
|
261
|
+
reloadable: true,
|
|
262
|
+
minimum: 0,
|
|
263
|
+
maximum: 1,
|
|
264
|
+
default: 0,
|
|
265
|
+
description: 'Event loop utilization (0..1) over the last sample above which requests are refused; 0: not checked',
|
|
266
|
+
}),
|
|
267
|
+
maxHeapUsedBytes: o.integer({
|
|
268
|
+
reloadable: true,
|
|
269
|
+
minimum: 0,
|
|
270
|
+
maximum: 1099511627776,
|
|
271
|
+
default: 0,
|
|
272
|
+
description: 'V8 heap used above which requests are refused; 0: not checked',
|
|
273
|
+
}),
|
|
274
|
+
maxRssBytes: o.integer({
|
|
275
|
+
reloadable: true,
|
|
276
|
+
minimum: 0,
|
|
277
|
+
maximum: 1099511627776,
|
|
278
|
+
default: 0,
|
|
279
|
+
description: 'Resident set size above which requests are refused; 0: not checked',
|
|
280
|
+
}),
|
|
281
|
+
sampleIntervalMs: o.integer({
|
|
282
|
+
minimum: 10,
|
|
283
|
+
maximum: 60000,
|
|
284
|
+
default: 1000,
|
|
285
|
+
description: 'How often the event loop and memory are sampled, in ms',
|
|
286
|
+
}),
|
|
287
|
+
retryAfterMs: o.integer({
|
|
288
|
+
reloadable: true,
|
|
289
|
+
minimum: 1000,
|
|
290
|
+
maximum: 600000,
|
|
291
|
+
default: 2000,
|
|
292
|
+
description: 'Retry-After of the 503 OVERLOADED answers (rounded up to seconds)',
|
|
293
|
+
}),
|
|
294
|
+
}, {
|
|
295
|
+
default: {
|
|
296
|
+
enabled: true,
|
|
297
|
+
maxEventLoopDelayMs: 200,
|
|
298
|
+
maxEventLoopUtilization: 0,
|
|
299
|
+
maxHeapUsedBytes: 0,
|
|
300
|
+
maxRssBytes: 0,
|
|
301
|
+
sampleIntervalMs: 1000,
|
|
302
|
+
retryAfterMs: 2000,
|
|
303
|
+
},
|
|
304
|
+
description: 'Overload protection (D-0150): limits on the event loop and memory of this process, checked on every request against the last sample.',
|
|
305
|
+
}),
|
|
306
|
+
securityHeaders: o.object({
|
|
307
|
+
enabled: o.boolean({
|
|
308
|
+
default: true,
|
|
309
|
+
description: 'Security headers on every answer (D-0149): nosniff, HSTS over HTTPS, and on HTML documents the CSP, X-Frame-Options, Referrer-Policy and the cross-origin policies. false: none (a front proxy sets them).',
|
|
310
|
+
}),
|
|
311
|
+
contentSecurityPolicy: o.union([
|
|
312
|
+
o.literal(false),
|
|
313
|
+
o.object({
|
|
314
|
+
directives: o.record(o.union([
|
|
315
|
+
o.array(o.string({ pattern: SOURCE }), { maxItems: 64 }),
|
|
316
|
+
o.literal(false),
|
|
317
|
+
]), {
|
|
318
|
+
default: {},
|
|
319
|
+
keys: { pattern: DIRECTIVE },
|
|
320
|
+
maxProperties: 64,
|
|
321
|
+
description: "Changes to the default policy, by directive: a list of sources replaces that directive ([] = a directive without sources), false removes it. Default policy: default-src 'self'; base-uri 'self'; object-src 'none'; frame-ancestors 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline' https:; img-src 'self' data: blob: https:; font-src 'self' data: https:; connect-src 'self'",
|
|
322
|
+
}),
|
|
323
|
+
reportOnly: o.boolean({
|
|
324
|
+
default: false,
|
|
325
|
+
description: 'Send Content-Security-Policy-Report-Only instead: the browser reports what the policy would block and blocks nothing',
|
|
326
|
+
}),
|
|
327
|
+
}),
|
|
328
|
+
], {
|
|
329
|
+
reloadable: true,
|
|
330
|
+
default: { directives: {}, reportOnly: false },
|
|
331
|
+
description: 'Content-Security-Policy of HTML documents (plugins add the sources they need: @dokebi/seal wasm, the Vite dev socket); false sends none',
|
|
332
|
+
}),
|
|
333
|
+
strictTransportSecurity: o.union([
|
|
334
|
+
o.literal(false),
|
|
335
|
+
o.object({
|
|
336
|
+
maxAgeSec: o.integer({
|
|
337
|
+
minimum: 0,
|
|
338
|
+
maximum: 63072000,
|
|
339
|
+
default: 31536000,
|
|
340
|
+
description: 'max-age in seconds (0 tells browsers to forget it)',
|
|
341
|
+
}),
|
|
342
|
+
includeSubDomains: o.boolean({ default: true, description: 'includeSubDomains' }),
|
|
343
|
+
preload: o.boolean({
|
|
344
|
+
default: false,
|
|
345
|
+
description: 'preload (only when the domain is submitted to the preload list)',
|
|
346
|
+
}),
|
|
347
|
+
}),
|
|
348
|
+
], {
|
|
349
|
+
reloadable: true,
|
|
350
|
+
default: { maxAgeSec: 31536000, includeSubDomains: true, preload: false },
|
|
351
|
+
description: 'Strict-Transport-Security on answers to HTTPS requests (TLS here, or X-Forwarded-Proto: https from a trustProxy address); never on plain HTTP. false: none',
|
|
352
|
+
}),
|
|
353
|
+
frameOptions: o.union([o.enum(['DENY', 'SAMEORIGIN']), o.literal(false)], {
|
|
354
|
+
reloadable: true,
|
|
355
|
+
default: 'SAMEORIGIN',
|
|
356
|
+
description: "X-Frame-Options of HTML documents (old browsers; CSP frame-ancestors 'self' is the modern one). false: none",
|
|
357
|
+
}),
|
|
358
|
+
referrerPolicy: o.union([
|
|
359
|
+
o.enum([
|
|
360
|
+
'no-referrer',
|
|
361
|
+
'no-referrer-when-downgrade',
|
|
362
|
+
'origin',
|
|
363
|
+
'origin-when-cross-origin',
|
|
364
|
+
'same-origin',
|
|
365
|
+
'strict-origin',
|
|
366
|
+
'strict-origin-when-cross-origin',
|
|
367
|
+
'unsafe-url',
|
|
368
|
+
]),
|
|
369
|
+
o.literal(false),
|
|
370
|
+
], {
|
|
371
|
+
reloadable: true,
|
|
372
|
+
default: 'strict-origin-when-cross-origin',
|
|
373
|
+
description: 'Referrer-Policy of HTML documents. false: none',
|
|
374
|
+
}),
|
|
375
|
+
crossOriginOpenerPolicy: o.union([o.enum(['same-origin', 'same-origin-allow-popups', 'unsafe-none']), o.literal(false)], {
|
|
376
|
+
reloadable: true,
|
|
377
|
+
default: 'same-origin-allow-popups',
|
|
378
|
+
description: 'Cross-Origin-Opener-Policy of HTML documents, over HTTPS only (same-origin-allow-popups keeps windows the page opens, such as a payment or sign-in popup, connected). false: none',
|
|
379
|
+
}),
|
|
380
|
+
crossOriginResourcePolicy: o.union([o.enum(['same-origin', 'same-site', 'cross-origin']), o.literal(false)], {
|
|
381
|
+
reloadable: true,
|
|
382
|
+
default: 'same-site',
|
|
383
|
+
description: 'Cross-Origin-Resource-Policy of HTML documents (same-site: the hosts of one site, the apps of @dokebi/app included). false: none',
|
|
384
|
+
}),
|
|
385
|
+
contentTypeOptions: o.boolean({
|
|
386
|
+
reloadable: true,
|
|
387
|
+
default: true,
|
|
388
|
+
description: 'X-Content-Type-Options: nosniff on every answer',
|
|
389
|
+
}),
|
|
390
|
+
}, {
|
|
391
|
+
default: {
|
|
392
|
+
enabled: true,
|
|
393
|
+
contentSecurityPolicy: { directives: {}, reportOnly: false },
|
|
394
|
+
strictTransportSecurity: { maxAgeSec: 31536000, includeSubDomains: true, preload: false },
|
|
395
|
+
frameOptions: 'SAMEORIGIN',
|
|
396
|
+
referrerPolicy: 'strict-origin-when-cross-origin',
|
|
397
|
+
crossOriginOpenerPolicy: 'same-origin-allow-popups',
|
|
398
|
+
crossOriginResourcePolicy: 'same-site',
|
|
399
|
+
contentTypeOptions: true,
|
|
400
|
+
},
|
|
401
|
+
description: 'Security headers (D-0149), on by default. A header a route or plugin already set is kept; a route changes them with config: { securityHeaders: { … } } or turns them off with config: { securityHeaders: false }.',
|
|
402
|
+
}),
|
|
403
|
+
}, {
|
|
404
|
+
checks: [
|
|
405
|
+
{
|
|
406
|
+
path: 'maxRouteBodyBytes',
|
|
407
|
+
message: 'must be at least maxBodyBytes',
|
|
408
|
+
test: (value) => value.maxRouteBodyBytes >= value.maxBodyBytes,
|
|
409
|
+
},
|
|
410
|
+
],
|
|
92
411
|
});
|
package/dist/points.d.ts
CHANGED
|
@@ -1,4 +1,6 @@
|
|
|
1
|
+
import { type Contribution, DokebiError, type OptionNode } from '@dokebi/core';
|
|
1
2
|
import type { FastifyRequest } from 'fastify';
|
|
3
|
+
export { BEFORE_HIJACK, beforeHijackSteps, runBeforeHijack, type WebBeforeHijackStep, } from './before-hijack.js';
|
|
2
4
|
/**
|
|
3
5
|
* A view engine (`dokebi-web:view-engine`): template-ejs contributes `{ name: 'ejs' }`,
|
|
4
6
|
* template-inertia `{ name: 'inertia' }`. `scope` gives the renderer of one app or module; the
|
|
@@ -47,7 +49,164 @@ export interface WebRealtimeTransport<TRoute = unknown, THandle = unknown> {
|
|
|
47
49
|
/** The operations on one namespace. */
|
|
48
50
|
handle(namespace: string): THandle;
|
|
49
51
|
}
|
|
52
|
+
/**
|
|
53
|
+
* Data a plugin adds to every rendered page (`dokebi-web:view-data`, D-0076 §5): dokebi-csrf adds
|
|
54
|
+
* `csrf`, dokebi-auth adds `auth`. dokebi-app puts it in the EJS data (`data.<key>`) and
|
|
55
|
+
* template-inertia in the shared props (`<key>`), under the app's own shared data and the page
|
|
56
|
+
* data. `value` runs once per render, only when a page is rendered (JSON routes never call it).
|
|
57
|
+
*/
|
|
58
|
+
export interface WebViewData {
|
|
59
|
+
/** The name the value appears under. Two contributors with the same key refuse the setup. */
|
|
60
|
+
readonly key: string;
|
|
61
|
+
/** The value for one request; may be a Promise. Must not throw for an ordinary request. */
|
|
62
|
+
value(request: FastifyRequest): unknown;
|
|
63
|
+
}
|
|
64
|
+
/**
|
|
65
|
+
* Turns an unhandled error into a coded one (`dokebi-web:error-translator`, D-0093): dokebi-db
|
|
66
|
+
* contributes one that asks its adapters' `classifyError` (a unique violation → 409
|
|
67
|
+
* DB_CONFLICT). dokebi-web asks every contribution in setup order, only for an error that would
|
|
68
|
+
* otherwise answer 500: an uncoded error (no Fastify 4xx), or a Dokebi error answering 500 (a
|
|
69
|
+
* plugin's coded failure around a driver error, such as a failed auth hook, or a plugin's own
|
|
70
|
+
* error its translator knows, such as a Redis QUEUE_FULL, D-0102), which only a 5xx translation
|
|
71
|
+
* replaces. The first Dokebi error returned is answered instead,
|
|
72
|
+
* through the normal path (status, JSON or HTML, `errorBody`, the error responders). It is logged
|
|
73
|
+
* at error with the whole thrown value as its cause (`WEB_ERROR_TRANSLATED`).
|
|
74
|
+
*/
|
|
75
|
+
export interface WebErrorTranslator {
|
|
76
|
+
/**
|
|
77
|
+
* The Dokebi error to answer with (put `error` in its `cause`; no driver text, values or
|
|
78
|
+
* constraint names in its message, hint or data), or undefined to pass. Synchronous and cheap;
|
|
79
|
+
* a numeric `data.retryAfterMs` also sets `Retry-After` (seconds, rounded up). A translator
|
|
80
|
+
* that throws or returns anything else is logged (`WEB_ERROR_TRANSLATOR_FAILED`) and skipped.
|
|
81
|
+
*/
|
|
82
|
+
translate(error: unknown, request: FastifyRequest): DokebiError | undefined;
|
|
83
|
+
}
|
|
50
84
|
/** `dokebi-web:view-engine`: template engines an app can render with. */
|
|
51
85
|
export declare const viewEngines: import("@dokebi/core").ContributionPoint<WebViewEngine<unknown, unknown>>;
|
|
52
86
|
/** `dokebi-web:realtime`: realtime transports an app can mount routes on. */
|
|
53
87
|
export declare const realtime: import("@dokebi/core").ContributionPoint<WebRealtimeTransport<unknown, unknown>>;
|
|
88
|
+
/** `dokebi-web:view-data`: values plugins add to every rendered page (EJS data, Inertia props). */
|
|
89
|
+
export declare const viewData: import("@dokebi/core").ContributionPoint<WebViewData>;
|
|
90
|
+
/** `dokebi-web:error-translator`: what an unhandled error means, asked before the 500 (D-0093). */
|
|
91
|
+
export declare const errorTranslators: import("@dokebi/core").ContributionPoint<WebErrorTranslator>;
|
|
92
|
+
/** The view data of one collector: the keys, and the values of a request. */
|
|
93
|
+
export interface WebViewDataCollection {
|
|
94
|
+
/** Contributed keys in setup order; empty when nothing was contributed (then `values` is never needed). */
|
|
95
|
+
readonly keys: readonly string[];
|
|
96
|
+
/** Every contributor's value for this request, computed together. */
|
|
97
|
+
values(request: FastifyRequest): Promise<Record<string, unknown>>;
|
|
98
|
+
}
|
|
99
|
+
/**
|
|
100
|
+
* Checks the contributions of `dokebi-web:view-data` for one collector (dokebi-app for EJS,
|
|
101
|
+
* template-inertia for props): a valid key and a `value` function each, no key twice and none of
|
|
102
|
+
* the collector's own `reserved` keys. Throws VIEW_DATA_CONFLICT (a setup error) otherwise.
|
|
103
|
+
*/
|
|
104
|
+
export declare function collectViewData(contributions: readonly Contribution<WebViewData>[], collector: {
|
|
105
|
+
readonly plugin: string;
|
|
106
|
+
readonly reserved: readonly string[];
|
|
107
|
+
}): WebViewDataCollection;
|
|
108
|
+
/** An app name, as @dokebi/app defines it (D-0132: the `app` of a route or a plugin option). */
|
|
109
|
+
export declare const APP_NAME: RegExp;
|
|
110
|
+
/** App names of one route or option at most. */
|
|
111
|
+
export declare const APP_NAMES_MAX = 64;
|
|
112
|
+
/** The `app` of a route, or the `<plugin>.app` option: one app name or several. */
|
|
113
|
+
export type WebAppSetting = string | readonly string[];
|
|
114
|
+
/**
|
|
115
|
+
* The shared `app` option of a plugin that adds routes (D-0132): `app: mcp` or
|
|
116
|
+
* `app: [studio, admin]`, the apps of @dokebi/app whose hosts answer the plugin's routes. Leave
|
|
117
|
+
* it out and the routes answer on every host. Put it in the plugin's `defineOptions` shape
|
|
118
|
+
* (`app: appOption('The apps whose hosts answer /mcp …')`) and pass the value as the `app` of
|
|
119
|
+
* each route; dokebi-web does the rest at boot.
|
|
120
|
+
*/
|
|
121
|
+
export declare function appOption(description: string): OptionNode<string | readonly string[], "optional">;
|
|
122
|
+
/**
|
|
123
|
+
* What @dokebi/app gives dokebi-web (`web.appRouting`, setup only, once): the constraint of its
|
|
124
|
+
* routes and the host map, for the routes other plugins bind to apps.
|
|
125
|
+
*/
|
|
126
|
+
export interface WebAppRouting {
|
|
127
|
+
/** The Fastify constraint name of app routes (`dokebiApp`). Its strategy takes one app name or a list. */
|
|
128
|
+
readonly constraint: string;
|
|
129
|
+
/** Every defined app. */
|
|
130
|
+
readonly names: readonly string[];
|
|
131
|
+
/** The app a configured domain points at (lower case, no port, no trailing dot), or undefined. */
|
|
132
|
+
domainApp(host: string): string | undefined;
|
|
133
|
+
/** The configured domains of an app. */
|
|
134
|
+
domainsOf(app: string): readonly string[];
|
|
135
|
+
/** The app that answers hosts no domain names (dokebi-app `unknownDomain`), or undefined. */
|
|
136
|
+
readonly fallback: string | undefined;
|
|
137
|
+
}
|
|
138
|
+
/** Where a URL a plugin publishes lands, compared with the apps that serve it (`appUrlMatch`). */
|
|
139
|
+
export type WebAppUrlMatch =
|
|
140
|
+
/** Its host is a domain of one of the apps (or no routing / no binding: nothing to check). */
|
|
141
|
+
{
|
|
142
|
+
readonly kind: 'ok';
|
|
143
|
+
}
|
|
144
|
+
/** Its host is a configured domain of another app: the URL leads to a 404. */
|
|
145
|
+
| {
|
|
146
|
+
readonly kind: 'other-app';
|
|
147
|
+
readonly host: string;
|
|
148
|
+
readonly app: string;
|
|
149
|
+
}
|
|
150
|
+
/** Its host is not a configured domain (a proxy may map it): `fallback` answers it, if any. */
|
|
151
|
+
| {
|
|
152
|
+
readonly kind: 'unconfigured';
|
|
153
|
+
readonly host: string;
|
|
154
|
+
readonly fallback: string | undefined;
|
|
155
|
+
};
|
|
156
|
+
/**
|
|
157
|
+
* Where `url` lands for routes bound to `apps` (D-0132): plugins that publish their own URLs
|
|
158
|
+
* (an OAuth issuer, a resource URI) check them at boot. `ok` when nothing is bound, there is
|
|
159
|
+
* no routing yet, or an app is unknown (the binding itself refuses that).
|
|
160
|
+
*/
|
|
161
|
+
export declare function appUrlMatch(routing: WebAppRouting | undefined, url: string, apps: readonly string[] | undefined): WebAppUrlMatch;
|
|
162
|
+
/** A route id (D-0077 A): `API-12`, `posts.index`, `mcp.endpoint`. */
|
|
163
|
+
export declare const ROUTE_ID: RegExp;
|
|
164
|
+
/**
|
|
165
|
+
* The owner mark on the `config` of a route a plugin adds itself (D-0142), a registered symbol:
|
|
166
|
+
* a plugin that does not import this module (@dokebi/seal, @dokebi/mail) writes
|
|
167
|
+
* `Symbol.for('dokebi-web:route-owner')` and means the same. Its value is a `WebRouteOwner`.
|
|
168
|
+
* dokebi-web reads it at onRoute: `web.routes()` and describe name the plugin, and the duplicate
|
|
169
|
+
* route id check names both owners. A symbol key is no config key (never checked or listed).
|
|
170
|
+
*/
|
|
171
|
+
export declare const ROUTE_OWNER: symbol;
|
|
172
|
+
/** Who added a route (D-0142): the plugin, and the key of its `routeIds` option. */
|
|
173
|
+
export interface WebRouteOwner {
|
|
174
|
+
/** The plugin id, for example `dokebi-mcp`. */
|
|
175
|
+
readonly plugin: string;
|
|
176
|
+
/** The route key of `options.<plugin>.routeIds`, for example `endpoint`. */
|
|
177
|
+
readonly key: string;
|
|
178
|
+
}
|
|
179
|
+
/** `dokebi-mcp` → `mcp`: the namespace of a plugin's default route ids (D-0142). */
|
|
180
|
+
export declare function routeNamespace(plugin: string): string;
|
|
181
|
+
/**
|
|
182
|
+
* The shared `routeIds` option of a plugin that adds routes itself (D-0142): one optional key per
|
|
183
|
+
* route role, whose value replaces the default id `<namespace>.<key>` of those routes
|
|
184
|
+
* (`options.dokebi-mcp.routeIds: { endpoint: ai.mcp }`). Other keys are refused like any unknown
|
|
185
|
+
* option, and values follow the rule of a route `config.id`. `routes` says, per key, which
|
|
186
|
+
* routes it names. Put it in the plugin's `defineOptions` shape as `routeIds` and pass the value
|
|
187
|
+
* to `pluginRouteIds`.
|
|
188
|
+
*/
|
|
189
|
+
export declare function routeIdsOption<const K extends string>(plugin: string, routes: Readonly<Record<K, string>>): OptionNode<{
|
|
190
|
+
readonly [P in K]?: string;
|
|
191
|
+
}, 'optional'>;
|
|
192
|
+
/** The ids of a plugin's own routes, and the `config` that carries one (D-0142). */
|
|
193
|
+
export interface WebPluginRouteIds<K extends string> {
|
|
194
|
+
/** The id of each route key: the `routeIds` value, or `<namespace>.<key>`. */
|
|
195
|
+
readonly ids: Readonly<Record<K, string>>;
|
|
196
|
+
/**
|
|
197
|
+
* The `config` of a route of `key`: `extra` with `id` and the owner mark. A new object each
|
|
198
|
+
* call (one per route).
|
|
199
|
+
*/
|
|
200
|
+
config<C extends object = Record<never, never>>(key: K, extra?: C): C & {
|
|
201
|
+
readonly id: string;
|
|
202
|
+
};
|
|
203
|
+
}
|
|
204
|
+
/**
|
|
205
|
+
* Resolves the ids of a plugin's own routes (D-0142). `overrides` is the parsed `routeIds`
|
|
206
|
+
* option; a key outside `keys` is INVALID_ARGUMENT (the option schema already refuses it). The
|
|
207
|
+
* ids are checked by dokebi-web at start like every route id (INVALID_ROUTE_CONFIG,
|
|
208
|
+
* DUPLICATE_ROUTE_ID), so a plugin never checks them itself.
|
|
209
|
+
*/
|
|
210
|
+
export declare function pluginRouteIds<const K extends string>(plugin: string, keys: readonly K[], overrides?: Readonly<Partial<Record<K, string>>>): WebPluginRouteIds<K>;
|
|
211
|
+
/** The owner mark of a route config, when it carries a valid one (read by dokebi-web). */
|
|
212
|
+
export declare function routeOwnerOf(config: unknown): WebRouteOwner | undefined;
|