@jwilleke/ngdpbase-types 5.22.0 → 5.23.0

package/lib/src/managers/AuthManager.d.ts

@@ -620,7 +620,9 @@ declare class AuthManager extends BaseManager {
      * Disable and delete both come through here, from UserManager, so nothing
      * an account holds is left reachable by one path and not the other.
      *
-     * - Both: every session of the account ends.
+     * - Both: every session of the account ends, destroyed in the live session
+     *   store (#1937); a session the store could not reach is still refused on
+     *   its next request (`checkSessionAccount`).
      * - Disable: its agent tokens, app grants and shares are suspended by the
      *   live owner-is-active checks that refuse them, and its credentials stay,
      *   so turning the account back on restores them.
@@ -1039,7 +1041,8 @@ declare class AuthManager extends BaseManager {
     /**
      * Stamp the session with the account's password-change generation (#1482):
      * at every sign-in, and on the session that changed the password, so that
-     * one stays signed in while every other session of the account ends.
+     * one stays signed in while every other session of the account ends. Also
+     * binds the session to the account itself (`accountCreatedAt`, #1937).
      */
     stampSessionGeneration(req: Request, username: string): Promise<void>;
     /**

package/lib/src/managers/SessionStatsManager.d.ts

@@ -0,0 +1,94 @@
+/**
+ * SessionStatsManager — in-process reads of the session store (#1246).
+ *
+ * Two things want to know how many sessions exist and who holds them: the
+ * `/api/session-count` and `/api/session-users` routes, and SessionsPlugin,
+ * which renders those numbers into a page. The plugin used to get them by
+ * making an HTTP request to this server's own address through a bare global
+ * `fetch` — an outbound call outside `src/http/` (#1133) that `guardedFetch`
+ * cannot take, because loopback is refused unconditionally (#1186), and one
+ * that silently rendered `0` in any container whose configured host was not
+ * reachable from inside the process.
+ *
+ * The store is an in-process object. Nothing about reading it needs a socket.
+ * app.ts attaches the store it built for express-session; the routes keep
+ * reading `req.sessionStore` (the same object) and both go through the same
+ * two helpers, so there is exactly one implementation of "count sessions" and
+ * "list session users".
+ */
+import BaseManager from './BaseManager.js';
+import type { WikiEngine } from '../types/WikiEngine.js';
+/** The two optional store methods express-session stores may implement. */
+export interface SessionStoreLike {
+    length?(callback: (err: unknown, count?: number) => void): void;
+    all?(callback: (err: unknown, sessions?: unknown) => void): void;
+    /** session-file-store: the session file names, not the sessions. */
+    list?(callback: (err: unknown, files?: string[]) => void): void;
+    get?(sid: string, callback: (err: unknown, session?: unknown) => void): void;
+    destroy?(sid: string, callback: (err: unknown) => void): void;
+    /** session-file-store keeps its file extension here (default `.json`). */
+    options?: {
+        fileExtension?: string;
+    };
+}
+export interface SessionCount {
+    sessionCount: number;
+    distinctUsers: number;
+}
+export interface SessionUsers {
+    users: string[];
+    anonymous: number;
+    total: number;
+}
+/** Thrown when the store implements neither `length` nor `all`. */
+export declare class SessionStoreUnsupportedError extends Error {
+    constructor(what: string);
+}
+/**
+ * Session count and distinct-user count. Prefers `length` (cheap), falls back
+ * to `all`. Under `length` the distinct-user figure equals the session count,
+ * which is what the route always reported on that path.
+ */
+export declare function countSessions(store: SessionStoreLike): Promise<SessionCount>;
+/**
+ * Authenticated usernames (sorted, distinct) and the anonymous session count.
+ * Needs `all`; under `length` alone the list is empty and every session is
+ * reported as anonymous.
+ */
+export declare function listSessionUsers(store: SessionStoreLike): Promise<SessionUsers>;
+/** A session in the store, with its id. */
+export interface StoredSession {
+    sid: string;
+    session: Record<string, unknown>;
+}
+/**
+ * Every session in the store with its id (#1937): `all()` keyed by id where
+ * the store has it, else list and read each (the file store). A store whose
+ * `all()` returns a bare array gives no ids, so it cannot be listed this way.
+ */
+export declare function storedSessions(store: SessionStoreLike): Promise<StoredSession[]>;
+/**
+ * The private-store handles held by sessions still in the store (#1626).
+ * Uses `all()` where the store has it, else lists and reads each session:
+ * the file store has no `all()`, so the sweep failed on every run there and
+ * no orphaned key was ever dropped.
+ */
+export declare function liveSessionHandles(store: SessionStoreLike): Promise<Set<string>>;
+declare class SessionStatsManager extends BaseManager {
+    private store;
+    constructor(engine: WikiEngine);
+    /** app.ts hands over the store it built for express-session. */
+    attachStore(store: SessionStoreLike): void;
+    hasStore(): boolean;
+    /** @throws Error when no store is attached; SessionStoreUnsupportedError when it cannot count. */
+    count(): Promise<SessionCount>;
+    /** @throws Error when no store is attached; SessionStoreUnsupportedError when it cannot list. */
+    users(): Promise<SessionUsers>;
+    /** @throws Error when no store is attached; SessionStoreUnsupportedError when it cannot list. */
+    liveHandles(): Promise<Set<string>>;
+    /** Every session in the store with its id (#1937). @throws Error when no store is attached; SessionStoreUnsupportedError when it cannot list by id. */
+    sessions(): Promise<StoredSession[]>;
+    /** Remove one session from the store (#1937). @throws Error when no store is attached, or SessionStoreUnsupportedError when it cannot destroy. */
+    destroy(sid: string): Promise<void>;
+}
+export default SessionStatsManager;

package/lib/src/managers/UserManager.d.ts

@@ -488,7 +488,27 @@ declare class UserManager extends BaseManager {
     createSession(username: string, additionalData?: Record<string, unknown>): Promise<string>;
     getSession(sessionId: string): Promise<UserSession | null>;
     deleteSession(sessionId: string): Promise<void>;
-    deleteUserSessions(username: string): Promise<void>;
+    /**
+     * End every signed-in session of `username` in the live session store
+     * (#1937): the account was deleted or turned off (`AuthManager.closeAccess`).
+     * Each goes through `endSession` (its keys dropped, `authentication-logout`
+     * recorded with the reason) and is removed from the store. Returns how many.
+     * The provider's own session list was cleared here before; nothing writes it,
+     * and the store express-session reads was never touched.
+     */
+    deleteUserSessions(username: string, reason: 'account-deleted' | 'account-disabled', from?: {
+        ipAddress?: string;
+    }): Promise<number>;
+    /**
+     * End every signed-in session in the store that no longer belongs to its
+     * account (#1937): the account is gone, turned off, another account of the
+     * same name, or its password changed since (`checkSessionAccount`, the
+     * per-request rule). Run once at startup, so sessions left from before the
+     * fix, or from a close the store missed, do not wait for their next request.
+     */
+    endStaleSessions(): Promise<number>;
+    /** End and remove each signed-in session `which` names a reason for; none without a session store. */
+    private endStoredSessions;
     backup(): Promise<BackupData>;
     restore(backupData: BackupData): Promise<void>;
 }

package/lib/src/types/express.d.ts

@@ -30,6 +30,8 @@ declare module 'express-session' {
         privateStoreHandle?: string;
         /** The account's password-change generation when this session signed in (#1482). */
         sessionGeneration?: number;
+        /** The `createdAt` of the account this session signed in to (#1937): a later account of the same name is not it. */
+        accountCreatedAt?: string;
         /** How this session signed in: provider, factors with their times, amr / aal / acr (#1523). */
         signIn?: SignInRecord;
         /** A pending WebAuthn challenge (#448): single-use, tied to its purpose, short-lived. */

package/lib/src/utils/sessionAccount.d.ts

@@ -0,0 +1,26 @@
+export type AccountEndReason = 'account-deleted' | 'account-disabled' | 'password-changed';
+interface AccountLike {
+    createdAt?: unknown;
+    isActive?: boolean;
+    sessionGeneration?: number;
+}
+interface SessionLike {
+    accountCreatedAt?: unknown;
+    signedInAt?: unknown;
+    sessionGeneration?: unknown;
+}
+/** The value a session is bound to: the account's creation time, or '' for a record without one. */
+export declare function accountBindingOf(account: AccountLike | null | undefined): string;
+/**
+ * What one request (or the sweep) does to a signed-in session, given its
+ * account as stored now (null when there is none). `bind` is set on a session
+ * signed in before the binding existed that still belongs to its account: the
+ * caller writes it to `accountCreatedAt`, once.
+ */
+export declare function checkSessionAccount(stored: SessionLike | Record<string, unknown>, account: AccountLike | null | undefined): {
+    end: AccountEndReason;
+} | {
+    end: null;
+    bind?: string;
+};
+export {};

package/lib/src/utils/sessionEnd.d.ts

@@ -1,4 +1,4 @@
-export type SessionEndReason = 'logout' | 'idle-timeout' | 'max-age' | 'password-changed' | 'superseded';
+export type SessionEndReason = 'logout' | 'idle-timeout' | 'max-age' | 'password-changed' | 'superseded' | 'account-deleted' | 'account-disabled';
 export declare function endSession(engine: {
     getManager(name: string): unknown;
 }, session: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jwilleke/ngdpbase-types",
-  "version": "5.22.0",
+  "version": "5.23.0",
   "description": "TypeScript types for ngdpbase add-ons, and a test kit of core's own values. A dev dependency, versioned with ngdpbase.",
   "license": "Apache-2.0",
   "author": "Jim Willeke",
@@ -46,7 +46,7 @@
     "ipaddr.js": "^2.5.0",
     "jose": "^6.2.12",
     "linkedom": "^0.18.13",
-    "markdown-it": "^14.3.1",
+    "markdown-it": "^14.3.3",
     "minimatch": "^10.2.6",
     "minisearch": "7.2.0",
     "multer": "^2.4.0",