@naturalcycles/backend-lib 9.72.0 → 9.73.1

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/createDefaultApp.js

@@ -2,7 +2,6 @@ import { asyncLocalStorageMiddleware } from '../server/asyncLocalStorageMiddlewa
 import { compressionMiddleware } from '../server/compressionMiddleware.js';
 import { genericErrorMiddleware } from '../server/genericErrorMiddleware.js';
 import { logMiddleware } from '../server/logMiddleware.js';
-import { methodOverrideMiddleware } from '../server/methodOverrideMiddleware.js';
 import { notFoundMiddleware } from '../server/notFoundMiddleware.js';
 import { requestTimeoutMiddleware } from '../server/requestTimeoutMiddleware.js';
 import { simpleRequestLoggerMiddleware } from '../server/simpleRequestLoggerMiddleware.js';
@@ -24,7 +23,6 @@ export async function createDefaultApp(cfg) {
     if (!isTest) {
         app.use(asyncLocalStorageMiddleware());
     }
-    app.use(methodOverrideMiddleware());
     app.use(requestTimeoutMiddleware());
     // app.use(serverStatsMiddleware()) // disabled by default
     // app.use(bodyParserTimeout()) // removed by default

package/dist/index.d.ts

@@ -7,7 +7,6 @@ export * from './server/compressionMiddleware.js';
 export * from './server/eventLoop.util.js';
 export * from './server/genericErrorMiddleware.js';
 export * from './server/logMiddleware.js';
-export * from './server/methodOverrideMiddleware.js';
 export * from './server/notFoundMiddleware.js';
 export * from './server/okMiddleware.js';
 export * from './server/request.log.util.js';

package/dist/index.js

@@ -7,7 +7,6 @@ export * from './server/compressionMiddleware.js';
 export * from './server/eventLoop.util.js';
 export * from './server/genericErrorMiddleware.js';
 export * from './server/logMiddleware.js';
-export * from './server/methodOverrideMiddleware.js';
 export * from './server/notFoundMiddleware.js';
 export * from './server/okMiddleware.js';
 export * from './server/request.log.util.js';

package/dist/server/notFoundMiddleware.js

@@ -1,6 +1,9 @@
 import { getRequestEndpoint } from './request.util.js';
 export function notFoundMiddleware() {
     return (req, res) => {
-        res.status(404).send(`404 Not Found: ${getRequestEndpoint(req)}`);
+        res
+            .status(404)
+            .type('text/plain')
+            .send(`404 Not Found: ${getRequestEndpoint(req)}`);
     };
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@naturalcycles/backend-lib",
   "type": "module",
-  "version": "9.72.0",
+  "version": "9.73.1",
   "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/createDefaultApp.ts

@@ -6,7 +6,6 @@ import { compressionMiddleware } from '../server/compressionMiddleware.js'
 import { genericErrorMiddleware } from '../server/genericErrorMiddleware.js'
 import type { GenericErrorMiddlewareCfg } from '../server/genericErrorMiddleware.js'
 import { logMiddleware } from '../server/logMiddleware.js'
-import { methodOverrideMiddleware } from '../server/methodOverrideMiddleware.js'
 import { notFoundMiddleware } from '../server/notFoundMiddleware.js'
 import { requestTimeoutMiddleware } from '../server/requestTimeoutMiddleware.js'
 import type {
@@ -42,7 +41,6 @@ export async function createDefaultApp(cfg: DefaultAppCfg): Promise<BackendAppli
     app.use(asyncLocalStorageMiddleware())
   }
 
-  app.use(methodOverrideMiddleware())
   app.use(requestTimeoutMiddleware())
   // app.use(serverStatsMiddleware()) // disabled by default
   // app.use(bodyParserTimeout()) // removed by default

package/src/index.ts

@@ -7,7 +7,6 @@ export * from './server/compressionMiddleware.js'
 export * from './server/eventLoop.util.js'
 export * from './server/genericErrorMiddleware.js'
 export * from './server/logMiddleware.js'
-export * from './server/methodOverrideMiddleware.js'
 export * from './server/notFoundMiddleware.js'
 export * from './server/okMiddleware.js'
 export * from './server/request.log.util.js'

package/src/server/notFoundMiddleware.ts

@@ -3,6 +3,9 @@ import type { BackendRequestHandler } from './server.model.js'
 
 export function notFoundMiddleware(): BackendRequestHandler {
   return (req, res) => {
-    res.status(404).send(`404 Not Found: ${getRequestEndpoint(req)}`)
+    res
+      .status(404)
+      .type('text/plain')
+      .send(`404 Not Found: ${getRequestEndpoint(req)}`)
   }
 }

package/dist/server/methodOverrideMiddleware.d.ts

@@ -1,8 +0,0 @@
-import type { BackendRequestHandler } from './server.model.js';
-export interface MethodOverrideMiddlewareCfg {
-    /**
-     * @default _method
-     */
-    methodKey?: string;
-}
-export declare function methodOverrideMiddleware(cfg?: MethodOverrideMiddlewareCfg): BackendRequestHandler;

package/dist/server/methodOverrideMiddleware.js

@@ -1,13 +0,0 @@
-export function methodOverrideMiddleware(cfg = {}) {
-    const { methodKey } = {
-        methodKey: '_method',
-        ...cfg,
-    };
-    return (req, _res, next) => {
-        if (req.query[methodKey]) {
-            req.method = req.query[methodKey];
-            // delete req.query[methodKey]
-        }
-        next();
-    };
-}

package/src/server/methodOverrideMiddleware.ts

@@ -1,26 +0,0 @@
-import type { BackendRequestHandler } from './server.model.js'
-
-export interface MethodOverrideMiddlewareCfg {
-  /**
-   * @default _method
-   */
-  methodKey?: string
-}
-
-export function methodOverrideMiddleware(
-  cfg: MethodOverrideMiddlewareCfg = {},
-): BackendRequestHandler {
-  const { methodKey } = {
-    methodKey: '_method',
-    ...cfg,
-  }
-
-  return (req, _res, next) => {
-    if (req.query[methodKey]) {
-      req.method = req.query[methodKey] as string
-      // delete req.query[methodKey]
-    }
-
-    next()
-  }
-}