@naturalcycles/backend-lib 9.74.0 → 9.76.0

package/dist/server/requestTimeoutMiddleware.d.ts

@@ -13,6 +13,13 @@ export interface RequestTimeoutMiddlewareCfg {
      * @default 'Request timed out'
      */
     httpErrorMessage?: string;
+    /**
+     * Upper bound for the `?requestTimeout=N` query override.
+     * Higher values are clamped to it, so a client cannot hold a request open for arbitrarily long.
+     *
+     * @default 600
+     */
+    maxTimeoutSeconds?: NumberOfSeconds;
 }
 export declare function requestTimeoutMiddleware(cfg?: RequestTimeoutMiddlewareCfg): BackendRequestHandler;
 export interface CustomRequestTimeoutMiddlewareCfg {
@@ -25,7 +32,7 @@ export interface CustomRequestTimeoutMiddlewareCfg {
  * Example:
  *
  * router.get('/', customRequestTimeoutMiddleware(
- *   (req, res) => res.status(409).send('my custom message!'),
+ *   (req, res) => res.status(409).type('text/plain').send('my custom message!'),
  *   { timeoutSeconds: 30 },
  * )
  */

package/dist/server/requestTimeoutMiddleware.js

@@ -6,7 +6,7 @@ import { getRequestEndpoint } from './request.util.js';
 const code = 'REQUEST_TIMEOUT';
 const REQUEST_TIMEOUT_QUERY_KEY = 'requestTimeout';
 export function requestTimeoutMiddleware(cfg = {}) {
-    const { timeoutSeconds: defTimeoutSeconds, backendResponseStatusCode, httpErrorMessage, } = {
+    const { timeoutSeconds: defTimeoutSeconds, backendResponseStatusCode, httpErrorMessage, maxTimeoutSeconds, } = {
         // Considerations about the default value of the timeout.
         // Ideally the default value here would be HIGHER than the default timeout for getGot (in nodejs-lib),
         // so, cross-service communication has a chance to fail SOONER than server times out,
@@ -14,12 +14,11 @@ export function requestTimeoutMiddleware(cfg = {}) {
         timeoutSeconds: 120,
         backendResponseStatusCode: 503,
         httpErrorMessage: 'Request timed out',
+        maxTimeoutSeconds: 600,
         ...cfg,
     };
     return function requestTimeoutHandler(req, res, next) {
-        const timeoutSeconds = req.query[REQUEST_TIMEOUT_QUERY_KEY]
-            ? Number.parseInt(req.query[REQUEST_TIMEOUT_QUERY_KEY])
-            : defTimeoutSeconds;
+        const timeoutSeconds = getTimeoutSeconds(req, defTimeoutSeconds, maxTimeoutSeconds);
         // If requestTimeout was previously set - cancel it first
         // Then set the new requestTimeout and handler
         if (req.requestTimeout)
@@ -39,11 +38,26 @@ export function requestTimeoutMiddleware(cfg = {}) {
         next();
     };
 }
+/**
+ * `?requestTimeout=N` query param lets the client override the timeout of its request
+ * (used e.g by Cloud Tasks for long-running tasks).
+ * Being client-controlled, it is validated: non-numeric or non-positive values are ignored
+ * (fall back to the default), values above `maxTimeoutSeconds` are clamped.
+ */
+function getTimeoutSeconds(req, defTimeoutSeconds, maxTimeoutSeconds) {
+    const raw = req.query[REQUEST_TIMEOUT_QUERY_KEY];
+    if (typeof raw !== 'string')
+        return defTimeoutSeconds;
+    const requested = Number.parseInt(raw, 10);
+    if (Number.isNaN(requested) || requested <= 0)
+        return defTimeoutSeconds;
+    return Math.min(requested, maxTimeoutSeconds);
+}
 /**
  * Example:
  *
  * router.get('/', customRequestTimeoutMiddleware(
- *   (req, res) => res.status(409).send('my custom message!'),
+ *   (req, res) => res.status(409).type('text/plain').send('my custom message!'),
  *   { timeoutSeconds: 30 },
  * )
  */

package/dist/server/serverStatsMiddleware.js

@@ -5,6 +5,7 @@ import { _ms } from '@naturalcycles/js-lib/datetime/time.util.js';
 import { _percentile } from '@naturalcycles/js-lib/math/math.util.js';
 import { NumberStack } from '@naturalcycles/js-lib/math/stack.util.js';
 import { _get, _mapValues } from '@naturalcycles/js-lib/object/object.util.js';
+import { htmlEscape } from '@naturalcycles/js-lib/string/escape.js';
 import { _stringMapEntries, _stringMapValues } from '@naturalcycles/js-lib/types';
 import { onFinished } from '../onFinished.js';
 import { getRequestEndpoint } from './request.util.js';
@@ -61,7 +62,7 @@ export const serverStatsHTMLHandler = (req, res) => {
         }).map(([endpoint, stat]) => {
             return [
                 '<tr>',
-                `<td><pre>${endpoint}</pre></td>`,
+                `<td><pre>${htmlEscape(endpoint)}</pre></td>`,
                 `<td align="right"><pre>${stat.total}</pre></td>`,
                 // oxlint-disable-next-line @typescript-eslint/no-base-to-string
                 ...families.map(f => `<td align="right"><pre>${stat[f]}</pre></td>`),
@@ -71,7 +72,7 @@ export const serverStatsHTMLHandler = (req, res) => {
         }),
         '</table>',
     ].join('\n');
-    res.send(html);
+    res.type('html').send(html);
 };
 /**
  * Unlocks serverStatsHTMLHandler
@@ -83,7 +84,12 @@ export function serverStatsMiddleware() {
         onFinished(res, () => {
             const now = Date.now();
             const latency = now - started;
-            const endpoint = getRequestEndpoint(req);
+            // Only requests that matched a route are recorded by their route pattern.
+            // Unmatched requests (404s, requests rejected by router-level middleware) carry an
+            // arbitrary client-controlled path: recording them per-path would let any client
+            // grow the map unboundedly and plant arbitrary strings into it.
+            // So they're bucketed per mount point instead.
+            const endpoint = req.route ? getRequestEndpoint(req) : getUnmatchedEndpoint(req);
             serverStatsMap[endpoint] ||= {
                 stack: new NumberStack(SIZE),
                 '2xx': 0,
@@ -102,6 +108,13 @@ export function serverStatsMiddleware() {
         next();
     };
 }
+/**
+ * Returns e.g `GET /*` or `GET /api/v3/admin/*`.
+ * `req.baseUrl` is the mount point that matched, so it's bounded by the app's routing config.
+ */
+function getUnmatchedEndpoint(req) {
+    return `${req.method} ${req.baseUrl.toLowerCase()}/*`;
+}
 function cleanupServerStats() {
     if (Object.keys(serverStatsMap).length <= MAX_ENDPOINTS)
         return;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@naturalcycles/backend-lib",
   "type": "module",
-  "version": "9.74.0",
+  "version": "9.76.0",
   "dependencies": {
     "@naturalcycles/db-lib": "^10",
     "@naturalcycles/js-lib": "^15",
@@ -53,6 +53,8 @@
     ".": "./dist/index.js",
     "./admin": "./dist/admin/index.js",
     "./admin/*.js": "./dist/admin/*.js",
+    "./auth": "./dist/auth/index.js",
+    "./auth/*.js": "./dist/auth/*.js",
     "./db": "./dist/db/index.js",
     "./deploy": "./dist/deploy/index.js",
     "./deploy/*.js": "./dist/deploy/*.js",

package/src/admin/adminMiddleware.ts

@@ -6,6 +6,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'
@@ -35,11 +38,17 @@ export interface RequireAdminCfg {
   andComparison?: boolean
 }
 
+/**
+ * @deprecated Use `AuthMiddleware`.
+ */
 export type AdminMiddleware = (
   reqPermissions?: string[],
   cfg?: RequireAdminCfg,
 ) => BackendRequestHandler
 
+/**
+ * @deprecated Use `AuthService.getLoginRedirectMiddleware`.
+ */
 export function createAdminMiddleware(
   adminService: BaseAdminService,
   cfgDefaults: RequireAdminCfg = {},
@@ -56,6 +65,8 @@ export function createAdminMiddleware(
  * 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: BaseAdminService,
@@ -97,6 +108,9 @@ interface LoginHtmlCfg {
   firebaseAuthProvider: string
 }
 
+/**
+ * @deprecated Use `loginHtmlHandler`.
+ */
 export function loginHtml(firebaseServiceCfg: FirebaseSharedServiceCfg): BackendRequestHandler {
   const {
     apiKey: firebaseApiKey,
@@ -124,6 +138,9 @@ const getLoginHtml = _memoized((cfg: LoginHtmlCfg) => {
     .replaceAll('<%= firebaseAuthProvider %>', cfg.firebaseAuthProvider)
 })
 
+/**
+ * @deprecated Use `AuthService.getLoginRedirectMiddleware`.
+ */
 export function getLoginHtmlRedirect(href: string): string {
   return `
 <html>

package/src/admin/base.admin.service.ts

@@ -7,6 +7,8 @@ import type { BackendRequest, BackendRequestHandler } from '../server/server.mod
 
 /**
  * Base implementation based on Firebase Auth tokens passed as 'admin_token' cookie.
+ *
+ * @deprecated Use `AuthService`, with `FirebaseAuthService` for `authenticate`.
  */
 export class BaseAdminService {
   constructor(
@@ -309,6 +311,9 @@ const adminInfoDisabled = (): AdminInfo => ({
   permissions: [],
 })
 
+/**
+ * @deprecated Use `AuthServiceCfg` and `FirebaseAuthServiceCfg`.
+ */
 export interface AdminServiceCfg {
   /**
    * @default 'admin_token'
@@ -323,11 +328,17 @@ 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
@@ -335,6 +346,9 @@ export interface ResolvedAdmin {
   permissions?: Set<string>
 }
 
+/**
+ * @deprecated Use `AuthCheckOptions`.
+ */
 export interface CheckPermissionsOptions {
   /**
    * false - one granted permission is enough.
@@ -344,6 +358,9 @@ export interface CheckPermissionsOptions {
   andComparison?: boolean
 }
 
+/**
+ * @deprecated Use `AuthService.has` / `AuthService.require`.
+ */
 export interface CheckPermissionsResult {
   /** undefined - no valid admin token */
   email?: string

package/src/admin/firebaseAuth.service.ts

@@ -0,0 +1,139 @@
+import { _Memo, _memoized } from '@naturalcycles/js-lib/decorators'
+import { _assert } from '@naturalcycles/js-lib/error'
+import { fs2 } from '@naturalcycles/nodejs-lib/fs2'
+import type { Auth, FirebaseAuthError } from 'firebase-admin/auth'
+import { srcDir } from '../paths.cnst.js'
+import type { BackendRequest, BackendRequestHandler } from '../server/server.model.js'
+import type { FirebaseSharedServiceCfg } from './firebase.shared.service.js'
+
+/**
+ * Verifies Firebase Auth tokens.
+ */
+export class FirebaseAuthService {
+  constructor(
+    private loadFirebaseAuth: () => Promise<FirebaseTokenVerifier>,
+    public cfg: FirebaseAuthServiceCfg,
+  ) {}
+
+  /**
+   * Reads the configured cookie first, then the header.
+   */
+  getToken(req: BackendRequest): string | undefined {
+    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: string | undefined): Promise<string | undefined> {
+    if (!token) return
+
+    const auth = await this.getFirebaseAuth()
+    try {
+      const decodedToken = await auth.verifyIdToken(token)
+      return decodedToken.email
+    } catch (err) {
+      if ((err as Partial<FirebaseAuthError> | undefined)?.hasCode?.('id-token-expired')) return
+      throw err
+    }
+  }
+
+  @_Memo()
+  private async getFirebaseAuth(): Promise<FirebaseTokenVerifier> {
+    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(): BackendRequestHandler {
+    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()
+    }
+  }
+}
+
+/**
+ * Serves login.html, configured for Firebase Auth.
+ */
+export function loginHtmlHandler(
+  firebaseServiceCfg: FirebaseSharedServiceCfg,
+): BackendRequestHandler {
+  const {
+    apiKey: firebaseApiKey,
+    authDomain: firebaseAuthDomain,
+    adminAuthProvider: firebaseAuthProvider = 'GoogleAuthProvider',
+  } = firebaseServiceCfg
+
+  return (_req, res) => {
+    res.send(
+      getLoginHtml({
+        firebaseApiKey,
+        firebaseAuthDomain,
+        firebaseAuthProvider,
+      }),
+    )
+  }
+}
+
+const getLoginHtml = _memoized((cfg: LoginHtmlCfg) => {
+  return fs2
+    .readText(`${srcDir}/admin/login.html`)
+    .replaceAll('<%= firebaseApiKey %>', cfg.firebaseApiKey)
+    .replaceAll('<%= firebaseAuthDomain %>', cfg.firebaseAuthDomain)
+    .replaceAll('<%= firebaseAuthProvider %>', cfg.firebaseAuthProvider)
+})
+
+/**
+ * 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
+}
+
+interface LoginHtmlCfg {
+  firebaseApiKey: string
+  firebaseAuthDomain: string
+  firebaseAuthProvider: string
+}

package/src/admin/index.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/src/admin/login.html

@@ -63,7 +63,8 @@
       })
 
       const qs = Object.fromEntries(new URLSearchParams(location.search))
-      const { autoLogin, logout, returnUrl, adminTokenKey = 'admin_token' } = qs
+      const { autoLogin, logout, adminTokenKey = 'admin_token' } = qs
+      const returnUrl = toSafeReturnUrl(qs.returnUrl)
       // console.log(qs)
 
       const app = createApp({
@@ -137,6 +138,20 @@
         alert('Error\n ' + JSON.stringify(err, null, 2))
       }
 
+      /**
+       * `returnUrl` is client-controlled. Only http(s) urls are allowed:
+       * anything else (e.g `javascript:`) would otherwise be executed by `location.href = returnUrl`
+       * in the context of this page, where the token is exposed.
+       */
+      function toSafeReturnUrl(url) {
+        if (!url) return
+        try {
+          const { protocol } = new URL(url, location.href)
+          if (protocol === 'http:' || protocol === 'https:') return url
+        } catch {}
+        console.warn('ignoring invalid returnUrl', url)
+      }
+
       async function postToken(token) {
         await fetch(`/admin/login`, {
           method: 'post',

package/src/admin/secureHeaderMiddleware.ts

@@ -5,6 +5,9 @@ import type { AdminMiddleware, RequireAdminCfg } from './adminMiddleware.js'
 import { requireAdminPermissions } from './adminMiddleware.js'
 import type { BaseAdminService } from './base.admin.service.js'
 
+/**
+ * @deprecated Use `AuthLoginRedirectMiddlewareCfg` with `secureHeader`.
+ */
 export interface SecureHeaderMiddlewareCfg extends RequireAdminCfg {
   adminService: BaseAdminService
 
@@ -22,6 +25,8 @@ 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 function createSecureHeaderMiddleware(cfg: SecureHeaderMiddlewareCfg): AdminMiddleware {
   return reqPermissions => requireSecureHeaderOrAdmin(cfg, reqPermissions)