@songsid/agend 2.2.0 → 2.2.5

package/dist/web-guest-access.js

@@ -0,0 +1,234 @@
+/**
+ * #1920 phase 1: what a guest web session may reach — default deny. A guest is a non-admin signed in as their own
+ * Discord or Telegram account; its scope (the instances it may see) is derived on every request (phase 2) and never
+ * stored. This module is the table and the decision; FleetManager applies it at the one entry every web request passes
+ * (the local listener and the public link's gateway), before any handler.
+ *
+ * - A route not on GUEST_ROUTES: 403 `guest_forbidden` — a new route is closed to guests until someone classifies it.
+ * - A route on it that names an instance out of scope: 404 (another instance's name is never confirmed).
+ * - An entry is `on` only once what it serves is safe for a guest. `later` entries are the design's (#1920 §4) and say
+ *   which phase opens them; until then they answer 403 like any other route.
+ * - Phase 1b: a guest's request carries its guest context (bindGuestRequest) for the handlers that answer per recipient —
+ *   the stream, the poll, a file — and their projections are here, default deny like the table.
+ *
+ * The `/auth/*` self routes (who am I, my devices, sign out) are not here: they are public by path and answer each
+ * caller about their own account only (auth-api.ts).
+ */
+import { shellRoute } from "./web-shell-routes.js";
+const READS = ["GET", "HEAD"];
+const NAME = "([^/]+)";
+/** The design's table (#1920 §4). Everything else is 403 for a guest. */
+export const GUEST_ROUTES = [
+    // The app shell and its code: static (the shell boots in guest mode in phase 3).
+    { methods: READS, pattern: /^\/ui$/, instance: null, state: "on", note: "the app shell (static)" },
+    { methods: READS, pattern: new RegExp(`^/ui/chat/${NAME}$`), instance: { group: 1 }, state: "on", note: "the app shell for one chat (static; out of scope: 404)" },
+    { methods: ["GET"], pattern: /^\/ui\/js\/[a-z0-9_-]+\.js$/, instance: null, state: "on", note: "the panels' code (static)" },
+    // What a member of the channel already sees of the instance: its profile, avatar, identity card and theme pictures.
+    { methods: READS, pattern: new RegExp(`^/api/(?:profile|avatar)/${NAME}$`), instance: { group: 1 }, state: "on", note: "the instance's profile and avatar" },
+    { methods: READS, pattern: new RegExp(`^/api/card/${NAME}(?:/(?:portrait|banner))?$`), instance: { group: 1 }, state: "on", note: "the instance's identity card" },
+    { methods: ["GET"], pattern: new RegExp(`^/ui/img/(?:avatar|bot)/${NAME}$`), instance: { group: 1 }, state: "on", note: "the instance's face in the sidebar" },
+    { methods: ["GET"], pattern: new RegExp(`^/ui/img/theme/${NAME}/[0-9a-f]{32}$`), instance: { group: 1 }, state: "on", note: "the instance's theme pictures" },
+    { methods: ["GET"], pattern: /^\/ui\/effect-posters$/, instance: { query: "instance" }, state: "on", note: "the instance's static effect posters (the list)" },
+    { methods: ["GET"], pattern: /^\/ui\/effects\/placements$/, instance: { query: "instance" }, state: "on", note: "current in-scope Chat effect metadata only, with a session epoch" },
+    { methods: ["GET"], pattern: /^\/ui\/effects\/resource\/[0-9a-f]{32}$/, instance: { query: "instance" }, state: "on", note: "a current in-scope Chat effect resource, never library or personal-slot reads" },
+    // Opened by phase 1b: the stream and the poll filtered per recipient; a file bound to its instance.
+    // The stream and the poll, projected per recipient (guestFrameData / guestPollBody); a file, bound to its stored
+    // instance by the handler (404 out of scope: an id from another instance is useless).
+    { methods: ["GET"], pattern: /^\/ui\/events$/, instance: null, state: "on", note: "the stream, projected for this guest (guestFrameData)" },
+    { methods: ["GET"], pattern: /^\/ui\/poll$/, instance: null, state: "on", note: "the poll, projected for this guest (guestPollBody)" },
+    { methods: ["GET"], pattern: /^\/ui\/file\/[^/]+$/, instance: null, state: "on", note: "a file, served only when its stored instance is in scope (the handler checks)" },
+    { methods: ["GET"], pattern: /^\/ui\/effect-posters\/[0-9a-f]{32}\.png$/, instance: { query: "instance" }, state: "on", note: "a placed effect's static poster, bound to its instance by the query" },
+    // Opened by phase 2: what needs the guest's own identity, authority and the history rule.
+    { methods: ["GET"], pattern: /^\/ui\/history$/, instance: { query: "instance" }, state: "on", note: "an in-scope instance's history, as its channel showed it (guestHistory, #1920 §5.2)" },
+    // Phase 2 (step 2b): chat as on the platform — authority none, never a command (guestChatRefusal, in the handlers).
+    { methods: ["POST"], pattern: /^\/ui\/send$/, instance: null, state: "on", note: "a message to an in-scope instance (the handler checks the body's instance and web.guests.chat); never a command" },
+    { methods: ["POST"], pattern: /^\/ui\/upload$/, instance: { query: "instance" }, state: "on", note: "a file for an in-scope instance's message (web.guests.chat)" },
+    { methods: ["POST"], pattern: /^\/ui\/reply-button$/, instance: null, state: "on", note: "a click on a reply the guest may see (the handler checks; web.guests.chat)" },
+    { methods: ["POST"], pattern: new RegExp(`^/ui/cancel/${NAME}$`), instance: { group: 1 }, state: "on", note: "Cancel, as the platform's button lets anyone allowed there (web.guests.chat)" },
+    { methods: ["GET"], pattern: /^\/ui\/prefs$/, instance: null, state: "on", note: "the host's look (theme, language, shown settings) and the guest's own — nothing that names an instance (guestPrefs)" },
+    { methods: ["POST"], pattern: /^\/ui\/prefs$/, instance: null, state: "later", note: "phase 3: what a guest may keep of its own" },
+    { methods: ["GET", "POST"], pattern: /^\/ui\/profile$/, instance: null, state: "on", note: "the guest's own web name (its account's, never anyone else's)" },
+];
+/** An instance name from a path segment, or null when it is not one (the shell's own rule). */
+function segmentName(path) {
+    const m = shellRoute("GET", `/ui/chat/${path}`);
+    return m && m.kind === "shell" && m.route.panel === "chat" ? m.route.instance : null;
+}
+/**
+ * A guest's request: allowed (an `on` route, its instance in `scope`), 404 (an `on` per-instance route whose instance is
+ * not in scope, or is not a name at all), or 403 (anything else).
+ */
+export function guestRouteDecision(method, url, scope) {
+    const m = (method || "GET").toUpperCase();
+    for (const route of GUEST_ROUTES) {
+        if (!route.methods.includes(m))
+            continue;
+        const match = route.pattern.exec(url.pathname);
+        if (!match)
+            continue;
+        if (route.state !== "on")
+            break;
+        if (route.instance === null)
+            return { kind: "allow", route };
+        const name = "group" in route.instance ? segmentName(match[route.instance.group]) : url.searchParams.get(route.instance.query);
+        if (name && scope.has(name))
+            return { kind: "allow", route };
+        return { kind: "deny", status: 404, error: "not found" };
+    }
+    return { kind: "deny", status: 403, error: "guest_forbidden" };
+}
+/** The same Discord or Telegram account (both sessions name one), for a guest's "my own sessions". */
+export function sameAccount(a, b) {
+    return !!a && !!b && a.adapterId === b.adapterId && a.userId === b.userId;
+}
+/**
+ * #1920 §5.1 (step 2b): why a guest may not write to `instance` now, or null (not a guest, or allowed): out of scope is
+ * "not found" (another instance's name is never confirmed); read-only when the host says so.
+ */
+export function guestChatRefusal(guest, instance) {
+    if (!guest)
+        return null;
+    if (typeof instance !== "string" || !guest.scope().has(instance))
+        return { status: 404, error: "not found" };
+    if (guest.chat?.() !== true)
+        return { status: 403, error: "guest_read_only" };
+    return null;
+}
+/** A guest never sends a command: text that starts (after spaces) with "/" is the platform's admin or command syntax. */
+export const guestCommandText = (text) => /^\s*\//.test(text);
+/**
+ * #1920 §4 (step 2b): the preferences a guest reads — the host's look and the guest's own; never one that names an
+ * instance (the sidebar's order, favourites, a card's size, the sidebar widget, names, the filter).
+ */
+export const GUEST_PREF_KEYS = new Set(["theme", "lang", "fx.show", "card.size", "color.show", "color.off", "fx.sidebar", "fx.header", "fx.page", "fx.box", "fx.cursor"]);
+export function guestPrefs(view) {
+    const values = {};
+    for (const [k, v] of Object.entries(view.values))
+        if (GUEST_PREF_KEYS.has(k))
+            values[k] = v;
+    return { ...view, values };
+}
+const guestRequests = new WeakMap();
+/** Set by the one entry that admits a guest (FleetManager's gate); read by the handlers that answer per recipient. */
+export function bindGuestRequest(req, guest) { guestRequests.set(req, guest); }
+export function guestRequestOf(req) { return guestRequests.get(req); }
+/**
+ * What a guest's status frame keeps of each in-scope instance: who it is and how it looks, its state — not its model,
+ * backend, effort, cost, context, description, tags or what it is waiting for (a prompt's text). And nothing of the
+ * fleet: no public link, connections, uptime, host memory, revisions.
+ */
+const STATUS_FIELDS = ["name", "display_name", "avatar", "accent", "theme_avatar", "theme_accent", "card_v", "effect_chat_v", "color", "color_show", "status", "state", "execution_state"];
+export function guestStatus(status, scope) {
+    const list = status && typeof status === "object" && Array.isArray(status.instances) ? status.instances : [];
+    const instances = [];
+    for (const raw of list) {
+        if (!raw || typeof raw !== "object")
+            continue;
+        const i = raw;
+        if (typeof i.name !== "string" || !scope.has(i.name))
+            continue;
+        const out = {};
+        for (const k of STATUS_FIELDS)
+            if (Object.prototype.hasOwnProperty.call(i, k) && i[k] !== undefined)
+                out[k] = i[k];
+        instances.push(out);
+    }
+    return { instances };
+}
+// ── Phase 2: the chat, as the channel showed it (#1920 §5.2) ──
+const accountOf = (o) => `${o.adapterId}:${o.userId}`;
+/**
+ * Whether a guest sees one kept message: an in-scope instance's message that reached its channel (what the channel's
+ * members already saw), the guest's own, or anything in its own private room. Never someone else's web-only exchange,
+ * a cross-instance notice, a fleet status line, or a row kept from before these were recorded (they have no mark).
+ */
+export function guestSeesMessage(m, guest, scope) {
+    if (!scope.has(m.instance))
+        return false;
+    return m.channel === true || m.from === accountOf(guest.owner) || guest.ownRoom?.(m.instance) === true;
+}
+/**
+ * A message as a guest gets it: without whose account wrote it (`mine` says it was the guest), and without another
+ * person's message id and ticks; never an effect Try (effects stay admin-only).
+ */
+export function guestMessage(m, guest) {
+    const { from, channel: _channel, messageId, delivery, effectTrial: _trial, seenSeq: _seen, ...rest } = m;
+    void _channel;
+    void _trial;
+    void _seen;
+    const mine = from === accountOf(guest.owner);
+    // #2085 review: a click's `text` is what the agent was given — the button's value too, which the platform never
+    // shows. A guest gets the label, as the channel showed it.
+    const click = rest.click ? { text: rest.click.label } : {};
+    return { ...rest, ...click, ...(mine ? { mine: true } : {}), ...(mine && messageId ? { messageId } : {}), ...(mine && delivery ? { delivery } : {}) };
+}
+const visibleList = (rows, guest, scope) => rows.filter((m) => !m.effectTrial && guestSeesMessage(m, guest, scope)).map((m) => guestMessage(m, guest));
+/**
+ * One stream event as a guest gets it, or undefined (not sent). Default deny:
+ * - the status (projected) and an in-scope instance's activity;
+ * - a chat message it may see (§5.2), a tick on one of its own messages, the buttons of a reply it may see;
+ * - never: the live reply receipt (effects), prompts (their nonces answer them), Needs you, the Log's ticks, traffic or
+ *   apply progress.
+ * Without `guest` (no context) only the status and activity pass.
+ */
+export function guestFrameData(event, data, scope, guest) {
+    if (event === "status")
+        return guestStatus(data, scope);
+    const d = data && typeof data === "object" ? data : {};
+    if (event === "activity")
+        return typeof d.instance === "string" && scope.has(d.instance) ? { instance: d.instance, state: d.state ?? null } : undefined;
+    if (!guest)
+        return undefined;
+    if (event === "message") {
+        const m = data;
+        return typeof m?.instance === "string" && guestSeesMessage(m, guest, scope) ? guestMessage(m, guest) : undefined;
+    }
+    const history = guest.history?.();
+    if (!history || typeof d.instance !== "string" || !scope.has(d.instance))
+        return undefined;
+    if (event === "delivery") {
+        const own = typeof d.messageId === "string" ? history.findByMessageId(d.instance, d.messageId) : undefined;
+        return own && own.from === accountOf(guest.owner) ? { instance: d.instance, messageId: d.messageId, delivery: d.delivery } : undefined;
+    }
+    if (event === "reply_buttons") {
+        const id = d.buttons && typeof d.buttons === "object" ? d.buttons.id : undefined;
+        const row = typeof id === "string" ? history.findByButtons(d.instance, id) : undefined;
+        return row && guestSeesMessage(row, guest, scope) ? { instance: d.instance, buttons: d.buttons } : undefined;
+    }
+    return undefined;
+}
+/** The ticks a guest is caught up with: its own messages' only. */
+export function guestDeliveries(history, guest, scope) {
+    return history.deliveries().filter((t) => scope.has(t.instance) && history.findByMessageId(t.instance, t.messageId)?.from === accountOf(guest.owner));
+}
+/** The ended (or open-poll) buttons a guest is caught up with: on replies it may see. */
+export function guestButtonStates(history, guest, scope) {
+    return history.buttonStates().filter((b) => { const row = history.findByButtons(b.instance, b.buttons.id); return !!row && guestSeesMessage(row, guest, scope); });
+}
+/** A guest's replay (a reconnecting stream, a poll): what it may see of `rows`. */
+export function guestMessages(rows, guest, scope) {
+    return visibleList(rows, guest, scope);
+}
+/** /ui/history for a guest: the newest `limit` messages of one instance that it may see. */
+export function guestHistory(history, instance, limit, guest, scope) {
+    return visibleList(history.list(instance), guest, scope).slice(-limit);
+}
+/**
+ * /ui/poll's answer for a guest: the projected status, and the chat it may see (the same rule as its stream) — with the
+ * cursor every poll hands out. Never prompts or Needs you.
+ */
+export function guestPollBody(status, scope, now, guest, after, replay) {
+    const history = guest?.history?.() ?? null;
+    if (!guest || !history || !replay)
+        return { status: guestStatus(status, scope), messages: [], deliveries: [], reply_buttons: [], prompts: [], needs: [], cursor: null, now };
+    return {
+        status: guestStatus(status, scope),
+        messages: guestMessages(replay(after ?? null), guest, scope),
+        deliveries: guestDeliveries(history, guest, scope),
+        reply_buttons: guestButtonStates(history, guest, scope),
+        prompts: [], needs: [],
+        cursor: history.pollCursor(),
+        now,
+    };
+}
+//# sourceMappingURL=web-guest-access.js.map

package/dist/web-guest-access.js.map

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

package/dist/web-guest-rooms.d.ts

@@ -0,0 +1,82 @@
+/**
+ * #1920 §3.2: a guest's ClassicBot group or guild rooms — in scope only while its membership is verified.
+ *
+ * The answers are read in the background (at sign-in, every ten minutes, and when the guest's stream connects) and
+ * kept in memory; a request only reads them, never the platform. A room is shown only on a "member" answer at most
+ * 15 minutes old; an unknown, failed or stale answer hides it (fail closed).
+ *
+ * Revocation needs more than "hidden": a scope that becomes empty ends the session, and an answer not read yet (a
+ * restart, a room just created) must not end it. A key with no answer is pending for at most the stale window from
+ * when it was first wanted; after that, and after a "not a member" answer, it is settled.
+ */
+import type { ClassicChannel } from "./classic-channel-manager.js";
+export interface GuestOwner {
+    readonly adapterId: string;
+    readonly userId: string;
+}
+/** A ClassicBot room a guest may be a member of: a Telegram group or a Discord channel, on the guest's connection. */
+export interface GuestRoom {
+    readonly instance: string;
+    readonly adapterId: string;
+    readonly channelId: string;
+    readonly kind: "telegram" | "discord";
+}
+/** The adapter's read: true a member, false not (a definite answer); a rejection or anything else is no answer. */
+export type RoomMemberRead = (room: GuestRoom, userId: string) => Promise<boolean> | undefined;
+export declare const GUEST_ROOM_RECHECK_MS: number;
+export declare const GUEST_ROOM_STALE_MS: number;
+export declare const GUEST_ROOM_FORCE_FLOOR_MS = 60000;
+/** A read a request started (a pending guest polling or retrying): at most one per key in this long, whatever the volume. */
+export declare const GUEST_ROOM_TRIGGER_FLOOR_MS = 30000;
+/** Failed reads back off — a minute, then 2, 4, 8 … — up to ten minutes (a bot without the permission, or removed). */
+export declare const GUEST_ROOM_RETRY_MS = 60000;
+export declare const GUEST_ROOM_RETRY_MAX_MS: number;
+/** Consecutive failures after which a key's failure is persistent: said once (onPersistentFailure), not every attempt. */
+export declare const GUEST_ROOM_PERSISTENT_FAILURES = 3;
+/** The background tick runs this often and reads only what is due. */
+export declare const GUEST_ROOM_TICK_MS = 60000;
+/**
+ * The group rooms on this guest's own connection. A Telegram private room (a positive id) is not here: it is the
+ * account's own room or someone else's, never a membership question.
+ */
+export declare function guestGroupRooms(rooms: readonly ClassicChannel[], owner: GuestOwner): GuestRoom[];
+/** Who reads: the background pass (what is due), a request of a pending guest (rate-limited), a stream connecting. */
+export type GuestRoomReadMode = "scheduled" | "triggered" | "force";
+export declare class GuestRoomMembership {
+    private readonly opts;
+    private readonly entries;
+    private readonly reads;
+    constructor(opts: {
+        now: () => number;
+        read: RoomMemberRead;
+        deadlineMs?: number;
+        staleMs?: number;
+        recheckMs?: number;
+        /** A key's reads keep failing (said once, until an answer); and when it answers again after that. */
+        onPersistentFailure?: (room: GuestRoom, failures: number) => void;
+        onRecovered?: (room: GuestRoom) => void;
+    });
+    private key;
+    private get staleMs();
+    /** Shown: a "member" answer no older than the stale window. */
+    verified(room: GuestRoom, userId: string): boolean;
+    /**
+     * Not settled yet: no definite answer, and first wanted less than the stale window ago (or never — a key nobody
+     * asked about yet is pending, and starts its window here). A pending room keeps an emptied scope from ending the
+     * session; it never shows the room.
+     */
+    pending(room: GuestRoom, userId: string): boolean;
+    /**
+     * Read this guest's rooms, one at a time; never rejects. One read per key at a time.
+     * - "scheduled": what is due (never asked; ten minutes after an answer; a failure's backoff).
+     * - "triggered" (a pending guest's request): the same, and never within 30 s of the key's last read, so a guest that
+     *   polls or retries is not platform traffic.
+     * - "force" (its stream connected): a minute after the key's last read — but a failing key keeps its backoff.
+     */
+    refresh(owner: GuestOwner, rooms: readonly GuestRoom[], opts?: {
+        mode?: GuestRoomReadMode;
+    }): Promise<void>;
+    private ask;
+    private readBounded;
+    private put;
+}

package/dist/web-guest-rooms.js

@@ -0,0 +1,135 @@
+import { inferClassicChannelType } from "./classic-channel-manager.js";
+export const GUEST_ROOM_RECHECK_MS = 10 * 60_000;
+export const GUEST_ROOM_STALE_MS = 15 * 60_000;
+export const GUEST_ROOM_FORCE_FLOOR_MS = 60_000;
+/** A read a request started (a pending guest polling or retrying): at most one per key in this long, whatever the volume. */
+export const GUEST_ROOM_TRIGGER_FLOOR_MS = 30_000;
+/** Failed reads back off — a minute, then 2, 4, 8 … — up to ten minutes (a bot without the permission, or removed). */
+export const GUEST_ROOM_RETRY_MS = 60_000;
+export const GUEST_ROOM_RETRY_MAX_MS = 10 * 60_000;
+/** Consecutive failures after which a key's failure is persistent: said once (onPersistentFailure), not every attempt. */
+export const GUEST_ROOM_PERSISTENT_FAILURES = 3;
+/** The background tick runs this often and reads only what is due. */
+export const GUEST_ROOM_TICK_MS = 60_000;
+const READ_DEADLINE_MS = 5_000;
+/** The guest caps (4 per account, 64 in all) bound the owners; this bounds a fleet with very many rooms. */
+const MAX_ENTRIES = 8192;
+/**
+ * The group rooms on this guest's own connection. A Telegram private room (a positive id) is not here: it is the
+ * account's own room or someone else's, never a membership question.
+ */
+export function guestGroupRooms(rooms, owner) {
+    const out = [];
+    for (const room of rooms) {
+        if (room.adapterId !== owner.adapterId)
+            continue;
+        const kind = inferClassicChannelType(room.channelId);
+        if (kind === "telegram" && room.channelId.trim().startsWith("-"))
+            out.push({ instance: room.instanceName, adapterId: room.adapterId, channelId: room.channelId, kind });
+        else if (kind === "discord")
+            out.push({ instance: room.instanceName, adapterId: room.adapterId, channelId: room.channelId, kind });
+    }
+    return out;
+}
+export class GuestRoomMembership {
+    opts;
+    entries = new Map();
+    reads = new Map();
+    constructor(opts) {
+        this.opts = opts;
+    }
+    key(room, userId) { return `${room.adapterId}\u0000${room.channelId}\u0000${userId}`; }
+    get staleMs() { return this.opts.staleMs ?? GUEST_ROOM_STALE_MS; }
+    /** Shown: a "member" answer no older than the stale window. */
+    verified(room, userId) {
+        const e = this.entries.get(this.key(room, userId));
+        return !!e && e.member === true && this.opts.now() - e.at <= this.staleMs;
+    }
+    /**
+     * Not settled yet: no definite answer, and first wanted less than the stale window ago (or never — a key nobody
+     * asked about yet is pending, and starts its window here). A pending room keeps an emptied scope from ending the
+     * session; it never shows the room.
+     */
+    pending(room, userId) {
+        const k = this.key(room, userId), now = this.opts.now();
+        let e = this.entries.get(k);
+        if (!e) {
+            e = { member: null, at: now, asked: Number.NEGATIVE_INFINITY, due: Number.NEGATIVE_INFINITY, failures: 0, reported: false };
+            this.put(k, e);
+        }
+        return e.member === null && now - e.at < this.staleMs;
+    }
+    /**
+     * Read this guest's rooms, one at a time; never rejects. One read per key at a time.
+     * - "scheduled": what is due (never asked; ten minutes after an answer; a failure's backoff).
+     * - "triggered" (a pending guest's request): the same, and never within 30 s of the key's last read, so a guest that
+     *   polls or retries is not platform traffic.
+     * - "force" (its stream connected): a minute after the key's last read — but a failing key keeps its backoff.
+     */
+    async refresh(owner, rooms, opts = {}) {
+        const mode = opts.mode ?? "scheduled";
+        for (const room of rooms) {
+            const k = this.key(room, owner.userId), now = this.opts.now();
+            const e = this.entries.get(k);
+            // A read in flight is never repeated: a scheduled refresh waits for it; the others skip it (asked just now).
+            if (e) {
+                const sinceAsked = now - e.asked;
+                if (mode === "force" ? sinceAsked < GUEST_ROOM_FORCE_FLOOR_MS || (e.failures > 0 && now < e.due)
+                    : now < e.due || (mode === "triggered" && sinceAsked < GUEST_ROOM_TRIGGER_FLOOR_MS))
+                    continue;
+            }
+            await (this.reads.get(k) ?? this.ask(k, room, owner.userId));
+        }
+    }
+    ask(k, room, userId) {
+        const started = this.opts.now();
+        const existing = this.entries.get(k);
+        const recheck = this.opts.recheckMs ?? GUEST_ROOM_RECHECK_MS;
+        const fresh = { member: null, at: started, asked: started, due: started, failures: 0, reported: false };
+        this.put(k, existing ? { ...existing, asked: started } : fresh);
+        const read = this.readBounded(room, userId).then((member) => {
+            const e = this.entries.get(k) ?? fresh;
+            const now = this.opts.now();
+            if (member === undefined) {
+                // A failure leaves the last answer to age (and hide the room when stale), and backs off: 1, 2, 4 … 10 min.
+                const failures = e.failures + 1;
+                const reported = failures >= GUEST_ROOM_PERSISTENT_FAILURES; // an answer resets both
+                this.put(k, { ...e, failures, reported, due: now + Math.min(GUEST_ROOM_RETRY_MAX_MS, GUEST_ROOM_RETRY_MS * 2 ** (failures - 1)) });
+                if (reported && !e.reported)
+                    this.opts.onPersistentFailure?.(room, failures);
+                return;
+            }
+            this.put(k, { member, at: now, asked: e.asked, due: now + recheck, failures: 0, reported: false });
+            if (e.reported)
+                this.opts.onRecovered?.(room);
+        }).finally(() => this.reads.delete(k));
+        this.reads.set(k, read);
+        return read;
+    }
+    readBounded(room, userId) {
+        return new Promise((resolve) => {
+            const timer = setTimeout(() => resolve(undefined), this.opts.deadlineMs ?? READ_DEADLINE_MS);
+            timer.unref?.();
+            let asked;
+            try {
+                asked = this.opts.read(room, userId);
+            }
+            catch {
+                asked = undefined;
+            }
+            if (!asked) {
+                clearTimeout(timer);
+                resolve(undefined);
+                return;
+            }
+            asked.then((m) => { clearTimeout(timer); resolve(m === true ? true : m === false ? false : undefined); }, () => { clearTimeout(timer); resolve(undefined); });
+        });
+    }
+    put(k, e) {
+        this.entries.delete(k); // re-insert: the map's order is its age, for the bound below
+        this.entries.set(k, e);
+        while (this.entries.size > MAX_ENTRIES)
+            this.entries.delete(this.entries.keys().next().value);
+    }
+}
+//# sourceMappingURL=web-guest-rooms.js.map

package/dist/web-guest-rooms.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"web-guest-rooms.js","sourceRoot":"","sources":["../src/web-guest-rooms.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AAQvE,MAAM,CAAC,MAAM,qBAAqB,GAAG,EAAE,GAAG,MAAM,CAAC;AACjD,MAAM,CAAC,MAAM,mBAAmB,GAAG,EAAE,GAAG,MAAM,CAAC;AAC/C,MAAM,CAAC,MAAM,yBAAyB,GAAG,MAAM,CAAC;AAChD,6HAA6H;AAC7H,MAAM,CAAC,MAAM,2BAA2B,GAAG,MAAM,CAAC;AAClD,uHAAuH;AACvH,MAAM,CAAC,MAAM,mBAAmB,GAAG,MAAM,CAAC;AAC1C,MAAM,CAAC,MAAM,uBAAuB,GAAG,EAAE,GAAG,MAAM,CAAC;AACnD,0HAA0H;AAC1H,MAAM,CAAC,MAAM,8BAA8B,GAAG,CAAC,CAAC;AAChD,sEAAsE;AACtE,MAAM,CAAC,MAAM,kBAAkB,GAAG,MAAM,CAAC;AACzC,MAAM,gBAAgB,GAAG,KAAK,CAAC;AAC/B,4GAA4G;AAC5G,MAAM,WAAW,GAAG,IAAI,CAAC;AAEzB;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,KAAgC,EAAE,KAAiB;IACjF,MAAM,GAAG,GAAgB,EAAE,CAAC;IAC5B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,IAAI,CAAC,SAAS,KAAK,KAAK,CAAC,SAAS;YAAE,SAAS;QACjD,MAAM,IAAI,GAAG,uBAAuB,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QACrD,IAAI,IAAI,KAAK,UAAU,IAAI,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC;YAAE,GAAG,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,IAAI,CAAC,YAAY,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;aACnK,IAAI,IAAI,KAAK,SAAS;YAAE,GAAG,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,IAAI,CAAC,YAAY,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACrI,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAmBD,MAAM,OAAO,mBAAmB;IAID;IAHZ,OAAO,GAAG,IAAI,GAAG,EAAiB,CAAC;IACnC,KAAK,GAAG,IAAI,GAAG,EAAyB,CAAC;IAE1D,YAA6B,IAI5B;QAJ4B,SAAI,GAAJ,IAAI,CAIhC;IAAG,CAAC;IAEG,GAAG,CAAC,IAAe,EAAE,MAAc,IAAY,OAAO,GAAG,IAAI,CAAC,SAAS,SAAS,IAAI,CAAC,SAAS,SAAS,MAAM,EAAE,CAAC,CAAC,CAAC;IAC1H,IAAY,OAAO,KAAa,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,IAAI,mBAAmB,CAAC,CAAC,CAAC;IAElF,+DAA+D;IAC/D,QAAQ,CAAC,IAAe,EAAE,MAAc;QACtC,MAAM,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;QACnD,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,KAAK,IAAI,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,EAAE,IAAI,IAAI,CAAC,OAAO,CAAC;IAC5E,CAAC;IAED;;;;OAIG;IACH,OAAO,CAAC,IAAe,EAAE,MAAc;QACrC,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC;QACxD,IAAI,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QAC5B,IAAI,CAAC,CAAC,EAAE,CAAC;YAAC,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM,CAAC,iBAAiB,EAAE,GAAG,EAAE,MAAM,CAAC,iBAAiB,EAAE,QAAQ,EAAE,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;YAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QAAC,CAAC;QACxJ,OAAO,CAAC,CAAC,MAAM,KAAK,IAAI,IAAI,GAAG,GAAG,CAAC,CAAC,EAAE,GAAG,IAAI,CAAC,OAAO,CAAC;IACxD,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,OAAO,CAAC,KAAiB,EAAE,KAA2B,EAAE,OAAqC,EAAE;QACnG,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,IAAI,WAAW,CAAC;QACtC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,EAAE,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC;YAC9D,MAAM,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;YAC9B,6GAA6G;YAC7G,IAAI,CAAC,EAAE,CAAC;gBACN,MAAM,UAAU,GAAG,GAAG,GAAG,CAAC,CAAC,KAAK,CAAC;gBACjC,IAAI,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,UAAU,GAAG,yBAAyB,IAAI,CAAC,CAAC,CAAC,QAAQ,GAAG,CAAC,IAAI,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC;oBAC9F,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,IAAI,KAAK,WAAW,IAAI,UAAU,GAAG,2BAA2B,CAAC;oBAAE,SAAS;YAClG,CAAC;YACD,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC;QAC/D,CAAC;IACH,CAAC;IAEO,GAAG,CAAC,CAAS,EAAE,IAAe,EAAE,MAAc;QACpD,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC;QAChC,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QACrC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,IAAI,qBAAqB,CAAC;QAC7D,MAAM,KAAK,GAAU,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;QAC/G,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAC,EAAE,GAAG,QAAQ,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;QAChE,MAAM,IAAI,GAAG,IAAI,CAAC,WAAW,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE;YAC1D,MAAM,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC;YACvC,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC;YAC5B,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;gBACzB,2GAA2G;gBAC3G,MAAM,QAAQ,GAAG,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC;gBAChC,MAAM,QAAQ,GAAG,QAAQ,IAAI,8BAA8B,CAAC,CAAG,wBAAwB;gBACvF,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,GAAG,CAAC,EAAE,QAAQ,EAAE,QAAQ,EAAE,GAAG,EAAE,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,uBAAuB,EAAE,mBAAmB,GAAG,CAAC,IAAI,CAAC,QAAQ,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;gBACnI,IAAI,QAAQ,IAAI,CAAC,CAAC,CAAC,QAAQ;oBAAE,IAAI,CAAC,IAAI,CAAC,mBAAmB,EAAE,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;gBAC7E,OAAO;YACT,CAAC;YACD,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,GAAG,EAAE,GAAG,GAAG,OAAO,EAAE,QAAQ,EAAE,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,CAAC;YACnG,IAAI,CAAC,CAAC,QAAQ;gBAAE,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,IAAI,CAAC,CAAC;QAChD,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;QACvC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;QACxB,OAAO,IAAI,CAAC;IACd,CAAC;IAEO,WAAW,CAAC,IAAe,EAAE,MAAc;QACjD,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;YAC7B,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,UAAU,IAAI,gBAAgB,CAAC,CAAC;YAC5F,KAAgC,CAAC,KAAK,EAAE,EAAE,CAAC;YAC5C,IAAI,KAAmC,CAAC;YACxC,IAAI,CAAC;gBAAC,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;YAAC,CAAC;YAAC,MAAM,CAAC;gBAAC,KAAK,GAAG,SAAS,CAAC;YAAC,CAAC;YAC1E,IAAI,CAAC,KAAK,EAAE,CAAC;gBAAC,YAAY,CAAC,KAAK,CAAC,CAAC;gBAAC,OAAO,CAAC,SAAS,CAAC,CAAC;gBAAC,OAAO;YAAC,CAAC;YAChE,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,EACtG,GAAG,EAAE,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACxD,CAAC,CAAC,CAAC;IACL,CAAC;IAEO,GAAG,CAAC,CAAS,EAAE,CAAQ;QAC7B,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAG,6DAA6D;QACvF,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QACvB,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,GAAG,WAAW;YAAE,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,KAAe,CAAC,CAAC;IAC1G,CAAC;CACF"}

package/dist/web-identity-color.d.ts

@@ -0,0 +1,87 @@
+import type Database from "better-sqlite3";
+import { type ThemeMode } from "./web-theme.js";
+import { type IdentityColor, type Placement } from "./web-identity-palette.js";
+export { AUTO_PALETTE, autoIdentityColor, canonicalIdentityColor, canonicalPlacements, DEFAULT_PLACEMENTS, IDENTITY_PALETTE, identityColorValue, PLACEMENTS, type AutoId, type IdentityColor, type Placement, type PresetId } from "./web-identity-palette.js";
+/** The sidebar's own background (src/ui/shared/tokens.css --bg-sidebar), where names are drawn as well as the page's. */
+export declare const SIDEBAR_BG: Record<ThemeMode, string>;
+export type IdentityColorSource = "person" | "agent" | "role" | "auto";
+export type PlacementSource = "person" | "agent" | "host";
+/**
+ * The shade of `hex` that name text uses on a page in `mode`: the colour itself if it reads at 4.5:1 against the
+ * page's and the sidebar's backgrounds, else the nearest step toward black (light page) or white (dark page) that does.
+ */
+export declare function readableShade(hex: string, mode: ThemeMode): string;
+/** The tiers one instance has, as the status frame carries them (`auto` always). */
+export interface IdentityColorTiers {
+    person?: IdentityColor;
+    agent?: string;
+    role?: string;
+    auto: IdentityColor;
+}
+/** The placement tiers one instance has (the host's default is the viewer's prefs, not the instance's). */
+export interface PlacementTiers {
+    person?: Placement[];
+    agent?: Placement[];
+}
+/**
+ * The colour in force and where it comes from. `showThemes`: whether the viewer shows agents' themes (fx.show, not
+ * safe mode) — when not, the agent's tier is skipped, as the rest of the agent's theme is.
+ */
+export declare function resolveIdentityColor(t: IdentityColorTiers, opts: {
+    showThemes: boolean;
+}): {
+    color: IdentityColor;
+    source: IdentityColorSource;
+};
+/** Where the colour shows: a person's choice, else the agent's (themes shown), else the host's default, else all three (DEFAULT_PLACEMENTS). */
+export declare function resolvePlacements(t: PlacementTiers, opts: {
+    showThemes: boolean;
+    hostDefault?: unknown;
+}): {
+    show: Placement[];
+    source: PlacementSource;
+};
+/** A person's choice for one instance: a colour, the places it shows, or both (null: not chosen — the next tier). */
+export interface PersonIdentity {
+    color: IdentityColor | null;
+    show: Placement[] | null;
+}
+export type ColorWrite = {
+    ok: true;
+} | {
+    ok: false;
+    status: 400 | 503;
+    error: string;
+    detail?: string;
+};
+/** The people's choices, one row per instance. */
+export declare class IdentityColorStore {
+    private readonly openDb;
+    private readonly now;
+    constructor(openDb: () => Database.Database, now?: () => number);
+    get(name: string): PersonIdentity;
+    /** Every choice, for a status read: only when profiles.db exists and has the table — a read creates nothing. */
+    static all(dataDir: string, openDb: () => Database.Database): Map<string, PersonIdentity>;
+    /**
+     * A person's choice, field by field: only the fields given change; `null` (or "" for the colour) clears one — the next
+     * tier shows again. Both checked before anything is written. A row with nothing left is removed.
+     */
+    set(name: string, patch: {
+        color?: unknown;
+        show?: unknown;
+    }): ColorWrite;
+    /** The patch, checked: `undefined` for a field not given, `null` to clear it. Writes nothing. */
+    check(patch: {
+        color?: unknown;
+        show?: unknown;
+    }): {
+        ok: true;
+        color?: IdentityColor | null;
+        show?: Placement[] | null;
+    } | {
+        ok: false;
+        status: 400;
+        error: string;
+        detail: string;
+    };
+}