@selvajs/server 1.0.0-beta.9 → 1.0.1

package/dist/http/redirect.js

@@ -1,18 +1,18 @@
 /**
- * Validate a user-supplied post-login redirect target. Accepts only same-origin
- * relative paths starting with `/` followed by a non-`/` character, so
- * `//evil.com/path` (protocol-relative URL — browser treats as cross-origin)
- * and `/\evil.com` (back-slash variants some browsers normalize) are rejected.
- *
- * Always returns a safe path: the validated target on success, the fallback
- * otherwise. Routes call this with `redirectTo` from form data or query string.
+ * Validate a user-supplied post-login redirect target (`redirectTo` from form
+ * data or a query string) against open redirects. Returns the target when it is
+ * a same-origin relative path, the fallback otherwise — never a raw target.
  */
 export function safeRedirectTarget(raw, fallback) {
+    // A valid target is `/` plus at least one more character, so the two guards
+    // below always have a real `raw[1]` to inspect.
     if (typeof raw !== 'string' || raw.length < 2)
         return fallback;
+    // Absolute URLs (`https://evil.com`) leave this origin.
     if (raw[0] !== '/')
         return fallback;
-    // Reject protocol-relative (`//host`) and back-slash bypass (`/\host`).
+    // `//evil.com` is protocol-relative — a browser treats it as cross-origin —
+    // and some browsers normalize `/\evil.com` into the same thing.
     if (raw[1] === '/' || raw[1] === '\\')
         return fallback;
     return raw;

package/dist/http/redirect.js.map

@@ -1 +1 @@
-{"version":3,"file":"redirect.js","sourceRoot":"","sources":["../../src/http/redirect.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,UAAU,kBAAkB,CAAC,GAA8B,EAAE,QAAgB;IAClF,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,QAAQ,CAAC;IAC/D,IAAI,GAAG,CAAC,CAAC,CAAC,KAAK,GAAG;QAAE,OAAO,QAAQ,CAAC;IACpC,wEAAwE;IACxE,IAAI,GAAG,CAAC,CAAC,CAAC,KAAK,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC,KAAK,IAAI;QAAE,OAAO,QAAQ,CAAC;IACvD,OAAO,GAAG,CAAC;AACZ,CAAC"}
+{"version":3,"file":"redirect.js","sourceRoot":"","sources":["../../src/http/redirect.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,GAA8B,EAAE,QAAgB;IAClF,4EAA4E;IAC5E,gDAAgD;IAChD,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,QAAQ,CAAC;IAC/D,wDAAwD;IACxD,IAAI,GAAG,CAAC,CAAC,CAAC,KAAK,GAAG;QAAE,OAAO,QAAQ,CAAC;IACpC,4EAA4E;IAC5E,gEAAgE;IAChE,IAAI,GAAG,CAAC,CAAC,CAAC,KAAK,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC,KAAK,IAAI;QAAE,OAAO,QAAQ,CAAC;IACvD,OAAO,GAAG,CAAC;AACZ,CAAC"}

package/dist/http/route-classifier.d.ts

@@ -1,46 +1,42 @@
 /**
- * Deny-by-default route classification. Every request is gated unless its
- * path matches one of the explicit allowlists supplied here — so adding a new
- * top-level route is safe: forgetting to update the lists makes it gated (a
- * loud 401/redirect), not silently public.
+ * Deny-by-default route classification. A request is gated unless its path
+ * matches one of the allowlists supplied here, so forgetting to list a new
+ * route makes it gated — a loud 401/redirect, not silently public.
  *
- * The *pattern* is reusable; the *values* are app policy — a consuming app
- * supplies its own route sets. All matching is plain exact/prefix string
- * comparison: cheap enough for the hooks hot path, and no regex to get wrong.
+ * The pattern is reusable; the values are app policy, supplied by the consuming
+ * app. Matching is plain exact/prefix string comparison: cheap enough for the
+ * hooks hot path, and no regex to get wrong.
  */
 export interface RouteClassifierConfig {
-    /** Exact-match public pages — no session needed (e.g. `/`, `/login`). */
+    /** Exact-match pages needing no session (e.g. `/`, `/login`). */
     publicPages?: Iterable<string>;
-    /**
-     * Public path prefixes (e.g. `/auth/` for OAuth start + callback — the
-     * user has no session yet by definition).
-     */
+    /** Public path prefixes (e.g. `/auth/` — OAuth start and callback precede any session). */
     publicPrefixes?: readonly string[];
     /**
-     * Exact-match API endpoints that must answer without a session (e.g. a
-     * load-balancer health probe). Anything added here must be safe to expose
-     * to anonymous callers.
+     * Exact-match API endpoints that answer without a session (e.g. a
+     * load-balancer health probe). Anything listed here is exposed to anonymous
+     * callers.
      */
     publicApis?: Iterable<string>;
     /**
-     * A single prefix whose routes apply their own per-request authorization
-     * (e.g. a blob proxy classifying each asset path). The hook must NOT deny
-     * these up front; they classify as public (best-effort session attach) and
-     * the route makes the real decision. Keep this to ONE prefix — every other
-     * API route stays deny-by-default.
+     * One prefix whose routes authorize each request themselves (e.g. a blob
+     * proxy classifying per asset path). These classify as public so the hook
+     * attaches a session best-effort and does not deny up front; the route makes
+     * the real decision. Keep it to ONE prefix — every other API route stays
+     * deny-by-default.
      */
     selfGatingPrefix?: string;
-    /** Static-asset path prefixes the adapter serves directly (e.g. `/_app/`). */
+    /** Static-asset prefixes the adapter serves directly (e.g. `/_app/`). */
     staticPrefixes?: readonly string[];
     /** Exact static-asset paths (e.g. `/favicon.svg`, `/robots.txt`). */
     staticPaths?: Iterable<string>;
 }
 export interface RouteClassifier {
-    /** Static assets bypass auth gating; callers may add cache headers. */
+    /** Matches `staticPaths`/`staticPrefixes`. These bypass auth gating entirely. */
     isStaticAsset(pathname: string): boolean;
-    /** True for paths under `selfGatingPrefix` — the route gates itself. */
+    /** Matches `selfGatingPrefix`. The hook must not deny these — the route gates itself. */
     isSelfGatingApiRoute(pathname: string): boolean;
-    /** True when the path needs no session: pages, APIs, prefixes, self-gating. */
+    /** Needs no session: a public page, API, prefix, or a self-gating route. */
     isPublicRoute(pathname: string): boolean;
 }
 export declare function createRouteClassifier(config: RouteClassifierConfig): RouteClassifier;

package/dist/http/route-classifier.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"route-classifier.d.ts","sourceRoot":"","sources":["../../src/http/route-classifier.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,MAAM,WAAW,qBAAqB;IACrC,yEAAyE;IACzE,WAAW,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC/B;;;OAGG;IACH,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC;;;;OAIG;IACH,UAAU,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC9B;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,8EAA8E;IAC9E,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,qEAAqE;IACrE,WAAW,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;CAC/B;AAED,MAAM,WAAW,eAAe;IAC/B,uEAAuE;IACvE,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;IACzC,wEAAwE;IACxE,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;IAChD,+EAA+E;IAC/E,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;CACzC;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,qBAAqB,GAAG,eAAe,CAyBpF"}
+{"version":3,"file":"route-classifier.d.ts","sourceRoot":"","sources":["../../src/http/route-classifier.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,WAAW,qBAAqB;IACrC,iEAAiE;IACjE,WAAW,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC/B,2FAA2F;IAC3F,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC;;;;OAIG;IACH,UAAU,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC9B;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,yEAAyE;IACzE,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,qEAAqE;IACrE,WAAW,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;CAC/B;AAED,MAAM,WAAW,eAAe;IAC/B,iFAAiF;IACjF,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;IACzC,yFAAyF;IACzF,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;IAChD,4EAA4E;IAC5E,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;CACzC;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,qBAAqB,GAAG,eAAe,CAyBpF"}

package/dist/http/route-classifier.js

@@ -1,12 +1,11 @@
 /**
- * Deny-by-default route classification. Every request is gated unless its
- * path matches one of the explicit allowlists supplied here — so adding a new
- * top-level route is safe: forgetting to update the lists makes it gated (a
- * loud 401/redirect), not silently public.
+ * Deny-by-default route classification. A request is gated unless its path
+ * matches one of the allowlists supplied here, so forgetting to list a new
+ * route makes it gated — a loud 401/redirect, not silently public.
  *
- * The *pattern* is reusable; the *values* are app policy — a consuming app
- * supplies its own route sets. All matching is plain exact/prefix string
- * comparison: cheap enough for the hooks hot path, and no regex to get wrong.
+ * The pattern is reusable; the values are app policy, supplied by the consuming
+ * app. Matching is plain exact/prefix string comparison: cheap enough for the
+ * hooks hot path, and no regex to get wrong.
  */
 export function createRouteClassifier(config) {
     const publicPages = new Set(config.publicPages ?? []);

package/dist/http/route-classifier.js.map

@@ -1 +1 @@
-{"version":3,"file":"route-classifier.js","sourceRoot":"","sources":["../../src/http/route-classifier.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAuCH,MAAM,UAAU,qBAAqB,CAAC,MAA6B;IAClE,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC;IACtD,MAAM,cAAc,GAAG,MAAM,CAAC,cAAc,IAAI,EAAE,CAAC;IACnD,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,UAAU,IAAI,EAAE,CAAC,CAAC;IACpD,MAAM,gBAAgB,GAAG,MAAM,CAAC,gBAAgB,CAAC;IACjD,MAAM,cAAc,GAAG,MAAM,CAAC,cAAc,IAAI,EAAE,CAAC;IACnD,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC;IAEtD,SAAS,aAAa,CAAC,QAAgB;QACtC,IAAI,WAAW,CAAC,GAAG,CAAC,QAAQ,CAAC;YAAE,OAAO,IAAI,CAAC;QAC3C,OAAO,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;IAC3D,CAAC;IAED,SAAS,oBAAoB,CAAC,QAAgB;QAC7C,OAAO,gBAAgB,KAAK,SAAS,IAAI,QAAQ,CAAC,UAAU,CAAC,gBAAgB,CAAC,CAAC;IAChF,CAAC;IAED,SAAS,aAAa,CAAC,QAAgB;QACtC,IAAI,WAAW,CAAC,GAAG,CAAC,QAAQ,CAAC;YAAE,OAAO,IAAI,CAAC;QAC3C,IAAI,UAAU,CAAC,GAAG,CAAC,QAAQ,CAAC;YAAE,OAAO,IAAI,CAAC;QAC1C,IAAI,oBAAoB,CAAC,QAAQ,CAAC;YAAE,OAAO,IAAI,CAAC;QAChD,OAAO,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;IAC3D,CAAC;IAED,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,aAAa,EAAE,CAAC;AAC/D,CAAC"}
+{"version":3,"file":"route-classifier.js","sourceRoot":"","sources":["../../src/http/route-classifier.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAoCH,MAAM,UAAU,qBAAqB,CAAC,MAA6B;IAClE,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC;IACtD,MAAM,cAAc,GAAG,MAAM,CAAC,cAAc,IAAI,EAAE,CAAC;IACnD,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,UAAU,IAAI,EAAE,CAAC,CAAC;IACpD,MAAM,gBAAgB,GAAG,MAAM,CAAC,gBAAgB,CAAC;IACjD,MAAM,cAAc,GAAG,MAAM,CAAC,cAAc,IAAI,EAAE,CAAC;IACnD,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC;IAEtD,SAAS,aAAa,CAAC,QAAgB;QACtC,IAAI,WAAW,CAAC,GAAG,CAAC,QAAQ,CAAC;YAAE,OAAO,IAAI,CAAC;QAC3C,OAAO,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;IAC3D,CAAC;IAED,SAAS,oBAAoB,CAAC,QAAgB;QAC7C,OAAO,gBAAgB,KAAK,SAAS,IAAI,QAAQ,CAAC,UAAU,CAAC,gBAAgB,CAAC,CAAC;IAChF,CAAC;IAED,SAAS,aAAa,CAAC,QAAgB;QACtC,IAAI,WAAW,CAAC,GAAG,CAAC,QAAQ,CAAC;YAAE,OAAO,IAAI,CAAC;QAC3C,IAAI,UAAU,CAAC,GAAG,CAAC,QAAQ,CAAC;YAAE,OAAO,IAAI,CAAC;QAC1C,IAAI,oBAAoB,CAAC,QAAQ,CAAC;YAAE,OAAO,IAAI,CAAC;QAChD,OAAO,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;IAC3D,CAAC;IAED,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,aAAa,EAAE,CAAC;AAC/D,CAAC"}

package/dist/http/security-headers.d.ts

@@ -1,31 +1,29 @@
 export interface SecurityHeaderOptions {
     /**
-     * Set `Strict-Transport-Security` — production only. Locking dev
-     * (http://localhost) into HTTPS would brick local development, so the
-     * caller decides what "production" means (e.g. `NODE_ENV`).
+     * Set `Strict-Transport-Security`. Production only — pinning
+     * http://localhost to HTTPS bricks local development. The caller decides
+     * what "production" means (e.g. `NODE_ENV`).
      */
     hsts: boolean;
 }
 /**
- * Apply baseline browser-hardening headers to a response. Cheap wins that
- * don't require UI verification:
+ * Apply baseline browser-hardening headers to a response and return it for
+ * chaining. Each is a cheap win that needs no UI verification:
  *
  *   - X-Content-Type-Options: nosniff — disables MIME sniffing.
- *   - Referrer-Policy: strict-origin-when-cross-origin — strips the path
- *     and query from cross-origin Referer headers; matches modern browser
- *     defaults but pins the behavior in case the default ever drifts.
- *   - Permissions-Policy: opt out of browser APIs Selva-engine apps don't
- *     use, so XSS can't enable them.
- *   - HSTS when `opts.hsts` (production).
+ *   - Referrer-Policy: strict-origin-when-cross-origin — strips path and query
+ *     from cross-origin Referer headers. Matches modern browser defaults, but
+ *     pins the behavior in case a default drifts.
+ *   - Permissions-Policy: opts out of browser APIs Selva-engine apps don't use,
+ *     so XSS can't enable them.
+ *   - HSTS when `opts.hsts`.
  *
  * **Intentionally NOT set here:**
  *   - Content-Security-Policy + frame-ancestors. Selva-engine apps are built
- *     for iframe embedding, so a strict CSP needs UI-phase validation against
- *     real consumer sites before it can ship.
+ *     for iframe embedding, so a strict CSP needs validating against real
+ *     consumer sites before it can ship.
  *   - X-Frame-Options. Same iframe-embedding constraint.
  *   - Cache-Control. Asset-path layout is app policy; set it in the caller.
- *
- * Returns the same response for chaining.
  */
 export declare function applySecurityHeaders(response: Response, opts: SecurityHeaderOptions): Response;
 //# sourceMappingURL=security-headers.d.ts.map

package/dist/http/security-headers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"security-headers.d.ts","sourceRoot":"","sources":["../../src/http/security-headers.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,qBAAqB;IACrC;;;;OAIG;IACH,IAAI,EAAE,OAAO,CAAC;CACd;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,qBAAqB,GAAG,QAAQ,CAW9F"}
+{"version":3,"file":"security-headers.d.ts","sourceRoot":"","sources":["../../src/http/security-headers.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,qBAAqB;IACrC;;;;OAIG;IACH,IAAI,EAAE,OAAO,CAAC;CACd;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,qBAAqB,GAAG,QAAQ,CAW9F"}

package/dist/http/security-headers.js

@@ -1,23 +1,21 @@
 /**
- * Apply baseline browser-hardening headers to a response. Cheap wins that
- * don't require UI verification:
+ * Apply baseline browser-hardening headers to a response and return it for
+ * chaining. Each is a cheap win that needs no UI verification:
  *
  *   - X-Content-Type-Options: nosniff — disables MIME sniffing.
- *   - Referrer-Policy: strict-origin-when-cross-origin — strips the path
- *     and query from cross-origin Referer headers; matches modern browser
- *     defaults but pins the behavior in case the default ever drifts.
- *   - Permissions-Policy: opt out of browser APIs Selva-engine apps don't
- *     use, so XSS can't enable them.
- *   - HSTS when `opts.hsts` (production).
+ *   - Referrer-Policy: strict-origin-when-cross-origin — strips path and query
+ *     from cross-origin Referer headers. Matches modern browser defaults, but
+ *     pins the behavior in case a default drifts.
+ *   - Permissions-Policy: opts out of browser APIs Selva-engine apps don't use,
+ *     so XSS can't enable them.
+ *   - HSTS when `opts.hsts`.
  *
  * **Intentionally NOT set here:**
  *   - Content-Security-Policy + frame-ancestors. Selva-engine apps are built
- *     for iframe embedding, so a strict CSP needs UI-phase validation against
- *     real consumer sites before it can ship.
+ *     for iframe embedding, so a strict CSP needs validating against real
+ *     consumer sites before it can ship.
  *   - X-Frame-Options. Same iframe-embedding constraint.
  *   - Cache-Control. Asset-path layout is app policy; set it in the caller.
- *
- * Returns the same response for chaining.
  */
 export function applySecurityHeaders(response, opts) {
     response.headers.set('X-Content-Type-Options', 'nosniff');

package/dist/http/security-headers.js.map

@@ -1 +1 @@
-{"version":3,"file":"security-headers.js","sourceRoot":"","sources":["../../src/http/security-headers.ts"],"names":[],"mappings":"AASA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,oBAAoB,CAAC,QAAkB,EAAE,IAA2B;IACnF,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,wBAAwB,EAAE,SAAS,CAAC,CAAC;IAC1D,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,iBAAiB,EAAE,iCAAiC,CAAC,CAAC;IAC3E,QAAQ,CAAC,OAAO,CAAC,GAAG,CACnB,oBAAoB,EACpB,+GAA+G,CAC/G,CAAC;IACF,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;QACf,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,2BAA2B,EAAE,qCAAqC,CAAC,CAAC;IAC1F,CAAC;IACD,OAAO,QAAQ,CAAC;AACjB,CAAC"}
+{"version":3,"file":"security-headers.js","sourceRoot":"","sources":["../../src/http/security-headers.ts"],"names":[],"mappings":"AASA;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,oBAAoB,CAAC,QAAkB,EAAE,IAA2B;IACnF,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,wBAAwB,EAAE,SAAS,CAAC,CAAC;IAC1D,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,iBAAiB,EAAE,iCAAiC,CAAC,CAAC;IAC3E,QAAQ,CAAC,OAAO,CAAC,GAAG,CACnB,oBAAoB,EACpB,+GAA+G,CAC/G,CAAC;IACF,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;QACf,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,2BAA2B,EAAE,qCAAqC,CAAC,CAAC;IAC1F,CAAC;IACD,OAAO,QAAQ,CAAC;AACjB,CAAC"}

package/dist/logging/PinoLogger.d.ts

@@ -1,10 +1,8 @@
 import type { ILogger, LogFields, LogLevel } from '@selvajs/platform';
 /**
- * Minimal `ILogger` over `console.*`, used when pino isn't installed.
- *
- * Renders as `LEVEL message {fields}` — readable in a terminal, greppable, and
- * honest about not being machine-parseable. `child` fields are merged eagerly
- * so correlation still works without pino.
+ * Minimal `ILogger` over `console.*`, used when pino isn't installed. Renders
+ * as `LEVEL message {fields}` — greppable, and honest about not being
+ * machine-parseable. `child` fields merge eagerly so correlation still works.
  */
 export declare class ConsoleLogger implements ILogger {
     private readonly bound;
@@ -19,21 +17,17 @@ export declare class ConsoleLogger implements ILogger {
     child(fields: LogFields): ILogger;
 }
 export interface CreateLoggerOptions {
-    /** Minimum level written. Below this, records are dropped. */
+    /** Minimum level written; records below it are dropped. Defaults to `info`. */
     level?: LogLevel;
     /**
-     * Pretty-print via `pino-pretty` (human-readable, colorized) instead of JSON.
-     * For local development — production wants JSON for the collector. Silently
-     * ignored if `pino-pretty` isn't installed.
+     * Pretty-print via `pino-pretty` instead of JSON — for local development;
+     * production wants JSON for the collector. Asking for this without
+     * `pino-pretty` installed drops the whole logger to {@link ConsoleLogger}.
      */
     pretty?: boolean;
     /** Fields stamped on every record (e.g. service name, release). */
     base?: LogFields;
 }
-/**
- * Build the app's root logger. Never throws and never returns `null`: a
- * deployment with no pino installed gets {@link ConsoleLogger}, because losing
- * warnings and errors is a worse outcome than losing JSON formatting.
- */
+/** Build the app's root logger. Never throws, never returns `null`. */
 export declare function createLogger(opts?: CreateLoggerOptions): Promise<ILogger>;
 //# sourceMappingURL=PinoLogger.d.ts.map

package/dist/logging/PinoLogger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PinoLogger.d.ts","sourceRoot":"","sources":["../../src/logging/PinoLogger.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAwDtE;;;;;;GAMG;AACH,qBAAa,aAAc,YAAW,OAAO;IAE3C,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBADR,KAAK,GAAE,SAAc,EACrB,QAAQ,GAAE,QAAiB;IAG7C,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAK3B;IAEF,OAAO,CAAC,KAAK;IAab,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,GAAG,IAAI;IAGhD,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,GAAG,IAAI;IAG/C,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,GAAG,IAAI;IAG/C,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,GAAG,IAAI;IAGhD,KAAK,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO;CAGjC;AAqDD,MAAM,WAAW,mBAAmB;IACnC,8DAA8D;IAC9D,KAAK,CAAC,EAAE,QAAQ,CAAC;IACjB;;;;OAIG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,mEAAmE;IACnE,IAAI,CAAC,EAAE,SAAS,CAAC;CACjB;AAED;;;;GAIG;AACH,wBAAsB,YAAY,CAAC,IAAI,GAAE,mBAAwB,GAAG,OAAO,CAAC,OAAO,CAAC,CAwBnF"}
+{"version":3,"file":"PinoLogger.d.ts","sourceRoot":"","sources":["../../src/logging/PinoLogger.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AA2DtE;;;;GAIG;AACH,qBAAa,aAAc,YAAW,OAAO;IAE3C,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBADR,KAAK,GAAE,SAAc,EACrB,QAAQ,GAAE,QAAiB;IAG7C,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAK3B;IAEF,OAAO,CAAC,KAAK;IAYb,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,GAAG,IAAI;IAGhD,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,GAAG,IAAI;IAG/C,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,GAAG,IAAI;IAG/C,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,GAAG,IAAI;IAGhD,KAAK,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO;CAGjC;AAqDD,MAAM,WAAW,mBAAmB;IACnC,+EAA+E;IAC/E,KAAK,CAAC,EAAE,QAAQ,CAAC;IACjB;;;;OAIG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,mEAAmE;IACnE,IAAI,CAAC,EAAE,SAAS,CAAC;CACjB;AAED,uEAAuE;AACvE,wBAAsB,YAAY,CAAC,IAAI,GAAE,mBAAwB,GAAG,OAAO,CAAC,OAAO,CAAC,CAuBnF"}

package/dist/logging/PinoLogger.js

@@ -1,8 +1,13 @@
 /**
- * Field paths scrubbed before a record is written. Defense-in-depth only — call
- * sites are required not to log secrets in the first place (see `LogFields`).
- * This catches the accident where a whole object is spread into fields and
- * happens to carry a token, which is exactly how credentials reach log indexes.
+ * Field paths scrubbed before a record is written. A backstop for accidents,
+ * NOT a licence to log objects: call sites are required not to log secrets in
+ * the first place (see `LogFields`). This catches the case where a whole object
+ * is spread into fields and happens to carry a credential.
+ *
+ * It matches by FIELD NAME, and only at the top level or one level deep (the
+ * `*.` entries). It will not catch personal data — an email nested in a payload
+ * sails straight through, and a log line reaches a collector that erasure can
+ * never reach. Note the nested `*.` set covers only five of the eight names.
  */
 const REDACTED_PATHS = [
     'token',
@@ -20,11 +25,9 @@ const REDACTED_PATHS = [
     '*.password'
 ];
 /**
- * Minimal `ILogger` over `console.*`, used when pino isn't installed.
- *
- * Renders as `LEVEL message {fields}` — readable in a terminal, greppable, and
- * honest about not being machine-parseable. `child` fields are merged eagerly
- * so correlation still works without pino.
+ * Minimal `ILogger` over `console.*`, used when pino isn't installed. Renders
+ * as `LEVEL message {fields}` — greppable, and honest about not being
+ * machine-parseable. `child` fields merge eagerly so correlation still works.
  */
 export class ConsoleLogger {
     bound;
@@ -45,9 +48,8 @@ export class ConsoleLogger {
         const merged = { ...this.bound, ...fields };
         const suffix = Object.keys(merged).length > 0 ? ` ${safeStringify(merged)}` : '';
         const line = `${level.toUpperCase()} ${message}${suffix}`;
-        // Route to the matching console method so stderr/stdout split as expected.
-        // `info` (not `log`) carries debug too — both go to stdout, and the level
-        // is already spelled out in the line's own prefix.
+        // Split stderr/stdout the way an operator expects. `info` carries debug
+        // too — both land on stdout, and the line already spells out its level.
         if (level === 'error')
             console.error(line);
         else if (level === 'warn')
@@ -85,8 +87,8 @@ class PinoLogger {
     constructor(pino) {
         this.pino = pino;
     }
-    // pino takes (fields, message); ILogger takes (message, fields) — the flip is
-    // deliberate, since the message is what a human scans for first.
+    // pino takes (fields, message); ILogger takes (message, fields). The flip is
+    // deliberate — the message is what a human scans for first.
     debug(message, fields) {
         try {
             this.pino.debug(fields ?? {}, message);
@@ -128,11 +130,7 @@ class PinoLogger {
         }
     }
 }
-/**
- * Build the app's root logger. Never throws and never returns `null`: a
- * deployment with no pino installed gets {@link ConsoleLogger}, because losing
- * warnings and errors is a worse outcome than losing JSON formatting.
- */
+/** Build the app's root logger. Never throws, never returns `null`. */
 export async function createLogger(opts = {}) {
     const level = opts.level ?? 'info';
     try {
@@ -150,10 +148,9 @@ export async function createLogger(opts = {}) {
         return new PinoLogger(pino);
     }
     catch (err) {
-        // pino resolved but could not be constructed — a real misconfiguration
-        // (e.g. `pretty: true` with pino-pretty absent). Unlike a plain absent
-        // package, this one is worth complaining about: the operator asked for
-        // something they didn't get. Fall back rather than go quiet.
+        // pino resolved but wouldn't construct — a real misconfiguration (e.g.
+        // `pretty: true` with pino-pretty absent). Worth complaining about, unlike
+        // a merely absent package: the operator asked for something they didn't get.
         console.warn(`[Logger] pino was found but could not be initialized; falling back to console logging. ${String(err)}`);
         return new ConsoleLogger(opts.base ?? {}, level);
     }
@@ -161,16 +158,13 @@ export async function createLogger(opts = {}) {
 /**
  * Load pino's factory, or `null` when it isn't installed.
  *
- * The indirection through a variable specifier is load-bearing, not stylistic.
- * A literal `import('pino')` is statically analyzable, so bundlers rewrite it —
- * and Vite, applying browser-field mapping to this server build, resolved it to
- * pino's `server_false` browser shim: a stub whose factory throws. That turned
- * "use pino" into a silent fall back to the console. Computing the specifier
- * defeats that resolution and leaves the import to Node at runtime, which is
- * exactly what an optional peer dependency needs.
- *
- * `@vite-ignore` alone was NOT sufficient — it suppressed the warning while the
- * rewrite happened anyway.
+ * Don't inline the specifier. A literal `import('pino')` is statically
+ * analyzable, so Vite applied browser-field mapping to this server build and
+ * resolved it to pino's `server_false` browser shim — a stub whose factory
+ * throws, turning "use pino" into a silent fall back to the console. Computing
+ * the specifier defeats that and leaves the import to Node at runtime.
+ * `@vite-ignore` alone was NOT enough: it silenced the warning and the rewrite
+ * still happened.
  */
 async function loadPinoFactory() {
     const specifier = 'pino';
@@ -181,8 +175,8 @@ async function loadPinoFactory() {
     }
     catch {
         // Not installed — the expected path on a base install, where the console
-        // fallback is the intended behavior. Staying quiet here on purpose: a
-        // boot-time complaint about an optional package nobody asked for is noise.
+        // fallback is intended. Quiet on purpose: complaining at boot about an
+        // optional package nobody asked for is noise.
         return null;
     }
 }

package/dist/logging/PinoLogger.js.map

@@ -1 +1 @@
-{"version":3,"file":"PinoLogger.js","sourceRoot":"","sources":["../../src/logging/PinoLogger.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"PinoLogger.js","sourceRoot":"","sources":["../../src/logging/PinoLogger.ts"],"names":[],"mappings":"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"}

package/dist/logging/requestId.d.ts

@@ -1,45 +1,37 @@
 /**
- * Request-id resolution for log correlation.
+ * Request-id resolution for log correlation. Every record on a request path
+ * carries the same `requestId`, so an operator handed one id can reconstruct
+ * that request's whole story.
  *
- * Every log record on a request path carries the same `requestId`, so an
- * operator handed one id can reconstruct that request's whole story — which is
- * the thing 199 uncorrelated `console.*` calls could never offer.
+ * Inbound ids are TRUSTED when present. Selva runs behind a reverse proxy
+ * (Caddy/nginx) that mints a request id for its own access logs; minting a
+ * second one here would split one request across two ids and kill cross-tier
+ * correlation. The trade — a direct caller picks their own id — is fine, because
+ * the id is only ever a log field and an echoed response header, never an
+ * authorization or uniqueness input.
  *
- * Inbound ids are TRUSTED when present. Selva is documented as running behind a
- * reverse proxy (Caddy/nginx), and those proxies mint a request id for their own
- * access logs; generating a second one here would split a single request across
- * two ids and make cross-tier correlation impossible. The trade is that a direct
- * caller can choose their own id — acceptable, because a request id is a
- * correlation hint, never an authorization or uniqueness input. It is used only
- * as a log field and an echoed response header.
- *
- * That trust is exactly why {@link sanitizeRequestId} exists: an attacker-chosen
- * id is untrusted *content*. Unbounded or newline-carrying values would let a
- * caller forge log lines (log injection) or bloat every record on the request.
+ * That trust is why {@link sanitizeRequestId} exists: an attacker-chosen id is
+ * untrusted content. Unbounded or newline-carrying values would let a caller
+ * forge log lines (log injection) or bloat every record on the request.
  */
 /** Header carrying a caller/proxy-supplied id. The de-facto standard spelling. */
 export declare const REQUEST_ID_HEADER = "x-request-id";
-/**
- * Reduce an untrusted inbound id to something safe to stamp on every record.
- * Returns `null` when nothing usable survives, so the caller generates instead.
- */
+/** Returns `null` when nothing usable survives, so the caller generates instead. */
 export declare function sanitizeRequestId(raw: string | null | undefined): string | null;
 /**
- * Resolve the id for a request: reuse the proxy's when it survives
- * sanitization, otherwise mint a fresh UUID.
+ * Reuse the proxy's id when it survives sanitization, otherwise mint a UUID.
  *
- * @param headers the inbound request headers
- * @param generate id source; injectable so tests get deterministic ids
+ * @param generate injectable so tests get deterministic ids
  */
 export declare function resolveRequestId(headers: Headers, generate?: () => string): string;
 /**
  * Render a thrown value into a log field.
  *
- * Not every rejection is an `Error` — provider adapters occasionally reject with
- * a plain `{ message, status }` object, which would otherwise stringify to a
- * useless `[object Object]` and destroy the only record of the failure. Errors
- * keep their stack (that's the diagnostic); anything else is JSON-serialized,
- * with `String()` as the last resort for cycles and exotic values.
+ * Not every rejection is an `Error` — provider adapters sometimes reject with a
+ * plain `{ message, status }`, which would stringify to a useless
+ * `[object Object]` and destroy the only record of the failure. Errors keep
+ * their stack; anything else is JSON-serialized, with `String()` as the last
+ * resort for cycles and exotic values.
  */
 export declare function renderThrown(error: unknown): string;
 //# sourceMappingURL=requestId.d.ts.map

package/dist/logging/requestId.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"requestId.d.ts","sourceRoot":"","sources":["../../src/logging/requestId.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,kFAAkF;AAClF,eAAO,MAAM,iBAAiB,iBAAiB,CAAC;AAahD;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAI/E;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,GAAE,MAAM,MAAiB,GAAG,MAAM,CAE5F;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAOnD"}
+{"version":3,"file":"requestId.d.ts","sourceRoot":"","sources":["../../src/logging/requestId.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,kFAAkF;AAClF,eAAO,MAAM,iBAAiB,iBAAiB,CAAC;AAahD,oFAAoF;AACpF,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAI/E;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,GAAE,MAAM,MAAiB,GAAG,MAAM,CAE5F;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAOnD"}

package/dist/logging/requestId.js

@@ -1,37 +1,31 @@
 /**
- * Request-id resolution for log correlation.
+ * Request-id resolution for log correlation. Every record on a request path
+ * carries the same `requestId`, so an operator handed one id can reconstruct
+ * that request's whole story.
  *
- * Every log record on a request path carries the same `requestId`, so an
- * operator handed one id can reconstruct that request's whole story — which is
- * the thing 199 uncorrelated `console.*` calls could never offer.
+ * Inbound ids are TRUSTED when present. Selva runs behind a reverse proxy
+ * (Caddy/nginx) that mints a request id for its own access logs; minting a
+ * second one here would split one request across two ids and kill cross-tier
+ * correlation. The trade — a direct caller picks their own id — is fine, because
+ * the id is only ever a log field and an echoed response header, never an
+ * authorization or uniqueness input.
  *
- * Inbound ids are TRUSTED when present. Selva is documented as running behind a
- * reverse proxy (Caddy/nginx), and those proxies mint a request id for their own
- * access logs; generating a second one here would split a single request across
- * two ids and make cross-tier correlation impossible. The trade is that a direct
- * caller can choose their own id — acceptable, because a request id is a
- * correlation hint, never an authorization or uniqueness input. It is used only
- * as a log field and an echoed response header.
- *
- * That trust is exactly why {@link sanitizeRequestId} exists: an attacker-chosen
- * id is untrusted *content*. Unbounded or newline-carrying values would let a
- * caller forge log lines (log injection) or bloat every record on the request.
+ * That trust is why {@link sanitizeRequestId} exists: an attacker-chosen id is
+ * untrusted content. Unbounded or newline-carrying values would let a caller
+ * forge log lines (log injection) or bloat every record on the request.
  */
 /** Header carrying a caller/proxy-supplied id. The de-facto standard spelling. */
 export const REQUEST_ID_HEADER = 'x-request-id';
-/** Max retained length. Long enough for a UUID or a W3C trace-id, short enough to bound a record. */
+/** Long enough for a UUID or a W3C trace-id, short enough to bound a record. */
 const MAX_REQUEST_ID_LENGTH = 128;
 /**
- * Characters allowed through verbatim. Deliberately strict: UUIDs, ULIDs, hex
- * trace-ids and nginx's `$request_id` all fit. Anything else (whitespace,
- * control chars, quotes, CR/LF) is dropped rather than escaped — there is no
- * legitimate id that needs them, and dropping can't be un-escaped downstream.
+ * Characters allowed through verbatim. Strict on purpose: UUIDs, ULIDs, hex
+ * trace-ids and nginx's `$request_id` all fit. Everything else — whitespace,
+ * control chars, quotes, CR/LF — is dropped rather than escaped, since no
+ * legitimate id needs them and dropping can't be un-escaped downstream.
  */
 const UNSAFE_REQUEST_ID_CHARS = /[^A-Za-z0-9._:-]/g;
-/**
- * Reduce an untrusted inbound id to something safe to stamp on every record.
- * Returns `null` when nothing usable survives, so the caller generates instead.
- */
+/** Returns `null` when nothing usable survives, so the caller generates instead. */
 export function sanitizeRequestId(raw) {
     if (!raw)
         return null;
@@ -39,11 +33,9 @@ export function sanitizeRequestId(raw) {
     return cleaned.length > 0 ? cleaned : null;
 }
 /**
- * Resolve the id for a request: reuse the proxy's when it survives
- * sanitization, otherwise mint a fresh UUID.
+ * Reuse the proxy's id when it survives sanitization, otherwise mint a UUID.
  *
- * @param headers the inbound request headers
- * @param generate id source; injectable so tests get deterministic ids
+ * @param generate injectable so tests get deterministic ids
  */
 export function resolveRequestId(headers, generate = randomId) {
     return sanitizeRequestId(headers.get(REQUEST_ID_HEADER)) ?? generate();
@@ -51,11 +43,11 @@ export function resolveRequestId(headers, generate = randomId) {
 /**
  * Render a thrown value into a log field.
  *
- * Not every rejection is an `Error` — provider adapters occasionally reject with
- * a plain `{ message, status }` object, which would otherwise stringify to a
- * useless `[object Object]` and destroy the only record of the failure. Errors
- * keep their stack (that's the diagnostic); anything else is JSON-serialized,
- * with `String()` as the last resort for cycles and exotic values.
+ * Not every rejection is an `Error` — provider adapters sometimes reject with a
+ * plain `{ message, status }`, which would stringify to a useless
+ * `[object Object]` and destroy the only record of the failure. Errors keep
+ * their stack; anything else is JSON-serialized, with `String()` as the last
+ * resort for cycles and exotic values.
  */
 export function renderThrown(error) {
     if (error instanceof Error)
@@ -68,10 +60,10 @@ export function renderThrown(error) {
     }
 }
 /**
- * `crypto.randomUUID` is available in every runtime Selva targets (Node 22+,
- * workers, modern browsers). The fallback covers non-secure contexts where
- * `randomUUID` is missing — ids only need to be collision-free enough to
- * correlate logs, never unguessable.
+ * `crypto.randomUUID` exists in every runtime Selva targets (Node 22+, workers,
+ * modern browsers); the `Math.random` branch only covers non-secure contexts
+ * where it is missing. Not a weakness: these ids need to be collision-free
+ * enough to correlate logs, never unguessable.
  */
 function randomId() {
     const c = globalThis.crypto;