@naturalcycles/backend-lib 9.71.1 → 9.73.0

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

@@ -1,21 +1,6 @@
+import type { AnyObject } from '@naturalcycles/js-lib/types';
 import type { Auth } from 'firebase-admin/auth';
 import type { BackendRequest, BackendRequestHandler } from '../server/server.model.js';
-export interface AdminServiceCfg {
-    /**
-     * @default 'admin_token'
-     */
-    adminTokenKey?: string;
-    /**
-     * If false - disables auth completely (useful for debugging locally, but never in production).
-     *
-     * @default true
-     */
-    authEnabled?: boolean;
-}
-export interface AdminInfo {
-    email: string;
-    permissions: string[];
-}
 /**
  * Base implementation based on Firebase Auth tokens passed as 'admin_token' cookie.
  */
@@ -24,35 +9,47 @@ export declare class BaseAdminService {
     constructor(loadFirebaseAuth: () => Promise<Auth>, cfg: AdminServiceCfg);
     cfg: Required<AdminServiceCfg>;
     adminInfoDisabled(): AdminInfo;
+    isAdmin(req: BackendRequest | undefined): Promise<boolean>;
+    getAdminInfo(req: BackendRequest): Promise<AdminInfo | undefined>;
+    hasPermission(req: BackendRequest, reqPermission: string, meta?: AnyObject): Promise<boolean>;
+    requirePermission(req: BackendRequest, reqPermission: string, meta?: AnyObject): Promise<AdminInfo>;
     /**
-     * To be extended.
-     *
-     * Returns undefined if it's not an Admin.
-     * Otherwise returns Set of permissions.
-     * Empty array means it IS and Admin, but has no permissions (except being an Admin).
+     * Returns AdminInfo if it has all required permissions.
+     * Otherwise returns undefined
      */
-    getEmailPermissions(email?: string): Promise<Set<string> | undefined>;
+    hasPermissions(req: BackendRequest, reqPermissions?: string[], meta?: AnyObject): Promise<AdminInfo | undefined>;
+    requirePermissions(req: BackendRequest, reqPermissions?: string[], meta?: AnyObject, andComparison?: boolean): Promise<AdminInfo>;
     /**
-     * To be extended.
+     * Doesn't check permissions, nor `authEnabled`. See `checkPermissions`.
      */
-    protected onPermissionCheck(req: BackendRequest, email: string, reqPermissions: string[], required: boolean, granted: boolean, meta?: Record<string, any>): Promise<void>;
-    getEmailByToken(req: BackendRequest, adminToken?: string): Promise<string | undefined>;
-    private getFirebaseAuth;
+    resolveAdmin(req: BackendRequest): Promise<ResolvedAdmin>;
+    /**
+     * Doesn't log or throw. See `requireGranted`.
+     */
+    checkPermissions(admin: ResolvedAdmin, reqPermissions?: string[], opt?: CheckPermissionsOptions): CheckPermissionsResult;
+    /**
+     * Throws 401 if there's no email, 403 if not granted.
+     */
+    requireGranted(result: CheckPermissionsResult): AdminInfo;
     /**
      * Current implementation is based on req=Request (from Express).
      * Override if needed.
      */
     getAdminToken(req: BackendRequest): string | undefined;
-    isAdmin(req: BackendRequest | undefined): Promise<boolean>;
-    getAdminInfo(req: BackendRequest): Promise<AdminInfo | undefined>;
+    getEmailByToken(req: BackendRequest, adminToken?: string): Promise<string | undefined>;
+    private getFirebaseAuth;
     /**
-     * Returns AdminInfo if it has all required permissions.
-     * Otherwise returns undefined
+     * To be extended.
+     *
+     * Returns undefined if it's not an Admin.
+     * Otherwise returns Set of permissions.
+     * Empty array means it IS and Admin, but has no permissions (except being an Admin).
+     */
+    getEmailPermissions(email?: string): Promise<Set<string> | undefined>;
+    /**
+     * To be extended.
      */
-    hasPermissions(req: BackendRequest, reqPermissions?: string[], meta?: Record<string, any>): Promise<AdminInfo | undefined>;
-    requirePermissions(req: BackendRequest, reqPermissions?: string[], meta?: Record<string, any>, andComparison?: boolean): Promise<AdminInfo>;
-    hasPermission(req: BackendRequest, reqPermission: string, meta?: Record<string, any>): Promise<boolean>;
-    requirePermission(req: BackendRequest, reqPermission: string, meta?: Record<string, any>): Promise<AdminInfo>;
+    protected onPermissionCheck(req: BackendRequest, email: string, reqPermissions: string[], required: boolean, granted: boolean, meta?: AnyObject): Promise<void>;
     /**
      * Install it on POST /admin/login url
      *
@@ -64,3 +61,42 @@ export declare class BaseAdminService {
      */
     getFirebaseAuthLoginHandler(): BackendRequestHandler;
 }
+export interface AdminServiceCfg {
+    /**
+     * @default 'admin_token'
+     */
+    adminTokenKey?: string;
+    /**
+     * If false - disables auth completely (useful for debugging locally, but never in production).
+     *
+     * @default true
+     */
+    authEnabled?: boolean;
+}
+export interface AdminInfo {
+    email: string;
+    permissions: string[];
+}
+export interface ResolvedAdmin {
+    /** undefined - no valid admin token */
+    email?: string;
+    /** undefined - not an Admin */
+    permissions?: Set<string>;
+}
+export interface CheckPermissionsOptions {
+    /**
+     * false - one granted permission is enough.
+     *
+     * @default true
+     */
+    andComparison?: boolean;
+}
+export interface CheckPermissionsResult {
+    /** undefined - no valid admin token */
+    email?: string;
+    isAdmin: boolean;
+    granted: boolean;
+    reqPermissions: string[];
+    grantedPermissions: string[];
+    authDisabled: boolean;
+}

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

@@ -1,11 +1,7 @@
 import { __decorate } from "tslib";
 import { _Memo } from '@naturalcycles/js-lib/decorators';
-import { _assert, AppError } from '@naturalcycles/js-lib/error';
+import { _assert } from '@naturalcycles/js-lib/error';
 import { dimGrey, green, red } from '@naturalcycles/nodejs-lib/colors';
-const adminInfoDisabled = () => ({
-    email: 'authDisabled',
-    permissions: [],
-});
 /**
  * Base implementation based on Firebase Auth tokens passed as 'admin_token' cookie.
  */
@@ -26,64 +22,11 @@ export class BaseAdminService {
             permissions: [],
         };
     }
-    /**
-     * To be extended.
-     *
-     * Returns undefined if it's not an Admin.
-     * Otherwise returns Set of permissions.
-     * Empty array means it IS and Admin, but has no permissions (except being an Admin).
-     */
-    async getEmailPermissions(email) {
-        if (!email)
-            return;
-        console.log(`getEmailPermissions (${dimGrey(email)}) returning undefined (please override the implementation)`);
-    }
-    /**
-     * To be extended.
-     */
-    // oxlint-disable-next-line max-params
-    async onPermissionCheck(req, email, reqPermissions, required, granted, meta = {}) {
-        req.log(`${dimGrey(email)} ${required ? 'required' : 'optional'} permissions check [${dimGrey(reqPermissions.join(', '))}]: ${granted ? green('GRANTED') : red('DENIED')}`, meta);
-    }
-    async getEmailByToken(req, adminToken) {
-        if (!adminToken)
-            return;
-        try {
-            const auth = await this.getFirebaseAuth();
-            const decodedToken = await auth.verifyIdToken(adminToken);
-            const email = decodedToken?.email;
-            req.log(`admin email: ${dimGrey(email)}`);
-            return email;
-        }
-        catch (err) {
-            // example:
-            // FirebaseAuthError: Firebase ID token has expired. Get a fresh ID token from your client app and try again (auth/id-token-expired).
-            if (
-            // err instanceof FirebaseAuthError && err.hasCode('id-token-expired')
-            err?.code?.includes('id-token-expired')) {
-                return; // skip logging, expected error
-            }
-            req.error(`getEmailByToken error:`, err);
-        }
-    }
-    async getFirebaseAuth() {
-        return await this.loadFirebaseAuth();
-    }
-    /**
-     * Current implementation is based on req=Request (from Express).
-     * Override if needed.
-     */
-    getAdminToken(req) {
-        return (req.cookies?.[this.cfg.adminTokenKey] ||
-            req.header(this.cfg.adminTokenKey) ||
-            req.header('x-admin-token'));
-    }
     async isAdmin(req) {
         if (!req)
             return false;
-        const adminToken = this.getAdminToken(req);
-        const email = await this.getEmailByToken(req, adminToken);
-        return !!(await this.getEmailPermissions(email));
+        const { permissions } = await this.resolveAdmin(req);
+        return !!permissions;
     }
     async getAdminInfo(req) {
         return await this.hasPermissions(req);
@@ -92,6 +35,14 @@ export class BaseAdminService {
     // async reqAdmin (req: Request): Promise<void> {
     //   await this.reqPermissions(req)
     // }
+    // convenience method
+    async hasPermission(req, reqPermission, meta) {
+        const adminInfo = await this.hasPermissions(req, [reqPermission], meta);
+        return !!adminInfo;
+    }
+    async requirePermission(req, reqPermission, meta) {
+        return await this.requirePermissions(req, [reqPermission], meta);
+    }
     /**
      * Returns AdminInfo if it has all required permissions.
      * Otherwise returns undefined
@@ -99,70 +50,148 @@ export class BaseAdminService {
     async hasPermissions(req, reqPermissions = [], meta = {}) {
         if (!this.cfg.authEnabled)
             return adminInfoDisabled();
-        const adminToken = this.getAdminToken(req);
-        const email = await this.getEmailByToken(req, adminToken);
-        const hasPermissions = await this.getEmailPermissions(email);
-        if (!hasPermissions)
+        const admin = await this.resolveAdmin(req);
+        const { email, permissions } = admin;
+        if (!email || !permissions)
             return;
-        const granted = reqPermissions.every(p => hasPermissions.has(p));
-        void this.onPermissionCheck(req, email, reqPermissions, false, granted, meta);
-        if (!granted)
+        const result = this.checkPermissions(admin, reqPermissions);
+        void this.onPermissionCheck(req, email, reqPermissions, false, result.granted, meta);
+        if (!result.granted)
             return;
         return {
-            email: email,
-            permissions: Array.from(hasPermissions),
+            email,
+            permissions: Array.from(permissions),
         };
     }
     async requirePermissions(req, reqPermissions = [], meta = {}, andComparison = true) {
         if (!this.cfg.authEnabled)
             return adminInfoDisabled();
+        const admin = await this.resolveAdmin(req);
+        const result = this.checkPermissions(admin, reqPermissions, { andComparison });
+        if (result.email) {
+            // Log only the granted permissions (differs from reqPermissions only on OR-comparison)
+            const checkedPermissions = result.granted ? result.grantedPermissions : reqPermissions;
+            void this.onPermissionCheck(req, result.email, checkedPermissions, true, result.granted, meta);
+        }
+        return this.requireGranted(result);
+    }
+    /**
+     * Doesn't check permissions, nor `authEnabled`. See `checkPermissions`.
+     */
+    async resolveAdmin(req) {
         const adminToken = this.getAdminToken(req);
         const email = await this.getEmailByToken(req, adminToken);
-        if (!email) {
-            throw new AppError('adminToken required', {
-                adminAuthRequired: true,
-                backendResponseStatusCode: 401,
-                userFriendly: true,
-            });
+        if (!email)
+            return {};
+        const permissions = await this.getEmailPermissions(email);
+        return { email, permissions };
+    }
+    /**
+     * Doesn't log or throw. See `requireGranted`.
+     */
+    checkPermissions(admin, reqPermissions = [], opt = {}) {
+        const { andComparison = true } = opt;
+        const { email, permissions: hasPermissions } = admin;
+        const isAdmin = !!hasPermissions;
+        if (!this.cfg.authEnabled) {
+            return {
+                email,
+                isAdmin,
+                granted: true,
+                reqPermissions,
+                grantedPermissions: [],
+                authDisabled: true,
+            };
         }
-        const hasPermissions = await this.getEmailPermissions(email);
         const grantedPermissions = hasPermissions
             ? reqPermissions.filter(p => hasPermissions.has(p))
             : [];
-        let granted;
-        if (andComparison) {
-            granted = !!hasPermissions && grantedPermissions.length === reqPermissions.length; // All permissions granted
-            void this.onPermissionCheck(req, email, reqPermissions, true, granted, meta);
-        }
-        else {
-            granted = !!hasPermissions && grantedPermissions.length > 0;
-            if (granted) {
-                // Require the permission(s), but only the ones the user was actually granted. 1+ is required
-                void this.onPermissionCheck(req, email, grantedPermissions, true, granted, meta);
-            }
-            else {
-                void this.onPermissionCheck(req, email, reqPermissions, true, granted, meta);
-            }
-        }
-        if (!granted) {
-            throw new AppError(`Admin permissions required: [${reqPermissions.join(', ')}]`, {
-                adminPermissionsRequired: reqPermissions,
-                email,
-                backendResponseStatusCode: 403,
-                userFriendly: true,
-            });
-        }
+        const granted = andComparison
+            ? isAdmin && grantedPermissions.length === reqPermissions.length // All permissions granted
+            : isAdmin && grantedPermissions.length > 0; // 1+ is required
+        return {
+            email,
+            isAdmin,
+            granted,
+            reqPermissions,
+            grantedPermissions,
+            authDisabled: false,
+        };
+    }
+    /**
+     * Throws 401 if there's no email, 403 if not granted.
+     */
+    requireGranted(result) {
+        if (result.authDisabled)
+            return adminInfoDisabled();
+        const { email, granted, reqPermissions, grantedPermissions } = result;
+        _assert(email, 'adminToken required', {
+            adminAuthRequired: true,
+            backendResponseStatusCode: 401,
+            userFriendly: true,
+        });
+        _assert(granted, `Admin permissions required: [${reqPermissions.join(', ')}]`, {
+            adminPermissionsRequired: reqPermissions,
+            email,
+            backendResponseStatusCode: 403,
+            userFriendly: true,
+        });
         return {
             email,
             permissions: grantedPermissions.slice(),
         };
     }
-    // convenience method
-    async hasPermission(req, reqPermission, meta) {
-        return !!(await this.hasPermissions(req, [reqPermission], meta));
+    /**
+     * Current implementation is based on req=Request (from Express).
+     * Override if needed.
+     */
+    getAdminToken(req) {
+        return (req.cookies?.[this.cfg.adminTokenKey] ||
+            req.header(this.cfg.adminTokenKey) ||
+            req.header('x-admin-token'));
     }
-    async requirePermission(req, reqPermission, meta) {
-        return await this.requirePermissions(req, [reqPermission], meta);
+    async getEmailByToken(req, adminToken) {
+        if (!adminToken)
+            return;
+        try {
+            const auth = await this.getFirebaseAuth();
+            const decodedToken = await auth.verifyIdToken(adminToken);
+            const email = decodedToken?.email;
+            req.log(`admin email: ${dimGrey(email)}`);
+            return email;
+        }
+        catch (err) {
+            // example:
+            // FirebaseAuthError: Firebase ID token has expired. Get a fresh ID token from your client app and try again (auth/id-token-expired).
+            if (
+            // err instanceof FirebaseAuthError && err.hasCode('id-token-expired')
+            err?.code?.includes('id-token-expired')) {
+                return; // skip logging, expected error
+            }
+            req.error(`getEmailByToken error:`, err);
+        }
+    }
+    async getFirebaseAuth() {
+        return await this.loadFirebaseAuth();
+    }
+    /**
+     * To be extended.
+     *
+     * Returns undefined if it's not an Admin.
+     * Otherwise returns Set of permissions.
+     * Empty array means it IS and Admin, but has no permissions (except being an Admin).
+     */
+    async getEmailPermissions(email) {
+        if (!email)
+            return;
+        console.log(`getEmailPermissions (${dimGrey(email)}) returning undefined (please override the implementation)`);
+    }
+    /**
+     * To be extended.
+     */
+    // oxlint-disable-next-line max-params
+    async onPermissionCheck(req, email, reqPermissions, required, granted, meta = {}) {
+        req.log(`${dimGrey(email)} ${required ? 'required' : 'optional'} permissions check [${dimGrey(reqPermissions.join(', '))}]: ${granted ? green('GRANTED') : red('DENIED')}`, meta);
     }
     /**
      * Install it on POST /admin/login url
@@ -202,3 +231,7 @@ export class BaseAdminService {
 __decorate([
     _Memo()
 ], BaseAdminService.prototype, "getFirebaseAuth", null);
+const adminInfoDisabled = () => ({
+    email: 'authDisabled',
+    permissions: [],
+});

package/dist/express/startServer.js

@@ -63,7 +63,7 @@ export class BackendServer {
             }
         }
         const cpus = os.cpus().length;
-        const availableParallelism = os.availableParallelism?.();
+        const availableParallelism = os.availableParallelism();
         const { version, platform, arch } = process;
         console.log(dimGrey(`node ${version} ${platform} ${arch}, NODE_OPTIONS: ${NODE_OPTIONS || 'undefined'}, APP_ENV: ${APP_ENV || 'undefined'}, cpus: ${cpus}, availableParallelism: ${availableParallelism}`));
         console.log(`serverStarted on ${white(address)} in ${dimGrey(_ms(process.uptime() * 1000))}`);

package/dist/server/serverStatusMiddleware.js

@@ -1,9 +1,11 @@
+import os from 'node:os';
 import { localTime } from '@naturalcycles/js-lib/datetime/localTime.js';
 import { _filterNullishValues } from '@naturalcycles/js-lib/object/object.util.js';
 import { memoryUsageFull, processSharedUtil } from '@naturalcycles/nodejs-lib';
 import { getDeployInfo } from '../deploy/deployInfo.util.js';
 const { versions, arch, platform } = process;
-const { GAE_APPLICATION, GAE_SERVICE, GAE_VERSION, GOOGLE_CLOUD_PROJECT, K_SERVICE, K_REVISION, APP_ENV, NODE_ENV, NODE_OPTIONS, UV_THREADPOOL_SIZE, DEPLOY_BUILD_TIME, BUILD_VERSION, } = process.env;
+const availableParallelismAtStart = os.availableParallelism();
+const { GAE_APPLICATION, GAE_SERVICE, GAE_VERSION, GOOGLE_CLOUD_PROJECT, K_SERVICE, K_REVISION, APP_ENV, NODE_ENV, NODE_OPTIONS, UV_THREADPOOL_SIZE, MALLOC_ARENA_MAX, DEPLOY_BUILD_TIME, BUILD_VERSION, } = process.env;
 export function serverStatusMiddleware(projectDir, extra) {
     return async (_req, res) => {
         res.json(getServerStatusData(projectDir, extra));
@@ -15,6 +17,7 @@ export function getServerStatusData(projectDir = process.cwd(), extra) {
         const { ts } = getDeployInfo(projectDir);
         deployBuildTime = localTime(ts).toPretty();
     }
+    const availableParallelism = os.availableParallelism();
     return _filterNullishValues({
         nodeProcessStarted: getStartedStr(),
         deployBuildTime,
@@ -33,10 +36,13 @@ export function getServerStatusData(projectDir = process.cwd(), extra) {
         mem: memoryUsageFull(),
         cpuAvg: processSharedUtil.cpuAvg(),
         cpuInfo: processSharedUtil.cpuInfo(),
+        availableParallelismAtStart,
+        availableParallelism,
         versions,
         NODE_OPTIONS,
         NODE_ENV,
         UV_THREADPOOL_SIZE,
+        MALLOC_ARENA_MAX,
         ...extra,
     });
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@naturalcycles/backend-lib",
   "type": "module",
-  "version": "9.71.1",
+  "version": "9.73.0",
   "dependencies": {
     "@naturalcycles/db-lib": "^10",
     "@naturalcycles/js-lib": "^15",

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

@@ -1,33 +1,10 @@
 import { _Memo } from '@naturalcycles/js-lib/decorators'
-import { _assert, AppError } from '@naturalcycles/js-lib/error'
+import { _assert } from '@naturalcycles/js-lib/error'
+import type { AnyObject } from '@naturalcycles/js-lib/types'
 import { dimGrey, green, red } from '@naturalcycles/nodejs-lib/colors'
 import type { Auth } from 'firebase-admin/auth'
 import type { BackendRequest, BackendRequestHandler } from '../server/server.model.js'
 
-export interface AdminServiceCfg {
-  /**
-   * @default 'admin_token'
-   */
-  adminTokenKey?: string
-
-  /**
-   * If false - disables auth completely (useful for debugging locally, but never in production).
-   *
-   * @default true
-   */
-  authEnabled?: boolean
-}
-
-export interface AdminInfo {
-  email: string
-  permissions: string[]
-}
-
-const adminInfoDisabled = (): AdminInfo => ({
-  email: 'authDisabled',
-  permissions: [],
-})
-
 /**
  * Base implementation based on Firebase Auth tokens passed as 'admin_token' cookie.
  */
@@ -52,87 +29,10 @@ export class BaseAdminService {
     }
   }
 
-  /**
-   * To be extended.
-   *
-   * Returns undefined if it's not an Admin.
-   * Otherwise returns Set of permissions.
-   * Empty array means it IS and Admin, but has no permissions (except being an Admin).
-   */
-  async getEmailPermissions(email?: string): Promise<Set<string> | undefined> {
-    if (!email) return
-    console.log(
-      `getEmailPermissions (${dimGrey(
-        email,
-      )}) returning undefined (please override the implementation)`,
-    )
-  }
-
-  /**
-   * To be extended.
-   */
-  // oxlint-disable-next-line max-params
-  protected async onPermissionCheck(
-    req: BackendRequest,
-    email: string,
-    reqPermissions: string[],
-    required: boolean,
-    granted: boolean,
-    meta: Record<string, any> = {},
-  ): Promise<void> {
-    req.log(
-      `${dimGrey(email)} ${required ? 'required' : 'optional'} permissions check [${dimGrey(
-        reqPermissions.join(', '),
-      )}]: ${granted ? green('GRANTED') : red('DENIED')}`,
-      meta,
-    )
-  }
-
-  async getEmailByToken(req: BackendRequest, adminToken?: string): Promise<string | undefined> {
-    if (!adminToken) return
-
-    try {
-      const auth = await this.getFirebaseAuth()
-      const decodedToken = await auth.verifyIdToken(adminToken)
-      const email = decodedToken?.email
-      req.log(`admin email: ${dimGrey(email)}`)
-      return email
-    } catch (err) {
-      // example:
-      // FirebaseAuthError: Firebase ID token has expired. Get a fresh ID token from your client app and try again (auth/id-token-expired).
-      if (
-        // err instanceof FirebaseAuthError && err.hasCode('id-token-expired')
-        (err as any)?.code?.includes('id-token-expired')
-      ) {
-        return // skip logging, expected error
-      }
-
-      req.error(`getEmailByToken error:`, err)
-    }
-  }
-
-  @_Memo()
-  private async getFirebaseAuth(): Promise<Auth> {
-    return await this.loadFirebaseAuth()
-  }
-
-  /**
-   * Current implementation is based on req=Request (from Express).
-   * Override if needed.
-   */
-  getAdminToken(req: BackendRequest): string | undefined {
-    return (
-      req.cookies?.[this.cfg.adminTokenKey] ||
-      req.header(this.cfg.adminTokenKey) ||
-      req.header('x-admin-token')
-    )
-  }
-
   async isAdmin(req: BackendRequest | undefined): Promise<boolean> {
     if (!req) return false
-    const adminToken = this.getAdminToken(req)
-    const email = await this.getEmailByToken(req, adminToken)
-    return !!(await this.getEmailPermissions(email))
+    const { permissions } = await this.resolveAdmin(req)
+    return !!permissions
   }
 
   async getAdminInfo(req: BackendRequest): Promise<AdminInfo | undefined> {
@@ -144,6 +44,24 @@ export class BaseAdminService {
   //   await this.reqPermissions(req)
   // }
 
+  // convenience method
+  async hasPermission(
+    req: BackendRequest,
+    reqPermission: string,
+    meta?: AnyObject,
+  ): Promise<boolean> {
+    const adminInfo = await this.hasPermissions(req, [reqPermission], meta)
+    return !!adminInfo
+  }
+
+  async requirePermission(
+    req: BackendRequest,
+    reqPermission: string,
+    meta?: AnyObject,
+  ): Promise<AdminInfo> {
+    return await this.requirePermissions(req, [reqPermission], meta)
+  }
+
   /**
    * Returns AdminInfo if it has all required permissions.
    * Otherwise returns undefined
@@ -151,73 +69,119 @@ export class BaseAdminService {
   async hasPermissions(
     req: BackendRequest,
     reqPermissions: string[] = [],
-    meta: Record<string, any> = {},
+    meta: AnyObject = {},
   ): Promise<AdminInfo | undefined> {
     if (!this.cfg.authEnabled) return adminInfoDisabled()
 
-    const adminToken = this.getAdminToken(req)
-    const email = await this.getEmailByToken(req, adminToken)
-    const hasPermissions = await this.getEmailPermissions(email)
-    if (!hasPermissions) return
+    const admin = await this.resolveAdmin(req)
+    const { email, permissions } = admin
+    if (!email || !permissions) return
 
-    const granted = reqPermissions.every(p => hasPermissions.has(p))
+    const result = this.checkPermissions(admin, reqPermissions)
 
-    void this.onPermissionCheck(req, email!, reqPermissions, false, granted, meta)
+    void this.onPermissionCheck(req, email, reqPermissions, false, result.granted, meta)
 
-    if (!granted) return
+    if (!result.granted) return
 
     return {
-      email: email!,
-      permissions: Array.from(hasPermissions),
+      email,
+      permissions: Array.from(permissions),
     }
   }
 
   async requirePermissions(
     req: BackendRequest,
     reqPermissions: string[] = [],
-    meta: Record<string, any> = {},
+    meta: AnyObject = {},
     andComparison = true,
   ): Promise<AdminInfo> {
     if (!this.cfg.authEnabled) return adminInfoDisabled()
 
+    const admin = await this.resolveAdmin(req)
+    const result = this.checkPermissions(admin, reqPermissions, { andComparison })
+
+    if (result.email) {
+      // Log only the granted permissions (differs from reqPermissions only on OR-comparison)
+      const checkedPermissions = result.granted ? result.grantedPermissions : reqPermissions
+      void this.onPermissionCheck(req, result.email, checkedPermissions, true, result.granted, meta)
+    }
+
+    return this.requireGranted(result)
+  }
+
+  /**
+   * Doesn't check permissions, nor `authEnabled`. See `checkPermissions`.
+   */
+  async resolveAdmin(req: BackendRequest): Promise<ResolvedAdmin> {
     const adminToken = this.getAdminToken(req)
     const email = await this.getEmailByToken(req, adminToken)
+    if (!email) return {}
 
-    if (!email) {
-      throw new AppError('adminToken required', {
-        adminAuthRequired: true,
-        backendResponseStatusCode: 401,
-        userFriendly: true,
-      })
+    const permissions = await this.getEmailPermissions(email)
+    return { email, permissions }
+  }
+
+  /**
+   * Doesn't log or throw. See `requireGranted`.
+   */
+  checkPermissions(
+    admin: ResolvedAdmin,
+    reqPermissions: string[] = [],
+    opt: CheckPermissionsOptions = {},
+  ): CheckPermissionsResult {
+    const { andComparison = true } = opt
+    const { email, permissions: hasPermissions } = admin
+    const isAdmin = !!hasPermissions
+
+    if (!this.cfg.authEnabled) {
+      return {
+        email,
+        isAdmin,
+        granted: true,
+        reqPermissions,
+        grantedPermissions: [],
+        authDisabled: true,
+      }
     }
 
-    const hasPermissions = await this.getEmailPermissions(email)
     const grantedPermissions = hasPermissions
       ? reqPermissions.filter(p => hasPermissions.has(p))
       : []
 
-    let granted: boolean
-    if (andComparison) {
-      granted = !!hasPermissions && grantedPermissions.length === reqPermissions.length // All permissions granted
-      void this.onPermissionCheck(req, email, reqPermissions, true, granted, meta)
-    } else {
-      granted = !!hasPermissions && grantedPermissions.length > 0
-      if (granted) {
-        // Require the permission(s), but only the ones the user was actually granted. 1+ is required
-        void this.onPermissionCheck(req, email, grantedPermissions, true, granted, meta)
-      } else {
-        void this.onPermissionCheck(req, email, reqPermissions, true, granted, meta)
-      }
-    }
+    const granted = andComparison
+      ? isAdmin && grantedPermissions.length === reqPermissions.length // All permissions granted
+      : isAdmin && grantedPermissions.length > 0 // 1+ is required
 
-    if (!granted) {
-      throw new AppError(`Admin permissions required: [${reqPermissions.join(', ')}]`, {
-        adminPermissionsRequired: reqPermissions,
-        email,
-        backendResponseStatusCode: 403,
-        userFriendly: true,
-      })
+    return {
+      email,
+      isAdmin,
+      granted,
+      reqPermissions,
+      grantedPermissions,
+      authDisabled: false,
     }
+  }
+
+  /**
+   * Throws 401 if there's no email, 403 if not granted.
+   */
+  requireGranted(result: CheckPermissionsResult): AdminInfo {
+    if (result.authDisabled) return adminInfoDisabled()
+
+    const { email, granted, reqPermissions, grantedPermissions } = result
+
+    _assert(email, 'adminToken required', {
+      adminAuthRequired: true,
+      backendResponseStatusCode: 401,
+      userFriendly: true,
+    })
+
+    _assert(granted, `Admin permissions required: [${reqPermissions.join(', ')}]`, {
+      adminPermissionsRequired: reqPermissions,
+      email,
+      backendResponseStatusCode: 403,
+      userFriendly: true,
+    })
 
     return {
       email,
@@ -225,21 +189,80 @@ export class BaseAdminService {
     }
   }
 
-  // convenience method
-  async hasPermission(
-    req: BackendRequest,
-    reqPermission: string,
-    meta?: Record<string, any>,
-  ): Promise<boolean> {
-    return !!(await this.hasPermissions(req, [reqPermission], meta))
+  /**
+   * Current implementation is based on req=Request (from Express).
+   * Override if needed.
+   */
+  getAdminToken(req: BackendRequest): string | undefined {
+    return (
+      req.cookies?.[this.cfg.adminTokenKey] ||
+      req.header(this.cfg.adminTokenKey) ||
+      req.header('x-admin-token')
+    )
   }
 
-  async requirePermission(
+  async getEmailByToken(req: BackendRequest, adminToken?: string): Promise<string | undefined> {
+    if (!adminToken) return
+
+    try {
+      const auth = await this.getFirebaseAuth()
+      const decodedToken = await auth.verifyIdToken(adminToken)
+      const email = decodedToken?.email
+      req.log(`admin email: ${dimGrey(email)}`)
+      return email
+    } catch (err) {
+      // example:
+      // FirebaseAuthError: Firebase ID token has expired. Get a fresh ID token from your client app and try again (auth/id-token-expired).
+      if (
+        // err instanceof FirebaseAuthError && err.hasCode('id-token-expired')
+        (err as any)?.code?.includes('id-token-expired')
+      ) {
+        return // skip logging, expected error
+      }
+
+      req.error(`getEmailByToken error:`, err)
+    }
+  }
+
+  @_Memo()
+  private async getFirebaseAuth(): Promise<Auth> {
+    return await this.loadFirebaseAuth()
+  }
+
+  /**
+   * To be extended.
+   *
+   * Returns undefined if it's not an Admin.
+   * Otherwise returns Set of permissions.
+   * Empty array means it IS and Admin, but has no permissions (except being an Admin).
+   */
+  async getEmailPermissions(email?: string): Promise<Set<string> | undefined> {
+    if (!email) return
+    console.log(
+      `getEmailPermissions (${dimGrey(
+        email,
+      )}) returning undefined (please override the implementation)`,
+    )
+  }
+
+  /**
+   * To be extended.
+   */
+  // oxlint-disable-next-line max-params
+  protected async onPermissionCheck(
     req: BackendRequest,
-    reqPermission: string,
-    meta?: Record<string, any>,
-  ): Promise<AdminInfo> {
-    return await this.requirePermissions(req, [reqPermission], meta)
+    email: string,
+    reqPermissions: string[],
+    required: boolean,
+    granted: boolean,
+    meta: AnyObject = {},
+  ): Promise<void> {
+    req.log(
+      `${dimGrey(email)} ${required ? 'required' : 'optional'} permissions check [${dimGrey(
+        reqPermissions.join(', '),
+      )}]: ${granted ? green('GRANTED') : red('DENIED')}`,
+      meta,
+    )
   }
 
   /**
@@ -280,3 +303,53 @@ export class BaseAdminService {
     }
   }
 }
+
+const adminInfoDisabled = (): AdminInfo => ({
+  email: 'authDisabled',
+  permissions: [],
+})
+
+export interface AdminServiceCfg {
+  /**
+   * @default 'admin_token'
+   */
+  adminTokenKey?: string
+
+  /**
+   * If false - disables auth completely (useful for debugging locally, but never in production).
+   *
+   * @default true
+   */
+  authEnabled?: boolean
+}
+
+export interface AdminInfo {
+  email: string
+  permissions: string[]
+}
+
+export interface ResolvedAdmin {
+  /** undefined - no valid admin token */
+  email?: string
+  /** undefined - not an Admin */
+  permissions?: Set<string>
+}
+
+export interface CheckPermissionsOptions {
+  /**
+   * false - one granted permission is enough.
+   *
+   * @default true
+   */
+  andComparison?: boolean
+}
+
+export interface CheckPermissionsResult {
+  /** undefined - no valid admin token */
+  email?: string
+  isAdmin: boolean
+  granted: boolean
+  reqPermissions: string[]
+  grantedPermissions: string[]
+  authDisabled: boolean
+}

package/src/express/startServer.ts

@@ -73,7 +73,7 @@ export class BackendServer {
     }
 
     const cpus = os.cpus().length
-    const availableParallelism = os.availableParallelism?.()
+    const availableParallelism = os.availableParallelism()
     const { version, platform, arch } = process
     console.log(
       dimGrey(

package/src/server/serverStatusMiddleware.ts

@@ -1,3 +1,4 @@
+import os from 'node:os'
 import { localTime } from '@naturalcycles/js-lib/datetime/localTime.js'
 import { _filterNullishValues } from '@naturalcycles/js-lib/object/object.util.js'
 import { memoryUsageFull, processSharedUtil } from '@naturalcycles/nodejs-lib'
@@ -5,6 +6,7 @@ import { getDeployInfo } from '../deploy/deployInfo.util.js'
 import type { BackendRequestHandler } from './server.model.js'
 
 const { versions, arch, platform } = process
+const availableParallelismAtStart = os.availableParallelism()
 const {
   GAE_APPLICATION,
   GAE_SERVICE,
@@ -16,6 +18,7 @@ const {
   NODE_ENV,
   NODE_OPTIONS,
   UV_THREADPOOL_SIZE,
+  MALLOC_ARENA_MAX,
   DEPLOY_BUILD_TIME,
   BUILD_VERSION,
 } = process.env
@@ -36,6 +39,8 @@ export function getServerStatusData(
     deployBuildTime = localTime(ts).toPretty()
   }
 
+  const availableParallelism = os.availableParallelism()
+
   return _filterNullishValues({
     nodeProcessStarted: getStartedStr(),
     deployBuildTime,
@@ -54,10 +59,13 @@ export function getServerStatusData(
     mem: memoryUsageFull(),
     cpuAvg: processSharedUtil.cpuAvg(),
     cpuInfo: processSharedUtil.cpuInfo(),
+    availableParallelismAtStart,
+    availableParallelism,
     versions,
     NODE_OPTIONS,
     NODE_ENV,
     UV_THREADPOOL_SIZE,
+    MALLOC_ARENA_MAX,
     ...extra,
   })
 }