@songsid/agend 2.2.1 → 2.2.6

package/dist/web-session-authorization.js

@@ -0,0 +1,193 @@
+/**
+ * #1939 S2b (design §0, §0.1): "Authorize this browser". A signed-in session asks; AgEnD posts a Confirm card in the DM of
+ * the account the session was signed in as; **Confirm** there authorizes that session, **Not me** signs it out. The card
+ * is the one gate that stops a stolen cookie speaking as the person, so it is guarded against confirm fatigue:
+ * - it says exactly what it authorizes (this browser, its device label, this computer or the network, when, until when);
+ * - one pending card per session, at most 3 asks an hour per account; a refusal is explained in the app;
+ * - a card expires after 5 minutes (marked in place), and Confirm is judged at the tap (the session read again by its
+ *   handle and §3 run again — FleetManager.authorizeWebSession);
+ * - after Confirm the card stays as the notice, with Not me (sign the session out) for as long as the authorization lasts,
+ *   and says so (no buttons) when it ends;
+ * - when no DM can be sent, the adapter's General gets one line with no details.
+ * Durations use a monotonic clock; what the card shows is wall-clock time.
+ */
+import { randomBytes } from "node:crypto";
+export const AUTHORIZATION_CARD_TTL_MS = 5 * 60_000;
+export const AUTHORIZATION_ASKS_PER_HOUR = 3;
+const HOUR_MS = 3_600_000;
+export const AUTHORIZATION_CALLBACK_PREFIX = "wauth:";
+export class SessionAuthorizationRequests {
+    deps;
+    byNonce = new Map();
+    /** One pending card per session. */
+    pendingByHandle = new Map();
+    /** Monotonic times of each account's asks in the last hour. */
+    asks = new Map();
+    constructor(deps) {
+        this.deps = deps;
+    }
+    choices(c, confirm) {
+        return [
+            ...(confirm ? [{ id: `${AUTHORIZATION_CALLBACK_PREFIX}${c.nonce}:confirm`, label: this.deps.text.confirmLabel() }] : []),
+            { id: `${AUTHORIZATION_CALLBACK_PREFIX}${c.nonce}:notme`, label: this.deps.text.notMeLabel() },
+        ];
+    }
+    recentAsks(key) {
+        const now = this.deps.now();
+        const kept = (this.asks.get(key) ?? []).filter(t => now - t < HOUR_MS);
+        if (kept.length)
+            this.asks.set(key, kept);
+        else
+            this.asks.delete(key);
+        return kept;
+    }
+    /**
+     * This session's pending card. One past its deadline is expired now, whether or not its timer has run yet (a timer can
+     * run late): the app never shows "waiting 0:00", and a new ask is not refused as "pending".
+     */
+    livePending(handle) {
+        const c = this.pendingByHandle.get(handle);
+        if (!c || c.state !== "pending")
+            return null;
+        if (this.deps.now() >= c.expiresAt) {
+            void this.expire(c);
+            return null;
+        }
+        return c;
+    }
+    /** What the app shows for this session: a pending card (until when), or nothing pending. */
+    pending(handle) {
+        const c = this.livePending(handle);
+        return c ? { expiresInMs: Math.max(0, c.expiresAt - this.deps.now()) } : null;
+    }
+    /**
+     * The session asks (it qualifies under §3 — the caller checked, on this request). Refused while a card for it is
+     * pending, after 3 asks this hour by the account, or when no DM can be sent (General then gets a line, no details).
+     */
+    async ask(input) {
+        const existing = this.livePending(input.handle);
+        if (existing)
+            return { ok: false, refusal: "pending", retryAfterMs: Math.max(0, existing.expiresAt - this.deps.now()) };
+        const key = `${input.owner.adapterId}:${input.owner.userId}`;
+        const recent = this.recentAsks(key);
+        if (recent.length >= AUTHORIZATION_ASKS_PER_HOUR)
+            return { ok: false, refusal: "rate_limited", retryAfterMs: Math.max(0, recent[0] + HOUR_MS - this.deps.now()) };
+        recent.push(this.deps.now());
+        this.asks.set(key, recent);
+        const c = { nonce: randomBytes(16).toString("hex"), handle: input.handle, owner: { ...input.owner }, label: input.label, peer: input.peer,
+            expiresAt: this.deps.now() + AUTHORIZATION_CARD_TTL_MS, state: "pending", where: null };
+        this.byNonce.set(c.nonce, c);
+        this.pendingByHandle.set(c.handle, c);
+        const wall = this.deps.wallNow();
+        let where = null;
+        try {
+            // Until when it would last: the authorization's end, or the session's own when that comes first (as Confirm says).
+            const until = Math.min(wall + this.deps.maxSessionMs(), input.sessionEnd);
+            where = await this.deps.sendDirect(c.owner, this.deps.text.ask({ label: c.label, peer: c.peer, askedAt: wall, until }), this.choices(c, true));
+        }
+        catch (err) {
+            this.deps.log.warn({ err: err?.message }, "Web authorization card could not be sent");
+        }
+        if (!where) {
+            this.forget(c);
+            try {
+                await this.deps.sendGeneralHint(c.owner, this.deps.text.generalHint());
+            }
+            catch { /* best effort: the app says why */ }
+            this.deps.event("session_authorization_failed", { session: c.handle, actor: key, peer: c.peer, reason: "dm_unavailable" });
+            return { ok: false, refusal: "dm_unavailable" };
+        }
+        c.where = where;
+        c.timer = setTimeout(() => { void this.expire(c); }, AUTHORIZATION_CARD_TTL_MS);
+        c.timer.unref?.();
+        this.deps.event("session_authorization_issued", { challenge: c.nonce, session: c.handle, actor: key, peer: c.peer });
+        return { ok: true, expiresInMs: AUTHORIZATION_CARD_TTL_MS };
+    }
+    forget(c) {
+        if (c.timer)
+            clearTimeout(c.timer);
+        if (this.pendingByHandle.get(c.handle) === c)
+            this.pendingByHandle.delete(c.handle);
+    }
+    async edit(c, text, confirm) {
+        if (!c.where)
+            return;
+        try {
+            await this.deps.editCard(c.owner, c.where, text, confirm === null ? [] : this.choices(c, confirm));
+        }
+        catch (err) {
+            this.deps.log.warn({ err: err?.message }, "Web authorization card could not be updated");
+        }
+    }
+    async expire(c) {
+        if (c.state !== "pending")
+            return;
+        c.state = "expired";
+        this.forget(c);
+        this.byNonce.delete(c.nonce);
+        this.deps.event("session_authorization_expired", { challenge: c.nonce, session: c.handle, actor: `${c.owner.adapterId}:${c.owner.userId}`, peer: c.peer });
+        await this.edit(c, this.deps.text.expired({ label: c.label }), null);
+    }
+    /** A confirmed card at its authorization's end: forgotten, and edited to say so (no Not me left to press). */
+    async end(c) {
+        if (c.state !== "confirmed" || this.byNonce.get(c.nonce) !== c)
+            return;
+        c.state = "ended";
+        this.byNonce.delete(c.nonce);
+        await this.edit(c, this.deps.text.ended({ label: c.label }), null);
+    }
+    /** A tap on a card's button. Only the account it was sent to may tap it; anyone else is told it is not theirs. */
+    async handleCallback(data, adapterId) {
+        if (!data.callbackData.startsWith(AUTHORIZATION_CALLBACK_PREFIX))
+            return false;
+        const m = /^wauth:([0-9a-f]{32}):(confirm|notme)$/.exec(data.callbackData);
+        const c = m ? this.byNonce.get(m[1]) : undefined;
+        if (!m || !c) {
+            data.ack?.();
+            return true;
+        }
+        if (c.owner.adapterId !== adapterId || c.owner.userId !== String(data.userId ?? "")) {
+            data.ack?.(this.deps.text.notYours());
+            return true;
+        }
+        const key = `${c.owner.adapterId}:${c.owner.userId}`;
+        if (m[2] === "notme") {
+            // Before or after Confirm: sign that session out (its authorization ends with it).
+            const was = c.state;
+            c.state = was === "confirmed" ? "revoked" : "denied";
+            this.forget(c);
+            this.byNonce.delete(c.nonce);
+            this.deps.signOut(c.handle);
+            this.deps.event("session_authorization_failed", { challenge: c.nonce, session: c.handle, actor: key, peer: c.peer, reason: was === "confirmed" ? "not_me_after_confirm" : "not_me" });
+            data.ack?.();
+            await this.edit(c, was === "confirmed" ? this.deps.text.revoked({ label: c.label }) : this.deps.text.denied({ label: c.label }), null);
+            return true;
+        }
+        // Confirm: only a pending card, before it expires, judged now.
+        if (c.state !== "pending" || this.deps.now() >= c.expiresAt) {
+            data.ack?.();
+            if (c.state === "pending")
+                await this.expire(c);
+            return true;
+        }
+        this.forget(c);
+        const r = this.deps.authorize(c.handle, c.peer);
+        data.ack?.();
+        if (!r.ok) {
+            c.state = "refused";
+            this.byNonce.delete(c.nonce);
+            this.deps.event("session_authorization_failed", { challenge: c.nonce, session: c.handle, actor: key, peer: c.peer, reason: r.refusal });
+            await this.edit(c, this.deps.text.refused({ label: c.label, refusal: r.refusal }), null);
+            return true;
+        }
+        c.state = "confirmed";
+        c.until = r.until;
+        this.deps.event("session_authorization_verified", { challenge: c.nonce, session: c.handle, actor: key, peer: c.peer });
+        // The card stays as the notice, with Not me, for as long as the authorization lasts; then it says it ended.
+        await this.edit(c, this.deps.text.confirmed({ label: c.label, peer: c.peer, until: r.until }), false);
+        const end = setTimeout(() => { void this.end(c); }, Math.max(0, Math.min(c.until - this.deps.wallNow(), 2 ** 31 - 1)));
+        end.unref?.();
+        return true;
+    }
+}
+//# sourceMappingURL=web-session-authorization.js.map

package/dist/web-session-authorization.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"web-session-authorization.js","sourceRoot":"","sources":["../src/web-session-authorization.ts"],"names":[],"mappings":"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"}

package/dist/web-session.d.ts

@@ -1,7 +1,11 @@
 import { closeSync, fsyncSync, openSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
 export type SessionSurface = "local" | "gateway";
-/** `admin` may do everything the panel can; `read` is reserved for the read-only tier (design D6). */
-export type SessionTier = "admin" | "read";
+/**
+ * `admin` may do everything the panel can; `read` is reserved for the read-only tier (design D6). #1920: `guest` is a
+ * non-admin signed in as their own account (`owner`, always set), allowed only GUEST_ROUTES within a scope derived on
+ * every request (web-guest-access.ts). No code issues one yet (phase 2).
+ */
+export type SessionTier = "admin" | "read" | "guest";
 export interface SessionPolicy {
     /** Hard cap from creation; activity never extends it. */
     readonly absoluteMs: number;
@@ -28,8 +32,31 @@ export declare function localSessionPolicy(cfg: {
     absolute_hours?: unknown;
     idle_hours?: unknown;
 } | undefined): SessionPolicy;
-/** More than this and the least recently used one is dropped. */
+/**
+ * #1920 §5.4: a guest's session — shorter than an admin's, never longer than the surface's own policy (on the public
+ * link the link's 4 h / 30 min wins). `web.guests.session`: absolute 1–24 h, idle 15 min–12 h.
+ */
+export declare const GUEST_SESSION_POLICY: SessionPolicy;
+export declare const GUEST_SESSION_BOUNDS: {
+    readonly absoluteHours: {
+        readonly min: 1;
+        readonly max: 24;
+    };
+    readonly idleMinutes: {
+        readonly min: 15;
+        readonly max: 720;
+    };
+};
+/** The guest policy `web.guests.session` asks for, or the default for what it leaves out; defensive as localSessionPolicy. */
+export declare function guestSessionPolicy(cfg: {
+    absolute_hours?: unknown;
+    idle_minutes?: unknown;
+} | undefined): SessionPolicy;
+/** More than this and the least recently used one is dropped (#1920: admins' and read sessions; guests count apart). */
 export declare const MAX_WEB_SESSIONS = 8;
+/** #1920: guests never push an admin out — their own caps, the least recently used of their kind dropped first. */
+export declare const MAX_GUEST_SESSIONS = 64;
+export declare const MAX_GUEST_SESSIONS_PER_ACCOUNT = 4;
 /** `lastSeen` is only written to disk this often; creation and revocation always write. */
 export declare const SESSION_PERSIST_DEBOUNCE_MS: number;
 export interface SessionRecord {
@@ -109,6 +136,8 @@ export interface WebSessionStoreOptions {
      * can change while the fleet runs). Takes precedence over `policy.local`.
      */
     readonly localPolicy?: () => SessionPolicy;
+    /** #1920: a guest's policy, read at every check (`web.guests.session`); never longer than the surface's. */
+    readonly guestPolicy?: () => SessionPolicy;
     readonly maxSessions?: number;
     readonly onWarn?: (message: string) => void;
 }
@@ -118,6 +147,7 @@ export declare class WebSessionStore {
     private readonly now;
     private readonly policy;
     private readonly localPolicy;
+    private readonly guestPolicy;
     private readonly maxSessions;
     private readonly path;
     private readonly warn;
@@ -129,8 +159,11 @@ export declare class WebSessionStore {
     constructor(opts?: WebSessionStoreOptions);
     get size(): number;
     /** How long a session on this surface may sit unused before it ends. For showing people, not for deciding. */
-    idleWindowMs(surface: SessionSurface): number;
-    /** The policy in force for a surface now (#1620: the local one as configured at this moment; the gateway's fixed). */
+    idleWindowMs(surface: SessionSurface, tier?: SessionTier): number;
+    /**
+     * The policy in force for a surface now (#1620: the local one as configured at this moment; the gateway's fixed).
+     * #1920: a guest's is its own policy, never longer than the surface's.
+     */
     private policyFor;
     /**
      * #1620: a session's limits under the policy in force NOW. Shortening takes effect on existing sessions: the
@@ -183,9 +216,30 @@ export declare class WebSessionStore {
         count: number;
         durable: boolean;
     };
-    /** Every live session, newest activity first. `currentIdHash` marks the caller's own. */
-    list(currentIdHash?: string): SessionSummary[];
-    revokeByHandle(handle: string): {
+    /**
+     * Every live session, newest activity first. `currentIdHash` marks the caller's own. #1920: `only` keeps those a
+     * non-admin may see (their own, web-guest-access.ts).
+     */
+    list(currentIdHash?: string, only?: (r: SessionRecord) => boolean): SessionSummary[];
+    /** #1920 §3.2: the accounts with a live guest session, each once — for the background room-membership reads. */
+    guestOwners(): Array<{
+        adapterId: string;
+        userId: string;
+    }>;
+    /** #1920 phase 3 (Settings → Guests): each account with a live guest session — how many, and when last seen. */
+    guestActivity(): Array<{
+        adapterId: string;
+        userId: string;
+        sessions: number;
+        lastSeen: number;
+    }>;
+    /**
+     * #1939 S2b: the live session with this handle (an active one, not expired — limits applied), or null. Read-only: a
+     * Confirm tapped in Discord is judged against the session as it is at that moment.
+     */
+    findByHandle(handle: string): SessionRecord | null;
+    /** #1920: `only` as in list() — a session it rejects is not found. */
+    revokeByHandle(handle: string, only?: (r: SessionRecord) => boolean): {
         found: boolean;
         durable: boolean;
     };
@@ -193,14 +247,20 @@ export declare class WebSessionStore {
         removed: boolean;
         durable: boolean;
     };
-    /** Every session: how many there were, and whether the revocation is durable. */
-    revokeAll(): {
+    /** Every session (#1920: or every one `only` keeps): how many there were, and whether the revocation is durable. */
+    revokeAll(only?: (r: SessionRecord) => boolean): {
         count: number;
         durable: boolean;
     };
     /** Write anything pending. Called on shutdown. */
     flush(): void;
     private purgeExpired;
+    /**
+     * The caps: admins' and read sessions together; guests apart (#1920) — per account, then all guests — so a guest
+     * signing in never drops an admin's session, and one account cannot fill the guests' room.
+     */
+    private enforceCaps;
+    private count;
     private evictLeastRecentlyUsed;
     private persistIfDue;
     /**

package/dist/web-session.js

@@ -50,8 +50,24 @@ export function localSessionPolicy(cfg) {
     const absoluteMs = ms(cfg?.absolute_hours, def.absoluteMs);
     return { absoluteMs, idleMs: Math.min(ms(cfg?.idle_hours, def.idleMs), absoluteMs) };
 }
-/** More than this and the least recently used one is dropped. */
+/**
+ * #1920 §5.4: a guest's session — shorter than an admin's, never longer than the surface's own policy (on the public
+ * link the link's 4 h / 30 min wins). `web.guests.session`: absolute 1–24 h, idle 15 min–12 h.
+ */
+export const GUEST_SESSION_POLICY = { absoluteMs: 12 * HOUR, idleMs: 2 * HOUR };
+export const GUEST_SESSION_BOUNDS = { absoluteHours: { min: 1, max: 24 }, idleMinutes: { min: 15, max: 720 } };
+/** The guest policy `web.guests.session` asks for, or the default for what it leaves out; defensive as localSessionPolicy. */
+export function guestSessionPolicy(cfg) {
+    const { absoluteHours: a, idleMinutes: i } = GUEST_SESSION_BOUNDS;
+    const ms = (v, min, max, unit, fallback) => typeof v !== "number" || !Number.isFinite(v) || v > max ? fallback : Math.max(v, min) * unit;
+    const absoluteMs = ms(cfg?.absolute_hours, a.min, a.max, HOUR, GUEST_SESSION_POLICY.absoluteMs);
+    return { absoluteMs, idleMs: Math.min(ms(cfg?.idle_minutes, i.min, i.max, MINUTE, GUEST_SESSION_POLICY.idleMs), absoluteMs) };
+}
+/** More than this and the least recently used one is dropped (#1920: admins' and read sessions; guests count apart). */
 export const MAX_WEB_SESSIONS = 8;
+/** #1920: guests never push an admin out — their own caps, the least recently used of their kind dropped first. */
+export const MAX_GUEST_SESSIONS = 64;
+export const MAX_GUEST_SESSIONS_PER_ACCOUNT = 4;
 /** `lastSeen` is only written to disk this often; creation and revocation always write. */
 export const SESSION_PERSIST_DEBOUNCE_MS = 60 * 1000;
 const SESSION_ID_PATTERN = /^[0-9a-f]{64}$/;
@@ -120,19 +136,22 @@ function isRecord(value) {
         && typeof v.lastSeen === "number" && Number.isFinite(v.lastSeen)
         && typeof v.absoluteExpiry === "number" && Number.isFinite(v.absoluteExpiry)
         && typeof v.idleExpiry === "number" && Number.isFinite(v.idleExpiry)
-        && (v.tier === "admin" || v.tier === "read")
+        && (v.tier === "admin" || v.tier === "read" || (v.tier === "guest" && v.owner !== undefined))
         && (v.surface === "local" || v.surface === "gateway")
         && (v.exposureId === undefined || (typeof v.exposureId === "string" && /^[0-9a-f]{32}$/.test(v.exposureId)))
         && (v.owner === undefined || isOwner(v.owner))
         && typeof v.label === "string" && v.label.length <= LABEL_MAX
         && typeof v.tokenEpoch === "string" && HASH_PATTERN.test(v.tokenEpoch);
 }
+/** One account, as a map key (adapter ids and user ids never hold a newline). */
+const accountKey = (o) => `${o.adapterId}\n${o.userId}`;
 export class WebSessionStore {
     pending = new Set();
     byHash = new Map();
     now;
     policy;
     localPolicy;
+    guestPolicy;
     maxSessions;
     path;
     warn;
@@ -148,6 +167,7 @@ export class WebSessionStore {
             gateway: opts.policy?.gateway ?? DEFAULT_SESSION_POLICY.gateway,
         };
         this.localPolicy = opts.localPolicy ?? null;
+        this.guestPolicy = opts.guestPolicy ?? (() => GUEST_SESSION_POLICY);
         this.maxSessions = opts.maxSessions ?? MAX_WEB_SESSIONS;
         this.path = opts.dataDir ? join(opts.dataDir, "web-sessions.json") : null;
         this.warn = opts.onWarn ?? (() => { });
@@ -156,10 +176,18 @@ export class WebSessionStore {
     }
     get size() { return this.byHash.size; }
     /** How long a session on this surface may sit unused before it ends. For showing people, not for deciding. */
-    idleWindowMs(surface) { return this.policyFor(surface).idleMs; }
-    /** The policy in force for a surface now (#1620: the local one as configured at this moment; the gateway's fixed). */
-    policyFor(surface) {
-        return surface === "local" && this.localPolicy ? this.localPolicy() : this.policy[surface];
+    idleWindowMs(surface, tier = "admin") { return this.policyFor(surface, tier).idleMs; }
+    /**
+     * The policy in force for a surface now (#1620: the local one as configured at this moment; the gateway's fixed).
+     * #1920: a guest's is its own policy, never longer than the surface's.
+     */
+    policyFor(surface, tier) {
+        const base = surface === "local" && this.localPolicy ? this.localPolicy() : this.policy[surface];
+        if (tier !== "guest")
+            return base;
+        const guest = this.guestPolicy();
+        const absoluteMs = Math.min(base.absoluteMs, guest.absoluteMs);
+        return { absoluteMs, idleMs: Math.min(base.idleMs, guest.idleMs, absoluteMs) };
     }
     /**
      * #1620: a session's limits under the policy in force NOW. Shortening takes effect on existing sessions: the
@@ -169,7 +197,7 @@ export class WebSessionStore {
      * up to that absolute limit. New sessions get the new windows whole.
      */
     limit(record) {
-        const p = this.policyFor(record.surface);
+        const p = this.policyFor(record.surface, record.tier);
         const absoluteExpiry = Math.min(record.absoluteExpiry, record.created + p.absoluteMs);
         const idleExpiry = Math.min(record.idleExpiry, record.lastSeen + p.idleMs, absoluteExpiry);
         if (absoluteExpiry !== record.absoluteExpiry || idleExpiry !== record.idleExpiry) {
@@ -183,10 +211,13 @@ export class WebSessionStore {
      * in a cookie and forgets it.
      */
     create(input) {
+        // #1920: a guest is always someone's own account; never a guest of nobody.
+        if (input.tier === "guest" && !input.owner)
+            throw new Error("a guest session needs its owner");
         const now = this.now();
         this.purgeExpired(now);
         const sessionId = randomBytes(32).toString("hex");
-        const policy = this.policyFor(input.surface);
+        const policy = this.policyFor(input.surface, input.tier);
         const absoluteExpiry = now + policy.absoluteMs;
         const record = {
             handle: randomBytes(8).toString("hex"),
@@ -205,8 +236,7 @@ export class WebSessionStore {
         this.byHash.set(record.idHash, record);
         if (input.pending)
             this.pending.add(record.idHash);
-        while (this.byHash.size > this.maxSessions)
-            this.evictLeastRecentlyUsed();
+        this.enforceCaps();
         this.persistNow();
         return { sessionId, record };
     }
@@ -239,7 +269,7 @@ export class WebSessionStore {
         }
         if (opts.touch !== false) {
             record.lastSeen = now;
-            record.idleExpiry = Math.min(now + this.policyFor(record.surface).idleMs, record.absoluteExpiry);
+            record.idleExpiry = Math.min(now + this.policyFor(record.surface, record.tier).idleMs, record.absoluteExpiry);
             this.dirty = true;
             this.persistIfDue(now);
         }
@@ -271,10 +301,13 @@ export class WebSessionStore {
         }
         return { count, durable: this.persistNow() };
     }
-    /** Every live session, newest activity first. `currentIdHash` marks the caller's own. */
-    list(currentIdHash) {
+    /**
+     * Every live session, newest activity first. `currentIdHash` marks the caller's own. #1920: `only` keeps those a
+     * non-admin may see (their own, web-guest-access.ts).
+     */
+    list(currentIdHash, only) {
         this.purgeExpired(this.now());
-        return [...this.byHash.values()].filter(r => !this.pending.has(r.idHash))
+        return [...this.byHash.values()].filter(r => !this.pending.has(r.idHash) && (!only || only(r)))
             .sort((a, b) => b.lastSeen - a.lastSeen)
             .map(r => ({
             handle: r.handle,
@@ -293,11 +326,56 @@ export class WebSessionStore {
      * Memory forgets it at once; the file may not. A caller that reports "signed out" must not report it
      * when it is not durable — the operator would believe a session is dead that the next start revives.
      */
-    revokeByHandle(handle) {
+    /** #1920 §3.2: the accounts with a live guest session, each once — for the background room-membership reads. */
+    guestOwners() {
+        this.purgeExpired(this.now());
+        const seen = new Map();
+        for (const r of this.byHash.values()) {
+            if (r.tier !== "guest" || !r.owner || this.pending.has(r.idHash))
+                continue;
+            seen.set(`${r.owner.adapterId}\u0000${r.owner.userId}`, { adapterId: r.owner.adapterId, userId: r.owner.userId });
+        }
+        return [...seen.values()];
+    }
+    /** #1920 phase 3 (Settings → Guests): each account with a live guest session — how many, and when last seen. */
+    guestActivity() {
+        this.purgeExpired(this.now());
+        const by = new Map();
+        for (const r of this.byHash.values()) {
+            if (r.tier !== "guest" || !r.owner || this.pending.has(r.idHash))
+                continue;
+            const k = `${r.owner.adapterId}\u0000${r.owner.userId}`, cur = by.get(k);
+            if (cur) {
+                cur.sessions++;
+                cur.lastSeen = Math.max(cur.lastSeen, r.lastSeen);
+            }
+            else
+                by.set(k, { adapterId: r.owner.adapterId, userId: r.owner.userId, sessions: 1, lastSeen: r.lastSeen });
+        }
+        return [...by.values()];
+    }
+    /**
+     * #1939 S2b: the live session with this handle (an active one, not expired — limits applied), or null. Read-only: a
+     * Confirm tapped in Discord is judged against the session as it is at that moment.
+     */
+    findByHandle(handle) {
+        if (!HANDLE_PATTERN.test(handle))
+            return null;
+        const now = this.now();
+        for (const record of this.byHash.values()) {
+            if (record.handle !== handle || this.pending.has(record.idHash))
+                continue;
+            this.limit(record);
+            return now < record.absoluteExpiry && now < record.idleExpiry ? record : null;
+        }
+        return null;
+    }
+    /** #1920: `only` as in list() — a session it rejects is not found. */
+    revokeByHandle(handle, only) {
         if (!HANDLE_PATTERN.test(handle))
             return { found: false, durable: true };
         for (const [hash, record] of this.byHash) {
-            if (record.handle === handle) {
+            if (record.handle === handle && (!only || only(record))) {
                 this.byHash.delete(hash);
                 this.pending.delete(hash);
                 return { found: true, durable: this.persistNow() };
@@ -313,8 +391,18 @@ export class WebSessionStore {
         const removed = this.byHash.delete(hash);
         return { removed, durable: removed ? this.persistNow() : true };
     }
-    /** Every session: how many there were, and whether the revocation is durable. */
-    revokeAll() {
+    /** Every session (#1920: or every one `only` keeps): how many there were, and whether the revocation is durable. */
+    revokeAll(only) {
+        if (only) {
+            let count = 0;
+            for (const [hash, record] of this.byHash)
+                if (only(record)) {
+                    this.byHash.delete(hash);
+                    this.pending.delete(hash);
+                    count++;
+                }
+            return { count, durable: count ? this.persistNow() : true };
+        }
         const count = this.byHash.size;
         this.byHash.clear();
         this.pending.clear();
@@ -338,10 +426,38 @@ export class WebSessionStore {
         if (removed)
             this.dirty = true;
     }
-    evictLeastRecentlyUsed() {
+    /**
+     * The caps: admins' and read sessions together; guests apart (#1920) — per account, then all guests — so a guest
+     * signing in never drops an admin's session, and one account cannot fill the guests' room.
+     */
+    enforceCaps() {
+        const notGuest = (r) => r.tier !== "guest";
+        while (this.count(notGuest) > this.maxSessions)
+            this.evictLeastRecentlyUsed(notGuest);
+        const accounts = new Set();
+        for (const r of this.byHash.values())
+            if (r.tier === "guest")
+                accounts.add(accountKey(r.owner));
+        for (const key of accounts) {
+            const mine = (r) => r.tier === "guest" && accountKey(r.owner) === key;
+            while (this.count(mine) > MAX_GUEST_SESSIONS_PER_ACCOUNT)
+                this.evictLeastRecentlyUsed(mine);
+        }
+        const guest = (r) => r.tier === "guest";
+        while (this.count(guest) > MAX_GUEST_SESSIONS)
+            this.evictLeastRecentlyUsed(guest);
+    }
+    count(which) {
+        let n = 0;
+        for (const record of this.byHash.values())
+            if (which(record))
+                n++;
+        return n;
+    }
+    evictLeastRecentlyUsed(which) {
         let oldest = null;
         for (const record of this.byHash.values()) {
-            if (!oldest || record.lastSeen < oldest.lastSeen)
+            if (which(record) && (!oldest || record.lastSeen < oldest.lastSeen))
                 oldest = record;
         }
         if (oldest) {
@@ -459,8 +575,7 @@ export class WebSessionStore {
                 continue;
             this.byHash.set(record.idHash, record);
         }
-        while (this.byHash.size > this.maxSessions)
-            this.evictLeastRecentlyUsed();
+        this.enforceCaps();
         this.persisted = new Set([...this.byHash.keys()].filter(hash => !this.pending.has(hash)));
     }
 }