@naturalcycles/backend-lib 9.74.0 → 9.76.0

package/dist/admin/adminMiddleware.d.ts

@@ -1,6 +1,9 @@
 import type { BackendRequestHandler } from '../server/server.model.js';
 import type { BaseAdminService } from './base.admin.service.js';
 import type { FirebaseSharedServiceCfg } from './firebase.shared.service.js';
+/**
+ * @deprecated Use `AuthLoginRedirectMiddlewareCfg`.
+ */
 export interface RequireAdminCfg {
     /**
      * @default '/login.html'
@@ -25,14 +28,28 @@ export interface RequireAdminCfg {
      */
     andComparison?: boolean;
 }
+/**
+ * @deprecated Use `AuthMiddleware`.
+ */
 export type AdminMiddleware = (reqPermissions?: string[], cfg?: RequireAdminCfg) => BackendRequestHandler;
+/**
+ * @deprecated Use `AuthService.getLoginRedirectMiddleware`.
+ */
 export declare function createAdminMiddleware(adminService: BaseAdminService, cfgDefaults?: RequireAdminCfg): AdminMiddleware;
 /**
  * Require Admin permission.
  * If not authenticated - will redirect to `loginHtmlPath` (default to /login.html).
  * If authenticated, but not authorized - will throw 403.
  * Otherwise will just pass.
+ *
+ * @deprecated Use `AuthService.getLoginRedirectMiddleware`.
  */
 export declare function requireAdminPermissions(adminService: BaseAdminService, reqPermissions?: string[], cfg?: RequireAdminCfg): BackendRequestHandler;
+/**
+ * @deprecated Use `loginHtmlHandler`.
+ */
 export declare function loginHtml(firebaseServiceCfg: FirebaseSharedServiceCfg): BackendRequestHandler;
+/**
+ * @deprecated Use `AuthService.getLoginRedirectMiddleware`.
+ */
 export declare function getLoginHtmlRedirect(href: string): string;

package/dist/admin/adminMiddleware.js

@@ -2,6 +2,9 @@ import { _memoized } from '@naturalcycles/js-lib/decorators';
 import { AppError } from '@naturalcycles/js-lib/error/error.util.js';
 import { fs2 } from '@naturalcycles/nodejs-lib/fs2';
 import { srcDir } from '../paths.cnst.js';
+/**
+ * @deprecated Use `AuthService.getLoginRedirectMiddleware`.
+ */
 export function createAdminMiddleware(adminService, cfgDefaults = {}) {
     return (reqPermissions, cfg) => requireAdminPermissions(adminService, reqPermissions, {
         ...cfgDefaults,
@@ -13,6 +16,8 @@ export function createAdminMiddleware(adminService, cfgDefaults = {}) {
  * If not authenticated - will redirect to `loginHtmlPath` (default to /login.html).
  * If authenticated, but not authorized - will throw 403.
  * Otherwise will just pass.
+ *
+ * @deprecated Use `AuthService.getLoginRedirectMiddleware`.
  */
 export function requireAdminPermissions(adminService, reqPermissions = [], cfg = {}) {
     const { loginHtmlPath = '/login.html', urlStartsWith, apiHost, autoLogin = true, andComparison = true, } = cfg;
@@ -36,6 +41,9 @@ export function requireAdminPermissions(adminService, reqPermissions = [], cfg =
         }
     };
 }
+/**
+ * @deprecated Use `loginHtmlHandler`.
+ */
 export function loginHtml(firebaseServiceCfg) {
     const { apiKey: firebaseApiKey, authDomain: firebaseAuthDomain, adminAuthProvider: firebaseAuthProvider = 'GoogleAuthProvider', } = firebaseServiceCfg;
     return (_req, res) => {
@@ -54,6 +62,9 @@ const getLoginHtml = _memoized((cfg) => {
         .replaceAll('<%= firebaseAuthDomain %>', cfg.firebaseAuthDomain)
         .replaceAll('<%= firebaseAuthProvider %>', cfg.firebaseAuthProvider);
 });
+/**
+ * @deprecated Use `AuthService.getLoginRedirectMiddleware`.
+ */
 export function getLoginHtmlRedirect(href) {
     return `
 <html>

package/dist/admin/base.admin.service.d.ts

@@ -3,6 +3,8 @@ import type { Auth } from 'firebase-admin/auth';
 import type { BackendRequest, BackendRequestHandler } from '../server/server.model.js';
 /**
  * Base implementation based on Firebase Auth tokens passed as 'admin_token' cookie.
+ *
+ * @deprecated Use `AuthService`, with `FirebaseAuthService` for `authenticate`.
  */
 export declare class BaseAdminService {
     private loadFirebaseAuth;
@@ -61,6 +63,9 @@ export declare class BaseAdminService {
      */
     getFirebaseAuthLoginHandler(): BackendRequestHandler;
 }
+/**
+ * @deprecated Use `AuthServiceCfg` and `FirebaseAuthServiceCfg`.
+ */
 export interface AdminServiceCfg {
     /**
      * @default 'admin_token'
@@ -73,16 +78,25 @@ export interface AdminServiceCfg {
      */
     authEnabled?: boolean;
 }
+/**
+ * @deprecated Use `PermissionInfo`.
+ */
 export interface AdminInfo {
     email: string;
     permissions: string[];
 }
+/**
+ * @deprecated Use `ResolvedAuth`.
+ */
 export interface ResolvedAdmin {
     /** undefined - no valid admin token */
     email?: string;
     /** undefined - not an Admin */
     permissions?: Set<string>;
 }
+/**
+ * @deprecated Use `AuthCheckOptions`.
+ */
 export interface CheckPermissionsOptions {
     /**
      * false - one granted permission is enough.
@@ -91,6 +105,9 @@ export interface CheckPermissionsOptions {
      */
     andComparison?: boolean;
 }
+/**
+ * @deprecated Use `AuthService.has` / `AuthService.require`.
+ */
 export interface CheckPermissionsResult {
     /** undefined - no valid admin token */
     email?: string;

package/dist/admin/base.admin.service.js

@@ -4,6 +4,8 @@ import { _assert } from '@naturalcycles/js-lib/error';
 import { dimGrey, green, red } from '@naturalcycles/nodejs-lib/colors';
 /**
  * Base implementation based on Firebase Auth tokens passed as 'admin_token' cookie.
+ *
+ * @deprecated Use `AuthService`, with `FirebaseAuthService` for `authenticate`.
  */
 export class BaseAdminService {
     loadFirebaseAuth;

package/dist/admin/firebaseAuth.service.d.ts

@@ -0,0 +1,41 @@
+import type { Auth } from 'firebase-admin/auth';
+import type { BackendRequest, BackendRequestHandler } from '../server/server.model.js';
+import type { FirebaseSharedServiceCfg } from './firebase.shared.service.js';
+/**
+ * Verifies Firebase Auth tokens.
+ */
+export declare class FirebaseAuthService {
+    private loadFirebaseAuth;
+    cfg: FirebaseAuthServiceCfg;
+    constructor(loadFirebaseAuth: () => Promise<FirebaseTokenVerifier>, cfg: FirebaseAuthServiceCfg);
+    /**
+     * Reads the configured cookie first, then the header.
+     */
+    getToken(req: BackendRequest): string | undefined;
+    /**
+     * Returns undefined if there's no token, or it's expired.
+     * Rejects on any other verification failure.
+     */
+    getEmailByToken(token: string | undefined): Promise<string | undefined>;
+    private getFirebaseAuth;
+    /**
+     * POST handler that stores the token from the `Authentication` header in `tokenCookie` (not validated).
+     * `Authentication: logout` clears it. The bundled login.html posts to `/admin/login`.
+     */
+    getLoginHandler(): BackendRequestHandler;
+}
+/**
+ * Serves login.html, configured for Firebase Auth.
+ */
+export declare function loginHtmlHandler(firebaseServiceCfg: FirebaseSharedServiceCfg): BackendRequestHandler;
+/**
+ * The part of Firebase `Auth` that FirebaseAuthService uses.
+ */
+export type FirebaseTokenVerifier = Pick<Auth, 'verifyIdToken'>;
+export interface FirebaseAuthServiceCfg {
+    /**
+     * Read by `getToken`, set by `getLoginHandler`.
+     */
+    tokenCookie?: string;
+    tokenHeader?: string;
+}

package/dist/admin/firebaseAuth.service.js

@@ -0,0 +1,103 @@
+import { __decorate } from "tslib";
+import { _Memo, _memoized } from '@naturalcycles/js-lib/decorators';
+import { _assert } from '@naturalcycles/js-lib/error';
+import { fs2 } from '@naturalcycles/nodejs-lib/fs2';
+import { srcDir } from '../paths.cnst.js';
+/**
+ * Verifies Firebase Auth tokens.
+ */
+export class FirebaseAuthService {
+    loadFirebaseAuth;
+    cfg;
+    constructor(loadFirebaseAuth, cfg) {
+        this.loadFirebaseAuth = loadFirebaseAuth;
+        this.cfg = cfg;
+    }
+    /**
+     * Reads the configured cookie first, then the header.
+     */
+    getToken(req) {
+        const { tokenCookie, tokenHeader } = this.cfg;
+        if (tokenCookie) {
+            const token = req.cookies?.[tokenCookie];
+            if (token)
+                return token;
+        }
+        if (tokenHeader)
+            return req.header(tokenHeader);
+    }
+    /**
+     * Returns undefined if there's no token, or it's expired.
+     * Rejects on any other verification failure.
+     */
+    async getEmailByToken(token) {
+        if (!token)
+            return;
+        const auth = await this.getFirebaseAuth();
+        try {
+            const decodedToken = await auth.verifyIdToken(token);
+            return decodedToken.email;
+        }
+        catch (err) {
+            if (err?.hasCode?.('id-token-expired'))
+                return;
+            throw err;
+        }
+    }
+    async getFirebaseAuth() {
+        return await this.loadFirebaseAuth();
+    }
+    /**
+     * POST handler that stores the token from the `Authentication` header in `tokenCookie` (not validated).
+     * `Authentication: logout` clears it. The bundled login.html posts to `/admin/login`.
+     */
+    getLoginHandler() {
+        const { tokenCookie } = this.cfg;
+        _assert(tokenCookie, 'getLoginHandler requires tokenCookie to be configured');
+        return async (req, res) => {
+            const token = req.header('authentication');
+            _assert(token, `401 Unauthenticated`, {
+                userFriendly: true,
+                backendResponseStatusCode: 401,
+            });
+            let maxAge = 1000 * 60 * 60 * 24 * 30; // 30 days
+            if (token === 'logout') {
+                // delete the cookie
+                maxAge = 0;
+            }
+            res
+                .cookie(tokenCookie, token, {
+                maxAge,
+                sameSite: 'lax', // can be: none, lax, strict
+                // comment these 2 lines to debug on localhost
+                httpOnly: true,
+                secure: true,
+            })
+                .status(204)
+                .end();
+        };
+    }
+}
+__decorate([
+    _Memo()
+], FirebaseAuthService.prototype, "getFirebaseAuth", null);
+/**
+ * Serves login.html, configured for Firebase Auth.
+ */
+export function loginHtmlHandler(firebaseServiceCfg) {
+    const { apiKey: firebaseApiKey, authDomain: firebaseAuthDomain, adminAuthProvider: firebaseAuthProvider = 'GoogleAuthProvider', } = firebaseServiceCfg;
+    return (_req, res) => {
+        res.send(getLoginHtml({
+            firebaseApiKey,
+            firebaseAuthDomain,
+            firebaseAuthProvider,
+        }));
+    };
+}
+const getLoginHtml = _memoized((cfg) => {
+    return fs2
+        .readText(`${srcDir}/admin/login.html`)
+        .replaceAll('<%= firebaseApiKey %>', cfg.firebaseApiKey)
+        .replaceAll('<%= firebaseAuthDomain %>', cfg.firebaseAuthDomain)
+        .replaceAll('<%= firebaseAuthProvider %>', cfg.firebaseAuthProvider);
+});

package/dist/admin/index.d.ts

@@ -1,4 +1,5 @@
 export * from './adminMiddleware.js';
 export * from './base.admin.service.js';
 export * from './firebase.shared.service.js';
+export * from './firebaseAuth.service.js';
 export * from './secureHeaderMiddleware.js';

package/dist/admin/index.js

@@ -1,4 +1,5 @@
 export * from './adminMiddleware.js';
 export * from './base.admin.service.js';
 export * from './firebase.shared.service.js';
+export * from './firebaseAuth.service.js';
 export * from './secureHeaderMiddleware.js';

package/dist/admin/secureHeaderMiddleware.d.ts

@@ -1,5 +1,8 @@
 import type { AdminMiddleware, RequireAdminCfg } from './adminMiddleware.js';
 import type { BaseAdminService } from './base.admin.service.js';
+/**
+ * @deprecated Use `AuthLoginRedirectMiddlewareCfg` with `secureHeader`.
+ */
 export interface SecureHeaderMiddlewareCfg extends RequireAdminCfg {
     adminService: BaseAdminService;
     /**
@@ -14,5 +17,7 @@ export interface SecureHeaderMiddlewareCfg extends RequireAdminCfg {
 /**
  * Secures the endpoint by requiring a secret header to be present.
  * Throws Error401Admin otherwise.
+ *
+ * @deprecated Use `AuthService.getLoginRedirectMiddleware` with `secureHeader`.
  */
 export declare function createSecureHeaderMiddleware(cfg: SecureHeaderMiddlewareCfg): AdminMiddleware;

package/dist/admin/secureHeaderMiddleware.js

@@ -4,6 +4,8 @@ import { requireAdminPermissions } from './adminMiddleware.js';
 /**
  * Secures the endpoint by requiring a secret header to be present.
  * Throws Error401Admin otherwise.
+ *
+ * @deprecated Use `AuthService.getLoginRedirectMiddleware` with `secureHeader`.
  */
 export function createSecureHeaderMiddleware(cfg) {
     return reqPermissions => requireSecureHeaderOrAdmin(cfg, reqPermissions);

package/dist/auth/auth.service.d.ts

@@ -0,0 +1,119 @@
+import type { AnyObject, Promisable } from '@naturalcycles/js-lib/types';
+import type { BackendRequest, BackendRequestHandler } from '../server/server.model.js';
+/**
+ * Authenticates requests and checks permissions.
+ */
+export declare class AuthService<CTX = AnyObject> {
+    constructor(cfg: AuthServiceCfg<CTX>);
+    cfg: AuthServiceCfg<CTX> & {
+        authEnabled: boolean;
+    };
+    /**
+     * Responds JSON 401 / 403.
+     */
+    getMiddleware(cfg?: AuthMiddlewareCfg<CTX>): AuthMiddleware;
+    /**
+     * Like `getMiddleware`, but 401 redirects to the login page.
+     */
+    getLoginRedirectMiddleware(cfg: AuthLoginRedirectMiddlewareCfg<CTX>): AuthMiddleware;
+    private createHandler;
+    /**
+     * Runs `authenticate`, then `getPermissions` and `isAlwaysAuthorized` if there's a subject.
+     * Ignores `authEnabled`.
+     */
+    resolve(req: BackendRequest): Promise<ResolvedAuth>;
+    /**
+     * Throws 401 if there's no subject, 403 if not granted.
+     * Returns the granted permissions (all of the subject's if alwaysAuthorized),
+     * or `{ subject: 'authDisabled', permissions: [] }` if auth is disabled.
+     */
+    require(resolved: ResolvedAuth | undefined, reqPermissions?: string[], opt?: AuthCheckOptions<CTX>): PermissionInfo;
+    private checkSubject;
+    private assertAuthenticated;
+    private authRequiredData;
+    private assertGranted;
+    /**
+     * undefined - not granted.
+     */
+    private getGrantedPermissions;
+    private getLoginHref;
+    private getLoginHtmlRedirect;
+}
+export interface AuthServiceCfg<CTX> {
+    /**
+     * Returns the subject, or undefined if not authenticated.
+     */
+    authenticate: (req: BackendRequest) => Promise<string | undefined>;
+    /**
+     * undefined - no permission set (never granted).
+     */
+    getPermissions: (subject: string, req: BackendRequest) => Promise<string[] | undefined>;
+    /**
+     * true - every check is granted for this subject.
+     */
+    isAlwaysAuthorized?: (subject: string, permissions: string[] | undefined, req: BackendRequest) => Promisable<boolean>;
+    /**
+     * Called on every `require` check that has a subject, while auth is enabled. Must not throw.
+     */
+    onCheck?: (check: AuthCheck, ctx: (CTX & AnyObject) | undefined) => void;
+    /**
+     * false - every check is granted. For tests / local debugging. Read on every check.
+     *
+     * @default true
+     */
+    authEnabled?: boolean;
+}
+export interface AuthCheck {
+    subject: string;
+    granted: boolean;
+    alwaysAuthorized: boolean;
+    reqPermissions: string[];
+    /** The granted permissions, or reqPermissions if denied */
+    checkedPermissions: string[];
+}
+export interface AuthLoginRedirectMiddlewareCfg<CTX> extends AuthMiddlewareCfg<CTX> {
+    loginHtmlPath: string;
+}
+export interface AuthMiddlewareCfg<CTX> {
+    /**
+     * Defaults to `resolve(req)`.
+     */
+    getResolved?: (req: BackendRequest) => Promisable<ResolvedAuth | undefined>;
+    getCtx?: (req: BackendRequest) => (CTX & AnyObject) | undefined;
+    /**
+     * @default true
+     */
+    andComparison?: boolean;
+    /**
+     * A request with this header passes without auth. A wrong value responds 401.
+     */
+    secureHeader?: SecureHeaderCfg;
+}
+export interface SecureHeaderCfg {
+    /** e.g. 'Authorization' */
+    name: string;
+    value: string;
+}
+export type AuthMiddleware = (reqPermissions?: string[]) => BackendRequestHandler;
+export interface AuthCheckOptions<CTX> {
+    /**
+     * false - one granted permission is enough.
+     *
+     * @default true
+     */
+    andComparison?: boolean;
+    /** Passed to onCheck: the app's CTX, plus any extra keys */
+    ctx?: CTX & AnyObject;
+}
+export interface PermissionInfo {
+    subject: string;
+    permissions: string[];
+}
+export interface ResolvedAuth {
+    /** undefined - not authenticated */
+    subject?: string;
+    /** undefined - no permission set */
+    permissions?: string[];
+    /** Result of `isAlwaysAuthorized` */
+    alwaysAuthorized?: boolean;
+}

package/dist/auth/auth.service.js

@@ -0,0 +1,147 @@
+import { _assert, AppError } from '@naturalcycles/js-lib/error';
+import { timingSafeStringEqual } from '@naturalcycles/nodejs-lib';
+/**
+ * Authenticates requests and checks permissions.
+ */
+export class AuthService {
+    constructor(cfg) {
+        this.cfg = {
+            authEnabled: true,
+            ...cfg,
+        };
+    }
+    cfg;
+    /**
+     * Responds JSON 401 / 403.
+     */
+    getMiddleware(cfg = {}) {
+        return reqPermissions => this.createHandler(cfg, reqPermissions);
+    }
+    /**
+     * Like `getMiddleware`, but 401 redirects to the login page.
+     */
+    getLoginRedirectMiddleware(cfg) {
+        const loginHref = this.getLoginHref(cfg);
+        return reqPermissions => this.createHandler(cfg, reqPermissions, loginHref);
+    }
+    createHandler(cfg, reqPermissions = [], loginHref) {
+        const { getResolved = req => this.resolve(req), getCtx, andComparison = true, secureHeader, } = cfg;
+        return async (req, res, next) => {
+            if (!this.cfg.authEnabled)
+                return next();
+            if (secureHeader) {
+                const providedHeader = req.get(secureHeader.name);
+                if (providedHeader) {
+                    if (timingSafeStringEqual(providedHeader, secureHeader.value)) {
+                        return next();
+                    }
+                    return next(new AppError('secureHeader or authentication required', this.authRequiredData()));
+                }
+            }
+            try {
+                const resolved = await getResolved(req);
+                if (!resolved?.subject && loginHref) {
+                    res.status(401).send(this.getLoginHtmlRedirect(loginHref));
+                    return;
+                }
+                this.require(resolved, reqPermissions, { andComparison, ctx: getCtx?.(req) });
+                return next();
+            }
+            catch (err) {
+                return next(err);
+            }
+        };
+    }
+    /**
+     * Runs `authenticate`, then `getPermissions` and `isAlwaysAuthorized` if there's a subject.
+     * Ignores `authEnabled`.
+     */
+    async resolve(req) {
+        const { authenticate, getPermissions, isAlwaysAuthorized } = this.cfg;
+        const subject = await authenticate(req);
+        if (!subject)
+            return {};
+        const permissions = await getPermissions(subject, req);
+        const alwaysAuthorized = isAlwaysAuthorized
+            ? await isAlwaysAuthorized(subject, permissions, req)
+            : false;
+        return { subject, permissions, alwaysAuthorized };
+    }
+    /**
+     * Throws 401 if there's no subject, 403 if not granted.
+     * Returns the granted permissions (all of the subject's if alwaysAuthorized),
+     * or `{ subject: 'authDisabled', permissions: [] }` if auth is disabled.
+     */
+    require(resolved, reqPermissions = [], opt = {}) {
+        if (!this.cfg.authEnabled)
+            return { subject: 'authDisabled', permissions: [] };
+        this.assertAuthenticated(resolved);
+        const { subject, permissions, alwaysAuthorized } = resolved;
+        const grantedPermissions = this.checkSubject(resolved, reqPermissions, opt);
+        this.assertGranted(subject, grantedPermissions, reqPermissions);
+        if (alwaysAuthorized) {
+            return { subject, permissions: permissions?.slice() || [] };
+        }
+        return { subject, permissions: grantedPermissions.slice() };
+    }
+    checkSubject(resolved, reqPermissions, opt) {
+        const { subject, permissions, alwaysAuthorized = false } = resolved;
+        const { andComparison = true, ctx } = opt;
+        const grantedPermissions = alwaysAuthorized
+            ? reqPermissions
+            : this.getGrantedPermissions(permissions, reqPermissions, andComparison);
+        this.cfg.onCheck?.({
+            subject,
+            granted: !!grantedPermissions,
+            alwaysAuthorized,
+            reqPermissions,
+            checkedPermissions: grantedPermissions || reqPermissions,
+        }, ctx);
+        return grantedPermissions;
+    }
+    assertAuthenticated(resolved) {
+        _assert(resolved?.subject, 'authentication required', this.authRequiredData());
+    }
+    authRequiredData() {
+        return {
+            authRequired: true,
+            backendResponseStatusCode: 401,
+            userFriendly: true,
+        };
+    }
+    assertGranted(subject, grantedPermissions, reqPermissions) {
+        _assert(grantedPermissions, `Permissions required: [${reqPermissions.join(', ')}]`, {
+            permissionsRequired: reqPermissions,
+            subject,
+            backendResponseStatusCode: 403,
+            userFriendly: true,
+        });
+    }
+    /**
+     * undefined - not granted.
+     */
+    getGrantedPermissions(permissions, reqPermissions, andComparison) {
+        if (!permissions)
+            return;
+        const grantedPermissions = reqPermissions.filter(p => permissions.includes(p));
+        const granted = andComparison
+            ? grantedPermissions.length === reqPermissions.length
+            : grantedPermissions.length > 0;
+        return granted ? grantedPermissions : undefined;
+    }
+    getLoginHref(cfg) {
+        return `${cfg.loginHtmlPath}?autoLogin=1&returnUrl=\${encodeURIComponent(location.href)}`;
+    }
+    getLoginHtmlRedirect(href) {
+        return `
+<html>
+<body>401 Authentication Required
+<script>
+  document.write(\`: <a href="${href}" id="loginLink">Login</a>\`)
+  document.getElementById('loginLink').click()
+</script>
+</body>
+</html>
+`;
+    }
+}

package/dist/auth/index.d.ts

@@ -0,0 +1 @@
+export * from './auth.service.js';

package/dist/auth/index.js

@@ -0,0 +1 @@
+export * from './auth.service.js';

package/dist/server/basicAuthMiddleware.js

@@ -14,6 +14,7 @@ export function basicAuthMiddleware(cfg) {
         res
             .set('WWW-Authenticate', `Basic${realm ? ` realm="${realm}"` : ''}`)
             .status(401)
+            .type('text/plain')
             .send('Unauthorized');
     };
 }

package/dist/server/request.util.d.ts

@@ -9,5 +9,19 @@ import type { BackendRequest } from './server.model.js';
  *
  * If stripPrefix (e.g `/api/v2`) is provided, and the path starts with it (like path.startsWith(stripPrefix)),
  * it will be stripped from the beginning of the path.
+ *
+ * The result is injection-safe: `req.baseUrl` and `req.path` come from the request as-is
+ * (not even url-decoded), so every character outside of a conservative allowlist is replaced with `_`.
+ * `req.route.path` is the server-defined route pattern, so it's used as-is.
+ *
+ * Use `getRequestEndpointUnsafe` if the exact path is needed.
  */
 export declare function getRequestEndpoint(req: BackendRequest, stripPrefix?: string): string;
+/**
+ * Same as `getRequestEndpoint`, but without sanitization:
+ * for requests that didn't match a route (e.g 404s) the path is returned exactly as the client sent it.
+ *
+ * Use at your own risk: the result must be escaped before it's embedded in html
+ * (or any other context where it could be interpreted).
+ */
+export declare function getRequestEndpointUnsafe(req: BackendRequest, stripPrefix?: string): string;

package/dist/server/request.util.js

@@ -8,9 +8,28 @@
  *
  * If stripPrefix (e.g `/api/v2`) is provided, and the path starts with it (like path.startsWith(stripPrefix)),
  * it will be stripped from the beginning of the path.
+ *
+ * The result is injection-safe: `req.baseUrl` and `req.path` come from the request as-is
+ * (not even url-decoded), so every character outside of a conservative allowlist is replaced with `_`.
+ * `req.route.path` is the server-defined route pattern, so it's used as-is.
+ *
+ * Use `getRequestEndpointUnsafe` if the exact path is needed.
  */
 export function getRequestEndpoint(req, stripPrefix) {
-    let path = (req.baseUrl + (req.route?.path || req.path)).toLowerCase();
+    return buildRequestEndpoint(req, stripPrefix, sanitizePath);
+}
+/**
+ * Same as `getRequestEndpoint`, but without sanitization:
+ * for requests that didn't match a route (e.g 404s) the path is returned exactly as the client sent it.
+ *
+ * Use at your own risk: the result must be escaped before it's embedded in html
+ * (or any other context where it could be interpreted).
+ */
+export function getRequestEndpointUnsafe(req, stripPrefix) {
+    return buildRequestEndpoint(req, stripPrefix, identity);
+}
+function buildRequestEndpoint(req, stripPrefix, sanitize) {
+    let path = (sanitize(req.baseUrl) + (req.route?.path || sanitize(req.path))).toLowerCase();
     if (path.length > 1 && path.endsWith('/')) {
         path = path.slice(0, path.length - 1);
     }
@@ -19,3 +38,11 @@ export function getRequestEndpoint(req, stripPrefix) {
     }
     return [req.method, path].join(' ');
 }
+// Letters, digits and the url punctuation that is inert in html, js, json and logs.
+// Everything else (< > & " ' ( ) ` \ control chars, etc) is replaced, not encoded:
+// the exact bytes are not worth preserving here, `req.url` still has them.
+const UNSAFE_PATH_CHAR = /[^\w\-./:@%!$*+,;=~]/gu;
+function sanitizePath(path) {
+    return path.replace(UNSAFE_PATH_CHAR, '_');
+}
+const identity = (path) => path;