@webtypen/webframez-core 0.3.70 → 0.3.72

package/README.md

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

package/agents/webframez_rules.md

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

package/dist/Api/ApiScope.d.ts

@@ -5,6 +5,8 @@ export declare class ApiScope {
     key: string;
     apiBasePath: string | null;
     mcpEndpoint: string | null;
+    /** Kernel middleware for HTTP routes, including automatic OPTIONS responses. */
+    routeMiddleware: string[];
     functions: Array<ApiFunctionClass> | (() => Array<ApiFunctionClass>);
     middleware(_req: Request, _res: Response, _abort: ApiScopeMiddlewareAbort): Promise<{
         [key: string]: any;

package/dist/Api/ApiScope.js

@@ -15,6 +15,8 @@ class ApiScope {
         this.key = "unique_scope_key";
         this.apiBasePath = "/api";
         this.mcpEndpoint = null;
+        /** Kernel middleware for HTTP routes, including automatic OPTIONS responses. */
+        this.routeMiddleware = [];
         this.functions = [];
     }
     middleware(_req, _res, _abort) {

package/dist/Api/ApiScopeRegistry.js

@@ -71,10 +71,10 @@ class ApiScopeRegistryFacade {
             const handler = (req, res) => __awaiter(this, void 0, void 0, function* () {
                 return yield this.handleHttpFunction(registration, FunctionClass, req, res);
             });
-            this.registerRouteMethod(func.requestMethod, path, handler);
+            this.registerRouteMethod(func.requestMethod, path, handler, scope.routeMiddleware);
         }
     }
-    registerRouteMethod(method, path, handler) {
+    registerRouteMethod(method, path, handler, middleware) {
         if (!method) {
             return;
         }
@@ -83,7 +83,7 @@ class ApiScopeRegistryFacade {
         if (!routeMethod || typeof routeMethod !== "function") {
             throw new Error(`ApiFunction request method "${method}" is not supported by Route`);
         }
-        routeMethod.bind(Route_1.Route)(path, handler);
+        routeMethod.bind(Route_1.Route)(path, handler, { middleware });
     }
     handleHttpFunction(registration, FunctionClass, req, res) {
         return __awaiter(this, void 0, void 0, function* () {

package/dist/Auth/AuthSecurity.d.ts

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

package/dist/Auth/AuthSecurity.js

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

package/dist/Auth/SessionAuth.d.ts

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

package/dist/Auth/SessionAuth.js

@@ -0,0 +1,151 @@
+"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.SessionAuth = void 0;
+const DBConnection_1 = require("../Database/DBConnection");
+const AuthSecurity_1 = require("./AuthSecurity");
+function publicSession(record) {
+    return { id: record.id, subject: record.subject, issuer: record.issuer, audience: record.audience,
+        environment: record.environment, createdAt: record.createdAt, expiresAt: record.expiresAt, parent: record.parent };
+}
+function tokenSessionId(token) {
+    return typeof token === "string" && /^[A-Za-z0-9_-]{43}\.[A-Za-z0-9_-]{43}$/.test(token) ? token.split(".")[0] : null;
+}
+/** Revocable, hashed, independently addressable device sessions. Legacy UserAuth is unaffected. */
+class SessionAuth {
+    constructor(options) {
+        this.options = options;
+        this.scope = { issuer: (0, AuthSecurity_1.authText)(options.issuer, "issuer"), audience: (0, AuthSecurity_1.authText)(options.audience, "audience"),
+            environment: options.environment === undefined ? null : (0, AuthSecurity_1.authText)(options.environment, "environment") };
+        this.accessSeconds = (0, AuthSecurity_1.authLifetime)(options.accessTokenSeconds, 15 * 60);
+        this.sessionSeconds = (0, AuthSecurity_1.authLifetime)(options.sessionSeconds, 30 * 86400);
+        if (typeof options.isSessionAllowed !== "function")
+            throw new Error("SessionAuth requires isSessionAllowed.");
+    }
+    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(this.options.collection || "auth_sessions");
+        });
+    }
+    allowed(record) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!record || record.revokedAt !== null || !Number.isFinite(record.expiresAt) || record.expiresAt <= Date.now())
+                return null;
+            const session = publicSession(record);
+            return (yield this.options.isSessionAllowed(session)) ? session : null;
+        });
+    }
+    pair(record, access, refresh) {
+        return { auth_token: access, refresh_token: refresh, auth_expires_at: record.accessExpiresAt,
+            refresh_expires_at: record.expiresAt, session: publicSession(record) };
+    }
+    create(subject, parent = null) {
+        return __awaiter(this, void 0, void 0, function* () {
+            (0, AuthSecurity_1.authText)(subject, "subject");
+            if (parent) {
+                (0, AuthSecurity_1.authText)(parent.issuer, "parent issuer");
+                (0, AuthSecurity_1.authText)(parent.sessionId, "parent session");
+            }
+            const now = Date.now(), id = (0, AuthSecurity_1.randomAuthToken)();
+            const access = `${id}.${(0, AuthSecurity_1.randomAuthToken)()}`, refresh = `${id}.${(0, AuthSecurity_1.randomAuthToken)()}`, csrf = (0, AuthSecurity_1.randomAuthToken)();
+            const record = Object.assign(Object.assign({ _id: id, id, subject }, this.scope), { parent: parent ? Object.assign({}, parent) : null, createdAt: now, expiresAt: now + this.sessionSeconds * 1000, accessExpiresAt: now + Math.min(this.accessSeconds, this.sessionSeconds) * 1000, accessHash: (0, AuthSecurity_1.hashAuthToken)(access), refreshHash: (0, AuthSecurity_1.hashAuthToken)(refresh), csrfHash: (0, AuthSecurity_1.hashAuthToken)(csrf), usedRefreshHashes: [], revokedAt: null });
+            if (!(yield this.allowed(record)))
+                throw new Error("Session is not allowed.");
+            yield (yield this.rows()).insertOne(record);
+            return Object.assign(Object.assign({}, this.pair(record, access, refresh)), { csrf_token: csrf });
+        });
+    }
+    authenticate(token) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const id = tokenSessionId(token);
+            if (!id)
+                return null;
+            const row = yield (yield this.rows()).findOne(Object.assign(Object.assign({ _id: id }, this.scope), { accessHash: (0, AuthSecurity_1.hashAuthToken)(token), accessExpiresAt: { $gt: Date.now() } }));
+            return this.allowed(row);
+        });
+    }
+    /** Trusted-server introspection; never expose this method as an unauthenticated endpoint. */
+    inspect(sessionId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (typeof sessionId !== "string" || !/^[A-Za-z0-9_-]{43}$/.test(sessionId))
+                return null;
+            return this.allowed(yield (yield this.rows()).findOne(Object.assign({ _id: sessionId }, this.scope)));
+        });
+    }
+    verifyCsrf(token, csrf, kind = "access") {
+        return __awaiter(this, void 0, void 0, function* () {
+            const id = tokenSessionId(token);
+            if (!id || typeof csrf !== "string" || !/^[A-Za-z0-9_-]{43}$/.test(csrf))
+                return false;
+            const row = yield (yield this.rows()).findOne(Object.assign(Object.assign(Object.assign(Object.assign({ _id: id }, this.scope), (kind === "access" ? { accessHash: (0, AuthSecurity_1.hashAuthToken)(token) } : { $or: [{ refreshHash: (0, AuthSecurity_1.hashAuthToken)(token) }, { usedRefreshHashes: (0, AuthSecurity_1.hashAuthToken)(token) }] })), { csrfHash: (0, AuthSecurity_1.hashAuthToken)(csrf) }), (kind === "access" ? { accessExpiresAt: { $gt: Date.now() } } : {})));
+            return !!(yield this.allowed(row));
+        });
+    }
+    /** One winner under concurrency. A previously consumed refresh token revokes its device session. */
+    refresh(token) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const id = tokenSessionId(token);
+            if (!id)
+                return null;
+            const rows = yield this.rows(), hash = (0, AuthSecurity_1.hashAuthToken)(token);
+            const row = yield rows.findOne(Object.assign({ _id: id }, this.scope));
+            if (!(yield this.allowed(row)) || !row)
+                return null;
+            if (row.refreshHash !== hash) {
+                if (row.usedRefreshHashes.includes(hash))
+                    yield this.revoke(id);
+                return null;
+            }
+            // Bound history size and retain an absolute expiry instead of extending sessions indefinitely.
+            if (row.usedRefreshHashes.length >= 4096) {
+                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({ _id: id }, this.scope), { refreshHash: hash, revokedAt: null, expiresAt: { $gt: Date.now() } }), { $set: { accessHash: (0, AuthSecurity_1.hashAuthToken)(access), refreshHash: (0, AuthSecurity_1.hashAuthToken)(refresh),
+                    accessExpiresAt: Math.min(Date.now() + this.accessSeconds * 1000, row.expiresAt),
+                    usedRefreshHashes: [...row.usedRefreshHashes, hash] } }, { returnDocument: "after" });
+            if (!next) {
+                // Also detect simultaneous replay that lost the compare-and-swap.
+                yield rows.updateOne(Object.assign(Object.assign({ _id: id }, this.scope), { usedRefreshHashes: hash, revokedAt: null }), { $set: { revokedAt: Date.now() } });
+                return null;
+            }
+            return this.pair(next, access, refresh);
+        });
+    }
+    revoke(sessionId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            (0, AuthSecurity_1.authText)(sessionId, "session ID");
+            yield (yield this.rows()).updateOne(Object.assign(Object.assign({ _id: sessionId }, this.scope), { revokedAt: null }), { $set: { revokedAt: Date.now() } });
+        });
+    }
+    revokeAll(subject) {
+        return __awaiter(this, void 0, void 0, function* () {
+            (0, AuthSecurity_1.authText)(subject, "subject");
+            yield (yield this.rows()).updateMany(Object.assign(Object.assign({ subject }, this.scope), { revokedAt: null }), { $set: { revokedAt: Date.now() } });
+        });
+    }
+    list(subject) {
+        return __awaiter(this, void 0, void 0, function* () {
+            (0, AuthSecurity_1.authText)(subject, "subject");
+            const rows = yield (yield this.rows()).find(Object.assign(Object.assign({ subject }, this.scope), { revokedAt: null, expiresAt: { $gt: Date.now() } })).toArray();
+            return rows.map(publicSession);
+        });
+    }
+    /** Run periodically; authorization checks never depend on cleanup scheduling. */
+    cleanup() {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield (yield this.rows()).deleteMany(Object.assign(Object.assign({}, this.scope), { expiresAt: { $lte: Date.now() } }));
+        });
+    }
+}
+exports.SessionAuth = SessionAuth;

package/dist/Auth/SingleSignOn.d.ts

@@ -0,0 +1,99 @@
+import type { DocumentDatabase } from "../Database/DatabaseAdapter";
+import type { Request } from "../Router/Request";
+import type { Response } from "../Router/Response";
+import { AuthSession, SessionAuth } from "./SessionAuth";
+import { AuthCookies, WebAuthOptions } from "./WebAuth";
+/** Generate once during trusted instance provisioning; store only secretHash at the authority. */
+export declare function createSsoClientCredentials(): {
+    id: string;
+    secret: string;
+    secretHash: string;
+};
+export declare function readSsoClientCredentials(req: Request): {
+    clientId: string;
+    clientSecret: string;
+} | null;
+export type SsoClientRegistration = {
+    id: string;
+    secretHash: string;
+    redirectUris: string[];
+};
+export type SsoAuthorizationRequest = {
+    clientId: string;
+    redirectUri: string;
+    environment: string;
+    state: string;
+    codeChallenge: string;
+    codeChallengeMethod: "S256";
+};
+export type SsoCodeExchange = {
+    clientId: string;
+    clientSecret: string;
+    redirectUri: string;
+    environment: string;
+    code: string;
+    codeVerifier: string;
+};
+export type SsoIdentity = {
+    issuer: string;
+    audience: string;
+    subject: string;
+    environment: string;
+    authoritySessionId: string;
+    expiresAt: number;
+};
+export type SsoAuthorityOptions = {
+    issuer: string;
+    sessions: SessionAuth;
+    getClient: (clientId: string) => Promise<SsoClientRegistration | null>;
+    /** Required on issuance, exchange and introspection: verify the instance owns the environment AND the user is a member. */
+    authorize: (session: AuthSession, client: SsoClientRegistration, environment: string) => Promise<boolean>;
+    connection?: string;
+    collection?: string;
+    database?: () => Promise<DocumentDatabase>;
+    allowInsecureLocalhost?: boolean;
+};
+/** First-party, confidential-client SSO code bridge. Not a full OAuth/OIDC provider. */
+export declare class SsoAuthority {
+    private readonly options;
+    readonly issuer: string;
+    constructor(options: SsoAuthorityOptions);
+    private rows;
+    private client;
+    private authenticatedClient;
+    /** The caller authenticates the central browser session; its access token never leaves the authority. */
+    authorize(accessToken: string, request: SsoAuthorizationRequest): Promise<string | null>;
+    /** Server-to-server only; registered client credentials and PKCE are both mandatory. */
+    exchange(request: SsoCodeExchange): Promise<SsoIdentity | null>;
+    /** Use from instance session policy for central logout/account/membership revocation. */
+    introspect(clientId: string, clientSecret: string, sessionId: string, environment: string): Promise<SsoIdentity | null>;
+    cleanup(): Promise<void>;
+}
+export type SsoClientOptions = WebAuthOptions & {
+    issuer: string;
+    clientId: string;
+    clientSecret: string;
+    authorizationEndpoint: string;
+    tokenEndpoint: string;
+    introspectionEndpoint: string;
+    redirectUri: string;
+    connection?: string;
+    collection?: string;
+    database?: () => Promise<DocumentDatabase>;
+};
+/** Instance-side redirect flow. state + server-held PKCE verifier + host-only browser-binding cookie. */
+export declare class SsoClient {
+    private readonly options;
+    readonly cookies: AuthCookies;
+    readonly issuer: string;
+    private readonly authorization;
+    private readonly token;
+    private readonly introspection;
+    constructor(options: SsoClientOptions);
+    private rows;
+    begin(res: Response, environment: string): Promise<string>;
+    private identity;
+    complete(req: Request, res: Response): Promise<SsoIdentity | null>;
+    introspect(sessionId: string, environment: string): Promise<SsoIdentity | null>;
+    cleanup(): Promise<void>;
+}