@naturalcycles/backend-lib 9.73.1 → 9.75.0

package/dist/server/asyncLocalStorageMiddleware.js

@@ -1,5 +1,6 @@
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { _lazyValue } from '@naturalcycles/js-lib';
+import { commonLoggerCreate } from '@naturalcycles/js-lib/log';
 import { ciLogger, devLogger, gcpStructuredLogger } from './logMiddleware.js';
 const { GAE_INSTANCE, K_SERVICE, CI } = process.env;
 const isGAE = !!GAE_INSTANCE;
@@ -43,9 +44,4 @@ export function getRequestLogger() {
  *
  * @experimental
  */
-export const requestLogger = {
-    debug: (...args) => getRequestLogger().debug(...args),
-    log: (...args) => getRequestLogger().log(...args),
-    warn: (...args) => getRequestLogger().warn(...args),
-    error: (...args) => getRequestLogger().error(...args),
-};
+export const requestLogger = commonLoggerCreate(({ level, ...data }) => getRequestLogger()[level](data));

package/dist/server/genericErrorMiddleware.js

@@ -40,10 +40,10 @@ export function respondWithError(req, res, err) {
     else {
         // 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
         // todo: add userId from the "Context" (or, just req.userId?) to the log

package/dist/server/logMiddleware.js

@@ -1,9 +1,9 @@
 import { inspect } from 'node:util';
-import { _isPlainObject } from '@naturalcycles/js-lib';
 import { _anyToErrorObject } from '@naturalcycles/js-lib/error';
+import { commonLoggerCreate } from '@naturalcycles/js-lib/log';
 import { _safeJsonStringify } from '@naturalcycles/js-lib/string/safeJsonStringify.js';
 import { _objectAssign } from '@naturalcycles/js-lib/types';
-import { _inspect } from '@naturalcycles/nodejs-lib';
+import { logEntryToString } from '@naturalcycles/nodejs-lib';
 import { dimGrey } from '@naturalcycles/nodejs-lib/colors';
 const { GOOGLE_CLOUD_PROJECT, GAE_INSTANCE, K_SERVICE, APP_ENV } = process.env;
 const isGAE = !!GAE_INSTANCE;
@@ -16,81 +16,49 @@ 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 = {
-    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 = commonLoggerCreate(entry => writeGCPStructuredLog({}, entry));
 /**
  * Fancy development logger, to be used in outside-of-request situations
  * (otherwise req.log should be used).
  */
-export const devLogger = {
-    debug: (...args) => logToDev(null, args),
-    log: (...args) => logToDev(null, args),
-    warn: (...args) => logToDev(null, args),
-    error: (...args) => logToDev(null, args),
-};
+export const devLogger = commonLoggerCreate(entry => logToDev(null, entry));
 /**
  * Same as devLogger, but without colors (e.g to not confuse Sentry).
  */
-export const ciLogger = {
-    debug: (...args) => logToCI(args),
-    log: (...args) => logToCI(args),
-    warn: (...args) => logToCI(args),
-    error: (...args) => logToCI(args),
+export const ciLogger = commonLoggerCreate(logToCI);
+const gcpSeverityByLevel = {
+    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, args) {
-    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, entry) {
+    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;
+            fields['err'] = err;
         if (msg !== undefined)
-            entry['message'] = msg;
+            fields['message'] = msg;
     }
-    console.log(_safeJsonStringify({ ...entry, ...meta }));
+    console.log(_safeJsonStringify({ ...fields, ...meta, severity: gcpSeverityByLevel[level] }));
 }
-function logToDev(requestId, args) {
+function logToDev(requestId, entry) {
     // 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 = [];
-    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) {
-    console.log(args.map(a => _inspect(a, { includeErrorStack: true, colors: false })).join(' '));
+function logToCI(entry) {
+    console.log(logEntryToString(entry, { colors: false }));
 }
 export function logMiddleware() {
     if (isGAE || isCloudRun) {
@@ -117,12 +85,7 @@ export function logMiddleware() {
             if (isGAE) {
                 meta['appengine.googleapis.com/request_id'] = req.header('x-appengine-request-log-id');
             }
-            _objectAssign(req, {
-                debug: (...args) => writeGCPStructuredLog({ ...meta, severity: 'DEBUG' }, args),
-                log: (...args) => writeGCPStructuredLog({ ...meta, severity: 'INFO' }, args),
-                warn: (...args) => writeGCPStructuredLog({ ...meta, severity: 'WARNING' }, args),
-                error: (...args) => writeGCPStructuredLog({ ...meta, severity: 'ERROR' }, args),
-            });
+            _objectAssign(req, commonLoggerCreate(entry => writeGCPStructuredLog(meta, entry)));
             next();
         };
     }
@@ -131,18 +94,14 @@ export function logMiddleware() {
         return function devLogHandler(req, _res, next) {
             // Local machine
             req.requestId = String(++reqCounter);
-            req.debug =
-                req.log =
-                    req.warn =
-                        req.error =
-                            (...args) => logToDev(req.requestId, args);
+            _objectAssign(req, commonLoggerCreate(entry => logToDev(req.requestId, entry)));
             next();
         };
     }
     // 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) => logToCI(args);
+        _objectAssign(req, ciLogger);
         next();
     };
 }

package/dist/server/server.model.d.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';
 /**
@@ -8,11 +8,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.
@@ -50,11 +46,7 @@ export type BackendErrorRequestHandler = (err: any, req: BackendRequest, res: Ba
 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;
         bodyParserTimeout?: NodeJS.Timeout;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@naturalcycles/backend-lib",
   "type": "module",
-  "version": "9.73.1",
+  "version": "9.75.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(
@@ -220,7 +222,7 @@ export class BaseAdminService {
         return // skip logging, expected error
       }
 
-      req.error(`getEmailByToken error:`, err)
+      req.error({ msg: `getEmailByToken error:`, err })
     }
   }
 
@@ -257,12 +259,12 @@ export class BaseAdminService {
     granted: boolean,
     meta: AnyObject = {},
   ): Promise<void> {
-    req.log(
-      `${dimGrey(email)} ${required ? 'required' : 'optional'} permissions check [${dimGrey(
+    req.log({
+      ...meta,
+      msg: `${dimGrey(email)} ${required ? 'required' : 'optional'} permissions check [${dimGrey(
         reqPermissions.join(', '),
       )}]: ${granted ? green('GRANTED') : red('DENIED')}`,
-      meta,
-    )
+    })
   }
 
   /**
@@ -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/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)