@webtypen/webframez-core 0.3.71 → 0.3.73

package/README.md

@@ -9,6 +9,7 @@ This README reflects the current API in this repository and focuses on:
 - DataBuilder
 - Console Commands
 - Queue and Jobs
+- Session, browser and cross-instance authentication
 
 ## Requirements
 
@@ -21,6 +22,16 @@ This README reflects the current API in this repository and focuses on:
 npm i @webtypen/webframez-core
 ```
 
+## Authentication
+
+New integrations can use `SessionAuth` for hashed, revocable device sessions,
+`WebAuth` for host-only browser cookies and CSRF protection, and
+`SsoAuthority` / `SsoClient` for first-party cross-instance login with single-use
+codes, PKCE and central session introspection. These APIs are opt-in; existing
+`UserAuth` consumers keep their current behavior.
+
+See [Authentication: setup, security model and migration](docs/authentication.md).
+
 ## Database drivers (from 0.3.69)
 
 The core has no MongoDB/BSON dependency. HTTP routing and database-independent
@@ -68,6 +79,7 @@ Die Regeln beschreiben unter anderem:
 - Nutzung von Model.objectId(...) statt eigener ObjectId-Resolver
 - bevorzugte Nutzung der vorhandenen Helper wie StringFunctions, NumericFunctions und DateFunctions
 - Verwendung der Webframez-Abstraktionen fuer Request, Response, Middleware, Storage, Datatables und Routes
+- sinnvolle Leerzeilen nach Imports, zwischen Eigenschaften und Methoden sowie zwischen Methoden
 
 Wichtig: AGENTS.md-Dateien haben keine universell standardisierte Import-Funktion. Die praktikable Variante ist deshalb, die Regeldatei aus dem Paket in der AGENTS.md des eigenen Projekts explizit zu referenzieren und projektspezifische Regeln lokal zu ergaenzen.
 
@@ -87,6 +99,7 @@ Insbesondere gilt:
 - fuer ObjectId-Konvertierungen Model.objectId(...) oder die passende Model-Instanzmethode verwenden
 - vorhandene Webframez-Helper und Facades bevorzugen statt neue Utilities oder Resolver anzulegen
 - fuer HTTP-, Routing-, Middleware-, Storage- und Datatable-Code die Webframez-APIs und Konventionen beibehalten
+- die Leerzeilenregeln aus dem Abschnitt "Code-Formatierung und Leerzeilen" einhalten
 
 Projektspezifische Ergaenzung:
 - dieses Projekt verwendet fuer Admin-Routen zusaetzlich die Middleware "admin-auth"
@@ -908,3 +921,7 @@ a penguin glyph fallback). Set `accessibilityLabel` only when the icon adds mean
 not already present in adjacent text. Optional `size` is a positive number.
 Content is rendered as text and icons, never HTML. Plain navigation labels retain
 the text representation; their separate `icon` property controls navigation icons.
+
+## DataBuilder model forms
+
+DataBuilder supports `@Field()`, parameterized `@Validates()`, server-side `ModelForm` classes and `Route.databuilder()` while retaining the v1 request protocol and legacy controller registrations. See [DataBuilder documentation](docs/databuilder.md).

package/agents/webframez_rules.md

@@ -15,6 +15,59 @@ Codex soll in Webframez-Projekten bevorzugt bestehende Framework-Abstraktionen n
 5. Neue Abstraktionen nur dann erzeugen, wenn die Framework-API die Anforderung nachweislich nicht abbildet.
 6. Controller-, Route-, Middleware-, Datatable- und Storage-Loesungen sollen idiomatisch fuer Webframez sein und nicht wie portierter Express-Code aussehen.
 
+## Code-Formatierung und Leerzeilen
+
+Diese Regeln gelten fuer neuen und bearbeiteten TypeScript-/JavaScript-Code im Core und in Webframez-Projekten. Verwende sinnvolle Leerzeilen, damit zusammengehoerige Bloecke erkennbar bleiben:
+
+1. Nach dem letzten Import folgt genau eine Leerzeile vor der ersten Deklaration bzw. ihrem zugehoerigen Kommentar oder Decorator.
+2. In Klassen folgt genau eine Leerzeile zwischen einem Block von Eigenschaften und dem ersten Konstruktor, Getter, Setter oder der ersten Methode.
+3. Zwischen einzelnen Konstruktoren, Methoden, Gettern und Settern steht genau eine Leerzeile. Zusammengehoerige TypeScript-Overload-Signaturen bleiben mit ihrer Implementierung als Gruppe zusammen.
+4. Zwischen eigenstaendigen Top-Level-Klassen, Funktionen, Interfaces und Typdefinitionen steht genau eine Leerzeile. Zugehoerige Kommentare und Decorators bleiben direkt an der Deklaration.
+5. Zusammengehoerige Eigenschaften, etwa `key` und `type`, bleiben ohne zusaetzliche Leerzeilen zusammen. Innerhalb von Methoden trennen Leerzeilen fachlich unterschiedliche Schritte; nicht jede einzelne Anweisung wird abgesetzt.
+6. Leerzeilen enthalten keine Leerzeichen oder Tabs. Keine mehrfachen Leerzeilen zur kuenstlichen Streckung verwenden. Vorhandene Einrueckungs- und Formatter-Vorgaben beibehalten.
+7. Die Abstaende beim Schreiben bzw. Bearbeiten direkt einhalten und vor Abschluss pruefen. Ein Formatter ersetzt diese Regel nicht, wenn er die erforderlichen Leerzeilen nicht selbst einfuegt. Unbeteiligte Dateien nicht allein fuer eine flaechenweite Formatierung umschreiben.
+
+Beispiel fuer den Abstand nach Imports:
+
+```ts
+import { FloatFieldType } from "./FloatFieldType";
+
+export class CurrencyFieldType extends FloatFieldType {
+    key = "currency";
+    type = "currency";
+}
+```
+
+Beispiel fuer Eigenschaften und Methoden:
+
+```ts
+import { DataBuilderFieldType, DataBuilderFieldContext, DataBuilderValidationContext } from "../DataBuilderFieldType";
+
+export class ObjectFieldType extends DataBuilderFieldType {
+    key = "object";
+    type = "object";
+
+    missingValue(context: DataBuilderFieldContext): any {
+        return context.structured && context.field.schema ? this.convert({}, context) : null;
+    }
+
+    async validate(value: any, context: DataBuilderValidationContext) {
+        const error = await super.validate(value, context);
+        if (error) return error;
+        return context.structured && !this.isMissing(value) && (typeof value !== "object" || Array.isArray(value))
+            ? "Bitte ein Objekt angeben."
+            : null;
+    }
+
+    async convert(value: any, context: DataBuilderFieldContext) {
+        if (context.structured && context.field.schema) {
+            return context.applyChildren(context.field.schema, { ...(context.currentValue || {}) }, context.path);
+        }
+        return value;
+    }
+}
+```
+
 ## Imports
 
 Bevorzuge immer dieses Muster:

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

@@ -0,0 +1,11 @@
+/// <reference types="node" />
+import type { Request } from "../Router/Request";
+/** Internal primitives shared by session, browser and SSO authentication. */
+export declare function randomAuthToken(): string;
+export declare function hashAuthToken(value: string): string;
+export declare function equalAuthToken(left: unknown, right: unknown): boolean;
+export declare function authText(value: unknown, name: string, max?: number): string;
+export declare function authLifetime(value: number | undefined, fallback: number): number;
+export declare function authHeader(req: Pick<Request, "headers">, name: string): string;
+export declare function authCookie(req: Pick<Request, "headers">, name: string): string;
+export declare function authUrl(value: string, allowInsecureLocalhost?: boolean): URL;

package/dist/Auth/AuthSecurity.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.authUrl = exports.authCookie = exports.authHeader = exports.authLifetime = exports.authText = exports.equalAuthToken = exports.hashAuthToken = exports.randomAuthToken = void 0;
+const crypto_1 = require("crypto");
+/** Internal primitives shared by session, browser and SSO authentication. */
+function randomAuthToken() { return (0, crypto_1.randomBytes)(32).toString("base64url"); }
+exports.randomAuthToken = randomAuthToken;
+function hashAuthToken(value) { return (0, crypto_1.createHash)("sha256").update(value).digest("hex"); }
+exports.hashAuthToken = hashAuthToken;
+function equalAuthToken(left, right) {
+    if (typeof left !== "string" || typeof right !== "string" || left.length > 4096 || right.length > 4096)
+        return false;
+    const a = Buffer.from(left), b = Buffer.from(right);
+    return a.length === b.length && (0, crypto_1.timingSafeEqual)(a, b);
+}
+exports.equalAuthToken = equalAuthToken;
+function authText(value, name, max = 512) {
+    if (typeof value !== "string" || !value.length || value.length > max || /[\x00-\x20\x7f]/.test(value))
+        throw new Error(`Invalid ${name}.`);
+    return value;
+}
+exports.authText = authText;
+function authLifetime(value, fallback) {
+    const result = value === undefined ? fallback : value;
+    if (!Number.isSafeInteger(result) || result <= 0)
+        throw new Error("Auth lifetimes must be positive integer seconds.");
+    return result;
+}
+exports.authLifetime = authLifetime;
+function authHeader(req, name) {
+    const key = Object.keys(req.headers || {}).find(key => key.toLowerCase() === name.toLowerCase());
+    const value = key ? req.headers[key] : undefined;
+    return typeof value === "string" ? value : "";
+}
+exports.authHeader = authHeader;
+function authCookie(req, name) {
+    const matches = authHeader(req, "cookie").split(";").map(part => part.trim()).filter(part => part.startsWith(`${name}=`));
+    if (matches.length !== 1)
+        return ""; // Reject ambiguous/shadowed cookies.
+    try {
+        return decodeURIComponent(matches[0].slice(name.length + 1));
+    }
+    catch (_a) {
+        return "";
+    }
+}
+exports.authCookie = authCookie;
+function authUrl(value, allowInsecureLocalhost = false) {
+    const url = new URL(value);
+    const local = allowInsecureLocalhost && url.protocol === "http:" && ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname);
+    if ((!local && url.protocol !== "https:") || url.username || url.password || url.hash)
+        throw new Error("Auth URLs require HTTPS and must not contain credentials or fragments.");
+    return url;
+}
+exports.authUrl = authUrl;

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

@@ -0,0 +1,67 @@
+import type { DocumentDatabase } from "../Database/DatabaseAdapter";
+export type AuthSession = {
+    id: string;
+    subject: string;
+    issuer: string;
+    audience: string;
+    environment: string | null;
+    userAgent?: string;
+    lastActiveAt?: number;
+    createdAt: number;
+    expiresAt: number;
+    parent: {
+        issuer: string;
+        sessionId: string;
+    } | null;
+};
+export type SessionTokenPair = {
+    auth_token: string;
+    refresh_token: string;
+    auth_expires_at: number;
+    refresh_expires_at: number;
+    session: AuthSession;
+};
+export type CreatedAuthSession = SessionTokenPair & {
+    csrf_token: string;
+};
+export type SessionAuthOptions = {
+    issuer: string;
+    audience: string;
+    environment?: string;
+    connection?: string;
+    collection?: string;
+    accessTokenSeconds?: number;
+    sessionSeconds?: number;
+    /** Called on creation, authentication and refresh. Check account status and tenant membership here.
+     * For federated sessions this can also introspect the parent authority session. Failures fail closed. */
+    isSessionAllowed: (session: AuthSession) => boolean | Promise<boolean>;
+    /** Dependency injection for a document-capable driver. Atomic findOneAndUpdate is required. */
+    database?: () => Promise<DocumentDatabase>;
+};
+/** Revocable, hashed, independently addressable device sessions. Legacy UserAuth is unaffected. */
+export declare class SessionAuth {
+    private readonly options;
+    private readonly scope;
+    private readonly accessSeconds;
+    private readonly sessionSeconds;
+    constructor(options: SessionAuthOptions);
+    private rows;
+    private allowed;
+    private pair;
+    create(subject: string, parent?: AuthSession["parent"]): Promise<CreatedAuthSession>;
+    authenticate(token: string): Promise<AuthSession | null>;
+    /** Trusted-server introspection; never expose this method as an unauthenticated endpoint. */
+    inspect(sessionId: string): Promise<AuthSession | null>;
+    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[]>;
+    /** Run periodically; authorization checks never depend on cleanup scheduling. */
+    cleanup(): Promise<void>;
+}