@webtypen/webframez-core 0.3.77 → 0.3.80

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, parentExpiresAt?: number): 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, parentExpiresAt) {
+        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, parentExpiresAt);
+            if (!pair.reused && 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, reused } = pair, tokens = __rest(pair, ["csrf_token", "reused"]);
+            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

@@ -24,12 +24,20 @@ export type SessionTokenPair = {
 };
 export type CreatedAuthSession = SessionTokenPair & {
     csrf_token: string;
+    reused?: boolean;
 };
 export type SessionAuthOptions = {
     issuer: string;
     audience: string;
     scope?: string;
     environment?: string;
+    /** Allow server-selected environments per session instead of one fixed environment. */
+    allowDynamicEnvironment?: boolean;
+    /** Reuse one child per parent, subject and environment. Requires a strong server-held secret. */
+    parentSessions?: {
+        mode: "new" | "reuse";
+        secret?: string;
+    };
     connection?: string;
     collection?: string;
     accessTokenSeconds?: number;
@@ -58,7 +66,10 @@ export declare class SessionAuth {
     private liveFilter;
     private allowed;
     private pair;
-    create(subject: string, parent?: AuthSession["parent"]): Promise<CreatedAuthSession>;
+    private credentials;
+    private reuse;
+    private linkedRecord;
+    create(subject: string, parent?: AuthSession["parent"], environment?: string, parentExpiresAt?: number): 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

@@ -10,6 +10,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SessionAuth = void 0;
+const crypto_1 = require("crypto");
 const DBConnection_1 = require("../Database/DBConnection");
 const AuthSecurity_1 = require("./AuthSecurity");
 function publicSession(record) {
@@ -21,13 +22,16 @@ function tokenSessionId(token) {
 /** Revocable, hashed, independently addressable device sessions. Legacy UserAuth is unaffected. */
 class SessionAuth {
     constructor(options) {
-        var _a;
+        var _a, _b;
         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);
+        if (((_b = options.parentSessions) === null || _b === void 0 ? void 0 : _b.mode) === "reuse" && (typeof options.parentSessions.secret !== "string" || options.parentSessions.secret.length < 32)) {
+            throw new Error("Parent session reuse requires a strong server secret.");
+        }
         if (typeof options.isSessionAllowed !== "function")
             throw new Error("SessionAuth requires isSessionAllowed.");
     }
@@ -66,18 +70,106 @@ 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) {
+    credentials(record) {
+        var _a, _b, _c;
+        if (!record.credentialState || !((_a = this.options.parentSessions) === null || _a === void 0 ? void 0 : _a.secret))
+            throw new Error("Linked session credentials are unavailable.");
+        const context = JSON.stringify([String(record._id), String(record._subject), record.issuer, record.audience,
+            record.scope, record.environment, (_b = record.parent) === null || _b === void 0 ? void 0 : _b.issuer, (_c = record.parent) === null || _c === void 0 ? void 0 : _c.sessionId]);
+        const derive = (kind) => (0, crypto_1.createHmac)("sha256", this.options.parentSessions.secret)
+            .update(JSON.stringify(["webframez-parent-session-v1", context, kind, record.credentialState[kind]])).digest("base64url");
+        return { access: `${record._id}.${derive("access")}`, refresh: `${record._id}.${derive("refresh")}`, csrf: derive("csrf") };
+    }
+    reuse(record) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!(yield this.allowed(record)))
+                throw new Error("Session is not allowed.");
+            const credentials = this.credentials(record);
+            if ((0, AuthSecurity_1.hashAuthToken)(credentials.access) !== record.accessHash || (0, AuthSecurity_1.hashAuthToken)(credentials.refresh) !== record.refreshHash
+                || (0, AuthSecurity_1.hashAuthToken)(credentials.csrf) !== record.csrfHash)
+                throw new Error("Linked session credentials have changed.");
+            if (record.accessExpiresAt <= Date.now()) {
+                yield this.renewAccess(credentials.refresh);
+                const current = yield (yield this.rows()).findOne(Object.assign({ _id: record._id }, this.scope));
+                if (!current || current.accessExpiresAt <= Date.now())
+                    throw new Error("Linked session access could not be renewed.");
+                return this.reuse(current);
+            }
+            const session = publicSession(record);
+            yield this.touch(session);
+            return Object.assign(Object.assign({}, this.pair(record, credentials.access, credentials.refresh)), { session, csrf_token: credentials.csrf, reused: true });
+        });
+    }
+    linkedRecord(record) {
+        var _a;
+        return __awaiter(this, void 0, void 0, function* () {
+            const db = yield (this.options.database ? this.options.database() : DBConnection_1.DBConnection.getDocumentStore(this.options.connection));
+            const links = db.collection(`${this.options.collection || "auth_sessions"}_links`);
+            const key = (0, AuthSecurity_1.hashAuthToken)(JSON.stringify([record.issuer, record.audience, record.scope, String(record._subject),
+                record.environment, record.parent.issuer, record.parent.sessionId]));
+            let link;
+            try {
+                link = yield links.findOneAndUpdate({ _id: key }, { $setOnInsert: Object.assign(Object.assign({}, this.scope), { environment: record.environment, sessionId: record._id, purgeAt: new Date(record.expiresAt) }) }, { upsert: true, returnDocument: "after" });
+            }
+            catch (error) {
+                if (error.code !== 11000)
+                    throw error;
+                link = yield links.findOne({ _id: key });
+            }
+            if (!link)
+                throw new Error("Linked session reference is unavailable.");
+            for (let attempt = 0; attempt < 5; attempt++) {
+                const candidate = Object.assign(Object.assign({}, record), { _id: link.sessionId, accessExpiresAt: Math.min(record.accessExpiresAt, record.expiresAt) });
+                const credentials = this.credentials(candidate);
+                Object.assign(candidate, { accessHash: (0, AuthSecurity_1.hashAuthToken)(credentials.access), refreshHash: (0, AuthSecurity_1.hashAuthToken)(credentials.refresh), csrfHash: (0, AuthSecurity_1.hashAuthToken)(credentials.csrf) });
+                let stored;
+                try {
+                    stored = yield (yield this.rows()).findOneAndUpdate({ _id: candidate._id }, { $setOnInsert: candidate }, { upsert: true, returnDocument: "after" });
+                }
+                catch (error) {
+                    if (error.code !== 11000)
+                        throw error;
+                    stored = yield (yield this.rows()).findOne({ _id: candidate._id });
+                }
+                if (!stored)
+                    throw new Error("Linked session is unavailable.");
+                // A denied parent or membership must fail closed, rather than create another session.
+                if (stored.revokedAt === null && stored.expiresAt > Date.now()
+                    && stored.createdAt + this.sessionSeconds * 1000 > Date.now()
+                    && (this.idleSeconds === false || ((_a = stored.lastActiveAt) !== null && _a !== void 0 ? _a : stored.createdAt) + this.idleSeconds * 1000 > Date.now()))
+                    return stored;
+                link = (yield links.findOneAndUpdate({ _id: key, sessionId: stored._id }, { $set: { sessionId: this.ids().create(), purgeAt: new Date(record.expiresAt) } }, { returnDocument: "after" }))
+                    || (yield links.findOne({ _id: key }));
+            }
+            throw new Error("Linked session could not be established.");
+        });
+    }
+    create(subject, parent = null, environment, parentExpiresAt) {
+        var _a, _b, _c;
         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");
             }
+            if (parentExpiresAt !== undefined && (!parent || !Number.isFinite(parentExpiresAt) || parentExpiresAt <= Date.now())) {
+                throw new Error("Invalid parent session expiry.");
+            }
             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: Math.min(now + this.sessionSeconds * 1000, parentExpiresAt !== null && parentExpiresAt !== void 0 ? parentExpiresAt : Infinity), 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.");
+            if (parent && ((_b = this.options.parentSessions) === null || _b === void 0 ? void 0 : _b.mode) === "reuse") {
+                record.credentialState = { access: (0, AuthSecurity_1.randomAuthToken)(), refresh: (0, AuthSecurity_1.randomAuthToken)(), csrf: (0, AuthSecurity_1.randomAuthToken)() };
+                const stored = yield this.linkedRecord(record);
+                const pair = yield this.reuse(stored);
+                return Object.assign(Object.assign({}, pair), { reused: ((_c = stored.credentialState) === null || _c === void 0 ? void 0 : _c.access) !== record.credentialState.access });
+            }
+            record.accessExpiresAt = Math.min(record.accessExpiresAt, record.expiresAt);
             yield (yield this.rows()).insertOne(record);
             return Object.assign(Object.assign({}, this.pair(record, access, refresh)), { csrf_token: csrf });
         });
@@ -113,6 +205,7 @@ class SessionAuth {
     }
     /** One winner under concurrency. A previously consumed refresh token revokes its device session. */
     refresh(token) {
+        var _a, _b;
         return __awaiter(this, void 0, void 0, function* () {
             const id = tokenSessionId(token);
             if (!id)
@@ -131,11 +224,10 @@ class SessionAuth {
                 yield this.revoke(id);
                 return null;
             }
-            const access = `${id}.${(0, AuthSecurity_1.randomAuthToken)()}`, refresh = `${id}.${(0, AuthSecurity_1.randomAuthToken)()}`;
-            const next = yield rows.findOneAndUpdate(Object.assign(Object.assign(Object.assign({ _id: this.sessionId(id) }, this.scope), { refreshHash: hash }), this.liveFilter()), { $set: { accessHash: (0, AuthSecurity_1.hashAuthToken)(access), refreshHash: (0, AuthSecurity_1.hashAuthToken)(refresh),
-                    accessExpiresAt: Math.min(Date.now() + this.accessSeconds * 1000, row.expiresAt, row.createdAt + this.sessionSeconds * 1000),
-                    lastActiveAt: Date.now(),
-                    usedRefreshHashes: [...row.usedRefreshHashes, hash] } }, { returnDocument: "after" });
+            const credentialState = row.credentialState ? Object.assign(Object.assign({}, row.credentialState), { access: (0, AuthSecurity_1.randomAuthToken)(), refresh: (0, AuthSecurity_1.randomAuthToken)() }) : undefined;
+            const credentials = credentialState ? this.credentials(Object.assign(Object.assign({}, row), { credentialState })) : null;
+            const access = (_a = credentials === null || credentials === void 0 ? void 0 : credentials.access) !== null && _a !== void 0 ? _a : `${id}.${(0, AuthSecurity_1.randomAuthToken)()}`, refresh = (_b = credentials === null || credentials === void 0 ? void 0 : credentials.refresh) !== null && _b !== void 0 ? _b : `${id}.${(0, AuthSecurity_1.randomAuthToken)()}`;
+            const next = yield rows.findOneAndUpdate(Object.assign(Object.assign(Object.assign({ _id: this.sessionId(id) }, this.scope), { refreshHash: hash }), this.liveFilter()), { $set: Object.assign(Object.assign({}, (credentialState ? { credentialState } : {})), { accessHash: (0, AuthSecurity_1.hashAuthToken)(access), refreshHash: (0, AuthSecurity_1.hashAuthToken)(refresh), accessExpiresAt: Math.min(Date.now() + this.accessSeconds * 1000, row.expiresAt, row.createdAt + this.sessionSeconds * 1000), lastActiveAt: Date.now(), usedRefreshHashes: [...row.usedRefreshHashes, hash] }) }, { returnDocument: "after" });
             if (!next) {
                 // Also detect simultaneous replay that lost the compare-and-swap.
                 yield rows.updateOne(Object.assign(Object.assign({ _id: this.sessionId(id) }, this.scope), { usedRefreshHashes: hash, revokedAt: null }), { $set: { revokedAt: Date.now() } });
@@ -164,10 +256,9 @@ class SessionAuth {
             const row = yield rows.findOne(filter);
             if (!row || !(yield this.allowed(row)))
                 return null;
-            const access = `${id}.${(0, AuthSecurity_1.randomAuthToken)()}`, now = Date.now();
-            const next = yield rows.findOneAndUpdate(filter, { $set: { accessHash: (0, AuthSecurity_1.hashAuthToken)(access),
-                    accessExpiresAt: Math.min(now + this.accessSeconds * 1000, row.expiresAt, row.createdAt + this.sessionSeconds * 1000),
-                    lastActiveAt: now } }, { returnDocument: "after" });
+            const credentialState = row.credentialState ? Object.assign(Object.assign({}, row.credentialState), { access: (0, AuthSecurity_1.randomAuthToken)() }) : undefined;
+            const access = credentialState ? this.credentials(Object.assign(Object.assign({}, row), { credentialState })).access : `${id}.${(0, AuthSecurity_1.randomAuthToken)()}`, now = Date.now();
+            const next = yield rows.findOneAndUpdate(filter, { $set: Object.assign(Object.assign({}, (credentialState ? { credentialState } : {})), { accessHash: (0, AuthSecurity_1.hashAuthToken)(access), accessExpiresAt: Math.min(now + this.accessSeconds * 1000, row.expiresAt, row.createdAt + this.sessionSeconds * 1000), lastActiveAt: now }) }, { returnDocument: "after" });
             const session = next ? yield this.allowed(next) : null;
             return next && session ? Object.assign(Object.assign({}, this.pair(next, access, token)), { session }) : null;
         });

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/docs/authentication.md

@@ -495,3 +495,92 @@ 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.
+
+### Linked parent session reuse
+
+`session.parentSessions: { mode: "reuse", secret: serverSecret }` opts into one local
+session per exact parent issuer/session, user, scope, audience and environment. The default
+`mode: "new"` retains independent session creation. Logins without a parent remain independent.
+The secret must be at least 32 characters and stay stable across all processes of an instance.
+Core stores hashes and independent random credential nonces, never plaintext tokens; a
+domain-separated HMAC derives the current credentials only on the trusted server. Rotation
+updates both hashes and nonces atomically. Reopening returns the current pair without rotating
+refresh or resetting the login timestamp. `auth_sessions_links` uses its primary key for atomic
+creation; add an optional TTL index on `purgeAt` for housekeeping. Session `_id` and `_subject`
+continue to use driver-native IDs. A revoked/expired local child creates a new generation.
+Changing the secret requires revoking existing linked sessions before reauthentication.
+
+Trusted callers can pass parent expiry as the fifth argument to
+`Auth.scope().establishBearerSession(request, subject, parent, environment, parentExpiresAt)`
+or fourth argument to `sessions.create`. It caps child expiry. Parent revocation must still be
+checked by `isSessionAllowed` on every authentication/refresh. To enforce logout on the next
+request, do not cache positive introspection results. This requires one authority round trip
+per check and fails closed when the authority is unavailable. No browser push is implied;
+clients detect logout when making their next authenticated request.

package/package.json

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