@webtypen/webframez-core 0.3.76 → 0.3.78

package/README.md

@@ -925,3 +925,16 @@ the text representation; their separate `icon` property controls navigation icon
 ## 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).
+
+## Routing and lifecycle performance
+
+Route and domain patterns are compiled at registration and reused while matching.
+`Router.init()` resets their caches; runtime registration and legacy direct route
+stores still work. Exact-route precedence, domain ordering, parameters and wildcards
+retain their existing behavior. Public regex builders still produce fresh regexes.
+
+Lifecycle hooks skip event normalization when no listeners are registered. Use
+`WebframezHooks.hasListeners(eventName)` before constructing an expensive payload.
+Registered handlers retain their ordered, awaited execution and snapshot behavior.
+The router applies this check before building telemetry payloads. Middleware keeps
+its existing `next`/`reject` callback contract.

package/bearer-auth-client.d.ts

@@ -0,0 +1,13 @@
+export type BearerAuthTokens = {
+    auth_token: string;
+    refresh_token: string;
+    auth_expires_at: number;
+    refresh_expires_at: number;
+};
+
+export function createBearerAuthFetch(options: {
+    configuration: (url: URL) => { key: string; refreshUrl: string } | null;
+    load: (key: string) => Promise<BearerAuthTokens | null>;
+    clear?: (key: string) => Promise<void>;
+    save: (key: string, tokens: BearerAuthTokens) => Promise<void>;
+}, originalFetch?: typeof fetch): typeof fetch;

package/bearer-auth-client.js

@@ -0,0 +1,67 @@
+/** Browser/native entry point; imports no server or database code. */
+exports.createBearerAuthFetch = function createBearerAuthFetch(options, originalFetch = globalThis.fetch.bind(globalThis)) {
+    const pending = new Map();
+    const refresh = (configuration, failedToken) => {
+        const key = configuration.key;
+        const perform = async () => {
+            const current = await options.load(key);
+            if (!current) return null;
+            if (failedToken && current.auth_token !== failedToken) return current;
+            let response;
+            try {
+                response = await originalFetch(configuration.refreshUrl, { method: "POST", credentials: "omit",
+                    headers: { "Content-Type": "application/json" }, body: JSON.stringify({ refresh_token: current.refresh_token }),
+                    redirect: "error", signal: typeof AbortSignal !== "undefined" && typeof AbortSignal.timeout === "function" ? AbortSignal.timeout(15000) : undefined });
+            } catch (error) {
+                // A timeout may have consumed the rotating token; never replay it automatically.
+                if (options.clear) await options.clear(key);
+                return null;
+            }
+            if (!response.ok) {
+                if (options.clear) await options.clear(key);
+                return null;
+            }
+            let pair;
+            try { pair = await response.json(); }
+            catch { if (options.clear) await options.clear(key); return null; }
+            if (pair.status !== "success" || typeof pair.auth_token !== "string" || typeof pair.refresh_token !== "string"
+                || !Number.isFinite(pair.auth_expires_at) || !Number.isFinite(pair.refresh_expires_at)) {
+                if (options.clear) await options.clear(key);
+                return null;
+            }
+            const latest = await options.load(key);
+            if (!latest || latest.refresh_token !== current.refresh_token) return latest;
+            await options.save(key, pair);
+            return pair;
+        };
+        if (!pending.has(key)) {
+            const task = typeof navigator !== "undefined" && navigator.locks
+                ? navigator.locks.request(`webframez-bearer:${key}`, perform) : perform();
+            pending.set(key, task.finally(() => pending.delete(key)));
+        }
+        return pending.get(key);
+    };
+    return async (input, init) => {
+        let url;
+        try { url = new URL(typeof Request !== "undefined" && input instanceof Request ? input.url : String(input), globalThis.location?.href); }
+        catch { return originalFetch(input, init); }
+        const configuration = options.configuration(url);
+        if (!configuration) return originalFetch(input, init);
+        const refreshUrl = new URL(configuration.refreshUrl);
+        if (refreshUrl.origin !== url.origin) throw new Error("Bearer refresh must use the request origin.");
+        let session = await options.load(configuration.key);
+        if (!session || url.href === refreshUrl.href) return originalFetch(input, init);
+        if (session.auth_expires_at <= Date.now() + 30000) session = await refresh(configuration, session.auth_token) || session;
+        const headers = new Headers(init?.headers || (typeof Request !== "undefined" && input instanceof Request ? input.headers : undefined));
+        headers.set("Authorization", `Bearer ${session.auth_token}`);
+        const retryInput = typeof Request !== "undefined" && input instanceof Request ? input.clone() : input;
+        const response = await originalFetch(input, { ...init, headers, credentials: "omit", redirect: "error" });
+        if (response.status !== 401) return response;
+        const failure = await response.clone().json().catch(() => null);
+        if (failure?.code !== "unauthorized") return response;
+        const renewed = await refresh(configuration, session.auth_token);
+        if (!renewed) return response;
+        headers.set("Authorization", `Bearer ${renewed.auth_token}`);
+        return originalFetch(retryInput, { ...init, headers, credentials: "omit", redirect: "error" });
+    };
+};

package/dist/Auth/Auth.js

@@ -15,7 +15,7 @@ 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), passwordReset: config.passwordReset === false ? false : config.passwordReset === undefined && base.passwordReset === false ? false
-            : Object.assign(Object.assign({}, (base.passwordReset || {})), (config.passwordReset || {})), messages: Object.assign(Object.assign({}, base.messages), config.messages) });
+            : Object.assign(Object.assign({}, (base.passwordReset || {})), (config.passwordReset || {})), memberships: Object.assign(Object.assign({}, base.memberships), config.memberships), messages: Object.assign(Object.assign({}, base.messages), config.messages) });
 }
 /** Application-wide registry of named browser-authentication scopes. */
 class AuthFacade {

package/dist/Auth/AuthHandoff.d.ts

@@ -0,0 +1,16 @@
+import type { DocumentDatabase } from "../Database/DatabaseAdapter";
+/** Single-use delivery to a separate frontend origin after a server-side SSO callback. */
+export declare class AuthHandoff {
+    private readonly options;
+    private readonly key;
+    constructor(options: {
+        secret: string;
+        audience: string;
+        connection?: string;
+        database?: () => Promise<DocumentDatabase>;
+    });
+    private rows;
+    create(payload: object): Promise<string>;
+    consume<T = unknown>(code: string): Promise<T | null>;
+    cleanup(): Promise<void>;
+}

package/dist/Auth/AuthHandoff.js

@@ -0,0 +1,64 @@
+"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.AuthHandoff = void 0;
+const crypto_1 = require("crypto");
+const DBConnection_1 = require("../Database/DBConnection");
+const AuthSecurity_1 = require("./AuthSecurity");
+/** Single-use delivery to a separate frontend origin after a server-side SSO callback. */
+class AuthHandoff {
+    constructor(options) {
+        this.options = options;
+        if (typeof options.secret !== "string" || options.secret.length < 32)
+            throw new Error("Auth handoff requires a strong server secret.");
+        if (!options.audience)
+            throw new Error("Auth handoff requires an audience.");
+        this.key = (0, crypto_1.createHash)("sha256").update(`webframez-handoff:${options.secret}`).digest();
+    }
+    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));
+            return db.collection("auth_handoffs");
+        });
+    }
+    create(payload) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const code = (0, AuthSecurity_1.randomAuthToken)(), iv = (0, crypto_1.randomBytes)(12);
+            const cipher = (0, crypto_1.createCipheriv)("aes-256-gcm", this.key, iv);
+            cipher.setAAD(Buffer.from(this.options.audience));
+            const encrypted = Buffer.concat([cipher.update(JSON.stringify(payload), "utf8"), cipher.final()]);
+            yield (yield this.rows()).insertOne({ _id: (0, AuthSecurity_1.hashAuthToken)(code), audience: this.options.audience,
+                iv: iv.toString("base64"), tag: cipher.getAuthTag().toString("base64"), payload: encrypted.toString("base64"),
+                expiresAt: Date.now() + 30000, purgeAt: new Date(Date.now() + 60000), consumedAt: null });
+            return code;
+        });
+    }
+    consume(code) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (typeof code !== "string" || !/^[A-Za-z0-9_-]{43}$/.test(code))
+                return null;
+            const row = yield (yield this.rows()).findOneAndUpdate({ _id: (0, AuthSecurity_1.hashAuthToken)(code), audience: this.options.audience,
+                expiresAt: { $gt: Date.now() }, consumedAt: null }, { $set: { consumedAt: Date.now(), payload: "" } }, { returnDocument: "before" });
+            if (!row)
+                return null;
+            const decipher = (0, crypto_1.createDecipheriv)("aes-256-gcm", this.key, Buffer.from(row.iv, "base64"));
+            decipher.setAAD(Buffer.from(this.options.audience));
+            decipher.setAuthTag(Buffer.from(row.tag, "base64"));
+            return JSON.parse(Buffer.concat([decipher.update(Buffer.from(row.payload, "base64")), decipher.final()]).toString("utf8"));
+        });
+    }
+    cleanup() {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield (yield this.rows()).deleteMany({ audience: this.options.audience, expiresAt: { $lte: Date.now() } });
+        });
+    }
+}
+exports.AuthHandoff = AuthHandoff;

package/dist/Auth/AuthMembership.d.ts

@@ -0,0 +1,39 @@
+import { Model } from "../Database/Model";
+export type AuthMembershipCondition = {
+    field: string;
+    operator: "=" | "!=";
+    value: unknown;
+};
+export type AuthMembershipBinding = {
+    user: {
+        foreignKey: string;
+        localKeys: readonly string[];
+        firstAvailable?: boolean;
+    };
+    resource: {
+        foreignKey: string;
+        localKeys: readonly string[];
+    };
+};
+/** Only server-loaded models and server-configured fields participate in authorization. */
+export type AuthMembershipOptions = {
+    model: typeof Model;
+    bindings: readonly AuthMembershipBinding[];
+    /** Optionally bind this membership to the environment selected by a federated session. */
+    sessionEnvironmentKey?: string;
+    conditions?: readonly AuthMembershipCondition[];
+    userConditions?: readonly AuthMembershipCondition[];
+    resourceConditions?: readonly AuthMembershipCondition[];
+};
+export type AuthMembershipContext<TMembership extends Model = Model, TResource extends Model = Model> = {
+    membership: TMembership;
+    resource: TResource;
+};
+/** Resolves fresh membership records without caching authorization between requests. */
+export declare class AuthMembership {
+    private readonly options;
+    constructor(options: AuthMembershipOptions);
+    private matches;
+    matchesEnvironment(resource: Model, environment: string | null): boolean;
+    find<TMembership extends Model = Model>(user: Model, resource: Model): Promise<TMembership | null>;
+}

package/dist/Auth/AuthMembership.js

@@ -0,0 +1,62 @@
+"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.AuthMembership = void 0;
+const Model_1 = require("../Database/Model");
+/** Resolves fresh membership records without caching authorization between requests. */
+class AuthMembership {
+    constructor(options) {
+        var _a;
+        this.options = options;
+        if (!options.model || !((_a = options.bindings) === null || _a === void 0 ? void 0 : _a.length))
+            throw new Error("Auth membership requires a model and bindings.");
+        for (const binding of options.bindings) {
+            if (!binding.user.foreignKey || !binding.resource.foreignKey
+                || !binding.user.localKeys.length || !binding.resource.localKeys.length) {
+                throw new Error("Auth membership requires user and resource reference fields.");
+            }
+        }
+    }
+    matches(model, conditions = []) {
+        return conditions.every(condition => condition.operator === "="
+            ? model[condition.field] === condition.value : model[condition.field] !== condition.value);
+    }
+    matchesEnvironment(resource, environment) {
+        const key = this.options.sessionEnvironmentKey;
+        return !environment || !key || String(resource === null || resource === void 0 ? void 0 : resource[key]) === environment;
+    }
+    find(user, resource) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!(user instanceof Model_1.Model) || !(resource instanceof Model_1.Model)
+                || !this.matches(user, this.options.userConditions) || !this.matches(resource, this.options.resourceConditions))
+                return null;
+            for (const binding of this.options.bindings) {
+                let userIds = binding.user.localKeys.map(key => user[key]).filter(value => value !== null && value !== undefined && value !== "");
+                if (binding.user.firstAvailable)
+                    userIds = userIds.slice(0, 1);
+                const resourceIds = binding.resource.localKeys.map(key => resource[key]).filter(value => value !== null && value !== undefined && value !== "");
+                // Missing references must never turn into an unbounded membership lookup.
+                if (!userIds.length || !resourceIds.length)
+                    continue;
+                let query = this.options.model.where(binding.user.foreignKey, "=", { $in: userIds })
+                    .where(binding.resource.foreignKey, "=", { $in: resourceIds });
+                for (const condition of this.options.conditions || []) {
+                    query = query.where(condition.field, condition.operator, condition.value);
+                }
+                const membership = yield query.first();
+                if (membership)
+                    return membership;
+            }
+            return null;
+        });
+    }
+}
+exports.AuthMembership = AuthMembership;

package/dist/Auth/ModelAuth.d.ts

@@ -1,12 +1,14 @@
 import { Model } from "../Database/Model";
 import { Request } from "../Router/Request";
 import type { Response } from "../Router/Response";
+import { AuthMembershipContext, AuthMembershipOptions } from "./AuthMembership";
 import { PasswordReset, PasswordResetOptions } from "./PasswordReset";
 import { AuthSession, SessionAuthOptions } from "./SessionAuth";
 import { WebAuth, WebAuthError, WebAuthOptions } from "./WebAuth";
 export type AuthContext<TUser extends Model = Model> = {
     user: TUser;
     session: AuthSession;
+    memberships?: Record<string, AuthMembershipContext>;
 };
 export type AuthSnapshot<TUser = Record<string, unknown>> = {
     user: TUser;
@@ -19,6 +21,8 @@ export declare class AuthLoginError extends WebAuthError {
 }
 export type ModelAuthOptions = Partial<WebAuthOptions> & {
     model: typeof Model;
+    /** Bearer scopes return opaque tokens and never use ambient authentication cookies. */
+    transport?: "cookie" | "bearer";
     key?: string;
     /** Takes precedence over session.audience; defaults to the configured origin. */
     audience?: string;
@@ -35,6 +39,8 @@ export type ModelAuthOptions = Partial<WebAuthOptions> & {
     session?: Partial<Omit<SessionAuthOptions, "issuer" | "isSessionAllowed">>;
     csrfDisabled?: false;
     verifyPassword?: (password: string, storedHash: string) => boolean | Promise<boolean>;
+    memberships?: Record<string, AuthMembershipOptions>;
+    isSessionAllowed?: (session: AuthSession, user: Model) => boolean | Promise<boolean>;
     isUserAllowed?: (user: Model) => boolean | Promise<boolean>;
     beforeLogin?: AuthActionHook;
     afterLogin?: AuthActionHook;
@@ -60,6 +66,8 @@ export declare class AuthScope extends WebAuth {
     readonly key: string;
     readonly passwordReset: PasswordReset | null;
     private readonly model;
+    private readonly memberships;
+    private readonly contexts;
     private authPaths;
     private readonly sessionUsers;
     private readonly fields;
@@ -77,8 +85,23 @@ export declare class AuthScope extends WebAuth {
     verifyCredentials(req: Request): Promise<string>;
     login(req: Request, res: Response, verifyCredentials?: () => Promise<string | null>): Promise<AuthSession>;
     logout(req: Request, res: Response): Promise<void>;
+    /** Trusted SSO/server entry point; the subject must already be verified by the caller. */
+    establishBearerSession(req: Request, subject: string, parent?: AuthSession["parent"], environment?: string): Promise<{
+        auth_token: string;
+        refresh_token: string;
+        auth_expires_at: number;
+        refresh_expires_at: number;
+        session: AuthSession;
+    }>;
+    logoutBearer(req: Request): Promise<void>;
+    /** Explicit Authorization credentials require no cookie CSRF and are never read from query parameters. */
+    resolveBearer<TUser extends Model = Model>(req: Request, res?: Response): Promise<AuthContext<TUser> | null>;
     /** Resolve a fresh validated session and its model; never trusts a client-supplied req.auth. */
     resolve<TUser extends Model = Model>(req: Request, res?: Response): Promise<AuthContext<TUser> | null>;
+    /** For integrations whose authenticated User was established by another trusted transport. */
+    findMembership<TMembership extends Model = Model>(name: string, user: Model, resource: Model): Promise<TMembership | null>;
+    /** Attaches a fresh membership only to a context authenticated by this scope. */
+    authorizeMembership<TMembership extends Model = Model>(req: Request, name: string, resource: Model): Promise<TMembership | 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;

package/dist/Auth/ModelAuth.js

@@ -8,6 +8,17 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
+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.ModelAuth = exports.AuthScope = exports.AuthLoginError = void 0;
 const bcryptjs_1 = require("bcryptjs");
@@ -15,6 +26,7 @@ const routing_1 = require("../routing");
 const Config_1 = require("../Config");
 const Request_1 = require("../Router/Request");
 const Auth_1 = require("./Auth");
+const AuthMembership_1 = require("./AuthMembership");
 const PasswordReset_1 = require("./PasswordReset");
 const AuthSecurity_1 = require("./AuthSecurity");
 const SessionAuth_1 = require("./SessionAuth");
@@ -79,14 +91,21 @@ class AuthScope extends WebAuth_1.WebAuth {
         const sessions = new SessionAuth_1.SessionAuth(Object.assign(Object.assign({ accessTokenSeconds: 15 * 60, sessionSeconds: 30 * 86400, idleTimeoutSeconds: 7 * 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)))
+                if (!(yield allowed(user)) || (modelOptions.isSessionAllowed && !(yield modelOptions.isSessionAllowed(session, 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.memberships = new Map();
+        this.contexts = new WeakSet();
         this.authPaths = { basePath: "/api/auth", loginPath: "/api/auth/login" };
+        for (const [name, options] of Object.entries(modelOptions.memberships || {})) {
+            if (!/^[A-Za-z0-9_-]+$/.test(name))
+                throw new Error("Invalid auth membership key.");
+            this.memberships.set(name, new AuthMembership_1.AuthMembership(options));
+        }
         this.key = key;
         this.sessionUsers = sessionUsers;
         this.model = model;
@@ -191,6 +210,82 @@ class AuthScope extends WebAuth_1.WebAuth {
                 yield this.modelOptions.afterLogout(req, user, this);
         });
     }
+    /** Trusted SSO/server entry point; the subject must already be verified by the caller. */
+    establishBearerSession(req, subject, parent = null, environment) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (this.modelOptions.transport !== "bearer")
+                throw new Error("Bearer transport is not enabled for this auth scope.");
+            const id = this.fields.primaryKey === "_id" ? yield this.model.objectId(subject, { noExceptions: true }) : subject;
+            const user = id == null ? null : yield this.model.where(this.fields.primaryKey, "=", id).first();
+            if (!user || (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"));
+            }
+            if (this.modelOptions.beforeLogin) {
+                try {
+                    yield this.modelOptions.beforeLogin(req, user, this);
+                }
+                catch (error) {
+                    throw new AuthHookError("login_blocked", error);
+                }
+            }
+            const pair = yield this.sessions.create(subject, parent, environment);
+            if (this.modelOptions.trackActivity !== false)
+                yield this.sessions.recordLogin(pair.session, (0, AuthSecurity_1.authHeader)(req, "user-agent"));
+            if (this.modelOptions.onLogin)
+                yield this.modelOptions.onLogin(pair.session, req);
+            if (this.modelOptions.afterLogin)
+                yield this.modelOptions.afterLogin(req, user, this);
+            const { csrf_token } = pair, tokens = __rest(pair, ["csrf_token"]);
+            return tokens;
+        });
+    }
+    logoutBearer(req) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (req.method !== "POST")
+                throw new WebAuth_1.WebAuthError(403, "Logout requires POST.");
+            const auth = yield this.resolveBearer(req);
+            if (!auth)
+                throw new AuthLoginError("unauthorized", 401, this.message("unauthorized"));
+            if (this.modelOptions.beforeLogout) {
+                try {
+                    yield this.modelOptions.beforeLogout(req, auth.user, this);
+                }
+                catch (error) {
+                    throw new AuthHookError("logout_blocked", error);
+                }
+            }
+            yield this.sessions.revoke(auth.session.id);
+            if (this.modelOptions.afterLogout)
+                yield this.modelOptions.afterLogout(req, auth.user, this);
+        });
+    }
+    /** Explicit Authorization credentials require no cookie CSRF and are never read from query parameters. */
+    resolveBearer(req, res) {
+        var _a;
+        return __awaiter(this, void 0, void 0, function* () {
+            if (this.modelOptions.transport !== "bearer")
+                throw new Error("Bearer transport is not enabled for this auth scope.");
+            res === null || res === void 0 ? void 0 : res.header("Cache-Control", "no-store");
+            Object.defineProperty(req, "auth", { value: null, writable: true, configurable: true, enumerable: false });
+            const header = (0, AuthSecurity_1.authHeader)(req, "authorization");
+            const token = (_a = /^Bearer ([A-Za-z0-9_-]{1,128}\.[A-Za-z0-9_-]{43})$/i.exec(header)) === null || _a === void 0 ? void 0 : _a[1];
+            if (!token)
+                return null;
+            const session = yield this.sessions.authenticate(token);
+            const user = session && this.sessionUsers.get(session);
+            if (!session || !user)
+                return null;
+            if (this.modelOptions.trackActivity !== false)
+                yield this.sessions.touch(session);
+            const auth = { user, session };
+            this.contexts.add(auth);
+            if (this.modelOptions.onAuthenticate)
+                yield this.modelOptions.onAuthenticate(auth, req);
+            req.auth = auth;
+            return auth;
+        });
+    }
     /** Resolve a fresh validated session and its model; never trusts a client-supplied req.auth. */
     resolve(req, res) {
         const _super = Object.create(null, {
@@ -198,6 +293,8 @@ class AuthScope extends WebAuth_1.WebAuth {
             resume: { get: () => super.resume }
         });
         return __awaiter(this, void 0, void 0, function* () {
+            if (this.modelOptions.transport === "bearer")
+                return this.resolveBearer(req, res);
             res === null || res === void 0 ? void 0 : res.header("Cache-Control", "no-store");
             Object.defineProperty(req, "auth", { value: null, writable: true, configurable: true, enumerable: false });
             const session = (yield _super.authenticate.call(this, req)) || (res ? yield _super.resume.call(this, req, res) : null);
@@ -209,12 +306,44 @@ class AuthScope extends WebAuth_1.WebAuth {
             if (this.modelOptions.trackActivity !== false)
                 yield this.sessions.touch(session);
             const auth = { user, session };
+            this.contexts.add(auth);
             if (this.modelOptions.onAuthenticate)
                 yield this.modelOptions.onAuthenticate(auth, req);
             req.auth = auth;
             return auth;
         });
     }
+    /** For integrations whose authenticated User was established by another trusted transport. */
+    findMembership(name, user, resource) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const resolver = this.memberships.get(name);
+            if (!resolver)
+                throw new Error(`Auth membership "${name}" is not configured.`);
+            return resolver.find(user, resource);
+        });
+    }
+    /** Attaches a fresh membership only to a context authenticated by this scope. */
+    authorizeMembership(req, name, resource) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const auth = req.auth;
+            if (!auth || !this.contexts.has(auth))
+                return null;
+            if (auth.memberships)
+                delete auth.memberships[name];
+            const resolver = this.memberships.get(name);
+            if (!resolver)
+                throw new Error(`Auth membership "${name}" is not configured.`);
+            if (!resolver.matchesEnvironment(resource, auth.session.environment))
+                return null;
+            const membership = yield resolver.find(auth.user, resource);
+            if (!membership)
+                return null;
+            if (!auth.memberships)
+                auth.memberships = Object.create(null);
+            auth.memberships[name] = { resource, membership };
+            return membership;
+        });
+    }
     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`] || "")}` } });
@@ -261,10 +390,29 @@ class AuthScope extends WebAuth_1.WebAuth {
         });
     }
     handle(operation, req, res, loginResponse) {
-        var _a, _b;
+        var _a, _b, _c;
         return __awaiter(this, void 0, void 0, function* () {
             res.header("Cache-Control", "no-store");
             try {
+                if (this.modelOptions.transport === "bearer") {
+                    if (operation === "csrf")
+                        return res.status(405).send({ status: "error", code: "unsupported_operation" });
+                    if (req.method !== "POST")
+                        throw new WebAuth_1.WebAuthError(403, "Authentication requires POST.");
+                    if (operation === "logout") {
+                        yield this.logoutBearer(req);
+                        return res.send({ status: "success" });
+                    }
+                    if (operation === "refresh") {
+                        const token = (_a = req.body) === null || _a === void 0 ? void 0 : _a.refresh_token;
+                        const pair = typeof token === "string" ? yield this.sessions.refresh(token) : null;
+                        if (!pair)
+                            throw new AuthLoginError("unauthorized", 401, this.message("unauthorized"));
+                        return res.send(Object.assign({ status: "success" }, pair));
+                    }
+                    const pair = yield this.establishBearerSession(req, yield this.verifyCredentials(req));
+                    return res.send(Object.assign(Object.assign(Object.assign({}, (loginResponse ? yield loginResponse(req, pair.session) : {})), { status: "success" }), pair));
+                }
                 if (operation === "csrf")
                     return res.send({ csrf: this.bootstrap(req, res) });
                 if (operation === "logout") {
@@ -284,7 +432,7 @@ class AuthScope extends WebAuth_1.WebAuth {
                 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) });
+                    message: error instanceof AuthHookError ? (_c = (_b = this.modelOptions.messages) === null || _b === void 0 ? void 0 : _b[code]) !== null && _c !== void 0 ? _c : error.message : this.message(code) });
             }
         });
     }

package/dist/Auth/SessionAuth.d.ts

@@ -30,6 +30,8 @@ export type SessionAuthOptions = {
     audience: string;
     scope?: string;
     environment?: string;
+    /** Allow server-selected environments per session instead of one fixed environment. */
+    allowDynamicEnvironment?: boolean;
     connection?: string;
     collection?: string;
     accessTokenSeconds?: number;
@@ -58,7 +60,7 @@ export declare class SessionAuth {
     private liveFilter;
     private allowed;
     private pair;
-    create(subject: string, parent?: AuthSession["parent"]): Promise<CreatedAuthSession>;
+    create(subject: string, parent?: AuthSession["parent"], environment?: string): 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>;

package/dist/Auth/SessionAuth.js

@@ -23,8 +23,8 @@ 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"), 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.scope = Object.assign({ 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") }, (options.allowDynamicEnvironment && options.environment === undefined ? {}
+            : { 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);
         this.idleSeconds = options.idleTimeoutSeconds === undefined || options.idleTimeoutSeconds === false ? false : (0, AuthSecurity_1.authLifetime)(options.idleTimeoutSeconds, 7 * 86400);
@@ -66,16 +66,20 @@ class SessionAuth {
         return { auth_token: access, refresh_token: refresh, auth_expires_at: record.accessExpiresAt,
             refresh_expires_at: Math.min(record.expiresAt, record.createdAt + this.sessionSeconds * 1000), session: publicSession(record) };
     }
-    create(subject, parent = null) {
+    create(subject, parent = null, environment) {
+        var _a;
         return __awaiter(this, void 0, void 0, function* () {
             (0, AuthSecurity_1.authText)(subject, "subject");
+            if (environment !== undefined && (!this.options.allowDynamicEnvironment || this.options.environment !== undefined)) {
+                throw new Error("Dynamic session environments are not enabled.");
+            }
             if (parent) {
                 (0, AuthSecurity_1.authText)(parent.issuer, "parent issuer");
                 (0, AuthSecurity_1.authText)(parent.sessionId, "parent session");
             }
             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, _subject: this.ids().create(subject) }, this.scope), { parent: parent ? Object.assign({}, parent) : null, createdAt: now, lastActiveAt: 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), { environment: environment === undefined ? (_a = this.scope.environment) !== null && _a !== void 0 ? _a : null : (0, AuthSecurity_1.authText)(environment, "environment"), parent: parent ? Object.assign({}, parent) : null, createdAt: now, lastActiveAt: 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);

package/dist/Auth/SingleSignOn.js

@@ -118,7 +118,7 @@ class SsoAuthority {
             yield (yield this.rows()).insertOne({ _id: (0, AuthSecurity_1.hashAuthToken)(code), issuer: this.issuer,
                 audience: client.id, subject: session.subject, environment: request.environment,
                 authoritySessionId: session.id, redirectUri: request.redirectUri, challenge: request.codeChallenge,
-                expiresAt: Math.min(Date.now() + 60000, session.expiresAt), consumedAt: null });
+                expiresAt: Math.min(Date.now() + 60000, session.expiresAt), purgeAt: new Date(Date.now() + 60000), consumedAt: null });
             const redirect = new URL(request.redirectUri);
             redirect.searchParams.set("code", code);
             redirect.searchParams.set("state", request.state);
@@ -160,6 +160,7 @@ class SsoAuthority {
             const session = client ? yield this.options.sessions.inspect(sessionId) : null;
             if (!client || !session || !(yield this.options.authorize(session, client, environment)))
                 return null;
+            yield this.options.sessions.touch(session);
             return { issuer: this.issuer, audience: client.id, subject: session.subject, environment,
                 authoritySessionId: session.id, expiresAt: session.expiresAt };
         });
@@ -236,7 +237,7 @@ class SsoClient {
             (0, AuthSecurity_1.authText)(environment, "environment");
             const state = (0, AuthSecurity_1.randomAuthToken)(), binding = (0, AuthSecurity_1.randomAuthToken)(), verifier = (0, AuthSecurity_1.randomAuthToken)();
             yield (yield this.rows()).insertOne({ _id: (0, AuthSecurity_1.hashAuthToken)(state), issuer: this.issuer, clientId: this.options.clientId,
-                bindingHash: (0, AuthSecurity_1.hashAuthToken)(binding), verifier, environment, expiresAt: Date.now() + 300000, consumedAt: null });
+                bindingHash: (0, AuthSecurity_1.hashAuthToken)(binding), verifier, environment, expiresAt: Date.now() + 300000, purgeAt: new Date(Date.now() + 300000), consumedAt: null });
             this.cookies.write(res, "sso", binding, 300);
             res.header("Referrer-Policy", "no-referrer");
             const url = new URL(this.authorization.href);

package/dist/Auth/index.d.ts

@@ -7,3 +7,5 @@ export * from "./SingleSignOn";
 export * from "./ModelAuth";
 export * from "./Auth";
 export * from "./PasswordReset";
+export * from "./AuthMembership";
+export * from "./AuthHandoff";

package/dist/Auth/index.js

@@ -23,3 +23,5 @@ __exportStar(require("./SingleSignOn"), exports);
 __exportStar(require("./ModelAuth"), exports);
 __exportStar(require("./Auth"), exports);
 __exportStar(require("./PasswordReset"), exports);
+__exportStar(require("./AuthMembership"), exports);
+__exportStar(require("./AuthHandoff"), exports);

package/dist/Hooks/WebframezHooks.d.ts

@@ -32,6 +32,7 @@ declare class WebframezHooksFacade {
     on<TEventName extends WebframezHookEventName>(eventName: TEventName, handler: WebframezHookHandler<TEventName>): () => this;
     off<TEventName extends WebframezHookEventName>(eventName: TEventName, handler: WebframezHookHandler<TEventName>): this;
     clear(eventName?: WebframezHookEventName): this;
+    hasListeners(eventName: WebframezHookEventName): boolean;
     emit<TEventName extends WebframezHookEventName>(eventName: TEventName, context: Omit<Partial<WebframezOperationContext>, "operation" | "phase"> & {
         operationId: string;
     }): Promise<void>;

package/dist/Hooks/WebframezHooks.js

@@ -56,8 +56,16 @@ class WebframezHooksFacade {
         this.handlers = {};
         return this;
     }
+    hasListeners(eventName) {
+        var _a;
+        return (((_a = this.handlers[eventName]) === null || _a === void 0 ? void 0 : _a.size) || 0) > 0;
+    }
     emit(eventName, context) {
         return __awaiter(this, void 0, void 0, function* () {
+            const handlers = this.handlers[eventName];
+            if (!handlers || handlers.size < 1) {
+                return;
+            }
             const parsed = parseEventName(eventName);
             const attributes = Object.assign({}, (context.attributes || {}));
             if (context.error && attributes["error.type"] === undefined) {
@@ -67,10 +75,6 @@ class WebframezHooksFacade {
                 type: eventName,
                 context: Object.assign(Object.assign({}, context), { operation: parsed.operation, phase: parsed.phase, timestamp: context.timestamp || new Date(), attributes }),
             };
-            const handlers = this.handlers[eventName];
-            if (!handlers || handlers.size < 1) {
-                return;
-            }
             for (const handler of Array.from(handlers)) {
                 try {
                     yield handler(event);

package/dist/Router/Router.d.ts

@@ -65,6 +65,8 @@ declare class RouterFacade {
     routesDELETE: {
         [key: string]: RouteObject[];
     };
+    private routeRegexCache;
+    private domainRegexCache;
     /**
      * Load the application-routes
      */
@@ -103,6 +105,8 @@ declare class RouterFacade {
     extractParams(path: string, match: any): any;
     escapeRegexPart(value: string): string;
     buildRouteRegex(path: string): RegExp;
+    private getRouteRegex;
+    private getDomainRegex;
     normalizeDomainString(value: string): string | null;
     getRequestHostCandidates(request?: Request): string[];
     getRouteDomainFilters(routeObj: RouteObject): string[];

package/dist/Router/Router.js

@@ -69,6 +69,8 @@ class RouterFacade {
          * DELETE Route Store
          */
         this.routesDELETE = {};
+        this.routeRegexCache = new Map();
+        this.domainRegexCache = new Map();
     }
     /**
      * Load the application-routes
@@ -88,6 +90,8 @@ class RouterFacade {
         this.routesPUT = {};
         this.routesPATCH = {};
         this.routesDELETE = {};
+        this.routeRegexCache.clear();
+        this.domainRegexCache.clear();
         // Load routes
         if (options.routesFunction) {
             options.routesFunction();
@@ -139,6 +143,10 @@ class RouterFacade {
         else {
             routeConf.component = component;
         }
+        this.getRouteRegex(path);
+        for (const domain of this.getRouteDomainFilters(routeConf)) {
+            this.getDomainRegex(domain);
+        }
         if (type === "GET") {
             if (!this.routesGET[path]) {
                 this.routesGET[path] = [];
@@ -273,6 +281,22 @@ class RouterFacade {
         const regexString = "^" + escaped.replace(/__WFZ_TOKEN_(\d+)__/g, (all, tokenIndex) => placeholders[tokenIndex]) + "$";
         return new RegExp(regexString);
     }
+    getRouteRegex(path) {
+        let regex = this.routeRegexCache.get(path);
+        if (!regex) {
+            regex = this.buildRouteRegex(path);
+            this.routeRegexCache.set(path, regex);
+        }
+        return regex;
+    }
+    getDomainRegex(domain) {
+        let regex = this.domainRegexCache.get(domain);
+        if (!regex) {
+            regex = this.buildDomainRegex(domain);
+            this.domainRegexCache.set(domain, regex);
+        }
+        return regex;
+    }
     normalizeDomainString(value) {
         if (!value || value.trim() === "") {
             return null;
@@ -342,7 +366,7 @@ class RouterFacade {
         return new RegExp("^" + regexBody + "$", "i");
     }
     matchDomainFilter(hostname, domainFilter) {
-        const regex = this.buildDomainRegex(domainFilter);
+        const regex = this.getDomainRegex(domainFilter);
         const match = hostname.match(regex);
         if (!match) {
             return { matches: false, matchedDomain: null, wildcard: null };
@@ -411,7 +435,7 @@ class RouterFacade {
                 continue;
             }
             for (const routeObj of routeCandidates) {
-                const match = url.match(this.buildRouteRegex(routeObj.path));
+                const match = url.match(this.getRouteRegex(routeObj.path));
                 if (!match) {
                     continue;
                 }
@@ -442,14 +466,16 @@ class RouterFacade {
                 : this.mode === "aws-lambda" && options && options.event && options.event.requestContext && options.event.requestContext.http
                     ? options.event.requestContext.http.method
                     : null;
-            yield WebframezHooks_1.WebframezHooks.emit("http.request.start", {
-                operationId: httpOperationId,
-                name: initialMethod || (this.mode === "aws-lambda" ? "lambda" : "request"),
-                attributes: {
-                    "http.request.method": initialMethod,
-                    "webframez.mode": this.mode,
-                },
-            });
+            if (WebframezHooks_1.WebframezHooks.hasListeners("http.request.start")) {
+                yield WebframezHooks_1.WebframezHooks.emit("http.request.start", {
+                    operationId: httpOperationId,
+                    name: initialMethod || (this.mode === "aws-lambda" ? "lambda" : "request"),
+                    attributes: {
+                        "http.request.method": initialMethod,
+                        "webframez.mode": this.mode,
+                    },
+                });
+            }
             let request;
             let routeOperationId = null;
             try {
@@ -478,15 +504,17 @@ class RouterFacade {
                     },
                 });
                 const errorResult = this.handleError(fallbackRequest, response, statusCode, e);
-                yield WebframezHooks_1.WebframezHooks.emit("http.request.error", {
-                    operationId: httpOperationId,
-                    name: `${fallbackRequest.method || "HTTP"} unmatched`,
-                    status: "error",
-                    error: e,
-                    request: fallbackRequest,
-                    response,
-                    attributes: Object.assign(Object.assign({ "http.request.method": fallbackRequest.method || null, "http.response.status_code": statusCode }, requestTelemetryAttributes(fallbackRequest)), { "webframez.mode": this.mode }),
-                });
+                if (WebframezHooks_1.WebframezHooks.hasListeners("http.request.error")) {
+                    yield WebframezHooks_1.WebframezHooks.emit("http.request.error", {
+                        operationId: httpOperationId,
+                        name: `${fallbackRequest.method || "HTTP"} unmatched`,
+                        status: "error",
+                        error: e,
+                        request: fallbackRequest,
+                        response,
+                        attributes: Object.assign(Object.assign({ "http.request.method": fallbackRequest.method || null, "http.response.status_code": statusCode }, requestTelemetryAttributes(fallbackRequest)), { "webframez.mode": this.mode }),
+                    });
+                }
                 return errorResult;
             }
             const route = this.dissolve(request);
@@ -496,83 +524,95 @@ class RouterFacade {
             }
             if (!route) {
                 const notFoundResult = this.handleError(request, response, 404, "Not found '" + request.url + "' ...");
-                yield WebframezHooks_1.WebframezHooks.emit("http.request.end", {
-                    operationId: httpOperationId,
-                    name: `${request.method} unmatched`,
-                    status: "ok",
-                    request,
-                    response,
-                    attributes: Object.assign(Object.assign({ "http.request.method": request.method, "http.response.status_code": 404 }, requestTelemetryAttributes(request)), { "webframez.mode": this.mode }),
-                });
+                if (WebframezHooks_1.WebframezHooks.hasListeners("http.request.end")) {
+                    yield WebframezHooks_1.WebframezHooks.emit("http.request.end", {
+                        operationId: httpOperationId,
+                        name: `${request.method} unmatched`,
+                        status: "ok",
+                        request,
+                        response,
+                        attributes: Object.assign(Object.assign({ "http.request.method": request.method, "http.response.status_code": 404 }, requestTelemetryAttributes(request)), { "webframez.mode": this.mode }),
+                    });
+                }
                 return notFoundResult;
             }
             if (!(route.component && typeof route.component === "function") && !(route.controller && route.method_name)) {
                 const missingRouteResult = this.handleError(request, response, 404, "Missing route function ...");
-                yield WebframezHooks_1.WebframezHooks.emit("http.request.end", {
-                    operationId: httpOperationId,
-                    name: `${request.method} ${route.path}`,
-                    status: "ok",
-                    request,
-                    response,
-                    attributes: Object.assign(Object.assign({ "http.request.method": request.method, "http.response.status_code": 404, "url.template": route.path, "webframez.route": route.path }, requestTelemetryAttributes(request)), { "webframez.mode": this.mode }),
-                });
-                return missingRouteResult;
-            }
-            try {
-                yield this.handleMiddleware(route, request, response);
-                if (request.method === "OPTIONS" && !request.skipOptionsForward) {
-                    const optionsResult = this.handleReturn(request, response, "");
+                if (WebframezHooks_1.WebframezHooks.hasListeners("http.request.end")) {
                     yield WebframezHooks_1.WebframezHooks.emit("http.request.end", {
                         operationId: httpOperationId,
                         name: `${request.method} ${route.path}`,
                         status: "ok",
                         request,
                         response,
-                        attributes: Object.assign(Object.assign({ "http.request.method": request.method, "http.response.status_code": response.statusCode || 200, "url.template": route.path, "webframez.route": route.path }, requestTelemetryAttributes(request)), { "webframez.mode": this.mode }),
+                        attributes: Object.assign(Object.assign({ "http.request.method": request.method, "http.response.status_code": 404, "url.template": route.path, "webframez.route": route.path }, requestTelemetryAttributes(request)), { "webframez.mode": this.mode }),
                     });
-                    return optionsResult;
                 }
-                let result = null;
-                routeOperationId = WebframezHooks_1.WebframezHooks.createOperationId("route");
-                yield WebframezHooks_1.WebframezHooks.emit("route.handler.start", {
-                    operationId: routeOperationId,
-                    parentOperationId: httpOperationId,
-                    name: `${request.method} ${route.path}`,
-                    attributes: {
-                        "http.request.method": request.method,
-                        "url.template": route.path,
-                        "webframez.route": route.path,
-                        "webframez.route.handler": route.controller && route.method_name
-                            ? `${route.controller.name || "Controller"}@${route.method_name}`
-                            : "component",
-                    },
-                });
-                if (route.controller && route.method_name) {
-                    const controllerInstance = new route.controller();
-                    if (!controllerInstance[route.method_name]) {
-                        const unknownMethodResult = this.handleError(request, response, 404, "Unknown method '" + route.method_name + "'.");
-                        yield WebframezHooks_1.WebframezHooks.emit("route.handler.error", {
-                            operationId: routeOperationId,
-                            parentOperationId: httpOperationId,
-                            name: `${request.method} ${route.path}`,
-                            status: "error",
-                            error: new Error("Unknown route method"),
-                            attributes: {
-                                "http.request.method": request.method,
-                                "http.response.status_code": 404,
-                                "url.template": route.path,
-                                "webframez.route": route.path,
-                                "webframez.route.handler": `${route.controller.name || "Controller"}@${route.method_name}`,
-                            },
-                        });
+                return missingRouteResult;
+            }
+            try {
+                yield this.handleMiddleware(route, request, response);
+                if (request.method === "OPTIONS" && !request.skipOptionsForward) {
+                    const optionsResult = this.handleReturn(request, response, "");
+                    if (WebframezHooks_1.WebframezHooks.hasListeners("http.request.end")) {
                         yield WebframezHooks_1.WebframezHooks.emit("http.request.end", {
                             operationId: httpOperationId,
                             name: `${request.method} ${route.path}`,
                             status: "ok",
                             request,
                             response,
-                            attributes: Object.assign(Object.assign({ "http.request.method": request.method, "http.response.status_code": 404, "url.template": route.path, "webframez.route": route.path }, requestTelemetryAttributes(request)), { "webframez.mode": this.mode }),
+                            attributes: Object.assign(Object.assign({ "http.request.method": request.method, "http.response.status_code": response.statusCode || 200, "url.template": route.path, "webframez.route": route.path }, requestTelemetryAttributes(request)), { "webframez.mode": this.mode }),
                         });
+                    }
+                    return optionsResult;
+                }
+                let result = null;
+                routeOperationId = WebframezHooks_1.WebframezHooks.createOperationId("route");
+                if (WebframezHooks_1.WebframezHooks.hasListeners("route.handler.start")) {
+                    yield WebframezHooks_1.WebframezHooks.emit("route.handler.start", {
+                        operationId: routeOperationId,
+                        parentOperationId: httpOperationId,
+                        name: `${request.method} ${route.path}`,
+                        attributes: {
+                            "http.request.method": request.method,
+                            "url.template": route.path,
+                            "webframez.route": route.path,
+                            "webframez.route.handler": route.controller && route.method_name
+                                ? `${route.controller.name || "Controller"}@${route.method_name}`
+                                : "component",
+                        },
+                    });
+                }
+                if (route.controller && route.method_name) {
+                    const controllerInstance = new route.controller();
+                    if (!controllerInstance[route.method_name]) {
+                        const unknownMethodResult = this.handleError(request, response, 404, "Unknown method '" + route.method_name + "'.");
+                        if (WebframezHooks_1.WebframezHooks.hasListeners("route.handler.error")) {
+                            yield WebframezHooks_1.WebframezHooks.emit("route.handler.error", {
+                                operationId: routeOperationId,
+                                parentOperationId: httpOperationId,
+                                name: `${request.method} ${route.path}`,
+                                status: "error",
+                                error: new Error("Unknown route method"),
+                                attributes: {
+                                    "http.request.method": request.method,
+                                    "http.response.status_code": 404,
+                                    "url.template": route.path,
+                                    "webframez.route": route.path,
+                                    "webframez.route.handler": `${route.controller.name || "Controller"}@${route.method_name}`,
+                                },
+                            });
+                        }
+                        if (WebframezHooks_1.WebframezHooks.hasListeners("http.request.end")) {
+                            yield WebframezHooks_1.WebframezHooks.emit("http.request.end", {
+                                operationId: httpOperationId,
+                                name: `${request.method} ${route.path}`,
+                                status: "ok",
+                                request,
+                                response,
+                                attributes: Object.assign(Object.assign({ "http.request.method": request.method, "http.response.status_code": 404, "url.template": route.path, "webframez.route": route.path }, requestTelemetryAttributes(request)), { "webframez.mode": this.mode }),
+                            });
+                        }
                         return unknownMethodResult;
                     }
                     result = yield controllerInstance[route.method_name].bind(controllerInstance)(request, response);
@@ -581,40 +621,46 @@ class RouterFacade {
                     result = yield route.component(request, response);
                 }
                 const returnResult = this.handleReturn(request, response, result);
-                yield WebframezHooks_1.WebframezHooks.emit("route.handler.end", {
-                    operationId: routeOperationId,
-                    parentOperationId: httpOperationId,
-                    name: `${request.method} ${route.path}`,
-                    status: "ok",
-                    attributes: {
-                        "http.request.method": request.method,
-                        "http.response.status_code": response.statusCode || 200,
-                        "url.template": route.path,
-                        "webframez.route": route.path,
-                    },
-                });
-                yield WebframezHooks_1.WebframezHooks.emit("http.request.end", {
-                    operationId: httpOperationId,
-                    name: `${request.method} ${route.path}`,
-                    status: "ok",
-                    request,
-                    response,
-                    attributes: Object.assign(Object.assign({ "http.request.method": request.method, "http.response.status_code": response.statusCode || 200, "url.template": route.path, "webframez.route": route.path }, requestTelemetryAttributes(request)), { "webframez.mode": this.mode }),
-                });
-                return returnResult;
-            }
-            catch (e) {
-                if (this.isMiddlewareRejectSignal(e)) {
-                    const middlewareErrorResult = this.handleError(request, response, 500, e.reason);
-                    yield WebframezHooks_1.WebframezHooks.emit("http.request.error", {
+                if (WebframezHooks_1.WebframezHooks.hasListeners("route.handler.end")) {
+                    yield WebframezHooks_1.WebframezHooks.emit("route.handler.end", {
+                        operationId: routeOperationId,
+                        parentOperationId: httpOperationId,
+                        name: `${request.method} ${route.path}`,
+                        status: "ok",
+                        attributes: {
+                            "http.request.method": request.method,
+                            "http.response.status_code": response.statusCode || 200,
+                            "url.template": route.path,
+                            "webframez.route": route.path,
+                        },
+                    });
+                }
+                if (WebframezHooks_1.WebframezHooks.hasListeners("http.request.end")) {
+                    yield WebframezHooks_1.WebframezHooks.emit("http.request.end", {
                         operationId: httpOperationId,
                         name: `${request.method} ${route.path}`,
-                        status: "error",
-                        error: e.reason || e,
+                        status: "ok",
                         request,
                         response,
-                        attributes: Object.assign(Object.assign({ "http.request.method": request.method, "http.response.status_code": 500, "url.template": route.path, "webframez.route": route.path }, requestTelemetryAttributes(request)), { "webframez.mode": this.mode }),
+                        attributes: Object.assign(Object.assign({ "http.request.method": request.method, "http.response.status_code": response.statusCode || 200, "url.template": route.path, "webframez.route": route.path }, requestTelemetryAttributes(request)), { "webframez.mode": this.mode }),
                     });
+                }
+                return returnResult;
+            }
+            catch (e) {
+                if (this.isMiddlewareRejectSignal(e)) {
+                    const middlewareErrorResult = this.handleError(request, response, 500, e.reason);
+                    if (WebframezHooks_1.WebframezHooks.hasListeners("http.request.error")) {
+                        yield WebframezHooks_1.WebframezHooks.emit("http.request.error", {
+                            operationId: httpOperationId,
+                            name: `${request.method} ${route.path}`,
+                            status: "error",
+                            error: e.reason || e,
+                            request,
+                            response,
+                            attributes: Object.assign(Object.assign({ "http.request.method": request.method, "http.response.status_code": 500, "url.template": route.path, "webframez.route": route.path }, requestTelemetryAttributes(request)), { "webframez.mode": this.mode }),
+                        });
+                    }
                     return middlewareErrorResult;
                 }
                 yield ErrorHandler_1.ErrorHandler.report(e, {
@@ -632,29 +678,33 @@ class RouterFacade {
                 });
                 const errorResult = this.handleError(request, response, 500, e);
                 if (routeOperationId) {
-                    yield WebframezHooks_1.WebframezHooks.emit("route.handler.error", {
-                        operationId: routeOperationId,
-                        parentOperationId: httpOperationId,
+                    if (WebframezHooks_1.WebframezHooks.hasListeners("route.handler.error")) {
+                        yield WebframezHooks_1.WebframezHooks.emit("route.handler.error", {
+                            operationId: routeOperationId,
+                            parentOperationId: httpOperationId,
+                            name: `${request.method} ${route.path}`,
+                            status: "error",
+                            error: e,
+                            attributes: {
+                                "http.request.method": request.method,
+                                "http.response.status_code": 500,
+                                "url.template": route.path,
+                                "webframez.route": route.path,
+                            },
+                        });
+                    }
+                }
+                if (WebframezHooks_1.WebframezHooks.hasListeners("http.request.error")) {
+                    yield WebframezHooks_1.WebframezHooks.emit("http.request.error", {
+                        operationId: httpOperationId,
                         name: `${request.method} ${route.path}`,
                         status: "error",
                         error: e,
-                        attributes: {
-                            "http.request.method": request.method,
-                            "http.response.status_code": 500,
-                            "url.template": route.path,
-                            "webframez.route": route.path,
-                        },
+                        request,
+                        response,
+                        attributes: Object.assign(Object.assign({ "http.request.method": request.method, "http.response.status_code": 500, "url.template": route.path, "webframez.route": route.path }, requestTelemetryAttributes(request)), { "webframez.mode": this.mode }),
                     });
                 }
-                yield WebframezHooks_1.WebframezHooks.emit("http.request.error", {
-                    operationId: httpOperationId,
-                    name: `${request.method} ${route.path}`,
-                    status: "error",
-                    error: e,
-                    request,
-                    response,
-                    attributes: Object.assign(Object.assign({ "http.request.method": request.method, "http.response.status_code": 500, "url.template": route.path, "webframez.route": route.path }, requestTelemetryAttributes(request)), { "webframez.mode": this.mode }),
-                });
                 return errorResult;
             }
         });

package/docs/authentication.md

@@ -495,3 +495,70 @@ when serializing entire models. Auth snapshots always exclude these fields.
 user automatically. Existing application plaintext reset links are intentionally
 not accepted; users must request a new link after migration. Reset pages should
 use `Referrer-Policy: no-referrer` and avoid response caching.
+
+## Declarative memberships
+
+Authentication identifies the user; memberships authorize access to a server-loaded resource.
+Configure named membership models on a scope:
+
+```ts
+const scope = Auth.registerScope("manager", {
+    model: User,
+    memberships: {
+        environment: {
+            model: EnvironmentUser,
+            bindings: [{
+                user: { foreignKey: "_user", localKeys: ["_id"] },
+                resource: { foreignKey: "_env", localKeys: ["_id"] },
+            }],
+            conditions: [{ field: "is_deleted", operator: "!=", value: true }],
+        },
+    },
+});
+
+await scope.resolve(req, res);
+const membership = await scope.authorizeMembership(req, "environment", environment);
+if (!membership) return res.status(403).send({ code: "forbidden" });
+// Actual server-side Models; excluded from browser snapshots:
+req.auth.memberships.environment.membership;
+req.auth.memberships.environment.resource;
+```
+
+Every authorization performs a fresh lookup. Missing IDs and unvalidated request contexts
+fail closed. `userConditions` and `resourceConditions` optionally constrain model status.
+`sessionEnvironmentKey` optionally binds resource authorization to a federated session environment.
+Multiple `bindings` support legacy schemas; `localKeys` can accept local and synchronized
+resource references. Set `user.firstAvailable: true` to prefer the first available user
+reference rather than matching all aliases. `findMembership(name, user, resource)` is the
+trusted-server adapter for integrations that already authenticate through another transport.
+It does not authenticate the supplied user or create a request auth context.
+
+## Bearer scopes for separate API origins
+
+Cookie scopes remain the default. An explicitly configured `transport: "bearer"` scope
+uses opaque, hashed Core access/refresh credentials through Authorization instead of cookies.
+`Route.auth()` returns `auth_token`, `refresh_token` and their expiry timestamps. Refresh
+requires POST with `refresh_token`; logout requires POST with the access Authorization header.
+Cookie/query credentials are never accepted by `scope.resolve()` in bearer mode. Cookie CSRF
+behavior remains unchanged; bearer endpoints do not use ambient browser credentials.
+
+Use the lightweight `@webtypen/webframez-core/bearer-auth-client` entry point's
+`createBearerAuthFetch()` with application-owned `configuration`, `load`, `save` and `clear`
+callbacks. Configure only trusted API targets and store credentials separately per instance.
+It renews expired access credentials, shares refresh requests within a client, uses Web Locks
+across browser tabs when available, and retries explicit unauthorized responses once.
+It clears credentials after an ambiguous network failure instead of replaying a rotating secret.
+Without Web Locks, cross-tab coordination must be provided by the host application.
+
+`establishBearerSession(req, subject, parent?, environment?)` is a trusted server entry point
+following verified SSO; never expose a caller-supplied subject as public login input. Lifecycle
+hooks apply. Set `session.allowDynamicEnvironment: true` to bind individual sessions to a
+server-selected environment; fixed/default session environment behavior stays unchanged.
+`isSessionAllowed(session, user)` can validate a parent SSO session and fails closed on denial.
+
+`AuthHandoff` delivers a short-lived one-use code to a separate frontend after the API callback.
+Its payload is encrypted with AES-GCM, its code is hashed, and redemption is atomic. Neither
+access nor refresh credentials need appear in navigation URLs. Configure a strong server secret
+and an instance-specific audience. Create TTL indexes on `auth_handoffs.purgeAt`,
+`auth_sso_transactions.purgeAt` and `auth_sso_codes.purgeAt`, or schedule their cleanup methods.
+SSO introspection records successful central session activity, respecting its absolute expiry.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@webtypen/webframez-core",
-    "version": "0.3.76",
+    "version": "0.3.78",
     "description": "The core package of the typescript based webframez (web-framework) by webtypen.de",
     "homepage": "https://webtypen.de/",
     "license": "MIT",
@@ -30,7 +30,9 @@
         "routing.js",
         "routing.d.ts",
         "auth-client.js",
-        "auth-client.d.ts"
+        "auth-client.d.ts",
+        "bearer-auth-client.js",
+        "bearer-auth-client.d.ts"
     ],
     "scripts": {
         "build": "tsc",