@dokebi/web 0.4.2 → 0.4.3

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.
Files changed (46) hide show
  1. package/AI.md +248 -39
  2. package/README.md +31 -10
  3. package/dist/app-routes.d.ts +20 -0
  4. package/dist/app-routes.js +137 -0
  5. package/dist/before-hijack.d.ts +24 -0
  6. package/dist/before-hijack.js +73 -0
  7. package/dist/body.d.ts +14 -0
  8. package/dist/body.js +30 -0
  9. package/dist/cluster-ready.d.ts +67 -0
  10. package/dist/cluster-ready.js +123 -0
  11. package/dist/compilers.d.ts +16 -0
  12. package/dist/compilers.js +25 -0
  13. package/dist/compression.d.ts +40 -0
  14. package/dist/compression.js +435 -0
  15. package/dist/connections.d.ts +44 -0
  16. package/dist/connections.js +282 -0
  17. package/dist/define-errors.d.ts +76 -0
  18. package/dist/define-errors.js +161 -0
  19. package/dist/describe.d.ts +37 -0
  20. package/dist/describe.js +96 -0
  21. package/dist/errors.d.ts +1 -1
  22. package/dist/errors.js +24 -3
  23. package/dist/forms.d.ts +23 -7
  24. package/dist/forms.js +53 -13
  25. package/dist/index.d.ts +134 -4
  26. package/dist/index.js +1518 -91
  27. package/dist/options.d.ts +56 -0
  28. package/dist/options.js +320 -1
  29. package/dist/points.d.ts +159 -0
  30. package/dist/points.js +162 -1
  31. package/dist/responses.d.ts +31 -6
  32. package/dist/responses.js +68 -6
  33. package/dist/route-config.d.ts +38 -0
  34. package/dist/route-config.js +222 -0
  35. package/dist/route-hooks.d.ts +75 -0
  36. package/dist/route-hooks.js +118 -0
  37. package/dist/route-table.d.ts +55 -0
  38. package/dist/route-table.js +142 -0
  39. package/dist/seal.d.ts +49 -1
  40. package/dist/seal.js +259 -24
  41. package/dist/security-headers.d.ts +121 -0
  42. package/dist/security-headers.js +298 -0
  43. package/dist/transient-log.d.ts +42 -0
  44. package/dist/transient-log.js +95 -0
  45. package/options.schema.json +488 -1
  46. package/package.json +22 -9
@@ -0,0 +1,298 @@
1
+ // Security headers (D-0149), on by default. Every answer gets `X-Content-Type-Options: nosniff`
2
+ // (and `Strict-Transport-Security` when the request came over HTTPS, a trusted proxy's
3
+ // X-Forwarded-Proto included); an HTML document also gets the Content-Security-Policy,
4
+ // X-Frame-Options, Referrer-Policy and Cross-Origin-Resource-Policy, and over HTTPS also the
5
+ // Cross-Origin-Opener-Policy (browsers ignore it, with a console error, on plain HTTP).
6
+ //
7
+ // The values are built once, at the first answer of a route after the start (the options, the
8
+ // route's `config.securityHeaders` and what plugins added with `web.contentSecurityPolicy` are
9
+ // final then), and set with one `reply.header` each; a header the handler or a plugin already set
10
+ // is kept (the sandboxing CSP of storage downloads, the dev mail inbox, the OAuth consent page).
11
+ // Measured on the hello JSON route (decision §2): @fastify/helmet, which builds helmet's
12
+ // middleware for every request and sets a dozen headers on every answer, answered at 0.71 of
13
+ // Fastify; this split at 0.99.
14
+ /** The CSP of an HTML page unless options or the route change it (decision §3). */
15
+ export const DEFAULT_DIRECTIVES = Object.freeze({
16
+ 'default-src': ["'self'"],
17
+ 'base-uri': ["'self'"],
18
+ 'object-src': ["'none'"],
19
+ 'frame-ancestors': ["'self'"],
20
+ 'script-src': ["'self'", "'unsafe-inline'"],
21
+ 'style-src': ["'self'", "'unsafe-inline'", 'https:'],
22
+ 'img-src': ["'self'", 'data:', 'blob:', 'https:'],
23
+ 'font-src': ["'self'", 'data:', 'https:'],
24
+ 'connect-src': ["'self'"],
25
+ });
26
+ /** A CSP directive name: lower case letters and `-`. */
27
+ export const DIRECTIVE = /^[a-z][a-z-]{1,63}$/;
28
+ /** One CSP source or keyword: no white space, `;` or `,` (they would end it). */
29
+ export const SOURCE = /^[^\s;,]{1,512}$/;
30
+ const FRAME = new Set(['DENY', 'SAMEORIGIN']);
31
+ const REFERRER = new Set([
32
+ 'no-referrer',
33
+ 'no-referrer-when-downgrade',
34
+ 'origin',
35
+ 'origin-when-cross-origin',
36
+ 'same-origin',
37
+ 'strict-origin',
38
+ 'strict-origin-when-cross-origin',
39
+ 'unsafe-url',
40
+ ]);
41
+ const OPENER = new Set(['same-origin', 'same-origin-allow-popups', 'unsafe-none']);
42
+ const RESOURCE = new Set(['same-origin', 'same-site', 'cross-origin']);
43
+ const ROUTE_KEYS = new Set([
44
+ 'contentSecurityPolicy',
45
+ 'strictTransportSecurity',
46
+ 'frameOptions',
47
+ 'referrerPolicy',
48
+ 'crossOriginOpenerPolicy',
49
+ 'crossOriginResourcePolicy',
50
+ 'contentTypeOptions',
51
+ ]);
52
+ function plain(value) {
53
+ return value !== null && typeof value === 'object' && !Array.isArray(value);
54
+ }
55
+ /** The problem of a directives map, or undefined. */
56
+ function directivesProblem(value, flagFalse) {
57
+ if (!plain(value))
58
+ return 'directives must be an object of directive name to a list of sources';
59
+ for (const [name, sources] of Object.entries(value)) {
60
+ if (!DIRECTIVE.test(name))
61
+ return `${name} is not a CSP directive name (lower case, a-z and -)`;
62
+ if (sources === false && flagFalse)
63
+ continue;
64
+ if (!Array.isArray(sources) ||
65
+ sources.some((item) => typeof item !== 'string' || !SOURCE.test(item)))
66
+ return `${name} must be a list of sources without white space, ';' or ','${flagFalse ? ', or false' : ''}`;
67
+ }
68
+ return undefined;
69
+ }
70
+ /** The problem of a route's `config.securityHeaders` value, or undefined (checked at start). */
71
+ export function securityHeadersProblem(value) {
72
+ if (value === false)
73
+ return undefined;
74
+ if (!plain(value))
75
+ return 'must be false (no security header on this route) or an object of the securityHeaders options to change';
76
+ for (const [key, item] of Object.entries(value)) {
77
+ if (!ROUTE_KEYS.has(key))
78
+ return `${key} is not a security header setting (${[...ROUTE_KEYS].join(', ')})`;
79
+ if (item === false && key !== 'contentTypeOptions')
80
+ continue;
81
+ switch (key) {
82
+ case 'contentSecurityPolicy': {
83
+ if (!plain(item))
84
+ return 'contentSecurityPolicy must be false or { directives?, reportOnly? }';
85
+ for (const field of Object.keys(item))
86
+ if (field !== 'directives' && field !== 'reportOnly')
87
+ return `contentSecurityPolicy.${field} is not a setting (directives, reportOnly)`;
88
+ if (item.reportOnly !== undefined && typeof item.reportOnly !== 'boolean')
89
+ return 'contentSecurityPolicy.reportOnly must be true or false';
90
+ if (item.directives !== undefined) {
91
+ const problem = directivesProblem(item.directives, true);
92
+ if (problem)
93
+ return `contentSecurityPolicy.${problem}`;
94
+ }
95
+ break;
96
+ }
97
+ case 'strictTransportSecurity':
98
+ return 'strictTransportSecurity takes only false on a route (its max-age is the options one)';
99
+ case 'frameOptions':
100
+ if (!FRAME.has(item))
101
+ return 'frameOptions must be DENY, SAMEORIGIN or false';
102
+ break;
103
+ case 'referrerPolicy':
104
+ if (!REFERRER.has(item))
105
+ return `referrerPolicy must be one of ${[...REFERRER].join(', ')} or false`;
106
+ break;
107
+ case 'crossOriginOpenerPolicy':
108
+ if (!OPENER.has(item))
109
+ return `crossOriginOpenerPolicy must be one of ${[...OPENER].join(', ')} or false`;
110
+ break;
111
+ case 'crossOriginResourcePolicy':
112
+ if (!RESOURCE.has(item))
113
+ return `crossOriginResourcePolicy must be one of ${[...RESOURCE].join(', ')} or false`;
114
+ break;
115
+ case 'contentTypeOptions':
116
+ if (typeof item !== 'boolean')
117
+ return 'contentTypeOptions must be true or false';
118
+ break;
119
+ }
120
+ }
121
+ return undefined;
122
+ }
123
+ /** The problem of a `web.contentSecurityPolicy` contribution, or undefined. */
124
+ export function contributionProblem(value) {
125
+ if (!plain(value) || typeof value.plugin !== 'string' || value.plugin === '')
126
+ return "pass { plugin: 'dokebi-…', directives: { 'connect-src': ['…'] } }";
127
+ return directivesProblem(value.directives, false);
128
+ }
129
+ const EMPTY = Object.freeze({
130
+ always: [],
131
+ document: [],
132
+ hsts: undefined,
133
+ opener: undefined,
134
+ });
135
+ /** The serialized CSP: `name sources; …` in the order of the merged directives. */
136
+ export function serializePolicy(directives) {
137
+ return Object.entries(directives)
138
+ .map(([name, sources]) => (sources.length ? `${name} ${sources.join(' ')}` : name))
139
+ .join('; ');
140
+ }
141
+ /** The merged directives: defaults, then the changes (options, then route), then contributions. */
142
+ export function mergeDirectives(changes, contributions) {
143
+ const merged = { ...DEFAULT_DIRECTIVES };
144
+ for (const change of changes)
145
+ for (const [name, sources] of Object.entries(change ?? {}))
146
+ if (sources === false)
147
+ delete merged[name];
148
+ else
149
+ merged[name] = [...sources];
150
+ for (const { directives } of contributions)
151
+ for (const [name, sources] of Object.entries(directives)) {
152
+ // A fetch directive that is not set falls back to default-src: keep that fallback.
153
+ const base = merged[name] ?? (name.endsWith('-src') ? (merged['default-src'] ?? []) : []);
154
+ merged[name] = [...new Set([...base, ...sources])];
155
+ }
156
+ return merged;
157
+ }
158
+ /** The answer of one route: the policy built at its first answer after the start. */
159
+ export class RouteSecurity {
160
+ owner;
161
+ override;
162
+ #built;
163
+ /** The options generation `#built` was made from (D-0154: a reload makes a new one). */
164
+ #generation = -1;
165
+ constructor(owner, override) {
166
+ this.owner = owner;
167
+ this.override = override;
168
+ }
169
+ get built() {
170
+ if (this.#built && this.#generation === this.owner.generation)
171
+ return this.#built;
172
+ const built = this.owner.build(this.override);
173
+ // Before the start (a 503 while starting) contributions may still come: not kept.
174
+ if (this.owner.frozen) {
175
+ this.#built = built;
176
+ this.#generation = this.owner.generation;
177
+ }
178
+ return built;
179
+ }
180
+ }
181
+ export class SecurityHeaders {
182
+ #options;
183
+ /** Bumped by `update`: every route builds its headers again at its next answer. */
184
+ generation = 0;
185
+ #contributions = [];
186
+ #frozen = false;
187
+ /** The policy of routes without an override and of answers without a route (404). */
188
+ defaults;
189
+ constructor(options) {
190
+ this.#options = options;
191
+ this.defaults = new RouteSecurity(this, undefined);
192
+ }
193
+ get enabled() {
194
+ return this.#options.enabled;
195
+ }
196
+ /**
197
+ * D-0154: reloaded header values. `enabled` stays as it was at start (the route steps exist
198
+ * only when it was on); the headers of every route are built again at their next answer.
199
+ */
200
+ update(options) {
201
+ this.#options = { ...options, enabled: this.#options.enabled };
202
+ this.generation++;
203
+ }
204
+ /** Setup only (web freezes it at start). */
205
+ contribute(contribution) {
206
+ this.#contributions.push(Object.freeze({
207
+ plugin: contribution.plugin,
208
+ directives: Object.freeze(Object.fromEntries(Object.entries(contribution.directives).map(([name, list]) => [
209
+ name,
210
+ Object.freeze([...list]),
211
+ ]))),
212
+ }));
213
+ }
214
+ /** At start: contributions are final, policies may be built. */
215
+ freeze() {
216
+ this.#frozen = true;
217
+ }
218
+ get frozen() {
219
+ return this.#frozen;
220
+ }
221
+ get contributions() {
222
+ return this.#contributions;
223
+ }
224
+ /** The policy of a route (its `config.securityHeaders`, already checked). */
225
+ route(override) {
226
+ return override === undefined
227
+ ? this.defaults
228
+ : new RouteSecurity(this, override);
229
+ }
230
+ /** The headers of the options with a route override. */
231
+ build(override) {
232
+ const options = this.#options;
233
+ if (!options.enabled || override === false)
234
+ return EMPTY;
235
+ const pick = (key) => (override?.[key] !== undefined ? override[key] : options[key]);
236
+ const always = [];
237
+ if (pick('contentTypeOptions'))
238
+ always.push(['x-content-type-options', 'nosniff']);
239
+ const document = [];
240
+ const csp = override?.contentSecurityPolicy === false ? false : options.contentSecurityPolicy;
241
+ if (csp !== false) {
242
+ const routeCsp = override?.contentSecurityPolicy || undefined;
243
+ const directives = mergeDirectives([csp.directives, routeCsp?.directives], this.#contributions);
244
+ const reportOnly = routeCsp?.reportOnly ?? csp.reportOnly;
245
+ document.push([
246
+ reportOnly ? 'content-security-policy-report-only' : 'content-security-policy',
247
+ serializePolicy(directives),
248
+ ]);
249
+ }
250
+ const frame = pick('frameOptions');
251
+ if (frame)
252
+ document.push(['x-frame-options', frame]);
253
+ const referrer = pick('referrerPolicy');
254
+ if (referrer)
255
+ document.push(['referrer-policy', referrer]);
256
+ const opener = pick('crossOriginOpenerPolicy') || undefined;
257
+ const resource = pick('crossOriginResourcePolicy');
258
+ if (resource)
259
+ document.push(['cross-origin-resource-policy', resource]);
260
+ const sts = override?.strictTransportSecurity === false ? false : options.strictTransportSecurity;
261
+ const hsts = sts
262
+ ? `max-age=${sts.maxAgeSec}${sts.includeSubDomains ? '; includeSubDomains' : ''}${sts.preload ? '; preload' : ''}`
263
+ : undefined;
264
+ return Object.freeze({
265
+ always: Object.freeze(always.map((pair) => Object.freeze(pair))),
266
+ document: Object.freeze(document.map((pair) => Object.freeze(pair))),
267
+ hsts,
268
+ opener,
269
+ });
270
+ }
271
+ /**
272
+ * The onSend step: the headers of `policy` that the reply does not have yet. `request.protocol`
273
+ * (it follows trustProxy) is read only for HSTS and only when it is on.
274
+ */
275
+ apply(policy, request, reply) {
276
+ const built = policy.built;
277
+ for (const [name, value] of built.always)
278
+ if (!reply.hasHeader(name))
279
+ reply.header(name, value);
280
+ let page = false;
281
+ if (built.document.length || built.opener !== undefined) {
282
+ const type = reply.getHeader('content-type');
283
+ page = typeof type === 'string' && type.startsWith('text/html');
284
+ if (page)
285
+ for (const [name, value] of built.document)
286
+ if (!reply.hasHeader(name))
287
+ reply.header(name, value);
288
+ }
289
+ if (built.hsts === undefined && !(page && built.opener !== undefined))
290
+ return;
291
+ if (request.protocol !== 'https')
292
+ return;
293
+ if (built.hsts !== undefined && !reply.hasHeader('strict-transport-security'))
294
+ reply.header('strict-transport-security', built.hsts);
295
+ if (page && built.opener !== undefined && !reply.hasHeader('cross-origin-opener-policy'))
296
+ reply.header('cross-origin-opener-policy', built.opener);
297
+ }
298
+ }
@@ -0,0 +1,42 @@
1
+ import type { LogFields, Logger } from '@dokebi/core';
2
+ /** The levels the transient error log may use (`transientLogLevel`). */
3
+ export type TransientLogLevel = 'error' | 'warn';
4
+ export interface TransientLogSettings {
5
+ readonly logger: Pick<Logger, 'log' | 'isEnabled'>;
6
+ /** `transientLogWindowMs`: how long one window counts. */
7
+ readonly windowMs: number;
8
+ /** `transientLogMaxKeys`: distinct keys one window logs in full. */
9
+ readonly maxKeys: number;
10
+ /** `transientLogLevel`: of the first records and the summaries. */
11
+ readonly level: TransientLogLevel;
12
+ }
13
+ /**
14
+ * D-0113: the error log of retryable 503s (a translated error, or a 503 with `Retry-After`).
15
+ * Under a burst every refused request is the same expected failure; a full stack for each one
16
+ * (AI-M25: 193,466 records, about 200 MB in 65 s) makes the overload worse and rotates every
17
+ * other log out. Like the event bus (`Repeats.pass` + `onRepeats`):
18
+ *
19
+ * - The first occurrence of a key (error code, method, route, status) in a window is logged in
20
+ * full by the caller (`first` returns true).
21
+ * - Later ones in the window are counted; when the window ends, or at `flush()` (close), one
22
+ * `WEB_TRANSIENT_REPEATED` line per key gives the exact count (`repeated`).
23
+ * - Past `maxKeys` distinct keys in one window, new keys are only counted, in one
24
+ * `WEB_TRANSIENT_REPEATED` line with `overflow: true`: the lines of a window stay bounded.
25
+ *
26
+ * One timer per window (unref'd), opened by the first occurrence; nothing runs while quiet.
27
+ */
28
+ export declare class TransientLog {
29
+ #private;
30
+ readonly windowMs: number;
31
+ readonly maxKeys: number;
32
+ readonly level: TransientLogLevel;
33
+ constructor(settings: TransientLogSettings);
34
+ /**
35
+ * True when this occurrence opens its key in the window: the caller logs it in full. False:
36
+ * it was counted for the window's summary. `fields` is read only for a new key; `level` is the
37
+ * level of its summary (default: the window's).
38
+ */
39
+ first(key: string, fields: () => LogFields, level?: TransientLogLevel): boolean;
40
+ /** Ends the window now: one summary line per key that repeated, and one for the overflow. */
41
+ flush(): void;
42
+ }
@@ -0,0 +1,95 @@
1
+ /**
2
+ * D-0113: the error log of retryable 503s (a translated error, or a 503 with `Retry-After`).
3
+ * Under a burst every refused request is the same expected failure; a full stack for each one
4
+ * (AI-M25: 193,466 records, about 200 MB in 65 s) makes the overload worse and rotates every
5
+ * other log out. Like the event bus (`Repeats.pass` + `onRepeats`):
6
+ *
7
+ * - The first occurrence of a key (error code, method, route, status) in a window is logged in
8
+ * full by the caller (`first` returns true).
9
+ * - Later ones in the window are counted; when the window ends, or at `flush()` (close), one
10
+ * `WEB_TRANSIENT_REPEATED` line per key gives the exact count (`repeated`).
11
+ * - Past `maxKeys` distinct keys in one window, new keys are only counted, in one
12
+ * `WEB_TRANSIENT_REPEATED` line with `overflow: true`: the lines of a window stay bounded.
13
+ *
14
+ * One timer per window (unref'd), opened by the first occurrence; nothing runs while quiet.
15
+ */
16
+ export class TransientLog {
17
+ windowMs;
18
+ maxKeys;
19
+ level;
20
+ #logger;
21
+ #keys = new Map();
22
+ /** Occurrences of keys past maxKeys in this window. */
23
+ #overflow = 0;
24
+ #timer;
25
+ constructor(settings) {
26
+ this.#logger = settings.logger;
27
+ this.windowMs = settings.windowMs;
28
+ this.maxKeys = settings.maxKeys;
29
+ this.level = settings.level;
30
+ }
31
+ /**
32
+ * True when this occurrence opens its key in the window: the caller logs it in full. False:
33
+ * it was counted for the window's summary. `fields` is read only for a new key; `level` is the
34
+ * level of its summary (default: the window's).
35
+ */
36
+ first(key, fields, level = this.level) {
37
+ const counted = this.#keys.get(key);
38
+ if (counted) {
39
+ counted.repeated++;
40
+ return false;
41
+ }
42
+ this.#open();
43
+ if (this.#keys.size >= this.maxKeys) {
44
+ this.#overflow++;
45
+ return false;
46
+ }
47
+ this.#keys.set(key, { fields: fields(), level, repeated: 0 });
48
+ return true;
49
+ }
50
+ /** Ends the window now: one summary line per key that repeated, and one for the overflow. */
51
+ flush() {
52
+ if (this.#timer !== undefined) {
53
+ clearTimeout(this.#timer);
54
+ this.#timer = undefined;
55
+ }
56
+ const logger = this.#logger;
57
+ let lines = 0;
58
+ for (const counted of this.#keys.values()) {
59
+ if (!counted.repeated)
60
+ continue;
61
+ lines++;
62
+ logger.log(counted.level, 'HTTP transient errors repeated', {
63
+ ...counted.fields,
64
+ code: 'WEB_TRANSIENT_REPEATED',
65
+ repeated: counted.repeated,
66
+ windowMs: this.windowMs,
67
+ });
68
+ }
69
+ if (this.#overflow) {
70
+ lines++;
71
+ logger.log(this.level, 'HTTP transient errors repeated', {
72
+ code: 'WEB_TRANSIENT_REPEATED',
73
+ overflow: true,
74
+ repeated: this.#overflow,
75
+ maxKeys: this.maxKeys,
76
+ windowMs: this.windowMs,
77
+ fix: 'More distinct routes and codes failed in one window than dokebi-web.transientLogMaxKeys: their first records were not written. Raise transientLogMaxKeys to see each one.',
78
+ });
79
+ }
80
+ const keys = this.#keys.size;
81
+ this.#keys.clear();
82
+ this.#overflow = 0;
83
+ if (keys && logger.isEnabled('debug'))
84
+ logger.log('debug', 'Web transient error window closed', { keys, lines });
85
+ }
86
+ #open() {
87
+ if (this.#timer !== undefined)
88
+ return;
89
+ this.#timer = setTimeout(() => {
90
+ this.#timer = undefined;
91
+ this.flush();
92
+ }, this.windowMs);
93
+ this.#timer.unref?.();
94
+ }
95
+ }