@naturalcycles/backend-lib 9.74.0 → 9.75.0

package/dist/admin/adminMiddleware.d.ts

@@ -1,6 +1,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'
@@ -25,14 +28,28 @@ export interface RequireAdminCfg {
      */
     andComparison?: boolean;
 }
+/**
+ * @deprecated Use `AuthMiddleware`.
+ */
 export type AdminMiddleware = (reqPermissions?: string[], cfg?: RequireAdminCfg) => BackendRequestHandler;
+/**
+ * @deprecated Use `AuthService.getLoginRedirectMiddleware`.
+ */
 export declare function createAdminMiddleware(adminService: BaseAdminService, cfgDefaults?: RequireAdminCfg): AdminMiddleware;
 /**
  * Require Admin permission.
  * 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 declare function requireAdminPermissions(adminService: BaseAdminService, reqPermissions?: string[], cfg?: RequireAdminCfg): BackendRequestHandler;
+/**
+ * @deprecated Use `loginHtmlHandler`.
+ */
 export declare function loginHtml(firebaseServiceCfg: FirebaseSharedServiceCfg): BackendRequestHandler;
+/**
+ * @deprecated Use `AuthService.getLoginRedirectMiddleware`.
+ */
 export declare function getLoginHtmlRedirect(href: string): string;

package/dist/admin/adminMiddleware.js

@@ -2,6 +2,9 @@ import { _memoized } from '@naturalcycles/js-lib/decorators';
 import { AppError } from '@naturalcycles/js-lib/error/error.util.js';
 import { fs2 } from '@naturalcycles/nodejs-lib/fs2';
 import { srcDir } from '../paths.cnst.js';
+/**
+ * @deprecated Use `AuthService.getLoginRedirectMiddleware`.
+ */
 export function createAdminMiddleware(adminService, cfgDefaults = {}) {
     return (reqPermissions, cfg) => requireAdminPermissions(adminService, reqPermissions, {
         ...cfgDefaults,
@@ -13,6 +16,8 @@ export function createAdminMiddleware(adminService, cfgDefaults = {}) {
  * 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, reqPermissions = [], cfg = {}) {
     const { loginHtmlPath = '/login.html', urlStartsWith, apiHost, autoLogin = true, andComparison = true, } = cfg;
@@ -36,6 +41,9 @@ export function requireAdminPermissions(adminService, reqPermissions = [], cfg =
         }
     };
 }
+/**
+ * @deprecated Use `loginHtmlHandler`.
+ */
 export function loginHtml(firebaseServiceCfg) {
     const { apiKey: firebaseApiKey, authDomain: firebaseAuthDomain, adminAuthProvider: firebaseAuthProvider = 'GoogleAuthProvider', } = firebaseServiceCfg;
     return (_req, res) => {
@@ -54,6 +62,9 @@ const getLoginHtml = _memoized((cfg) => {
         .replaceAll('<%= firebaseAuthDomain %>', cfg.firebaseAuthDomain)
         .replaceAll('<%= firebaseAuthProvider %>', cfg.firebaseAuthProvider);
 });
+/**
+ * @deprecated Use `AuthService.getLoginRedirectMiddleware`.
+ */
 export function getLoginHtmlRedirect(href) {
     return `
 <html>

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

@@ -3,6 +3,8 @@ import type { Auth } from 'firebase-admin/auth';
 import type { BackendRequest, BackendRequestHandler } from '../server/server.model.js';
 /**
  * Base implementation based on Firebase Auth tokens passed as 'admin_token' cookie.
+ *
+ * @deprecated Use `AuthService`, with `FirebaseAuthService` for `authenticate`.
  */
 export declare class BaseAdminService {
     private loadFirebaseAuth;
@@ -61,6 +63,9 @@ export declare class BaseAdminService {
      */
     getFirebaseAuthLoginHandler(): BackendRequestHandler;
 }
+/**
+ * @deprecated Use `AuthServiceCfg` and `FirebaseAuthServiceCfg`.
+ */
 export interface AdminServiceCfg {
     /**
      * @default 'admin_token'
@@ -73,16 +78,25 @@ 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;
     /** undefined - not an Admin */
     permissions?: Set<string>;
 }
+/**
+ * @deprecated Use `AuthCheckOptions`.
+ */
 export interface CheckPermissionsOptions {
     /**
      * false - one granted permission is enough.
@@ -91,6 +105,9 @@ export interface CheckPermissionsOptions {
      */
     andComparison?: boolean;
 }
+/**
+ * @deprecated Use `AuthService.has` / `AuthService.require`.
+ */
 export interface CheckPermissionsResult {
     /** undefined - no valid admin token */
     email?: string;

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

@@ -4,6 +4,8 @@ import { _assert } from '@naturalcycles/js-lib/error';
 import { dimGrey, green, red } from '@naturalcycles/nodejs-lib/colors';
 /**
  * Base implementation based on Firebase Auth tokens passed as 'admin_token' cookie.
+ *
+ * @deprecated Use `AuthService`, with `FirebaseAuthService` for `authenticate`.
  */
 export class BaseAdminService {
     loadFirebaseAuth;

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

@@ -0,0 +1,41 @@
+import type { Auth } from 'firebase-admin/auth';
+import type { BackendRequest, BackendRequestHandler } from '../server/server.model.js';
+import type { FirebaseSharedServiceCfg } from './firebase.shared.service.js';
+/**
+ * Verifies Firebase Auth tokens.
+ */
+export declare class FirebaseAuthService {
+    private loadFirebaseAuth;
+    cfg: FirebaseAuthServiceCfg;
+    constructor(loadFirebaseAuth: () => Promise<FirebaseTokenVerifier>, cfg: FirebaseAuthServiceCfg);
+    /**
+     * Reads the configured cookie first, then the header.
+     */
+    getToken(req: BackendRequest): string | undefined;
+    /**
+     * Returns undefined if there's no token, or it's expired.
+     * Rejects on any other verification failure.
+     */
+    getEmailByToken(token: string | undefined): Promise<string | undefined>;
+    private getFirebaseAuth;
+    /**
+     * 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;
+}
+/**
+ * Serves login.html, configured for Firebase Auth.
+ */
+export declare function loginHtmlHandler(firebaseServiceCfg: FirebaseSharedServiceCfg): BackendRequestHandler;
+/**
+ * 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;
+}

package/dist/admin/firebaseAuth.service.js

@@ -0,0 +1,103 @@
+import { __decorate } from "tslib";
+import { _Memo, _memoized } from '@naturalcycles/js-lib/decorators';
+import { _assert } from '@naturalcycles/js-lib/error';
+import { fs2 } from '@naturalcycles/nodejs-lib/fs2';
+import { srcDir } from '../paths.cnst.js';
+/**
+ * Verifies Firebase Auth tokens.
+ */
+export class FirebaseAuthService {
+    loadFirebaseAuth;
+    cfg;
+    constructor(loadFirebaseAuth, cfg) {
+        this.loadFirebaseAuth = loadFirebaseAuth;
+        this.cfg = cfg;
+    }
+    /**
+     * Reads the configured cookie first, then the header.
+     */
+    getToken(req) {
+        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) {
+        if (!token)
+            return;
+        const auth = await this.getFirebaseAuth();
+        try {
+            const decodedToken = await auth.verifyIdToken(token);
+            return decodedToken.email;
+        }
+        catch (err) {
+            if (err?.hasCode?.('id-token-expired'))
+                return;
+            throw err;
+        }
+    }
+    async getFirebaseAuth() {
+        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() {
+        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();
+        };
+    }
+}
+__decorate([
+    _Memo()
+], FirebaseAuthService.prototype, "getFirebaseAuth", null);
+/**
+ * Serves login.html, configured for Firebase Auth.
+ */
+export function loginHtmlHandler(firebaseServiceCfg) {
+    const { apiKey: firebaseApiKey, authDomain: firebaseAuthDomain, adminAuthProvider: firebaseAuthProvider = 'GoogleAuthProvider', } = firebaseServiceCfg;
+    return (_req, res) => {
+        res.send(getLoginHtml({
+            firebaseApiKey,
+            firebaseAuthDomain,
+            firebaseAuthProvider,
+        }));
+    };
+}
+const getLoginHtml = _memoized((cfg) => {
+    return fs2
+        .readText(`${srcDir}/admin/login.html`)
+        .replaceAll('<%= firebaseApiKey %>', cfg.firebaseApiKey)
+        .replaceAll('<%= firebaseAuthDomain %>', cfg.firebaseAuthDomain)
+        .replaceAll('<%= firebaseAuthProvider %>', cfg.firebaseAuthProvider);
+});

package/dist/admin/index.d.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/dist/admin/index.js

@@ -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/dist/admin/secureHeaderMiddleware.d.ts

@@ -1,5 +1,8 @@
 import type { AdminMiddleware, RequireAdminCfg } from './adminMiddleware.js';
 import type { BaseAdminService } from './base.admin.service.js';
+/**
+ * @deprecated Use `AuthLoginRedirectMiddlewareCfg` with `secureHeader`.
+ */
 export interface SecureHeaderMiddlewareCfg extends RequireAdminCfg {
     adminService: BaseAdminService;
     /**
@@ -14,5 +17,7 @@ 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 declare function createSecureHeaderMiddleware(cfg: SecureHeaderMiddlewareCfg): AdminMiddleware;

package/dist/admin/secureHeaderMiddleware.js

@@ -4,6 +4,8 @@ import { requireAdminPermissions } from './adminMiddleware.js';
 /**
  * Secures the endpoint by requiring a secret header to be present.
  * Throws Error401Admin otherwise.
+ *
+ * @deprecated Use `AuthService.getLoginRedirectMiddleware` with `secureHeader`.
  */
 export function createSecureHeaderMiddleware(cfg) {
     return reqPermissions => requireSecureHeaderOrAdmin(cfg, reqPermissions);

package/dist/auth/auth.service.d.ts

@@ -0,0 +1,119 @@
+import type { AnyObject, Promisable } from '@naturalcycles/js-lib/types';
+import type { BackendRequest, BackendRequestHandler } from '../server/server.model.js';
+/**
+ * Authenticates requests and checks permissions.
+ */
+export declare class AuthService<CTX = AnyObject> {
+    constructor(cfg: AuthServiceCfg<CTX>);
+    cfg: AuthServiceCfg<CTX> & {
+        authEnabled: boolean;
+    };
+    /**
+     * Responds JSON 401 / 403.
+     */
+    getMiddleware(cfg?: AuthMiddlewareCfg<CTX>): AuthMiddleware;
+    /**
+     * Like `getMiddleware`, but 401 redirects to the login page.
+     */
+    getLoginRedirectMiddleware(cfg: AuthLoginRedirectMiddlewareCfg<CTX>): AuthMiddleware;
+    private createHandler;
+    /**
+     * Runs `authenticate`, then `getPermissions` and `isAlwaysAuthorized` if there's a subject.
+     * Ignores `authEnabled`.
+     */
+    resolve(req: BackendRequest): Promise<ResolvedAuth>;
+    /**
+     * 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;
+    private checkSubject;
+    private assertAuthenticated;
+    private authRequiredData;
+    private assertGranted;
+    /**
+     * undefined - not granted.
+     */
+    private getGrantedPermissions;
+    private getLoginHref;
+    private getLoginHtmlRedirect;
+}
+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[];
+}
+export interface ResolvedAuth {
+    /** undefined - not authenticated */
+    subject?: string;
+    /** undefined - no permission set */
+    permissions?: string[];
+    /** Result of `isAlwaysAuthorized` */
+    alwaysAuthorized?: boolean;
+}

package/dist/auth/auth.service.js

@@ -0,0 +1,147 @@
+import { _assert, AppError } from '@naturalcycles/js-lib/error';
+import { timingSafeStringEqual } from '@naturalcycles/nodejs-lib';
+/**
+ * Authenticates requests and checks permissions.
+ */
+export class AuthService {
+    constructor(cfg) {
+        this.cfg = {
+            authEnabled: true,
+            ...cfg,
+        };
+    }
+    cfg;
+    /**
+     * Responds JSON 401 / 403.
+     */
+    getMiddleware(cfg = {}) {
+        return reqPermissions => this.createHandler(cfg, reqPermissions);
+    }
+    /**
+     * Like `getMiddleware`, but 401 redirects to the login page.
+     */
+    getLoginRedirectMiddleware(cfg) {
+        const loginHref = this.getLoginHref(cfg);
+        return reqPermissions => this.createHandler(cfg, reqPermissions, loginHref);
+    }
+    createHandler(cfg, reqPermissions = [], loginHref) {
+        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) {
+        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, reqPermissions = [], opt = {}) {
+        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() };
+    }
+    checkSubject(resolved, reqPermissions, opt) {
+        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;
+    }
+    assertAuthenticated(resolved) {
+        _assert(resolved?.subject, 'authentication required', this.authRequiredData());
+    }
+    authRequiredData() {
+        return {
+            authRequired: true,
+            backendResponseStatusCode: 401,
+            userFriendly: true,
+        };
+    }
+    assertGranted(subject, grantedPermissions, reqPermissions) {
+        _assert(grantedPermissions, `Permissions required: [${reqPermissions.join(', ')}]`, {
+            permissionsRequired: reqPermissions,
+            subject,
+            backendResponseStatusCode: 403,
+            userFriendly: true,
+        });
+    }
+    /**
+     * undefined - not granted.
+     */
+    getGrantedPermissions(permissions, reqPermissions, andComparison) {
+        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;
+    }
+    getLoginHref(cfg) {
+        return `${cfg.loginHtmlPath}?autoLogin=1&returnUrl=\${encodeURIComponent(location.href)}`;
+    }
+    getLoginHtmlRedirect(href) {
+        return `
+<html>
+<body>401 Authentication Required
+<script>
+  document.write(\`: <a href="${href}" id="loginLink">Login</a>\`)
+  document.getElementById('loginLink').click()
+</script>
+</body>
+</html>
+`;
+    }
+}

package/dist/auth/index.d.ts

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

package/dist/auth/index.js

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@naturalcycles/backend-lib",
   "type": "module",
-  "version": "9.74.0",
+  "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(
@@ -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)

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'