@naturalcycles/backend-lib 9.74.0 → 9.76.0

package/src/auth/auth.service.ts

@@ -0,0 +1,303 @@
+import { _assert, AppError } from '@naturalcycles/js-lib/error'
+import type { ErrorData } from '@naturalcycles/js-lib/error'
+import type { AnyObject, Promisable } from '@naturalcycles/js-lib/types'
+import { timingSafeStringEqual } from '@naturalcycles/nodejs-lib'
+import type { BackendRequest, BackendRequestHandler } from '../server/server.model.js'
+
+/**
+ * Authenticates requests and checks permissions.
+ */
+export class AuthService<CTX = AnyObject> {
+  constructor(cfg: AuthServiceCfg<CTX>) {
+    this.cfg = {
+      authEnabled: true,
+      ...cfg,
+    }
+  }
+
+  cfg: AuthServiceCfg<CTX> & { authEnabled: boolean }
+
+  /**
+   * Responds JSON 401 / 403.
+   */
+  getMiddleware(cfg: AuthMiddlewareCfg<CTX> = {}): AuthMiddleware {
+    return reqPermissions => this.createHandler(cfg, reqPermissions)
+  }
+
+  /**
+   * Like `getMiddleware`, but 401 redirects to the login page.
+   */
+  getLoginRedirectMiddleware(cfg: AuthLoginRedirectMiddlewareCfg<CTX>): AuthMiddleware {
+    const loginHref = this.getLoginHref(cfg)
+    return reqPermissions => this.createHandler(cfg, reqPermissions, loginHref)
+  }
+
+  private createHandler(
+    cfg: AuthMiddlewareCfg<CTX>,
+    reqPermissions: string[] = [],
+    loginHref?: string,
+  ): BackendRequestHandler {
+    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: BackendRequest): Promise<ResolvedAuth> {
+    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: ResolvedAuth | undefined,
+    reqPermissions: string[] = [],
+    opt: AuthCheckOptions<CTX> = {},
+  ): PermissionInfo {
+    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() }
+  }
+
+  private checkSubject(
+    resolved: AuthenticatedAuth,
+    reqPermissions: string[],
+    opt: AuthCheckOptions<CTX>,
+  ): string[] | undefined {
+    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
+  }
+
+  private assertAuthenticated(
+    resolved: ResolvedAuth | undefined,
+  ): asserts resolved is AuthenticatedAuth {
+    _assert(resolved?.subject, 'authentication required', this.authRequiredData())
+  }
+
+  private authRequiredData(): ErrorData {
+    return {
+      authRequired: true,
+      backendResponseStatusCode: 401,
+      userFriendly: true,
+    }
+  }
+
+  private assertGranted(
+    subject: string,
+    grantedPermissions: string[] | undefined,
+    reqPermissions: string[],
+  ): asserts grantedPermissions is string[] {
+    _assert(grantedPermissions, `Permissions required: [${reqPermissions.join(', ')}]`, {
+      permissionsRequired: reqPermissions,
+      subject,
+      backendResponseStatusCode: 403,
+      userFriendly: true,
+    })
+  }
+
+  /**
+   * undefined - not granted.
+   */
+  private getGrantedPermissions(
+    permissions: string[] | undefined,
+    reqPermissions: string[],
+    andComparison: boolean,
+  ): string[] | undefined {
+    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
+  }
+
+  private getLoginHref(cfg: AuthLoginRedirectMiddlewareCfg<CTX>): string {
+    return `${cfg.loginHtmlPath}?autoLogin=1&returnUrl=\${encodeURIComponent(location.href)}`
+  }
+
+  private getLoginHtmlRedirect(href: string): string {
+    return `
+<html>
+<body>401 Authentication Required
+<script>
+  document.write(\`: <a href="${href}" id="loginLink">Login</a>\`)
+  document.getElementById('loginLink').click()
+</script>
+</body>
+</html>
+`
+  }
+}
+
+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[]
+}
+
+type AuthenticatedAuth = ResolvedAuth & { subject: string }
+
+export interface ResolvedAuth {
+  /** undefined - not authenticated */
+  subject?: string
+  /** undefined - no permission set */
+  permissions?: string[]
+  /** Result of `isAlwaysAuthorized` */
+  alwaysAuthorized?: boolean
+}

package/src/auth/index.ts

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

package/src/server/basicAuthMiddleware.ts

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

package/src/server/request.util.ts

@@ -10,9 +10,34 @@ 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 function getRequestEndpoint(req: BackendRequest, stripPrefix?: string): string {
-  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: BackendRequest, stripPrefix?: string): string {
+  return buildRequestEndpoint(req, stripPrefix, identity)
+}
+
+function buildRequestEndpoint(
+  req: BackendRequest,
+  stripPrefix: string | undefined,
+  sanitize: (path: string) => string,
+): string {
+  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)
   }
@@ -23,3 +48,14 @@ export function getRequestEndpoint(req: BackendRequest, stripPrefix?: string): s
 
   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: string): string {
+  return path.replace(UNSAFE_PATH_CHAR, '_')
+}
+
+const identity = (path: string): string => path

package/src/server/requestTimeoutMiddleware.ts

@@ -21,6 +21,14 @@ 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
 }
 
 const code = 'REQUEST_TIMEOUT'
@@ -33,6 +41,7 @@ export function requestTimeoutMiddleware(
     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),
@@ -41,13 +50,12 @@ export function requestTimeoutMiddleware(
     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] as string)
-      : defTimeoutSeconds
+    const timeoutSeconds = getTimeoutSeconds(req, defTimeoutSeconds, maxTimeoutSeconds)
 
     // If requestTimeout was previously set - cancel it first
     // Then set the new requestTimeout and handler
@@ -76,6 +84,26 @@ export function requestTimeoutMiddleware(
   }
 }
 
+/**
+ * `?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: BackendRequest,
+  defTimeoutSeconds: NumberOfSeconds,
+  maxTimeoutSeconds: NumberOfSeconds,
+): NumberOfSeconds {
+  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)
+}
+
 export interface CustomRequestTimeoutMiddlewareCfg {
   /**
    * @default 120
@@ -87,7 +115,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/src/server/serverStatsMiddleware.ts

@@ -5,11 +5,12 @@ 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 type { StringMap } from '@naturalcycles/js-lib/types'
 import { onFinished } from '../onFinished.js'
 import { getRequestEndpoint } from './request.util.js'
-import type { BackendRequestHandler } from './server.model.js'
+import type { BackendRequest, BackendRequestHandler } from './server.model.js'
 
 const { GAE_INSTANCE } = process.env
 
@@ -86,7 +87,7 @@ export const serverStatsHTMLHandler: BackendRequestHandler = (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>`),
@@ -97,7 +98,7 @@ export const serverStatsHTMLHandler: BackendRequestHandler = (req, res) => {
     '</table>',
   ].join('\n')
 
-  res.send(html)
+  res.type('html').send(html)
 }
 
 /**
@@ -113,7 +114,12 @@ export function serverStatsMiddleware(): BackendRequestHandler {
       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),
@@ -137,6 +143,14 @@ export function serverStatsMiddleware(): BackendRequestHandler {
   }
 }
 
+/**
+ * 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: BackendRequest): string {
+  return `${req.method} ${req.baseUrl.toLowerCase()}/*`
+}
+
 function cleanupServerStats(): void {
   if (Object.keys(serverStatsMap).length <= MAX_ENDPOINTS) return