@webtypen/webframez-core 0.3.78 → 0.3.80

package/dist/Auth/ModelAuth.d.ts

@@ -86,7 +86,7 @@ export declare class AuthScope extends WebAuth {
     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<{
+    establishBearerSession(req: Request, subject: string, parent?: AuthSession["parent"], environment?: string, parentExpiresAt?: number): Promise<{
         auth_token: string;
         refresh_token: string;
         auth_expires_at: number;

package/dist/Auth/ModelAuth.js

@@ -211,7 +211,7 @@ class AuthScope extends WebAuth_1.WebAuth {
         });
     }
     /** Trusted SSO/server entry point; the subject must already be verified by the caller. */
-    establishBearerSession(req, subject, parent = null, environment) {
+    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.");
@@ -229,14 +229,14 @@ class AuthScope extends WebAuth_1.WebAuth {
                     throw new AuthHookError("login_blocked", error);
                 }
             }
-            const pair = yield this.sessions.create(subject, parent, environment);
-            if (this.modelOptions.trackActivity !== false)
+            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 } = pair, tokens = __rest(pair, ["csrf_token"]);
+            const { csrf_token, reused } = pair, tokens = __rest(pair, ["csrf_token", "reused"]);
             return tokens;
         });
     }

package/dist/Auth/SessionAuth.d.ts

@@ -24,6 +24,7 @@ export type SessionTokenPair = {
 };
 export type CreatedAuthSession = SessionTokenPair & {
     csrf_token: string;
+    reused?: boolean;
 };
 export type SessionAuthOptions = {
     issuer: string;
@@ -32,6 +33,11 @@ export type SessionAuthOptions = {
     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;
@@ -60,7 +66,10 @@ export declare class SessionAuth {
     private liveFilter;
     private allowed;
     private pair;
-    create(subject: string, parent?: AuthSession["parent"], environment?: string): 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 = 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,8 +70,82 @@ 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, environment) {
+    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)) {
@@ -77,11 +155,21 @@ class SessionAuth {
                 (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), { 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 });
+            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 });
         });
@@ -117,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)
@@ -135,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() } });
@@ -168,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/docs/authentication.md

@@ -562,3 +562,25 @@ access nor refresh credentials need appear in navigation URLs. Configure a stron
 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.78",
+    "version": "0.3.80",
     "description": "The core package of the typescript based webframez (web-framework) by webtypen.de",
     "homepage": "https://webtypen.de/",
     "license": "MIT",