@steve31415/baselib 3.46.0 → 3.47.0

package/README.md

@@ -6,7 +6,7 @@ What it provides and why: `docs/SPEC.md`. How it's put together:
 `~/migration/research/base-services-design.md`.
 
 Server subpath exports: `config`, `log`, `auth`, `oauth-resource`, `connector`, `s2s`, `db`, `http`, `sync`,
-`app-update`, `llm`, `email`, and `twitter`. Browser exports: `log-browser`, `rum`,
+`app-update`, `llm`, `email`, `twitter`, and `hub` (the connection hub's server core and app notifier). Browser exports: `log-browser`, `rum`,
 `slow-fetch`, `sync-browser`, and `app-update-browser`.
 
 `sync` provides the Postgres event-log and server protocol primitives;

package/dist/hub/index.d.ts

@@ -0,0 +1,3 @@
+export * from './types.js';
+export * from './server.js';
+export * from './notify.js';

package/dist/hub/index.js

@@ -0,0 +1,3 @@
+export * from './types.js';
+export * from './server.js';
+export * from './notify.js';

package/dist/hub/notify.d.ts

@@ -0,0 +1,52 @@
+import type { Logger } from '../log.js';
+import { serviceFetch } from '../s2s.js';
+import type { Hint } from './types.js';
+export declare const NOTIFY_HUB_TIMEOUT_MS = 1000;
+/** Consecutive failures that open the circuit. */
+export declare const HUB_BREAKER_FAILURES = 3;
+/** How long an open circuit skips the hub before trying again. */
+export declare const HUB_BREAKER_OPEN_MS = 30000;
+export type AppHint = Omit<Hint, 'app'>;
+export interface HubNotifierOptions {
+    /** The hub's canonical URL (also the OIDC audience). */
+    hubUrl: string;
+    /** This app's name; the hub checks it against the caller's service account. */
+    app: string;
+    logger: Logger;
+    timeoutMs?: number;
+    breakerFailures?: number;
+    breakerOpenMs?: number;
+    /** Injectable for tests (default baselib serviceFetch). */
+    fetch?: typeof serviceFetch;
+    now?: () => number;
+}
+export declare class HubNotifier {
+    private readonly url;
+    private readonly audience;
+    private readonly app;
+    private readonly logger;
+    private readonly timeoutMs;
+    private readonly breakerFailures;
+    private readonly breakerOpenMs;
+    private readonly fetch;
+    private readonly now;
+    private consecutiveFailures;
+    private openUntil;
+    private skipped;
+    constructor(opts: HubNotifierOptions);
+    /** Send one hint. Never throws; resolves within the bound. */
+    notify(hint: AppHint): Promise<void>;
+    /** Hints for one request, coalesced: add() as events commit, then await
+     *  flush() once, after the commit, before answering. */
+    batch(): HubNotifyBatch;
+    private send;
+}
+export declare class HubNotifyBatch {
+    private readonly notifier;
+    private readonly hints;
+    constructor(notifier: HubNotifier);
+    add(hint: AppHint): void;
+    /** Send every distinct hint (concurrently, each within the notifier's
+     *  bound) and empty the batch. Never throws. */
+    flush(): Promise<void>;
+}

package/dist/hub/notify.js

@@ -0,0 +1,112 @@
+// The app side of the connection hub (design §5.3, review §14.3 S1/S7):
+// after every commit, whoever made it, the app tells the hub which user's
+// clients should go and ask. Rules: called after commit and awaited inside
+// the request (a throttled instance still has CPU then); one attempt bounded
+// at 1 s including the ID-token mint, no inline retry; a failure is a WARN and
+// never fails the write; after repeated failures the notifier skips the hub
+// for a while (a hub outage must not add 1 s to every write). Fire it on an
+// apply outcome of `duplicate` as well as `applied`: a retried POST whose first
+// attempt secretly succeeded must still hint. Lost hints are tolerated: every
+// client re-checks on its own timer.
+import { serializeError } from '../log.js';
+import { serviceFetch } from '../s2s.js';
+export const NOTIFY_HUB_TIMEOUT_MS = 1_000;
+/** Consecutive failures that open the circuit. */
+export const HUB_BREAKER_FAILURES = 3;
+/** How long an open circuit skips the hub before trying again. */
+export const HUB_BREAKER_OPEN_MS = 30_000;
+export class HubNotifier {
+    url;
+    audience;
+    app;
+    logger;
+    timeoutMs;
+    breakerFailures;
+    breakerOpenMs;
+    fetch;
+    now;
+    consecutiveFailures = 0;
+    openUntil = -Infinity;
+    skipped = 0;
+    constructor(opts) {
+        this.audience = opts.hubUrl.replace(/\/$/, '');
+        this.url = `${this.audience}/api/notify`;
+        this.app = opts.app;
+        this.logger = opts.logger;
+        this.timeoutMs = opts.timeoutMs ?? NOTIFY_HUB_TIMEOUT_MS;
+        this.breakerFailures = opts.breakerFailures ?? HUB_BREAKER_FAILURES;
+        this.breakerOpenMs = opts.breakerOpenMs ?? HUB_BREAKER_OPEN_MS;
+        this.fetch = opts.fetch ?? serviceFetch;
+        this.now = opts.now ?? (() => performance.now());
+    }
+    /** Send one hint. Never throws; resolves within the bound. */
+    async notify(hint) {
+        if (this.now() < this.openUntil) {
+            this.skipped++;
+            return;
+        }
+        const failure = await this.send(hint);
+        if (failure === null) {
+            if (this.consecutiveFailures >= this.breakerFailures) {
+                this.logger.info('hub notify recovered', { skipped: this.skipped });
+            }
+            this.consecutiveFailures = 0;
+            this.skipped = 0;
+            return;
+        }
+        this.consecutiveFailures++;
+        const fields = { kind: hint.kind, consecutiveFailures: this.consecutiveFailures, ...failure.fields };
+        if (failure.bug)
+            this.logger.error('hub notify refused', fields);
+        else
+            this.logger.warn('hub notify failed', fields);
+        if (this.consecutiveFailures >= this.breakerFailures) {
+            this.openUntil = this.now() + this.breakerOpenMs;
+            if (this.consecutiveFailures === this.breakerFailures) {
+                this.logger.warn('hub notify circuit open', { openMs: this.breakerOpenMs });
+            }
+        }
+    }
+    /** Hints for one request, coalesced: add() as events commit, then await
+     *  flush() once, after the commit, before answering. */
+    batch() {
+        return new HubNotifyBatch(this);
+    }
+    async send(hint) {
+        try {
+            const res = await this.fetch(this.url, {
+                audience: this.audience,
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify({ ...hint, app: this.app }),
+                signal: AbortSignal.timeout(this.timeoutMs),
+            });
+            if (res.status === 202)
+                return null;
+            // 400/401/403/413: the hint or the grant is wrong, not the network.
+            return { bug: [400, 401, 403, 413].includes(res.status), fields: { status: res.status } };
+        }
+        catch (error) {
+            return { bug: false, fields: { error: serializeError(error) } };
+        }
+    }
+}
+export class HubNotifyBatch {
+    notifier;
+    hints = new Map();
+    constructor(notifier) {
+        this.notifier = notifier;
+    }
+    add(hint) {
+        const key = JSON.stringify([hint.user, hint.kind, hint.ref ?? null, hint.payload ?? null]);
+        if (!this.hints.has(key))
+            this.hints.set(key, hint);
+    }
+    /** Send every distinct hint (concurrently, each within the notifier's
+     *  bound) and empty the batch. Never throws. */
+    async flush() {
+        const hints = [...this.hints.values()];
+        this.hints.clear();
+        await Promise.all(hints.map((hint) => this.notifier.notify(hint)));
+    }
+}

package/dist/hub/server.d.ts

@@ -0,0 +1,66 @@
+import type { Hono } from 'hono';
+import type { UpgradeWebSocket } from 'hono/ws';
+import type pg from 'pg';
+import { type RequireIdentityOptions } from '../auth.js';
+import { type Logger } from '../log.js';
+import type { Grants } from '../s2s.js';
+import { type DbBroadcastBridgeOptions } from '../sync/db-bridge.js';
+/** The hub database's one table (the hub repo's first migration carries the
+ *  same statements). */
+export declare const HUB_SCHEMA_SQL = "\ncreate table if not exists daemon_tokens (\n  app text not null,\n  daemon_id text not null,\n  token_hash text not null unique,\n  expires_at timestamptz not null,\n  registered_at timestamptz not null default now(),\n  primary key (app, daemon_id)\n);\ncreate index if not exists daemon_tokens_expires_at on daemon_tokens (expires_at);\n";
+export declare const HUB_CHANNEL = "hub_hints";
+/** A registered token's lifetime, on the database clock. */
+export declare const DAEMON_TOKEN_TTL_SECONDS = 3600;
+/** Distinct daemon ids per app with live tokens: a backstop against a daemon
+ *  minting in a loop (each process upserts one row by its daemon id). */
+export declare const DAEMON_IDS_PER_APP_MAX = 20;
+/** The cross-copy publish's own bound; it runs after the 202. */
+export declare const HUB_PUBLISH_TIMEOUT_MS = 2000;
+export declare const DAEMON_WAIT_MAX_SECONDS = 55;
+export declare const DAEMON_LOOKBACK_MAX_MS = 60000;
+/** 401s per client address per minute on the token path before further
+ *  tokens from it are refused without a database lookup. */
+export declare const TOKEN_FAILURES_PER_MIN = 20;
+export interface HubOptions {
+    pool: pg.Pool;
+    logger: Logger;
+    /** The hub's canonical URL, e.g. https://hub.apps.snewman.net: the OIDC
+     *  audience, and its host is the load-balancer host for client addresses. */
+    audience: string;
+    /** The hub's grants: every app's service account on POST /api/notify and
+     *  POST /api/register-daemon; the coding agent is always admitted. */
+    grants: Grants;
+    /** Service accounts are `<app>-svc@<serviceAccountDomain>`; the part
+     *  before `-svc@` names the caller's app (test mode: e.g. 'test'). */
+    serviceAccountDomain: string;
+    /** Pages are `https://<app>.<appDomain>`; a socket for app A is admitted
+     *  only from that origin. */
+    appDomain: string;
+    /** Also admit `http://localhost:<port>` and `http://127.0.0.1:<port>`
+     *  origins (local development and Playwright). */
+    allowLocalOrigins?: boolean;
+    upgradeWebSocket: UpgradeWebSocket;
+    /** Passed through to requireIdentity (authUrl, whoamiFetch, verifyClient,
+     *  rateLimitPerMin…). The hub admits invited users for sockets. */
+    identity?: Partial<Omit<RequireIdentityOptions, 'audience' | 'grants' | 'logger' | 'userAccess'>>;
+    /** Injectable for tests. */
+    bridge?: Partial<Pick<DbBroadcastBridgeOptions, 'heartbeatMs' | 'heartbeatTimeoutMs' | 'reconnectDelaysMs'>>;
+    /** Monotonic milliseconds (tests). */
+    now?: () => number;
+}
+export interface Hub {
+    /** Start the cross-copy bridge. Call before the server accepts
+     *  connections; never rejects (a failed first connect enters the bridge's
+     *  reconnect ladder). */
+    start(): Promise<void>;
+    /** SIGTERM: stop admitting, close browser sockets with 1012, answer every
+     *  parked wait 204, wait (bounded) for in-flight publishes, stop the
+     *  bridge. The caller then ends the pool and flushes the logger. */
+    stop(): Promise<void>;
+    /** Local counts, for logs and tests. */
+    stats(): {
+        sockets: number;
+        waits: number;
+    };
+}
+export declare function createHub(app: Hono, opts: HubOptions): Hub;

package/dist/hub/server.js

@@ -0,0 +1,490 @@
+// The connection hub's server core (design: ~/migration/research/
+// connection-hub-design-2026-10-30.md §5, as refined by §14 and its review
+// dispositions §14.3, which bind). The `hub` repo is a thin wrapper: it builds
+// the pool, logger and WebSocket upgrader, mounts this, and starts the server.
+//
+// One always-on service holds the fleet's long-lived connections so the apps
+// need not: browser pages park a socket here and daemons park their idle
+// waits here; apps POST a hint after every commit and the hub fans it out.
+// Hints are information only ("go ask the app"): the hub stores none, a hint
+// with no listener is gone, and every client re-checks on its own timer.
+//
+// Copies. Any number of hub copies may run (two is normal). Each delivers a
+// hint to its own sockets and waits, then publishes it on the hub database's
+// `hub_hints` channel tagged with its bridge's origin; the other copies relay
+// it to theirs and skip their own. State per copy is memory only and
+// rebuildable from nothing, apart from the daemon-token table (§14.1), which
+// both copies read.
+//
+// Routes:
+//   POST /api/notify            app → hub, OIDC; the hint's app must be the
+//                               caller's own (from its service account)
+//   POST /api/register-daemon   app → hub, OIDC; registers a daemon hub token
+//   GET  /api/daemon/wait       daemon, X-Hub-Token (or a granted service
+//                               caller, for the dark-run curl); answers on a
+//                               `work` hint, else 204 after `wait` seconds
+//   GET  /api/ws?app=<app>      browser WebSocket, fleet cookie, Origin
+//                               must be that app's page
+import { createHash } from 'node:crypto';
+import { createMiddleware } from 'hono/factory';
+import { requireIdentity } from '../auth.js';
+import { forwardedClientIp } from '../http.js';
+import { serializeError } from '../log.js';
+import { DbBroadcastBridge } from '../sync/db-bridge.js';
+import { checkHint, isAppName } from './types.js';
+/** The hub database's one table (the hub repo's first migration carries the
+ *  same statements). */
+export const HUB_SCHEMA_SQL = `
+create table if not exists daemon_tokens (
+  app text not null,
+  daemon_id text not null,
+  token_hash text not null unique,
+  expires_at timestamptz not null,
+  registered_at timestamptz not null default now(),
+  primary key (app, daemon_id)
+);
+create index if not exists daemon_tokens_expires_at on daemon_tokens (expires_at);
+`;
+export const HUB_CHANNEL = 'hub_hints';
+/** A registered token's lifetime, on the database clock. */
+export const DAEMON_TOKEN_TTL_SECONDS = 3600;
+/** Distinct daemon ids per app with live tokens: a backstop against a daemon
+ *  minting in a loop (each process upserts one row by its daemon id). */
+export const DAEMON_IDS_PER_APP_MAX = 20;
+/** The cross-copy publish's own bound; it runs after the 202. */
+export const HUB_PUBLISH_TIMEOUT_MS = 2_000;
+export const DAEMON_WAIT_MAX_SECONDS = 55;
+export const DAEMON_LOOKBACK_MAX_MS = 60_000;
+/** 401s per client address per minute on the token path before further
+ *  tokens from it are refused without a database lookup. */
+export const TOKEN_FAILURES_PER_MIN = 20;
+const TOKEN_FORMAT = /^hubt_[A-Za-z0-9_-]{43}$/;
+const TOKEN_HASH_FORMAT = /^[0-9a-f]{64}$/;
+const DAEMON_ID_FORMAT = /^[A-Za-z0-9_-]{8,64}$/;
+export function createHub(app, opts) {
+    const { pool, logger } = opts;
+    const now = opts.now ?? (() => performance.now());
+    const canonicalHost = new URL(opts.audience).host;
+    const identity = requireIdentity({
+        rateLimitPerMin: 6_000,
+        ...opts.identity,
+        audience: opts.audience,
+        grants: opts.grants,
+        logger,
+        userAccess: 'invited',
+    });
+    const serviceAccount = new RegExp(`^([a-z][a-z0-9-]*)-svc@${escapeRegExp(opts.serviceAccountDomain)}$`);
+    // app → user → sockets
+    const sockets = new Map();
+    const waits = new Map();
+    // app → when this copy last saw a `work` hint for it (local or relayed)
+    const lastWork = new Map();
+    // when the bridge last recovered: hints sent while it was deaf are unknowable
+    let lastBlanketAt = -Infinity;
+    const publishes = new Set();
+    const tokenFailures = new FailureCounter(TOKEN_FAILURES_PER_MIN);
+    let stopping = false;
+    const bridge = new DbBroadcastBridge({
+        pool,
+        channel: HUB_CHANNEL,
+        logger,
+        ignoreOwn: true,
+        ...opts.bridge,
+        onMessage: (message) => {
+            const check = checkHint(message?.hint);
+            if (!check.ok) {
+                logger.warn('hub relayed hint invalid', { error: check.error });
+                return;
+            }
+            deliverLocal(check.hint);
+        },
+        onRecovered: () => blanket(),
+    });
+    function deliverLocal(hint) {
+        if (hint.kind === 'work') {
+            // Work hints go to daemon waits only, never to a browser socket
+            // whatever its app (review B1).
+            lastWork.set(hint.app, { at: now(), ...(hint.ref !== undefined ? { ref: hint.ref } : {}) });
+            for (const waiter of [...(waits.get(hint.app) ?? [])])
+                waiter.finish(workResponse(hint.ref));
+            return;
+        }
+        const users = sockets.get(hint.app);
+        if (!users)
+            return;
+        const targets = hint.user === '*' ? [...users.values()].flatMap((set) => [...set]) : [...(users.get(hint.user) ?? [])];
+        if (targets.length === 0)
+            return;
+        const frame = JSON.stringify({ type: 'hint', ...hint });
+        for (const socket of targets)
+            send(socket, frame);
+    }
+    function send(socket, frame) {
+        try {
+            socket.ws.send(frame);
+        }
+        catch (error) {
+            logger.warn('hub socket send failed', { app: socket.app, error: serializeError(error) });
+        }
+    }
+    function blanket() {
+        lastBlanketAt = now();
+        for (const [appName, users] of sockets) {
+            for (const [user, set] of users) {
+                const frame = JSON.stringify({ type: 'hint', app: appName, user, kind: 'sync_available' });
+                for (const socket of set)
+                    send(socket, frame);
+            }
+        }
+        for (const set of waits.values())
+            for (const waiter of [...set])
+                waiter.finish(workResponse());
+    }
+    function publish(hint) {
+        const p = withinMs(bridge.notify({ hint }), HUB_PUBLISH_TIMEOUT_MS, 'hub publish')
+            .catch((error) => {
+            logger.warn('hub publish failed', { app: hint.app, kind: hint.kind, error: serializeError(error) });
+        })
+            .finally(() => publishes.delete(p));
+        publishes.add(p);
+    }
+    /** requireIdentity without letting it end the chain: whether it admitted
+     *  the request (identity set), else the response it chose. */
+    async function runIdentity(c) {
+        let admitted = false;
+        const response = await identity(c, async () => {
+            admitted = true;
+        });
+        return { admitted, response: response ?? undefined };
+    }
+    /** The caller's app, from its service account; null for any other caller
+     *  (the coding agent, a browser). */
+    function callerApp(c) {
+        const id = c.var.identity;
+        if (id?.type !== 's2s')
+            return null;
+        return serviceAccount.exec(id.email)?.[1] ?? null;
+    }
+    // ---- app → hub ----
+    app.post('/api/notify', identity, async (c) => {
+        const caller = callerApp(c);
+        if (!caller)
+            return c.json({ error: 'app service accounts only' }, 403);
+        const check = checkHint(await c.req.json().catch(() => null));
+        if (!check.ok)
+            return c.json({ error: check.error }, check.status);
+        if (check.hint.app !== caller) {
+            logger.warn('hub notify for another app refused', { caller, app: check.hint.app });
+            return c.json({ error: 'an app may hint only its own clients' }, 403);
+        }
+        deliverLocal(check.hint);
+        // After local delivery and off the response path, with its own bound, so
+        // a slow hub pool never trips the apps' 1 s notify bound (review S1).
+        publish(check.hint);
+        return c.body(null, 202);
+    });
+    app.post('/api/register-daemon', identity, async (c) => {
+        const caller = callerApp(c);
+        if (!caller)
+            return c.json({ error: 'app service accounts only' }, 403);
+        const body = (await c.req.json().catch(() => null));
+        const tokenHash = body?.tokenHash;
+        const daemonId = body?.daemonId;
+        if (typeof tokenHash !== 'string' || !TOKEN_HASH_FORMAT.test(tokenHash))
+            return c.json({ error: 'invalid tokenHash' }, 400);
+        if (typeof daemonId !== 'string' || !DAEMON_ID_FORMAT.test(daemonId))
+            return c.json({ error: 'invalid daemonId' }, 400);
+        const client = await pool.connect();
+        let ok = false;
+        try {
+            await client.query('begin');
+            // Serializes this app's registrations, so the cap is exact.
+            await client.query(`select pg_advisory_xact_lock(hashtext('hub_register:' || $1))`, [caller]);
+            const { rows } = await client.query(`select count(*)::int as n from daemon_tokens where app = $1 and daemon_id <> $2 and expires_at > now()`, [caller, daemonId]);
+            if (rows[0].n >= DAEMON_IDS_PER_APP_MAX) {
+                await client.query('rollback');
+                ok = true;
+                logger.error('hub daemon registration cap reached', { app: caller, daemons: rows[0].n });
+                return c.json({ error: 'too many daemons registered for this app' }, 429);
+            }
+            // Upsert by daemon id: a retry or an orphaned register overwrites the
+            // process's one row, and its previous token dies at once (review S3).
+            await client.query(`insert into daemon_tokens (app, daemon_id, token_hash, expires_at)
+         values ($1, $2, $3, now() + make_interval(secs => $4))
+         on conflict (app, daemon_id) do update
+           set token_hash = excluded.token_hash, expires_at = excluded.expires_at, registered_at = now()`, [caller, daemonId, tokenHash, DAEMON_TOKEN_TTL_SECONDS]);
+            await client.query(`delete from daemon_tokens where expires_at < now() - interval '1 day'`);
+            await client.query('commit');
+            ok = true;
+        }
+        finally {
+            if (!ok)
+                await client.query('rollback').catch(() => { });
+            client.release(ok ? undefined : true);
+        }
+        return c.json({ ttlSeconds: DAEMON_TOKEN_TTL_SECONDS });
+    });
+    // ---- daemon waits ----
+    /** Resolves the waiting app: from a daemon hub token, or (no token) from
+     *  `?app=` for a granted service caller. Cookies are refused (review B1). */
+    const daemonAuth = createMiddleware(async (c, next) => {
+        const token = c.req.header('x-hub-token');
+        if (token === undefined) {
+            const { admitted, response } = await runIdentity(c);
+            if (!admitted)
+                return response;
+            if (c.var.identity?.type !== 's2s')
+                return c.json({ error: 'service callers only' }, 403);
+            const named = c.req.query('app');
+            if (!isAppName(named))
+                return c.json({ error: 'app required' }, 400);
+            c.set('hubApp', named);
+            await next();
+            return;
+        }
+        if (c.req.header('authorization') !== undefined) {
+            // A daemon's hub client never sends Authorization; both together means
+            // an app credential is travelling to the hub (review S4).
+            logger.error('hub daemon wait with both X-Hub-Token and Authorization', {});
+            return c.json({ error: 'send X-Hub-Token or Authorization, not both' }, 400);
+        }
+        const ip = forwardedClientIp(c, canonicalHost);
+        if (tokenFailures.blocked(ip, now()))
+            return c.json({ error: 'too many invalid tokens' }, 429);
+        if (!TOKEN_FORMAT.test(token)) {
+            tokenFailures.fail(ip, now());
+            return c.json({ error: 'invalid token' }, 401);
+        }
+        let found;
+        try {
+            const { rows } = await pool.query(`select app from daemon_tokens where token_hash = $1 and expires_at > now()`, [createHash('sha256').update(token).digest('hex')]);
+            found = rows[0]?.app;
+        }
+        catch (error) {
+            // 503, not 401: a hub database outage must not make every daemon
+            // re-mint; the daemon treats 503 as a hub failure.
+            logger.warn('hub token lookup failed', { error: serializeError(error) });
+            return c.json({ error: 'token lookup unavailable' }, 503);
+        }
+        if (!found) {
+            tokenFailures.fail(ip, now());
+            return c.json({ error: 'invalid or expired token' }, 401);
+        }
+        c.set('hubApp', found);
+        await next();
+    });
+    app.get('/api/daemon/wait', daemonAuth, (c) => {
+        const appName = c.var.hubApp;
+        const waitSeconds = intParam(c.req.query('wait'), 0, DAEMON_WAIT_MAX_SECONDS, 50);
+        const lookbackMs = intParam(c.req.query('lookbackMs'), 0, DAEMON_LOOKBACK_MAX_MS, 0);
+        if (stopping)
+            return c.body(null, 204);
+        // A work hint between the daemon's direct request and this wait being
+        // parked would otherwise be lost to the 30 s timer (review S2).
+        const t = now();
+        const last = lastWork.get(appName);
+        if (lookbackMs > 0 && last && t - last.at <= lookbackMs)
+            return workResponse(last.ref);
+        if (lookbackMs > 0 && t - lastBlanketAt <= lookbackMs)
+            return workResponse();
+        return new Promise((resolve) => {
+            let set = waits.get(appName);
+            if (!set)
+                waits.set(appName, (set = new Set()));
+            const waiters = set;
+            const signal = c.req.raw.signal;
+            const waiter = {
+                app: appName,
+                finish: (response) => {
+                    if (!waiters.delete(waiter))
+                        return;
+                    if (waiters.size === 0 && waits.get(appName) === waiters)
+                        waits.delete(appName);
+                    clearTimeout(timer);
+                    signal.removeEventListener('abort', onAbort);
+                    resolve(response);
+                },
+            };
+            const onAbort = () => waiter.finish(new Response(null, { status: 204 }));
+            const timer = setTimeout(() => waiter.finish(new Response(null, { status: 204 })), waitSeconds * 1000);
+            waiters.add(waiter);
+            if (signal.aborted)
+                onAbort();
+            else
+                signal.addEventListener('abort', onAbort, { once: true });
+        });
+    });
+    // ---- browser sockets ----
+    // requireIdentity's refusal (401/403/503), kept so the socket can open and
+    // close with a code the client understands rather than fail its handshake.
+    const refusals = new WeakMap();
+    const originCheck = createMiddleware(async (c, next) => {
+        const appName = c.req.query('app');
+        if (!isAppName(appName))
+            return c.json({ error: 'app required' }, 400);
+        if (!originAllowed(c.req.header('origin'), appName, opts)) {
+            logger.warn('hub socket origin refused', { app: appName, origin: c.req.header('origin') ?? null });
+            return c.json({ error: 'origin not allowed' }, 403);
+        }
+        await next();
+    });
+    const socketIdentity = createMiddleware(async (c, next) => {
+        const { admitted, response } = await runIdentity(c);
+        if (!admitted)
+            refusals.set(c, response?.status ?? 401);
+        await next();
+    });
+    app.get('/api/ws', originCheck, socketIdentity, opts.upgradeWebSocket((c) => {
+        const appName = c.req.query('app');
+        const refusal = refusals.get(c);
+        const id = c.var.identity;
+        const user = refusal === undefined && id?.type === 'user' ? id.email : null;
+        let socket = null;
+        const remove = () => {
+            if (!socket)
+                return;
+            const users = sockets.get(socket.app);
+            const set = users?.get(socket.user);
+            set?.delete(socket);
+            if (set?.size === 0)
+                users.delete(socket.user);
+            if (users?.size === 0)
+                sockets.delete(socket.app);
+            socket = null;
+        };
+        return {
+            onOpen: (_evt, ws) => {
+                if (stopping) {
+                    ws.close(1012, 'hub restarting');
+                    return;
+                }
+                if (!user) {
+                    // 4403: identity missing or expired (the client re-checks its
+                    // session); 1013: the auth service is unavailable, try again.
+                    if (refusal === 503)
+                        ws.close(1013, 'auth unavailable');
+                    else
+                        ws.close(4403, 'user identity required');
+                    return;
+                }
+                socket = { ws, app: appName, user };
+                let users = sockets.get(appName);
+                if (!users)
+                    sockets.set(appName, (users = new Map()));
+                let set = users.get(user);
+                if (!set)
+                    users.set(user, (set = new Set()));
+                set.add(socket);
+            },
+            onMessage: (evt, ws) => {
+                if (!socket)
+                    return;
+                let message;
+                try {
+                    message = JSON.parse(String(evt.data));
+                }
+                catch {
+                    return;
+                }
+                // Unknown frames and fields are ignored on both sides: hub
+                // versions overlap during a hub deploy.
+                if (message?.type === 'ping')
+                    ws.send(JSON.stringify({ type: 'pong' }));
+                else if (message?.type === 'connect')
+                    ws.send(JSON.stringify({ type: 'ack' }));
+            },
+            onClose: remove,
+            onError: remove,
+        };
+    }));
+    return {
+        start: () => bridge.start(),
+        async stop() {
+            stopping = true;
+            for (const users of sockets.values()) {
+                for (const set of users.values()) {
+                    for (const socket of set) {
+                        try {
+                            socket.ws.close(1012, 'hub restarting');
+                        }
+                        catch {
+                            // already closing
+                        }
+                    }
+                }
+            }
+            sockets.clear();
+            for (const set of waits.values())
+                for (const waiter of [...set])
+                    waiter.finish(new Response(null, { status: 204 }));
+            await Promise.allSettled([...publishes]);
+            await bridge.stop();
+        },
+        stats() {
+            let socketCount = 0;
+            for (const users of sockets.values())
+                for (const set of users.values())
+                    socketCount += set.size;
+            let waitCount = 0;
+            for (const set of waits.values())
+                waitCount += set.size;
+            return { sockets: socketCount, waits: waitCount };
+        },
+    };
+}
+function workResponse(ref) {
+    return Response.json({ kind: 'work', ...(ref !== undefined ? { ref } : {}) });
+}
+function originAllowed(origin, appName, opts) {
+    if (!origin)
+        return false;
+    if (origin === `https://${appName}.${opts.appDomain}`)
+        return true;
+    return opts.allowLocalOrigins === true && /^http:\/\/(localhost|127\.0\.0\.1)(:\d+)?$/.test(origin);
+}
+function intParam(value, min, max, fallback) {
+    if (value === undefined || !/^\d+$/.test(value))
+        return fallback;
+    return Math.min(max, Math.max(min, Number(value)));
+}
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/** `promise`, or a rejection once `ms` pass; the work itself continues. */
+function withinMs(promise, ms, what) {
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error(`${what} timed out after ${ms} ms`)), ms);
+    });
+    return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
+}
+/** Failed token attempts per client address in a fixed one-minute window.
+ *  Keys are chosen by unauthenticated callers, so the map is bounded. */
+class FailureCounter {
+    perMinute;
+    windows = new Map();
+    constructor(perMinute) {
+        this.perMinute = perMinute;
+    }
+    blocked(key, t) {
+        const w = this.windows.get(key);
+        return w !== undefined && t - w.start < 60_000 && w.count >= this.perMinute;
+    }
+    fail(key, t) {
+        const w = this.windows.get(key);
+        if (w && t - w.start < 60_000) {
+            w.count++;
+            return;
+        }
+        this.windows.delete(key);
+        if (this.windows.size >= 10_000) {
+            for (const [k, old] of this.windows) {
+                if (t - old.start >= 60_000 || this.windows.size >= 10_000)
+                    this.windows.delete(k);
+                else
+                    break;
+            }
+        }
+        this.windows.set(key, { start: t, count: 1 });
+    }
+}

package/dist/hub/types.d.ts

@@ -0,0 +1,25 @@
+export type HintKind = 'sync_available' | 'build_changed' | 'notification' | 'work';
+export interface Hint {
+    app: string;
+    /** A user's email, or '*' (every user of the app: build_changed, work). */
+    user: string;
+    kind: HintKind;
+    ref?: string;
+    payload?: Record<string, unknown>;
+}
+export declare const HINT_KINDS: readonly HintKind[];
+/** The largest `payload`, serialized. NOTIFY allows 8000 bytes. */
+export declare const HINT_PAYLOAD_MAX_BYTES = 1024;
+export declare const HINT_REF_MAX_LENGTH = 200;
+export declare function isAppName(value: unknown): value is string;
+export type HintCheck = {
+    ok: true;
+    hint: Hint;
+} | {
+    ok: false;
+    status: 400 | 413;
+    error: string;
+};
+/** Validate an untrusted hint. `build_changed` and `work` go to every user
+ *  ('*'); `sync_available` and `notification` name one. */
+export declare function checkHint(value: unknown): HintCheck;

package/dist/hub/types.js

@@ -0,0 +1,47 @@
+// The connection hub's one message shape (design: ~/migration/research/
+// connection-hub-design-2026-10-30.md §5.2). A hint means only "go ask the
+// app": it carries ids and kinds, never content, and duplicates, reordering
+// and drops are all harmless because every client re-checks on a timer.
+export const HINT_KINDS = ['sync_available', 'build_changed', 'notification', 'work'];
+/** The largest `payload`, serialized. NOTIFY allows 8000 bytes. */
+export const HINT_PAYLOAD_MAX_BYTES = 1024;
+export const HINT_REF_MAX_LENGTH = 200;
+const APP_NAME = /^[a-z][a-z0-9-]{0,39}$/;
+export function isAppName(value) {
+    return typeof value === 'string' && APP_NAME.test(value);
+}
+/** Validate an untrusted hint. `build_changed` and `work` go to every user
+ *  ('*'); `sync_available` and `notification` name one. */
+export function checkHint(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return bad('hint must be an object');
+    const v = value;
+    if (!isAppName(v.app))
+        return bad('invalid app');
+    if (typeof v.kind !== 'string' || !HINT_KINDS.includes(v.kind))
+        return bad('invalid kind');
+    const kind = v.kind;
+    if (typeof v.user !== 'string' || v.user.length === 0 || v.user.length > 320)
+        return bad('invalid user');
+    const broadcast = kind === 'build_changed' || kind === 'work';
+    if (broadcast !== (v.user === '*'))
+        return bad(`${kind} takes ${broadcast ? "user '*'" : 'one user'}`);
+    if (v.ref !== undefined && (typeof v.ref !== 'string' || v.ref.length > HINT_REF_MAX_LENGTH))
+        return bad('invalid ref');
+    if (v.payload !== undefined) {
+        if (v.payload === null || typeof v.payload !== 'object' || Array.isArray(v.payload))
+            return bad('invalid payload');
+        if (Buffer.byteLength(JSON.stringify(v.payload)) > HINT_PAYLOAD_MAX_BYTES) {
+            return { ok: false, status: 413, error: `payload over ${HINT_PAYLOAD_MAX_BYTES} bytes` };
+        }
+    }
+    const hint = { app: v.app, user: v.user, kind };
+    if (v.ref !== undefined)
+        hint.ref = v.ref;
+    if (v.payload !== undefined)
+        hint.payload = v.payload;
+    return { ok: true, hint };
+}
+function bad(error) {
+    return { ok: false, status: 400, error };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@steve31415/baselib",
-  "version": "3.46.0",
+  "version": "3.47.0",
   "description": "Plasticine new-world shared platform library: logging, auth, service-to-service auth, db, HTTP, sync, app updates",
   "type": "module",
   "license": "MIT",
@@ -65,6 +65,10 @@
       "types": "./dist/sync-browser/index.d.ts",
       "default": "./dist/sync-browser/index.js"
     },
+    "./hub": {
+      "types": "./dist/hub/index.d.ts",
+      "default": "./dist/hub/index.js"
+    },
     "./app-update": {
       "types": "./dist/app-update/index.d.ts",
       "default": "./dist/app-update/index.js"
@@ -116,6 +120,7 @@
     "zod": "^4.6.5"
   },
   "devDependencies": {
+    "@hono/node-ws": "^1.3.1",
     "@types/node": "^22.0.0",
     "@types/pg": "^8.11.0",
     "fake-indexeddb": "^6.2.5",