@naturalcycles/backend-lib 9.73.1 → 9.75.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/sentry/sentry.shared.service.ts

@@ -1,8 +1,10 @@
 import { _anyToError, _isErrorObject } from '@naturalcycles/js-lib/error'
+import { commonLoggerCreate } from '@naturalcycles/js-lib/log'
 import type { CommonLogger, CommonLogLevel } from '@naturalcycles/js-lib/log'
+import { _omit } from '@naturalcycles/js-lib/object/object.util.js'
 import type { Primitive, StringMap } from '@naturalcycles/js-lib/types'
 import type { InspectAnyOptions } from '@naturalcycles/nodejs-lib'
-import { _inspect } from '@naturalcycles/nodejs-lib'
+import { _inspect, logEntryToString } from '@naturalcycles/nodejs-lib'
 import type { Breadcrumb, SeverityLevel } from '@sentry/node-core/light'
 import type * as SentryLib from '@sentry/node-core/light'
 import { getRequestLogger } from '../server/asyncLocalStorageMiddleware.js'
@@ -78,7 +80,7 @@ export class SentrySharedService {
 
     // Using request-aware logger here
     // Log both the error and attached ErrorData (if any)
-    getRequestLogger().error(...[err_, data].filter(Boolean))
+    getRequestLogger().error({ err: err_, ...data })
 
     if (data?.report === false) {
       // Skip reporting the error
@@ -106,7 +108,7 @@ export class SentrySharedService {
    * Returns "eventId"
    */
   captureMessage(msg: string, level?: SeverityLevel): string {
-    getRequestLogger()[sentrySeverityMap[level!] || 'log']('captureMessage:', msg)
+    getRequestLogger()[sentrySeverityMap[level!] || 'log'](`captureMessage: ${msg}`)
     return this.sentry.captureMessage(msg, level)
   }
 
@@ -122,19 +124,15 @@ export class SentrySharedService {
    * @experimental
    */
   getCommonLogger(): CommonLogger {
-    return {
-      debug: () => {}, // noop
-      log: () => {}, // noop
-      warn: () => {}, // noop
-      error: (...args) => {
-        const message = args.map(arg => _inspect(arg, INSPECT_OPT)).join(' ')
-
-        this.sentry.addBreadcrumb({
-          message,
-        })
-
-        this.sentry.captureException(_anyToError(args.length === 1 ? args[0] : args))
-      },
-    }
+    return commonLoggerCreate(entry => {
+      if (entry.level !== 'error') return // noop
+      const { msg, err } = entry
+
+      this.sentry.addBreadcrumb({
+        message: logEntryToString(entry, INSPECT_OPT),
+      })
+
+      this.sentry.captureException(_anyToError(err ?? msg ?? _omit(entry, ['level'])))
+    })
   }
 }

package/src/server/asyncLocalStorageMiddleware.ts

@@ -1,5 +1,6 @@
 import { AsyncLocalStorage } from 'node:async_hooks'
 import { _lazyValue } from '@naturalcycles/js-lib'
+import { commonLoggerCreate } from '@naturalcycles/js-lib/log'
 import type { CommonLogger } from '@naturalcycles/js-lib/log'
 import { ciLogger, devLogger, gcpStructuredLogger } from './logMiddleware.js'
 import type { BackendRequest, BackendRequestHandler } from './server.model.js'
@@ -53,9 +54,6 @@ export function getRequestLogger(): CommonLogger {
  *
  * @experimental
  */
-export const requestLogger: CommonLogger = {
-  debug: (...args) => getRequestLogger().debug(...args),
-  log: (...args) => getRequestLogger().log(...args),
-  warn: (...args) => getRequestLogger().warn(...args),
-  error: (...args) => getRequestLogger().error(...args),
-}
+export const requestLogger: CommonLogger = commonLoggerCreate(({ level, ...data }) =>
+  getRequestLogger()[level](data),
+)

package/src/server/genericErrorMiddleware.ts

@@ -75,9 +75,9 @@ export function respondWithError(req: BackendRequest, res: BackendResponse, err:
     // because errorService was not provided - we are going to log the error here
 
     if (headersSent) {
-      req.error(`error after headersSent:`, err)
+      req.error({ msg: `error after headersSent:`, err })
     } else {
-      req.error(err)
+      req.error({ err })
     }
 
     // todo: add endpoint to the log

package/src/server/logMiddleware.ts

@@ -1,11 +1,11 @@
 import { inspect } from 'node:util'
-import { _isPlainObject } from '@naturalcycles/js-lib'
 import { _anyToErrorObject } from '@naturalcycles/js-lib/error'
-import type { CommonLogger } from '@naturalcycles/js-lib/log'
+import { commonLoggerCreate } from '@naturalcycles/js-lib/log'
+import type { CommonLogger, CommonLogLevel, LogEntry } from '@naturalcycles/js-lib/log'
 import { _safeJsonStringify } from '@naturalcycles/js-lib/string/safeJsonStringify.js'
 import { _objectAssign } from '@naturalcycles/js-lib/types'
 import type { AnyObject } from '@naturalcycles/js-lib/types'
-import { _inspect } from '@naturalcycles/nodejs-lib'
+import { logEntryToString } from '@naturalcycles/nodejs-lib'
 import { dimGrey } from '@naturalcycles/nodejs-lib/colors'
 import type { BackendRequestHandler } from './server.model.js'
 
@@ -22,85 +22,54 @@ let reqCounter = 0
  * Logger that logs in "GCP structured log" format.
  * To be used in outside-of-request situations (otherwise req.log should be used).
  */
-export const gcpStructuredLogger: CommonLogger = {
-  debug: (...args) => writeGCPStructuredLog({ severity: 'DEBUG' }, args),
-  log: (...args) => writeGCPStructuredLog({}, args),
-  warn: (...args) => writeGCPStructuredLog({ severity: 'WARNING' }, args),
-  error: (...args) => writeGCPStructuredLog({ severity: 'ERROR' }, args),
-}
+export const gcpStructuredLogger: CommonLogger = commonLoggerCreate(entry =>
+  writeGCPStructuredLog({}, entry),
+)
 
 /**
  * Fancy development logger, to be used in outside-of-request situations
  * (otherwise req.log should be used).
  */
-export const devLogger: CommonLogger = {
-  debug: (...args) => logToDev(null, args),
-  log: (...args) => logToDev(null, args),
-  warn: (...args) => logToDev(null, args),
-  error: (...args) => logToDev(null, args),
-}
+export const devLogger: CommonLogger = commonLoggerCreate(entry => logToDev(null, entry))
 
 /**
  * Same as devLogger, but without colors (e.g to not confuse Sentry).
  */
-export const ciLogger: CommonLogger = {
-  debug: (...args) => logToCI(args),
-  log: (...args) => logToCI(args),
-  warn: (...args) => logToCI(args),
-  error: (...args) => logToCI(args),
+export const ciLogger: CommonLogger = commonLoggerCreate(logToCI)
+
+const gcpSeverityByLevel: Record<CommonLogLevel, string> = {
+  debug: 'DEBUG',
+  log: 'INFO',
+  warn: 'WARNING',
+  error: 'ERROR',
 }
 
 // Documented here: https://cloud.google.com/logging/docs/structured-logging
 // Cloud Run logging: https://cloud.google.com/run/docs/logging
-function writeGCPStructuredLog(meta: AnyObject, args: any[]): void {
-  if (args.length !== 1 || !_isPlainObject(args[0])) {
-    console.log(
-      JSON.stringify({
-        message: args.map(a => (typeof a === 'string' ? a : inspect(a))).join(' '),
-        ...meta,
-      }),
-    )
-    return
-  }
-
-  const { msg, err, ...entry } = args[0]
+function writeGCPStructuredLog(meta: AnyObject, entry: LogEntry): void {
+  const { level, msg, err, ...fields } = entry
   if (err instanceof Error) {
-    entry['err'] = _anyToErrorObject(err)
-    entry['message'] = msg ? `${msg}\n${inspect(err)}` : inspect(err)
+    fields['err'] = _anyToErrorObject(err)
+    fields['message'] = msg ? `${msg}\n${inspect(err)}` : inspect(err)
   } else {
-    if (err !== undefined) entry['err'] = err
-    if (msg !== undefined) entry['message'] = msg
+    if (err !== undefined) fields['err'] = err
+    if (msg !== undefined) fields['message'] = msg
   }
-  console.log(_safeJsonStringify({ ...entry, ...meta }))
+  console.log(_safeJsonStringify({ ...fields, ...meta, severity: gcpSeverityByLevel[level] }))
 }
 
-function logToDev(requestId: string | null, args: any[]): void {
+function logToDev(requestId: string | null, entry: LogEntry): void {
   // Run on local machine
-  if (args.length !== 1 || !_isPlainObject(args[0])) {
-    console.log(
-      [
-        requestId ? [dimGrey(`[${requestId}]`)] : [],
-        ...args.map(a => _inspect(a, { includeErrorStack: true, colors: true })),
-      ].join(' '),
-    )
-    return
-  }
-
-  const { msg, err, ...rest } = args[0]
-  const parts: string[] = []
-  if (requestId) parts.push(dimGrey(`[${requestId}]`))
-  if (msg !== undefined) parts.push(String(msg))
-  if (err !== undefined) parts.push(_inspect(err, { includeErrorStack: true, colors: true }))
-  if (Object.keys(rest).length) parts.push(dimGrey(_inspect(rest, { colors: false })))
-  console.log(parts.join(' '))
+  const line = logEntryToString(entry, { colors: true })
+  console.log(requestId ? `${dimGrey(`[${requestId}]`)} ${line}` : line)
 }
 
 /**
  * Same as logToDev, but without request and without colors.
  * This is to not confuse e.g Sentry when it picks up messages with colors
  */
-function logToCI(args: any[]): void {
-  console.log(args.map(a => _inspect(a, { includeErrorStack: true, colors: false })).join(' '))
+function logToCI(entry: LogEntry): void {
+  console.log(logEntryToString(entry, { colors: false }))
 }
 
 export function logMiddleware(): BackendRequestHandler {
@@ -130,12 +99,10 @@ export function logMiddleware(): BackendRequestHandler {
         meta['appengine.googleapis.com/request_id'] = req.header('x-appengine-request-log-id')
       }
 
-      _objectAssign(req, {
-        debug: (...args: any[]) => writeGCPStructuredLog({ ...meta, severity: 'DEBUG' }, args),
-        log: (...args: any[]) => writeGCPStructuredLog({ ...meta, severity: 'INFO' }, args),
-        warn: (...args: any[]) => writeGCPStructuredLog({ ...meta, severity: 'WARNING' }, args),
-        error: (...args: any[]) => writeGCPStructuredLog({ ...meta, severity: 'ERROR' }, args),
-      } satisfies CommonLogger)
+      _objectAssign(
+        req,
+        commonLoggerCreate(entry => writeGCPStructuredLog(meta, entry)),
+      )
 
       next()
     }
@@ -146,11 +113,10 @@ export function logMiddleware(): BackendRequestHandler {
     return function devLogHandler(req, _res, next) {
       // Local machine
       req.requestId = String(++reqCounter)
-      req.debug =
-        req.log =
-        req.warn =
-        req.error =
-          (...args: any[]) => logToDev(req.requestId!, args)
+      _objectAssign(
+        req,
+        commonLoggerCreate(entry => logToDev(req.requestId!, entry)),
+      )
       next()
     }
   }
@@ -158,7 +124,7 @@ export function logMiddleware(): BackendRequestHandler {
   // Otherwise, return "simple" logger
   // This includes: unit tests, CI environments
   return function simpleLogHandler(req, _res, next) {
-    req.debug = req.log = req.warn = req.error = (...args: any[]) => logToCI(args)
+    _objectAssign(req, ciLogger)
     next()
   }
 }

package/src/server/server.model.ts

@@ -1,4 +1,4 @@
-import type { CommonLogFunction } from '@naturalcycles/js-lib/log'
+import type { CommonLogger } from '@naturalcycles/js-lib/log'
 import type { Promisable } from '@naturalcycles/js-lib/types'
 import type { Application, IRouter, NextFunction, Request, Response } from 'express'
 
@@ -9,12 +9,7 @@ import type { Application, IRouter, NextFunction, Request, Response } from 'expr
  * `BackendRequest` seems to not conflict with anything right now.
  * Previous name `ExpressRequest` was clashing with Sentry.
  */
-export interface BackendRequest<BODY = unknown> extends Request {
-  debug: CommonLogFunction
-  log: CommonLogFunction
-  warn: CommonLogFunction
-  error: CommonLogFunction
-
+export interface BackendRequest<BODY = unknown> extends Request, CommonLogger {
   requestId?: string
   /**
    * Only used for request logging purposes.
@@ -71,12 +66,7 @@ export type BackendRouter = IRouter
 export type BackendApplication = Application
 
 declare module 'http' {
-  interface IncomingMessage {
-    debug: CommonLogFunction
-    log: CommonLogFunction
-    warn: CommonLogFunction
-    error: CommonLogFunction
-
+  interface IncomingMessage extends CommonLogger {
     requestId?: string
 
     requestTimeout?: NodeJS.Timeout