@webtypen/webframez-core 0.3.72 → 0.3.73

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/ModelAuth.d.ts

@@ -0,0 +1,72 @@
+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";
+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;
+    /** 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>;
+    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 AuthOperation = "csrf" | "login" | "logout" | "refresh";
+export type AuthRouteOptions = Partial<ModelAuthOptions> & {
+    auth?: ModelAuth | (() => ModelAuth);
+    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 ModelAuth extends WebAuth {
+    private readonly modelOptions;
+    private readonly model;
+    private readonly sessionUsers;
+    private readonly fields;
+    constructor(modelOptions: 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>;
+    /** 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>;
+}
+export declare function authRoute(operation: AuthOperation, options: AuthRouteOptions): (req: Request, res: Response) => Promise<Response>;

package/dist/Auth/ModelAuth.js

@@ -0,0 +1,226 @@
+"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.authRoute = exports.ModelAuth = 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;
+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.",
+    },
+    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.",
+    },
+};
+// Verify a dummy password hash for unknown accounts as well.
+let dummyHash;
+/** Model-backed browser authentication with secure default routes and revocable sessions. */
+class ModelAuth extends WebAuth_1.WebAuth {
+    constructor(modelOptions) {
+        var _a, _b, _c, _d, _e;
+        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 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, audience: (_c = (_a = modelOptions.audience) !== null && _a !== void 0 ? _a : (_b = modelOptions.session) === null || _b === void 0 ? void 0 : _b.audience) !== null && _c !== void 0 ? _c : origin, connection: ((_d = modelOptions.session) === null || _d === void 0 ? void 0 : _d.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, allowInsecureLocalhost: (_e = modelOptions.allowInsecureLocalhost) !== null && _e !== void 0 ? _e : true }));
+        this.modelOptions = modelOptions;
+        this.sessionUsers = sessionUsers;
+        this.model = model;
+        this.fields = fields;
+    }
+    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* () {
+            const session = yield _super.login.call(this, req, res, verifyCredentials);
+            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);
+            return session;
+        });
+    }
+    /** 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) {
+        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: this.message(code) });
+            }
+        });
+    }
+}
+exports.ModelAuth = ModelAuth;
+function authRoute(operation, options) {
+    let auth;
+    return (req, res) => {
+        auth || (auth = typeof options.auth === "function" ? options.auth() : options.auth || new ModelAuth(options));
+        return auth.handle(operation, req, res, options.loginResponse);
+    };
+}
+exports.authRoute = authRoute;

package/dist/Auth/SessionAuth.d.ts

@@ -5,6 +5,8 @@ export type AuthSession = {
     issuer: string;
     audience: string;
     environment: string | null;
+    userAgent?: string;
+    lastActiveAt?: number;
     createdAt: number;
     expiresAt: number;
     parent: {
@@ -53,6 +55,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,8 +13,7 @@ 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: record.id, subject: record.subject, issuer: record.issuer, audience: record.audience, 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;
@@ -122,6 +121,25 @@ class SessionAuth {
             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: 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: 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");

package/dist/Auth/index.d.ts

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

package/dist/Auth/index.js

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

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

@@ -4,6 +4,7 @@ exports.Route = exports.RouteFacade = void 0;
 const routing_1 = require("../routing");
 const Router_1 = require("./Router");
 const DataBuilderRoute_1 = require("../DataBuilder/DataBuilderRoute");
+const ModelAuth_1 = require("../Auth/ModelAuth");
 class RouteFacade {
     constructor() {
         this.tempGroupPrefix = null;
@@ -69,6 +70,17 @@ 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) {
+        if (!(options === null || options === void 0 ? void 0 : options.auth) && !(options === null || options === void 0 ? void 0 : options.model))
+            throw new Error("Route.auth requires a Model class or auth instance.");
+        const base = prefix.replace(/\/+$/, "");
+        const registration = { middleware: options.middleware, domains: options.domains };
+        this.get(`${base}/csrf`, (0, ModelAuth_1.authRoute)("csrf", options), registration);
+        this.post(options.loginPath || `${base}/login`, (0, ModelAuth_1.authRoute)("login", options), registration);
+        this.post(`${base}/logout`, (0, ModelAuth_1.authRoute)("logout", options), registration);
+        this.post(`${base}/refresh`, (0, ModelAuth_1.authRoute)("refresh", options), registration);
+    }
     /**
      * Register a POST-Method
      *

package/docs/authentication.md

@@ -279,3 +279,88 @@ 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, ModelAuth, 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 ModelAuth.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 `ModelAuth`, 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`.
+
+Existing applications can pass `auth: instance` or `auth: () => instance` instead
+of `model`; use a shared `ModelAuth` for middleware and session-management APIs.
+`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 `ModelAuth`. 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",
+    session: { collection: "website_auth_sessions" },
+    // 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.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@webtypen/webframez-core",
-    "version": "0.3.72",
+    "version": "0.3.73",
     "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",