@webtypen/webframez-core 0.3.72 → 0.3.74

package/auth-client.d.ts

@@ -0,0 +1,11 @@
+/** Public browser-only entry point for ModelAuth / Route.auth. */
+export type AuthClientOptions = {
+    basePath?: string;
+    loginPaths?: string[];
+    cookieName?: string;
+    requiresCsrf?: (url: URL) => boolean;
+};
+
+export declare function createAuthFetch(options?: AuthClientOptions, originalFetch?: typeof fetch): typeof fetch;
+
+export declare function installAuthForms(options?: AuthClientOptions & { fetch?: typeof fetch }): () => void;

package/auth-client.js

@@ -0,0 +1,50 @@
+/** Browser-only entry point. No server or database modules are loaded. */
+function csrfCookie(name) {
+    const cookieName = name || (window.location.protocol === "https:" ? "__Host-wf_csrf" : "wf_dev_csrf");
+    const values = document.cookie.split(";").map(part => part.trim()).filter(part => part.startsWith(`${cookieName}=`));
+    return values.length === 1 ? decodeURIComponent(values[0].slice(cookieName.length + 1)) : "";
+}
+
+exports.createAuthFetch = function createAuthFetch(options = {}, originalFetch = window.fetch.bind(window)) {
+    const base = (options.basePath || "/api/auth").replace(/\/+$/, "");
+    const loginPaths = options.loginPaths || [`${base}/login`];
+    return async (input, init) => {
+        const url = new URL(input instanceof Request ? input.url : String(input), window.location.href);
+        const method = String(init?.method || (input instanceof Request ? input.method : "GET")).toUpperCase();
+        if (url.origin !== window.location.origin || ["GET", "HEAD", "OPTIONS"].includes(method)
+            || (options.requiresCsrf && !options.requiresCsrf(url))) return originalFetch(input, init);
+        let token;
+        if (loginPaths.includes(url.pathname)) {
+            const bootstrap = await originalFetch(`${base}/csrf`, { credentials: "same-origin", cache: "no-store" });
+            if (!bootstrap.ok) return bootstrap;
+            token = (await bootstrap.json()).csrf;
+        } else token = csrfCookie(options.cookieName);
+        const headers = new Headers(init?.headers || (input instanceof Request ? input.headers : undefined));
+        if (typeof token === "string" && token) headers.set("X-CSRF-Token", token);
+        return originalFetch(input, { ...init, headers });
+    };
+};
+
+exports.installAuthForms = function installAuthForms(options = {}) {
+    const loginPaths = options.loginPaths || ["/api/auth/login"];
+    const fetch = options.fetch || window.fetch.bind(window);
+    const listener = event => {
+        const form = event.target;
+        if (!(form instanceof HTMLFormElement) || form.method.toLowerCase() !== "post") return;
+        const url = new URL(form.action);
+        if (url.origin !== window.location.origin || !loginPaths.includes(url.pathname)) return;
+        const token = csrfCookie(options.cookieName);
+        if (!token) {
+            event.preventDefault();
+            const submitter = event.submitter;
+            void fetch(`${(options.basePath || "/api/auth").replace(/\/+$/, "")}/csrf`, { credentials: "same-origin", cache: "no-store" })
+                .then(response => { if (response.ok && csrfCookie(options.cookieName)) form.requestSubmit(submitter); });
+            return;
+        }
+        let field = form.querySelector('input[name="_csrf"]');
+        if (!field) { field = document.createElement("input"); field.type = "hidden"; field.name = "_csrf"; form.append(field); }
+        field.value = token;
+    };
+    document.addEventListener("submit", listener, true);
+    return () => document.removeEventListener("submit", listener, true);
+};

package/dist/Auth/Auth.d.ts

@@ -0,0 +1,19 @@
+import type { Request } from "../Router/Request";
+import type { Response } from "../Router/Response";
+import { AuthScope, AuthScopeOptions, AuthOperation, AuthRouteOptions } from "./ModelAuth";
+export type AuthConfig = {
+    /** Disable automatic main creation; explicitly configured scopes remain available. */
+    main?: boolean;
+    defaults?: Partial<AuthScopeOptions>;
+    scopes?: Record<string, AuthScopeOptions>;
+};
+/** Application-wide registry of named browser-authentication scopes. */
+export declare class AuthFacade {
+    private readonly scopes;
+    private initialized;
+    init(): void;
+    scope(key?: string): AuthScope;
+    registerScope(key: string, config: Partial<AuthScopeOptions>): AuthScope;
+}
+export declare const Auth: AuthFacade;
+export declare function authRoute(operation: AuthOperation, options: AuthRouteOptions): (req: Request, res: Response) => Promise<Response>;

package/dist/Auth/Auth.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.authRoute = exports.Auth = exports.AuthFacade = void 0;
+const Config_1 = require("../Config");
+const Model_1 = require("../Database/Model");
+const ModelAuth_1 = require("./ModelAuth");
+function mergeOptions(base, config) {
+    return Object.assign(Object.assign(Object.assign({ model: Model_1.Model }, base), config), { fields: Object.assign(Object.assign({}, base.fields), config.fields), session: Object.assign(Object.assign({}, base.session), config.session), messages: Object.assign(Object.assign({}, base.messages), config.messages) });
+}
+/** Application-wide registry of named browser-authentication scopes. */
+class AuthFacade {
+    constructor() {
+        this.scopes = new Map();
+        this.initialized = false;
+    }
+    init() {
+        if (this.initialized)
+            return;
+        const config = Config_1.Config.get("auth") || {};
+        const configured = new Map();
+        for (const [key, options] of Object.entries(config.scopes || {})) {
+            configured.set(key, new ModelAuth_1.AuthScope(Object.assign(Object.assign({}, mergeOptions(config.defaults || {}, options)), { key })));
+        }
+        if (config.main !== false && !configured.has("main")) {
+            configured.set("main", new ModelAuth_1.AuthScope(Object.assign(Object.assign({}, mergeOptions(config.defaults || {}, {})), { key: "main" })));
+        }
+        for (const [key, scope] of configured)
+            this.scopes.set(key, scope);
+        this.initialized = true;
+    }
+    scope(key = "main") {
+        this.init();
+        const scope = this.scopes.get(key);
+        if (!scope)
+            throw new Error(`Auth scope "${key}" is not registered.`);
+        return scope;
+    }
+    registerScope(key, config) {
+        var _a;
+        this.init();
+        const defaults = Config_1.Config.get("auth.defaults") || {};
+        const base = ((_a = this.scopes.get(key)) === null || _a === void 0 ? void 0 : _a.configuration) || defaults;
+        const scope = new ModelAuth_1.AuthScope(Object.assign(Object.assign({}, mergeOptions(base, config)), { key }));
+        this.scopes.set(key, scope);
+        return scope;
+    }
+}
+exports.AuthFacade = AuthFacade;
+exports.Auth = new AuthFacade();
+function authRoute(operation, options) {
+    return (req, res) => exports.Auth.scope(options.auth || "main").handle(operation, req, res, options.loginResponse);
+}
+exports.authRoute = authRoute;

package/dist/Auth/ModelAuth.d.ts

@@ -0,0 +1,83 @@
+import { Model } from "../Database/Model";
+import { Request } from "../Router/Request";
+import type { Response } from "../Router/Response";
+import { AuthSession, SessionAuthOptions } from "./SessionAuth";
+import { WebAuth, WebAuthError, WebAuthOptions } from "./WebAuth";
+export type AuthContext<TUser extends Model = Model> = {
+    user: TUser;
+    session: AuthSession;
+};
+export type AuthSnapshot<TUser = Record<string, unknown>> = {
+    user: TUser;
+    session: AuthSession;
+};
+export type AuthErrorCode = "missing_login" | "invalid_login" | "inactive_user" | "invalid_origin" | "invalid_csrf" | "unauthorized" | "server_error" | "login_blocked" | "logout_blocked";
+export declare class AuthLoginError extends WebAuthError {
+    readonly code: AuthErrorCode;
+    constructor(code: AuthErrorCode, status: 401 | 403, message: string);
+}
+export type ModelAuthOptions = Partial<WebAuthOptions> & {
+    model: typeof Model;
+    key?: string;
+    /** Takes precedence over session.audience; defaults to the configured origin. */
+    audience?: string;
+    locale?: "en" | "de";
+    /** Record browser metadata and update activity at most once per minute. */
+    trackActivity?: boolean;
+    fields?: {
+        identifier?: string;
+        password?: string;
+        active?: string | false;
+        primaryKey?: string;
+    };
+    session?: Partial<Omit<SessionAuthOptions, "issuer" | "isSessionAllowed">>;
+    csrfDisabled?: false;
+    verifyPassword?: (password: string, storedHash: string) => boolean | Promise<boolean>;
+    isUserAllowed?: (user: Model) => boolean | Promise<boolean>;
+    beforeLogin?: AuthActionHook;
+    afterLogin?: AuthActionHook;
+    beforeLogout?: AuthActionHook;
+    afterLogout?: AuthActionHook;
+    onLogin?: (session: AuthSession, req: Request) => void | Promise<void>;
+    publicUserFields?: readonly string[];
+    onAuthenticate?: (auth: AuthContext, req: Request) => void | Promise<void>;
+    messages?: Partial<Record<AuthErrorCode, string>>;
+};
+export type AuthActionHook = (req: Request, user: Model, scope: AuthScope) => void | Promise<void>;
+export type AuthOperation = "csrf" | "login" | "logout" | "refresh";
+export type AuthRouteOptions = Partial<ModelAuthOptions> & {
+    auth?: string;
+    loginPath?: string;
+    loginResponse?: (req: Request, session: AuthSession) => object | Promise<object>;
+    middleware?: string[];
+    domains?: string[];
+};
+/** Model-backed browser authentication with secure default routes and revocable sessions. */
+export declare class AuthScope extends WebAuth {
+    private readonly modelOptions;
+    readonly key: string;
+    private readonly model;
+    private readonly sessionUsers;
+    private readonly fields;
+    constructor(modelOptions: ModelAuthOptions);
+    get configuration(): ModelAuthOptions;
+    private message;
+    /** Use this when creating users; existing bcrypt hashes are supported without migration. */
+    static hashPassword(password: string): Promise<string>;
+    verifyCredentials(req: Request): Promise<string>;
+    login(req: Request, res: Response, verifyCredentials?: () => Promise<string | null>): Promise<AuthSession>;
+    logout(req: Request, res: Response): Promise<void>;
+    /** Resolve a fresh validated session and its model; never trusts a client-supplied req.auth. */
+    resolve<TUser extends Model = Model>(req: Request): Promise<AuthContext<TUser> | null>;
+    resolveCookies<TUser extends Model = Model>(cookies: Record<string, string | undefined>): Promise<AuthContext<TUser> | null>;
+    /** Only explicit public fields are sent to browsers; Model instances remain on the server. */
+    snapshot(auth: AuthContext | null | undefined): AuthSnapshot | null;
+    /** Optional auth for public routes, or required auth for protected controllers. */
+    middleware(options?: {
+        required?: boolean;
+    }): (next: Function, reject: Function, req: Request, res: Response) => Promise<any>;
+    handle(operation: AuthOperation, req: Request, res: Response, loginResponse?: AuthRouteOptions["loginResponse"]): Promise<Response>;
+}
+/** Compatibility name for existing integrations. Prefer Auth.scope(). */
+export { AuthScope as ModelAuth };
+export type AuthScopeOptions = ModelAuthOptions;

package/dist/Auth/ModelAuth.js

@@ -0,0 +1,275 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ModelAuth = exports.AuthScope = exports.AuthLoginError = void 0;
+const bcryptjs_1 = require("bcryptjs");
+const Config_1 = require("../Config");
+const Request_1 = require("../Router/Request");
+const AuthSecurity_1 = require("./AuthSecurity");
+const SessionAuth_1 = require("./SessionAuth");
+const WebAuth_1 = require("./WebAuth");
+class AuthLoginError extends WebAuth_1.WebAuthError {
+    constructor(code, status, message) {
+        super(status, message);
+        this.code = code;
+    }
+}
+exports.AuthLoginError = AuthLoginError;
+class AuthHookError extends AuthLoginError {
+    constructor(code, error) {
+        super(code, error instanceof WebAuth_1.WebAuthError ? error.status : 403, error instanceof Error ? error.message : typeof error === "string" ? error : "Authentication action was blocked.");
+    }
+}
+const defaultMessages = {
+    en: {
+        missing_login: "Please provide your login and password.",
+        invalid_login: "Invalid login or password.",
+        inactive_user: "This account is inactive.",
+        invalid_origin: "The login address does not match the configured website URL.",
+        invalid_csrf: "Please reload the page and try logging in again.",
+        unauthorized: "Please log in.",
+        server_error: "Authentication could not be processed.",
+        login_blocked: "Login was blocked.",
+        logout_blocked: "Logout was blocked.",
+    },
+    de: {
+        missing_login: "Bitte gib E-Mail-Adresse und Passwort an.",
+        invalid_login: "Es wurde kein Benutzer mit dieser E-Mail-/Passwort-Kombination gefunden.",
+        inactive_user: "Bitte aktiviere deinen Account über die E-Mail, die wir dir geschickt haben.",
+        invalid_origin: "Die Login-Adresse stimmt nicht mit der konfigurierten Website-URL überein.",
+        invalid_csrf: "Der Login konnte gerade nicht verarbeitet werden. Bitte lade die Seite neu.",
+        unauthorized: "Bitte melde dich an.",
+        server_error: "Die Anmeldung konnte gerade nicht verarbeitet werden.",
+        login_blocked: "Die Anmeldung wurde abgelehnt.",
+        logout_blocked: "Die Abmeldung wurde abgelehnt.",
+    },
+};
+// Verify a dummy password hash for unknown accounts as well.
+let dummyHash;
+/** Model-backed browser authentication with secure default routes and revocable sessions. */
+class AuthScope extends WebAuth_1.WebAuth {
+    constructor(modelOptions) {
+        var _a, _b, _c, _d, _e, _f, _g;
+        if (modelOptions.csrfDisabled)
+            throw new Error("Browser auth routes require CSRF protection.");
+        if (!modelOptions.model)
+            throw new Error("Route.auth requires a Model class.");
+        const origin = new URL(modelOptions.origin || Config_1.Config.get("auth.origin") || Config_1.Config.get("website.baseUrl") || Config_1.Config.get("application.website.baseUrl") || process.env.WEBSITE_URL || process.env.PUBLIC_BASE_URL || `http://localhost:${process.env.PORT || 3035}`).origin;
+        const key = (_a = modelOptions.key) !== null && _a !== void 0 ? _a : "main";
+        if (!/^[A-Za-z0-9_-]+$/.test(key))
+            throw new Error("Invalid auth scope key.");
+        const model = modelOptions.model;
+        const fields = Object.assign({ identifier: "email", password: "password", active: "is_active", primaryKey: new model().__primaryKey || "_id" }, modelOptions.fields);
+        const allowed = (user) => __awaiter(this, void 0, void 0, function* () {
+            return Boolean(user && (fields.active === false || user[fields.active] !== false)
+                && (!modelOptions.isUserAllowed || (yield modelOptions.isUserAllowed(user))));
+        });
+        const sessionUsers = new WeakMap();
+        const sessions = new SessionAuth_1.SessionAuth(Object.assign(Object.assign({ accessTokenSeconds: 30 * 86400, sessionSeconds: 30 * 86400 }, modelOptions.session), { issuer: origin, scope: key, audience: (_d = (_b = modelOptions.audience) !== null && _b !== void 0 ? _b : (_c = modelOptions.session) === null || _c === void 0 ? void 0 : _c.audience) !== null && _d !== void 0 ? _d : origin, connection: ((_e = modelOptions.session) === null || _e === void 0 ? void 0 : _e.connection) || new model().__connection, isSessionAllowed: (session) => __awaiter(this, void 0, void 0, function* () {
+                const id = fields.primaryKey === "_id" ? yield model.objectId(session.subject, { noExceptions: true }) : session.subject;
+                const user = id !== null && id !== undefined ? yield model.where(fields.primaryKey, "=", id).first() : null;
+                if (!(yield allowed(user)))
+                    return false;
+                sessionUsers.set(session, user);
+                return true;
+            }) }));
+        super(sessions, Object.assign(Object.assign({}, modelOptions), { origin, cookiePrefix: (_f = modelOptions.cookiePrefix) !== null && _f !== void 0 ? _f : (key === "main" ? undefined : `${origin.startsWith("https:") ? "__Host-wf_" : "wf_dev_"}${key}_`), allowInsecureLocalhost: (_g = modelOptions.allowInsecureLocalhost) !== null && _g !== void 0 ? _g : true }));
+        this.modelOptions = modelOptions;
+        this.key = key;
+        this.sessionUsers = sessionUsers;
+        this.model = model;
+        this.fields = fields;
+    }
+    get configuration() {
+        return this.modelOptions;
+    }
+    message(code) {
+        var _a, _b;
+        return (_b = (_a = this.modelOptions.messages) === null || _a === void 0 ? void 0 : _a[code]) !== null && _b !== void 0 ? _b : defaultMessages[this.modelOptions.locale || "en"][code];
+    }
+    /** Use this when creating users; existing bcrypt hashes are supported without migration. */
+    static hashPassword(password) {
+        return (0, bcryptjs_1.hash)(password, 12);
+    }
+    verifyCredentials(req) {
+        var _a, _b;
+        return __awaiter(this, void 0, void 0, function* () {
+            const identifier = (_a = req.body) === null || _a === void 0 ? void 0 : _a[this.fields.identifier], password = (_b = req.body) === null || _b === void 0 ? void 0 : _b.password;
+            if (typeof identifier !== "string" || !identifier.trim() || identifier.length > 320
+                || typeof password !== "string" || !password || password.length > 1024) {
+                throw new AuthLoginError("missing_login", 401, this.message("missing_login"));
+            }
+            const user = yield this.model.where(this.fields.identifier, "=", identifier.trim().toLowerCase()).first();
+            const stored = user === null || user === void 0 ? void 0 : user[this.fields.password];
+            const verify = this.modelOptions.verifyPassword || bcryptjs_1.compare;
+            const valid = yield verify(password, typeof stored === "string" ? stored : yield (dummyHash || (dummyHash = (0, bcryptjs_1.hash)("webframez-invalid-account", 12))));
+            if (!user || typeof stored !== "string" || !valid)
+                throw new AuthLoginError("invalid_login", 401, this.message("invalid_login"));
+            if ((this.fields.active !== false && user[this.fields.active] === false)
+                || (this.modelOptions.isUserAllowed && !(yield this.modelOptions.isUserAllowed(user)))) {
+                throw new AuthLoginError("inactive_user", 403, this.message("inactive_user"));
+            }
+            const id = user[this.fields.primaryKey];
+            if (id === null || id === undefined || id === "")
+                throw new Error("Auth user has no primary key.");
+            return String(id);
+        });
+    }
+    login(req, res, verifyCredentials = () => this.verifyCredentials(req)) {
+        const _super = Object.create(null, {
+            login: { get: () => super.login }
+        });
+        return __awaiter(this, void 0, void 0, function* () {
+            let user = null;
+            const session = yield _super.login.call(this, req, res, () => __awaiter(this, void 0, void 0, function* () {
+                const subject = yield verifyCredentials();
+                if (subject && (this.modelOptions.beforeLogin || this.modelOptions.afterLogin)) {
+                    const id = this.fields.primaryKey === "_id" ? yield this.model.objectId(subject, { noExceptions: true }) : subject;
+                    user = id == null ? null : yield this.model.where(this.fields.primaryKey, "=", id).first();
+                    if (!user)
+                        throw new AuthLoginError("invalid_login", 401, this.message("invalid_login"));
+                    if (this.modelOptions.beforeLogin) {
+                        try {
+                            yield this.modelOptions.beforeLogin(req, user, this);
+                        }
+                        catch (error) {
+                            throw new AuthHookError("login_blocked", error);
+                        }
+                    }
+                }
+                return subject;
+            }));
+            if (this.modelOptions.trackActivity !== false)
+                yield this.sessions.recordLogin(session, (0, AuthSecurity_1.authHeader)(req, "user-agent"));
+            if (this.modelOptions.onLogin)
+                yield this.modelOptions.onLogin(session, req);
+            if (this.modelOptions.afterLogin)
+                yield this.modelOptions.afterLogin(req, user, this);
+            return session;
+        });
+    }
+    logout(req, res) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const session = yield this.logoutSession(req);
+            const user = this.sessionUsers.get(session);
+            if (!user)
+                throw new AuthLoginError("unauthorized", 401, this.message("unauthorized"));
+            if (this.modelOptions.beforeLogout) {
+                try {
+                    yield this.modelOptions.beforeLogout(req, user, this);
+                }
+                catch (error) {
+                    throw new AuthHookError("logout_blocked", error);
+                }
+            }
+            yield this.finishLogout(session, res);
+            if (this.modelOptions.afterLogout)
+                yield this.modelOptions.afterLogout(req, user, this);
+        });
+    }
+    /** Resolve a fresh validated session and its model; never trusts a client-supplied req.auth. */
+    resolve(req) {
+        const _super = Object.create(null, {
+            authenticate: { get: () => super.authenticate }
+        });
+        return __awaiter(this, void 0, void 0, function* () {
+            Object.defineProperty(req, "auth", { value: null, writable: true, configurable: true, enumerable: false });
+            const session = yield _super.authenticate.call(this, req);
+            if (!session)
+                return null;
+            const user = this.sessionUsers.get(session);
+            if (!user)
+                return null;
+            if (this.modelOptions.trackActivity !== false)
+                yield this.sessions.touch(session);
+            const auth = { user, session };
+            if (this.modelOptions.onAuthenticate)
+                yield this.modelOptions.onAuthenticate(auth, req);
+            req.auth = auth;
+            return auth;
+        });
+    }
+    resolveCookies(cookies) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const req = Object.assign(new Request_1.Request(), { method: "GET", headers: { cookie: `${this.cookies.prefix}access=${encodeURIComponent(cookies[`${this.cookies.prefix}access`] || "")}` } });
+            return this.resolve(req);
+        });
+    }
+    /** Only explicit public fields are sent to browsers; Model instances remain on the server. */
+    snapshot(auth) {
+        var _a;
+        if (!auth)
+            return null;
+        const fields = this.modelOptions.publicUserFields || [this.fields.primaryKey, "email", "name", "firstname", "lastname", "roles"];
+        const user = {};
+        for (const field of fields) {
+            if (field.startsWith("__") || field === this.fields.password || ((_a = auth.user.__hidden) === null || _a === void 0 ? void 0 : _a.includes(field))
+                || ["constructor", "prototype"].includes(field))
+                continue;
+            const value = auth.user[field];
+            if (value !== undefined)
+                user[field] = value;
+        }
+        return JSON.parse(JSON.stringify({ user, session: auth.session }));
+    }
+    /** Optional auth for public routes, or required auth for protected controllers. */
+    middleware(options = {}) {
+        return (next, reject, req, res) => __awaiter(this, void 0, void 0, function* () {
+            try {
+                const auth = yield this.resolve(req);
+                res.header("Cache-Control", "no-store");
+                if (!auth && options.required) {
+                    res.status(401).send({ status: "error", code: "unauthorized" });
+                    res.end();
+                    return reject("Unauthorized");
+                }
+                return next(true);
+            }
+            catch (error) {
+                if (!(error instanceof WebAuth_1.WebAuthError))
+                    throw error;
+                res.status(error.status).send({ status: "error", code: "invalid_csrf" });
+                res.end();
+                return reject(error.message);
+            }
+        });
+    }
+    handle(operation, req, res, loginResponse) {
+        var _a, _b;
+        return __awaiter(this, void 0, void 0, function* () {
+            res.header("Cache-Control", "no-store");
+            try {
+                if (operation === "csrf")
+                    return res.send({ csrf: this.bootstrap(req, res) });
+                if (operation === "logout") {
+                    yield this.logout(req, res);
+                    return res.send({ status: "success" });
+                }
+                if (operation === "refresh") {
+                    yield this.refresh(req, res);
+                    return res.send({ status: "success" });
+                }
+                const session = yield this.login(req, res);
+                return res.send(Object.assign(Object.assign({}, (loginResponse ? yield loginResponse(req, session) : {})), { status: "success" }));
+            }
+            catch (error) {
+                const code = error instanceof AuthLoginError ? error.code : error instanceof WebAuth_1.WebAuthError
+                    ? error.message === "Invalid request origin." ? "invalid_origin" : error.status === 401 ? "unauthorized" : "invalid_csrf" : "server_error";
+                if (!(error instanceof WebAuth_1.WebAuthError))
+                    console.error(error);
+                return res.status(error instanceof WebAuth_1.WebAuthError ? error.status : 500).send({ status: "error", code,
+                    message: error instanceof AuthHookError ? (_b = (_a = this.modelOptions.messages) === null || _a === void 0 ? void 0 : _a[code]) !== null && _b !== void 0 ? _b : error.message : this.message(code) });
+            }
+        });
+    }
+}
+exports.AuthScope = AuthScope;
+exports.ModelAuth = AuthScope;

package/dist/Auth/SessionAuth.d.ts

@@ -1,10 +1,13 @@
-import type { DocumentDatabase } from "../Database/DatabaseAdapter";
+import type { DatabaseIdAdapter, DocumentDatabase } from "../Database/DatabaseAdapter";
 export type AuthSession = {
     id: string;
     subject: string;
     issuer: string;
     audience: string;
+    scope: string;
     environment: string | null;
+    userAgent?: string;
+    lastActiveAt?: number;
     createdAt: number;
     expiresAt: number;
     parent: {
@@ -25,6 +28,7 @@ export type CreatedAuthSession = SessionTokenPair & {
 export type SessionAuthOptions = {
     issuer: string;
     audience: string;
+    scope?: string;
     environment?: string;
     connection?: string;
     collection?: string;
@@ -35,6 +39,8 @@ export type SessionAuthOptions = {
     isSessionAllowed: (session: AuthSession) => boolean | Promise<boolean>;
     /** Dependency injection for a document-capable driver. Atomic findOneAndUpdate is required. */
     database?: () => Promise<DocumentDatabase>;
+    /** ID handling for an injected document store; otherwise the selected driver owns IDs. */
+    idAdapter?: DatabaseIdAdapter;
 };
 /** Revocable, hashed, independently addressable device sessions. Legacy UserAuth is unaffected. */
 export declare class SessionAuth {
@@ -43,6 +49,8 @@ export declare class SessionAuth {
     private readonly accessSeconds;
     private readonly sessionSeconds;
     constructor(options: SessionAuthOptions);
+    private ids;
+    private sessionId;
     private rows;
     private allowed;
     private pair;
@@ -53,6 +61,10 @@ export declare class SessionAuth {
     verifyCsrf(token: string, csrf: string, kind?: "access" | "refresh"): Promise<boolean>;
     /** One winner under concurrency. A previously consumed refresh token revokes its device session. */
     refresh(token: string): Promise<SessionTokenPair | null>;
+    /** Browser login metadata; arbitrary request data and token hashes are never exposed. */
+    recordLogin(session: AuthSession, userAgent: string): Promise<void>;
+    /** Persist activity with a one-minute throttle; authorization does not depend on this timestamp. */
+    touch(session: AuthSession): Promise<void>;
     revoke(sessionId: string): Promise<void>;
     revokeAll(subject: string): Promise<void>;
     list(subject: string): Promise<AuthSession[]>;

package/dist/Auth/SessionAuth.js

@@ -13,23 +13,32 @@ exports.SessionAuth = void 0;
 const DBConnection_1 = require("../Database/DBConnection");
 const AuthSecurity_1 = require("./AuthSecurity");
 function publicSession(record) {
-    return { id: record.id, subject: record.subject, issuer: record.issuer, audience: record.audience,
-        environment: record.environment, createdAt: record.createdAt, expiresAt: record.expiresAt, parent: record.parent };
+    return Object.assign(Object.assign({ id: String(record._id), subject: String(record._subject), issuer: record.issuer, audience: record.audience, scope: record.scope, environment: record.environment, createdAt: record.createdAt, expiresAt: record.expiresAt, parent: record.parent }, (record.userAgent !== undefined ? { userAgent: record.userAgent } : {})), (record.lastActiveAt !== undefined ? { lastActiveAt: record.lastActiveAt } : {}));
 }
 function tokenSessionId(token) {
-    return typeof token === "string" && /^[A-Za-z0-9_-]{43}\.[A-Za-z0-9_-]{43}$/.test(token) ? token.split(".")[0] : null;
+    return typeof token === "string" && /^[A-Za-z0-9_-]{1,128}\.[A-Za-z0-9_-]{43}$/.test(token) ? token.split(".")[0] : null;
 }
 /** Revocable, hashed, independently addressable device sessions. Legacy UserAuth is unaffected. */
 class SessionAuth {
     constructor(options) {
+        var _a;
         this.options = options;
-        this.scope = { issuer: (0, AuthSecurity_1.authText)(options.issuer, "issuer"), audience: (0, AuthSecurity_1.authText)(options.audience, "audience"),
+        this.scope = { issuer: (0, AuthSecurity_1.authText)(options.issuer, "issuer"), audience: (0, AuthSecurity_1.authText)(options.audience, "audience"), scope: (0, AuthSecurity_1.authText)((_a = options.scope) !== null && _a !== void 0 ? _a : "main", "scope"),
             environment: options.environment === undefined ? null : (0, AuthSecurity_1.authText)(options.environment, "environment") };
         this.accessSeconds = (0, AuthSecurity_1.authLifetime)(options.accessTokenSeconds, 15 * 60);
         this.sessionSeconds = (0, AuthSecurity_1.authLifetime)(options.sessionSeconds, 30 * 86400);
         if (typeof options.isSessionAllowed !== "function")
             throw new Error("SessionAuth requires isSessionAllowed.");
     }
+    ids() {
+        return this.options.idAdapter || DBConnection_1.DBConnection.getIdAdapter(this.options.connection);
+    }
+    sessionId(value) {
+        const adapter = this.ids();
+        const native = adapter.normalize(value);
+        // Converted legacy MongoDB sessions keep working with their existing opaque token prefix.
+        return native !== null && native !== void 0 ? native : (/^[A-Za-z0-9_-]{43}$/.test(value) ? adapter.normalize((0, AuthSecurity_1.hashAuthToken)(value).slice(0, 24)) : null);
+    }
     rows() {
         return __awaiter(this, void 0, void 0, function* () {
             const db = yield (this.options.database ? this.options.database() : DBConnection_1.DBConnection.getDocumentStore(this.options.connection));
@@ -55,9 +64,9 @@ class SessionAuth {
                 (0, AuthSecurity_1.authText)(parent.issuer, "parent issuer");
                 (0, AuthSecurity_1.authText)(parent.sessionId, "parent session");
             }
-            const now = Date.now(), id = (0, AuthSecurity_1.randomAuthToken)();
+            const now = Date.now(), id = this.ids().create();
             const access = `${id}.${(0, AuthSecurity_1.randomAuthToken)()}`, refresh = `${id}.${(0, AuthSecurity_1.randomAuthToken)()}`, csrf = (0, AuthSecurity_1.randomAuthToken)();
-            const record = Object.assign(Object.assign({ _id: id, id, subject }, this.scope), { parent: parent ? Object.assign({}, parent) : null, createdAt: now, expiresAt: now + this.sessionSeconds * 1000, accessExpiresAt: now + Math.min(this.accessSeconds, this.sessionSeconds) * 1000, accessHash: (0, AuthSecurity_1.hashAuthToken)(access), refreshHash: (0, AuthSecurity_1.hashAuthToken)(refresh), csrfHash: (0, AuthSecurity_1.hashAuthToken)(csrf), usedRefreshHashes: [], revokedAt: null });
+            const record = Object.assign(Object.assign({ _id: id, _subject: this.ids().create(subject) }, this.scope), { parent: parent ? Object.assign({}, parent) : null, createdAt: now, expiresAt: now + this.sessionSeconds * 1000, accessExpiresAt: now + Math.min(this.accessSeconds, this.sessionSeconds) * 1000, accessHash: (0, AuthSecurity_1.hashAuthToken)(access), refreshHash: (0, AuthSecurity_1.hashAuthToken)(refresh), csrfHash: (0, AuthSecurity_1.hashAuthToken)(csrf), usedRefreshHashes: [], revokedAt: null });
             if (!(yield this.allowed(record)))
                 throw new Error("Session is not allowed.");
             yield (yield this.rows()).insertOne(record);
@@ -69,16 +78,16 @@ class SessionAuth {
             const id = tokenSessionId(token);
             if (!id)
                 return null;
-            const row = yield (yield this.rows()).findOne(Object.assign(Object.assign({ _id: id }, this.scope), { accessHash: (0, AuthSecurity_1.hashAuthToken)(token), accessExpiresAt: { $gt: Date.now() } }));
+            const row = yield (yield this.rows()).findOne(Object.assign(Object.assign({ _id: this.sessionId(id) }, this.scope), { accessHash: (0, AuthSecurity_1.hashAuthToken)(token), accessExpiresAt: { $gt: Date.now() } }));
             return this.allowed(row);
         });
     }
     /** Trusted-server introspection; never expose this method as an unauthenticated endpoint. */
     inspect(sessionId) {
         return __awaiter(this, void 0, void 0, function* () {
-            if (typeof sessionId !== "string" || !/^[A-Za-z0-9_-]{43}$/.test(sessionId))
+            if (typeof sessionId !== "string" || !/^[A-Za-z0-9_-]{1,128}$/.test(sessionId))
                 return null;
-            return this.allowed(yield (yield this.rows()).findOne(Object.assign({ _id: sessionId }, this.scope)));
+            return this.allowed(yield (yield this.rows()).findOne(Object.assign({ _id: this.sessionId(sessionId) }, this.scope)));
         });
     }
     verifyCsrf(token, csrf, kind = "access") {
@@ -86,7 +95,7 @@ class SessionAuth {
             const id = tokenSessionId(token);
             if (!id || typeof csrf !== "string" || !/^[A-Za-z0-9_-]{43}$/.test(csrf))
                 return false;
-            const row = yield (yield this.rows()).findOne(Object.assign(Object.assign(Object.assign(Object.assign({ _id: id }, this.scope), (kind === "access" ? { accessHash: (0, AuthSecurity_1.hashAuthToken)(token) } : { $or: [{ refreshHash: (0, AuthSecurity_1.hashAuthToken)(token) }, { usedRefreshHashes: (0, AuthSecurity_1.hashAuthToken)(token) }] })), { csrfHash: (0, AuthSecurity_1.hashAuthToken)(csrf) }), (kind === "access" ? { accessExpiresAt: { $gt: Date.now() } } : {})));
+            const row = yield (yield this.rows()).findOne(Object.assign(Object.assign(Object.assign(Object.assign({ _id: this.sessionId(id) }, this.scope), (kind === "access" ? { accessHash: (0, AuthSecurity_1.hashAuthToken)(token) } : { $or: [{ refreshHash: (0, AuthSecurity_1.hashAuthToken)(token) }, { usedRefreshHashes: (0, AuthSecurity_1.hashAuthToken)(token) }] })), { csrfHash: (0, AuthSecurity_1.hashAuthToken)(csrf) }), (kind === "access" ? { accessExpiresAt: { $gt: Date.now() } } : {})));
             return !!(yield this.allowed(row));
         });
     }
@@ -97,7 +106,7 @@ class SessionAuth {
             if (!id)
                 return null;
             const rows = yield this.rows(), hash = (0, AuthSecurity_1.hashAuthToken)(token);
-            const row = yield rows.findOne(Object.assign({ _id: id }, this.scope));
+            const row = yield rows.findOne(Object.assign({ _id: this.sessionId(id) }, this.scope));
             if (!(yield this.allowed(row)) || !row)
                 return null;
             if (row.refreshHash !== hash) {
@@ -111,33 +120,52 @@ class SessionAuth {
                 return null;
             }
             const access = `${id}.${(0, AuthSecurity_1.randomAuthToken)()}`, refresh = `${id}.${(0, AuthSecurity_1.randomAuthToken)()}`;
-            const next = yield rows.findOneAndUpdate(Object.assign(Object.assign({ _id: id }, this.scope), { refreshHash: hash, revokedAt: null, expiresAt: { $gt: Date.now() } }), { $set: { accessHash: (0, AuthSecurity_1.hashAuthToken)(access), refreshHash: (0, AuthSecurity_1.hashAuthToken)(refresh),
+            const next = yield rows.findOneAndUpdate(Object.assign(Object.assign({ _id: this.sessionId(id) }, this.scope), { refreshHash: hash, revokedAt: null, expiresAt: { $gt: Date.now() } }), { $set: { accessHash: (0, AuthSecurity_1.hashAuthToken)(access), refreshHash: (0, AuthSecurity_1.hashAuthToken)(refresh),
                     accessExpiresAt: Math.min(Date.now() + this.accessSeconds * 1000, row.expiresAt),
                     usedRefreshHashes: [...row.usedRefreshHashes, hash] } }, { returnDocument: "after" });
             if (!next) {
                 // Also detect simultaneous replay that lost the compare-and-swap.
-                yield rows.updateOne(Object.assign(Object.assign({ _id: id }, this.scope), { usedRefreshHashes: hash, revokedAt: null }), { $set: { revokedAt: Date.now() } });
+                yield rows.updateOne(Object.assign(Object.assign({ _id: this.sessionId(id) }, this.scope), { usedRefreshHashes: hash, revokedAt: null }), { $set: { revokedAt: Date.now() } });
                 return null;
             }
             return this.pair(next, access, refresh);
         });
     }
+    /** Browser login metadata; arbitrary request data and token hashes are never exposed. */
+    recordLogin(session, userAgent) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const metadata = { userAgent: userAgent.slice(0, 512), lastActiveAt: session.createdAt };
+            yield (yield this.rows()).updateOne(Object.assign(Object.assign({ _id: this.sessionId(session.id) }, this.scope), { revokedAt: null }), { $set: metadata });
+            Object.assign(session, metadata);
+        });
+    }
+    /** Persist activity with a one-minute throttle; authorization does not depend on this timestamp. */
+    touch(session) {
+        var _a;
+        return __awaiter(this, void 0, void 0, function* () {
+            const now = Date.now();
+            if (((_a = session.lastActiveAt) !== null && _a !== void 0 ? _a : session.createdAt) >= now - 60000)
+                return;
+            yield (yield this.rows()).updateOne(Object.assign(Object.assign({ _id: this.sessionId(session.id) }, this.scope), { revokedAt: null, expiresAt: { $gt: now } }), { $set: { lastActiveAt: now } });
+            session.lastActiveAt = now;
+        });
+    }
     revoke(sessionId) {
         return __awaiter(this, void 0, void 0, function* () {
             (0, AuthSecurity_1.authText)(sessionId, "session ID");
-            yield (yield this.rows()).updateOne(Object.assign(Object.assign({ _id: sessionId }, this.scope), { revokedAt: null }), { $set: { revokedAt: Date.now() } });
+            yield (yield this.rows()).updateOne(Object.assign(Object.assign({ _id: this.sessionId(sessionId) }, this.scope), { revokedAt: null }), { $set: { revokedAt: Date.now() } });
         });
     }
     revokeAll(subject) {
         return __awaiter(this, void 0, void 0, function* () {
             (0, AuthSecurity_1.authText)(subject, "subject");
-            yield (yield this.rows()).updateMany(Object.assign(Object.assign({ subject }, this.scope), { revokedAt: null }), { $set: { revokedAt: Date.now() } });
+            yield (yield this.rows()).updateMany(Object.assign(Object.assign({ _subject: this.ids().create(subject) }, this.scope), { revokedAt: null }), { $set: { revokedAt: Date.now() } });
         });
     }
     list(subject) {
         return __awaiter(this, void 0, void 0, function* () {
             (0, AuthSecurity_1.authText)(subject, "subject");
-            const rows = yield (yield this.rows()).find(Object.assign(Object.assign({ subject }, this.scope), { revokedAt: null, expiresAt: { $gt: Date.now() } })).toArray();
+            const rows = yield (yield this.rows()).find(Object.assign(Object.assign({ _subject: this.ids().create(subject) }, this.scope), { revokedAt: null, expiresAt: { $gt: Date.now() } })).toArray();
             return rows.map(publicSession);
         });
     }

package/dist/Auth/SingleSignOn.js

@@ -57,6 +57,10 @@ function readSsoClientCredentials(req) {
 exports.readSsoClientCredentials = readSsoClientCredentials;
 function challenge(verifier) { return (0, crypto_1.createHash)("sha256").update(verifier).digest("base64url"); }
 function verifierValid(value) { return typeof value === "string" && /^[A-Za-z0-9._~-]{43,128}$/.test(value); }
+function sessionIdValid(value) {
+    return typeof value === "string" && (/^[a-fA-F0-9]{24}$/.test(value) || /^[0-9]{1,20}$/.test(value)
+        || /^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$/.test(value) || opaqueValid(value));
+}
 function opaqueValid(value) { return typeof value === "string" && /^[A-Za-z0-9_-]{43}$/.test(value); }
 function redirectAllowed(value, allowLocal = false) {
     const url = (0, AuthSecurity_1.authUrl)(value, allowLocal);
@@ -245,7 +249,7 @@ class SsoClient {
     identity(value, environment) {
         if (!value || value.issuer !== this.issuer || value.audience !== this.options.clientId || value.environment !== environment ||
             typeof value.subject !== "string" || !value.subject.length || value.subject.length > 512 ||
-            !opaqueValid(value.authoritySessionId) || !Number.isFinite(value.expiresAt) || value.expiresAt <= Date.now())
+            !sessionIdValid(value.authoritySessionId) || !Number.isFinite(value.expiresAt) || value.expiresAt <= Date.now())
             return null;
         return { issuer: value.issuer, audience: value.audience, subject: value.subject, environment: value.environment,
             authoritySessionId: value.authoritySessionId, expiresAt: value.expiresAt };
@@ -272,7 +276,7 @@ class SsoClient {
     }
     introspect(sessionId, environment) {
         return __awaiter(this, void 0, void 0, function* () {
-            if (!opaqueValid(sessionId))
+            if (!sessionIdValid(sessionId))
                 return null;
             (0, AuthSecurity_1.authText)(environment, "environment");
             const response = yield postBackchannel(this.introspection, this.options.clientId, this.options.clientSecret, { session_id: sessionId, environment });

package/dist/Auth/WebAuth.d.ts

@@ -38,5 +38,7 @@ export declare class WebAuth {
     establishSession(subject: string, res: Response, parent?: AuthSession["parent"]): Promise<AuthSession>;
     authenticate(req: Request): Promise<AuthSession | null>;
     refresh(req: Request, res: Response): Promise<AuthSession>;
+    protected logoutSession(req: Request): Promise<AuthSession>;
+    protected finishLogout(session: AuthSession, res: Response): Promise<void>;
     logout(req: Request, res: Response): Promise<void>;
 }

package/dist/Auth/WebAuth.js

@@ -130,16 +130,29 @@ class WebAuth {
             return pair.session;
         });
     }
-    logout(req, res) {
+    logoutSession(req) {
         return __awaiter(this, void 0, void 0, function* () {
             this.post(req);
             const csrf = this.csrf(req), token = this.cookies.read(req, "refresh");
             if (!(yield this.sessions.verifyCsrf(token, csrf, "refresh")))
                 throw new WebAuthError(403, "Invalid session CSRF token.");
-            yield this.sessions.revoke(token.split(".")[0]);
+            const session = yield this.sessions.inspect(token.split(".")[0]);
+            if (!session)
+                throw new WebAuthError(401, "Invalid session.");
+            return session;
+        });
+    }
+    finishLogout(session, res) {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this.sessions.revoke(session.id);
             for (const key of ["access", "refresh", "csrf"])
                 this.cookies.write(res, key, "", 0, key !== "csrf");
         });
     }
+    logout(req, res) {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this.finishLogout(yield this.logoutSession(req), res);
+        });
+    }
 }
 exports.WebAuth = WebAuth;

package/dist/Auth/index.d.ts

@@ -4,3 +4,5 @@ export * from "./UserPermissions";
 export * from "./SessionAuth";
 export * from "./WebAuth";
 export * from "./SingleSignOn";
+export * from "./ModelAuth";
+export * from "./Auth";

package/dist/Auth/index.js

@@ -20,3 +20,5 @@ __exportStar(require("./UserPermissions"), exports);
 __exportStar(require("./SessionAuth"), exports);
 __exportStar(require("./WebAuth"), exports);
 __exportStar(require("./SingleSignOn"), exports);
+__exportStar(require("./ModelAuth"), exports);
+__exportStar(require("./Auth"), exports);

package/dist/ConsoleApplication.js

@@ -10,6 +10,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ConsoleApplication = void 0;
+const Auth_1 = require("./Auth/Auth");
 /// <reference types="node" />
 const Config_1 = require("./Config");
 const ConsoleOutputHelper_1 = require("./Commands/ConsoleOutputHelper");
@@ -63,6 +64,7 @@ class ConsoleApplication {
                 Config_1.Config.register(key, options.config[key]);
             }
         }
+        Auth_1.Auth.init();
         NotificationService_1.NotificationService.init();
         if (options && options.errorHandler) {
             if (Array.isArray(options.errorHandler)) {

package/dist/LambdaApplication.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.LambdaApplication = void 0;
+const Auth_1 = require("./Auth/Auth");
 const Config_1 = require("./Config");
 const DatatableRegistry_1 = require("./Datatable/DatatableRegistry");
 const QueueJobsRegisty_1 = require("./Queue/QueueJobsRegisty");
@@ -26,6 +27,7 @@ class LambdaApplication {
                 Config_1.Config.register(key, options.config[key]);
             }
         }
+        Auth_1.Auth.init();
         if (options && options.errorHandler) {
             if (Array.isArray(options.errorHandler)) {
                 ErrorHandler_1.ErrorHandler.setHandlers(options.errorHandler);

package/dist/Router/Request.d.ts

@@ -1,7 +1,9 @@
 /// <reference types="node" />
+import type { AuthContext } from "../Auth/ModelAuth";
 import { IncomingMessage } from "http";
 export declare class Request {
     [key: string]: any;
+    auth?: AuthContext | null;
     method: string;
     url: string;
     headers: any;

package/dist/Router/Route.d.ts

@@ -1,4 +1,5 @@
 import { DataBuilderRouteOptions } from "../DataBuilder/DataBuilderRoute";
+import { AuthRouteOptions } from "../Auth/ModelAuth";
 type RouteRegistrationOptions = {
     [key: string]: any;
 };
@@ -28,6 +29,8 @@ export declare class RouteFacade {
     get(path: string, component: any, options?: RouteRegistrationOptions): void;
     /** Register the existing DataBuilder POST protocol with request-local configuration. */
     databuilder(path: string, options?: DataBuilderRouteOptions): void;
+    /** Register CSRF, model login, logout and refresh using the browser auth contract. */
+    auth(prefix: string, options?: AuthRouteOptions): void;
     /**
      * Register a POST-Method
      *

package/dist/Router/Route.js

@@ -1,9 +1,21 @@
 "use strict";
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Route = exports.RouteFacade = void 0;
 const routing_1 = require("../routing");
 const Router_1 = require("./Router");
 const DataBuilderRoute_1 = require("../DataBuilder/DataBuilderRoute");
+const Auth_1 = require("../Auth/Auth");
 class RouteFacade {
     constructor() {
         this.tempGroupPrefix = null;
@@ -69,6 +81,21 @@ class RouteFacade {
     databuilder(path, options = {}) {
         this.registerWithGroupContext("POST", path, (0, DataBuilderRoute_1.dataBuilderRoute)(options), { middleware: options.middleware, domains: options.domains });
     }
+    /** Register CSRF, model login, logout and refresh using the browser auth contract. */
+    auth(prefix, options = {}) {
+        const { auth = "main", loginPath, loginResponse, middleware, domains } = options, overrides = __rest(options, ["auth", "loginPath", "loginResponse", "middleware", "domains"]);
+        if (typeof auth !== "string" || !/^[A-Za-z0-9_-]+$/.test(auth))
+            throw new Error("Route.auth expects an auth scope key.");
+        if (Object.keys(overrides).length) {
+            Auth_1.Auth.registerScope(auth, overrides);
+        }
+        const base = prefix.replace(/\/+$/, "");
+        const registration = { middleware: options.middleware, domains: options.domains };
+        this.get(`${base}/csrf`, (0, Auth_1.authRoute)("csrf", options), registration);
+        this.post(options.loginPath || `${base}/login`, (0, Auth_1.authRoute)("login", options), registration);
+        this.post(`${base}/logout`, (0, Auth_1.authRoute)("logout", options), registration);
+        this.post(`${base}/refresh`, (0, Auth_1.authRoute)("refresh", options), registration);
+    }
     /**
      * Register a POST-Method
      *

package/dist/WebApplication.js

@@ -13,6 +13,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.WebApplication = void 0;
+const Auth_1 = require("./Auth/Auth");
 /// <reference types="node" />
 const http_1 = __importDefault(require("http"));
 const Config_1 = require("./Config");
@@ -47,6 +48,7 @@ class WebApplication {
                 Config_1.Config.register(key, options.config[key]);
             }
         }
+        Auth_1.Auth.init();
         NotificationService_1.NotificationService.init();
         if (options && options.errorHandler) {
             if (Array.isArray(options.errorHandler)) {

package/docs/authentication.md

@@ -279,3 +279,152 @@ configuration before rolling the new auth flow out to existing applications.
 - [OWASP Session Management](https://cheatsheetseries.owasp.org/cheatsheets/Session_Management_Cheat_Sheet.html)
 - [OWASP CSRF Prevention](https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html)
 - [OAuth Security BCP (RFC 9700)](https://www.rfc-editor.org/rfc/rfc9700.html)
+
+## Standard browser login with `Route.auth`
+
+```ts
+import { Model, AuthScope, Route } from "@webtypen/webframez-core";
+
+class User extends Model {
+    __table = "users";
+    __hidden = ["password"];
+}
+
+Route.auth("/api/auth", { model: User });
+// GET /api/auth/csrf
+// POST /api/auth/login, /api/auth/logout, /api/auth/refresh
+
+// During registration: user.password = await AuthScope.hashPassword(password);
+```
+
+Set `auth.origin` or `website.baseUrl` to the canonical public URL (including the
+correct development port); alternatively pass `origin` explicitly. HTTPS is
+required outside localhost/loopback. Origins are never inferred from untrusted
+Host or forwarding headers. Origin mismatches return `invalid_origin`; token
+mismatches return `invalid_csrf`. Browser CSRF protection cannot be disabled:
+`csrfDisabled` accepts only `false`. Non-browser bearer authentication uses a
+separate adapter.
+
+The default model fields are `_id`, `email`, `password` and `is_active`. Identifiers
+are trimmed and lowercased before lookup; store them normalized. Passwords are
+not trimmed. Store a bcrypt hash; existing bcrypt hashes work without migration.
+`fields` configures field names, `verifyPassword` supports other existing hashes,
+and `isUserAllowed` adds account/tenant checks on login and every session access.
+An explicit `false` in `is_active` rejects the account; `fields.active: false`
+disables this field check. Optional `session` options configure storage, scope
+and lifetimes. For `AuthScope`, access and absolute session lifetimes default to
+30 days; both remain configurable through `session.accessTokenSeconds` and
+`session.sessionSeconds`. The lower-level `SessionAuth` retains its 15-minute
+access-token default.
+
+```ts
+import { createAuthFetch, installAuthForms } from "@webtypen/webframez-core/auth-client";
+
+window.fetch = createAuthFetch({ basePath: "/api/auth" });
+installAuthForms({ basePath: "/api/auth" });
+```
+
+This public entry is browser-only and does not import server modules. It fetches
+CSRF before login, sends `X-CSRF-Token` on same-origin mutations, and inserts
+`_csrf` into native login forms. For a basename, supply the mounted `basePath`.
+`loginPaths` supports aliases; `requiresCsrf` narrows mutation paths;
+`cookieName` supports custom cookie prefixes. For a custom Fetch implementation,
+pass it as the second argument to `createAuthFetch`.
+
+`Route.auth` selects a shared registered scope with `auth: "main"` (the default).
+Model and other scope options passed to `Route.auth` configure that scope in the
+same `Auth` registry, including partial nested overrides.
+`loginPath` keeps existing URLs, `loginResponse` adds application-specific response
+fields (for example a validated redirect), and `onLogin` / `onAuthenticate` add application-specific callbacks. Browser
+user-agent metadata and last activity are recorded automatically; `trackActivity: false`
+disables tracking. Activity writes are throttled to once per minute. No user object or tokens are serialized by the default routes.
+Route groups retain their middleware and domain restrictions. Login routes must
+be accessible before authentication; apply authentication middleware to protected
+application routes separately.
+
+
+`audience` is a top-level option in both `Route.auth` and `AuthScope`. It takes
+precedence over the still-supported `session.audience`; the default is the origin.
+Standard error messages are included in English and German (`locale: "de"`);
+`messages` overrides individual entries while retaining the remaining defaults.
+Origin resolution also supports `application.website.baseUrl`, `WEBSITE_URL` and
+`PUBLIC_BASE_URL`; explicit `origin` retains precedence.
+
+```ts
+Route.auth("/api/auth", {
+    model: User,
+    audience: "simplebis-website",
+    locale: "de",
+    auth: "main",
+    // Optional overrides:
+    messages: { invalid_login: "Bitte prüfe deine Zugangsdaten." },
+});
+```
+
+Session metadata stays in the existing session collection. `sessions.list(subject)`
+includes `userAgent` and `lastActiveAt` when available, so applications do not need
+a second model/query or callbacks to maintain the session list. Existing records
+without metadata remain valid; last activity falls back to the creation timestamp.
+
+
+## Named auth scopes and lifecycle hooks
+
+```ts
+import { Auth, Config, Route } from "@webtypen/webframez-core";
+
+Config.register("auth", {
+    scopes: {
+        main: { model: User, audience: "website", locale: "de" },
+        admin: { model: AdminUser, audience: "administration" },
+    },
+});
+Route.auth("/api/auth", {
+    auth: "main",
+    beforeLogin: async (req, user, scope) => {
+        if (!await canLogIn(user, req)) throw new Error("Login denied by policy.");
+    },
+    afterLogin: async (req, user, scope) => { /* Login has completed. */ },
+    beforeLogout: async (req, user, scope) => { /* Throw to prevent logout. */ },
+    afterLogout: async (req, user, scope) => { /* Session revoked and cookies cleared. */ },
+});
+
+Auth.scope(); // same singleton scope as Auth.scope("main")
+Auth.scope("admin");
+Auth.registerScope("staff", { model: StaffUser });
+```
+
+Applications pass the auth configuration to the regular boot `config` object.
+Web, console and Lambda boot initialize the registry after registering Config.
+An automatic `main` scope exists unless `auth.main: false`; define its model in
+`auth.scopes.main` or in `Route.auth({ model: User })` before using login. Configured
+scopes and scopes registered at runtime remain available when automatic main is
+disabled. Unknown keys fail explicitly. `auth.defaults` supplies shared options.
+Registering an existing key updates its scope; routes resolve the current registry
+entry on each request. `ModelAuth` remains a compatibility alias of `AuthScope`.
+
+Each record in the default `auth_sessions` collection contains `scope`. Scope,
+issuer, audience and environment are checked for all session operations. Named
+scopes use separate cookie prefixes by default; configure the browser auth client
+with the selected scope's CSRF cookie name when using a non-main scope.
+The selected driver's ID adapter creates `_id` and converts `_subject`; MongoDB
+stores both as BSON ObjectId. Stored records contain no extra `id` or `subject`.
+Public session metadata still exposes string `id` and `subject` for transport.
+Injected document stores must provide `session.idAdapter` as well as `database`.
+
+The four hooks receive `(req, user, scope)` and await async callbacks. Login hooks
+receive the verified user, never a browser-supplied subject. CSRF and origin checks
+happen first. Exceptions in `beforeLogin` return `login_blocked`, and exceptions
+in `beforeLogout` return `logout_blocked`; the response includes the exception's
+message and a 403 status (or a thrown WebAuthError's status). No session/cookie
+mutation or after-hook occurs on a rejected before-hook. After-hooks run after the
+operation completes; their failures do not undo an already completed operation.
+Existing `onLogin(session, req)` and `onAuthenticate(auth, req)` callbacks remain
+supported. Individual `messages` entries can override before-hook error messages.
+
+When migrating old MongoDB sessions, convert the former opaque `_id` to ObjectId
+using the first 24 hex characters of SHA-256 of the former ID. Convert `subject`
+to `_subject`, remove duplicate `id`/`subject`, and set the correct `scope`. Keep
+hashes and expiry unchanged. SessionAuth recognizes the former token prefixes,
+so converted sessions retain their existing cookies. Applications should run
+an explicit migration while stopping auth writes, rather than changing schemas
+implicitly during a request.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@webtypen/webframez-core",
-    "version": "0.3.72",
+    "version": "0.3.74",
     "description": "The core package of the typescript based webframez (web-framework) by webtypen.de",
     "homepage": "https://webtypen.de/",
     "license": "MIT",
@@ -28,7 +28,9 @@
         "docs/authentication.md",
         "docs/databuilder.md",
         "routing.js",
-        "routing.d.ts"
+        "routing.d.ts",
+        "auth-client.js",
+        "auth-client.d.ts"
     ],
     "scripts": {
         "build": "tsc",
@@ -47,6 +49,7 @@
         "typescript": "^4.9.3"
     },
     "dependencies": {
+        "bcryptjs": "^3.0.3",
         "busboy": "^1.6.0",
         "dotenv": "^8.2.0",
         "extract-zip": "^2.0.1",