@steve31415/baselib 3.57.0 → 3.58.1

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`, `twitter`, `hub` (the connection hub's server core and app notifier), `code-manifest` and
+`app-update`, `llm`, `email`, `twitter`, `hub` (the connection hub's server core, app notifier and daemon-token mint; `hub/testing` a local hub for tests), `hub-daemon` (the daemons' hub client), `code-manifest` and
 `client-version`. Browser exports: `log-browser`, `rum`, `slow-fetch`, `sync-browser`, `app-update-browser`, and
 `extension-self-update`.
 

package/dist/bin/test-hub.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/test-hub.js

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+// `baselib-test-hub` — a local connection hub for an app's Playwright boot
+// (hub design §8 step 0): `AUTH_MODE=test TEST_USER=<email> baselib-test-hub
+// --database-url <url> --apps radar[,todo] [--port N]`. Prints
+// "test hub listening on <url>" once it accepts connections, and stops on
+// SIGTERM or SIGINT. The app under test then runs with HUB_URL=<url> and
+// TEST_S2S_IDENTITY=<app>-svc@test. All logic lives in ../hub/testing.ts.
+import { parseArgs } from 'node:util';
+import { startTestHub } from '../hub/testing.js';
+const { values } = parseArgs({
+    options: {
+        'database-url': { type: 'string' },
+        apps: { type: 'string' },
+        port: { type: 'string' },
+        host: { type: 'string' },
+    },
+});
+const databaseUrl = values['database-url'] ?? process.env.DATABASE_URL;
+const apps = (values.apps ?? '').split(',').map((a) => a.trim()).filter(Boolean);
+if (!databaseUrl || apps.length === 0) {
+    process.stderr.write('usage: baselib-test-hub --database-url <url> --apps <app>[,<app>] [--port N] [--host H]\n');
+    process.exit(2);
+}
+const hub = await startTestHub({
+    databaseUrl,
+    apps,
+    port: values.port ? Number(values.port) : undefined,
+    host: values.host,
+});
+process.stdout.write(`test hub listening on ${hub.url}\n`);
+const stop = () => void hub.stop().finally(() => process.exit(0));
+process.once('SIGTERM', stop);
+process.once('SIGINT', stop);

package/dist/hub/index.d.ts

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

package/dist/hub/index.js

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

package/dist/hub/mint.d.ts

@@ -0,0 +1,26 @@
+import { serviceFetch } from '../s2s.js';
+/** The register call's bound (design §14.1: 5 s abort, mint included). */
+export declare const HUB_REGISTER_TIMEOUT_MS = 5000;
+export declare function isDaemonId(value: unknown): value is string;
+/** The hub was unreachable or refused: the mint route answers 503 and the
+ *  daemon treats the hub as unavailable. `status` is the hub's, if any. */
+export declare class HubRegisterError extends Error {
+    readonly status?: number | undefined;
+    constructor(message: string, status?: number | undefined);
+}
+export interface MintDaemonHubTokenOptions {
+    /** The hub's canonical URL (also the OIDC audience). */
+    hubUrl: string;
+    /** The daemon's stable id, from its mint request. */
+    daemonId: string;
+    timeoutMs?: number;
+    /** Injectable for tests (default baselib serviceFetch). */
+    fetch?: typeof serviceFetch;
+}
+/** Make and register one daemon hub token. Throws HubRegisterError when the
+ *  hub does not accept it (the caller answers 503), TypeError for a bad
+ *  daemon id (the caller answers 400). */
+export declare function mintDaemonHubToken(opts: MintDaemonHubTokenOptions): Promise<{
+    token: string;
+    ttlSeconds: number;
+}>;

package/dist/hub/mint.js

@@ -0,0 +1,53 @@
+// The app side of a daemon hub token (design §14.1 as amended by §14.3 S3 and
+// §14.4): the app's mint route, reached by its daemon with the daemon's own
+// bearer, makes a random token, registers only its hash at the hub over s2s
+// (the hub binds the registration to the calling app's service account), and
+// hands the token to the daemon. The app never stores the token. The token
+// authorizes nothing but parking on that app's `work` hints at the hub.
+import { createHash, randomBytes } from 'node:crypto';
+import { serviceFetch } from '../s2s.js';
+/** The register call's bound (design §14.1: 5 s abort, mint included). */
+export const HUB_REGISTER_TIMEOUT_MS = 5_000;
+/** What the hub accepts as a daemon id (stable per host and app, §14.4). */
+const DAEMON_ID_FORMAT = /^[A-Za-z0-9_-]{8,64}$/;
+export function isDaemonId(value) {
+    return typeof value === 'string' && DAEMON_ID_FORMAT.test(value);
+}
+/** The hub was unreachable or refused: the mint route answers 503 and the
+ *  daemon treats the hub as unavailable. `status` is the hub's, if any. */
+export class HubRegisterError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+        this.name = 'HubRegisterError';
+    }
+}
+/** Make and register one daemon hub token. Throws HubRegisterError when the
+ *  hub does not accept it (the caller answers 503), TypeError for a bad
+ *  daemon id (the caller answers 400). */
+export async function mintDaemonHubToken(opts) {
+    if (!isDaemonId(opts.daemonId))
+        throw new TypeError('daemonId must be 8-64 characters of [A-Za-z0-9_-]');
+    const audience = opts.hubUrl.replace(/\/$/, '');
+    const token = `hubt_${randomBytes(32).toString('base64url')}`;
+    const tokenHash = createHash('sha256').update(token).digest('hex');
+    let res;
+    try {
+        res = await (opts.fetch ?? serviceFetch)(`${audience}/api/register-daemon`, {
+            audience,
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ tokenHash, daemonId: opts.daemonId }),
+            signal: AbortSignal.timeout(opts.timeoutMs ?? HUB_REGISTER_TIMEOUT_MS),
+        });
+    }
+    catch (error) {
+        throw new HubRegisterError(`hub register failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const body = (await res.json().catch(() => null));
+    if (res.status !== 200 && res.status !== 201)
+        throw new HubRegisterError(`hub register answered ${res.status}`, res.status);
+    const ttlSeconds = typeof body?.ttlSeconds === 'number' && body.ttlSeconds > 0 ? body.ttlSeconds : 3600;
+    return { token, ttlSeconds };
+}

package/dist/hub/server.js

@@ -33,6 +33,7 @@ import { forwardedClientIp } from '../http.js';
 import { serializeError } from '../log.js';
 import { capSocketAge } from '../socket-age.js';
 import { DbBroadcastBridge } from '../sync/db-bridge.js';
+import { isDaemonId } from './mint.js';
 import { checkHint, isAppName } from './types.js';
 /** The hub database's one table (the hub repo's first migration carries the
  *  same statements). */
@@ -73,7 +74,6 @@ const HUB_SOCKET_SWEEP_MS = 30_000;
 const TOKEN_FORMAT = /^hubt_[A-Za-z0-9_-]{43}$/;
 const WEBSOCKET_KEY = /^[+/0-9A-Za-z]{22}==$/;
 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());
@@ -220,7 +220,7 @@ export function createHub(app, opts) {
         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))
+        if (!isDaemonId(daemonId))
             return c.json({ error: 'invalid daemonId' }, 400);
         const client = await pool.connect();
         let ok = false;

package/dist/hub/testing.d.ts

@@ -0,0 +1,24 @@
+import { type Logger } from '../log.js';
+import { type Hub, type HubOptions } from './server.js';
+/** The service-account domain of test identities: `<app>-svc@test`. */
+export declare const TEST_HUB_SA_DOMAIN = "test";
+export interface TestHubOptions {
+    /** A Postgres database for the token table and the cross-copy channel
+     *  (an app's own test database is fine: one table, `daemon_tokens`). */
+    databaseUrl: string;
+    /** Apps whose `<app>-svc@test` identity may notify and register. */
+    apps: string[];
+    port?: number;
+    host?: string;
+    logger?: Logger;
+    /** Passed through (tests: short socket idle or age limits). */
+    hub?: Pick<HubOptions, 'socketIdle' | 'socketAge' | 'bridge' | 'now'>;
+}
+export interface TestHub {
+    /** http://<host>:<port>, no trailing slash: the app's HUB_URL. */
+    url: string;
+    hub: Hub;
+    stop(): Promise<void>;
+}
+export declare function testHubIdentity(app: string): string;
+export declare function startTestHub(opts: TestHubOptions): Promise<TestHub>;

package/dist/hub/testing.js

@@ -0,0 +1,71 @@
+// A real hub for tests (design §8 step 0, review F-S5 and §14.3's per-app
+// test identities): createHub on a database the caller owns, in test auth
+// mode, so a converted app's vitest and Playwright runs exercise the
+// production hub mode rather than a fake. Refuses to start outside
+// AUTH_MODE=test.
+//
+// Identities in test mode: an app process calls the hub with serviceFetch,
+// which sends X-Test-S2S-Caller from TEST_S2S_IDENTITY, so an app under test
+// sets TEST_S2S_IDENTITY=<app>-svc@test and the hub derives its app from
+// that. Browser sockets are the hub process's TEST_USER (or an X-Test-User
+// header), from any http://localhost or http://127.0.0.1 origin.
+import { once } from 'node:events';
+import { serve } from '@hono/node-server';
+import { createNodeWebSocket } from '@hono/node-ws';
+import { Hono } from 'hono';
+import pg from 'pg';
+import { endPool, FLEET_POOL_DEFAULTS } from '../db.js';
+import { createLogger } from '../log.js';
+import { createHub, HUB_SCHEMA_SQL } from './server.js';
+/** The service-account domain of test identities: `<app>-svc@test`. */
+export const TEST_HUB_SA_DOMAIN = 'test';
+export function testHubIdentity(app) {
+    return `${app}-svc@${TEST_HUB_SA_DOMAIN}`;
+}
+export async function startTestHub(opts) {
+    if (process.env.AUTH_MODE !== 'test')
+        throw new Error('startTestHub runs only with AUTH_MODE=test');
+    const pool = new pg.Pool({ connectionString: opts.databaseUrl, ...FLEET_POOL_DEFAULTS, max: 6, application_name: 'test_hub' });
+    pool.on('error', () => { });
+    await pool.query(HUB_SCHEMA_SQL);
+    const logger = opts.logger ?? createLogger({ app: 'hub', context: { build_id: 'test' } });
+    const grants = Object.fromEntries(opts.apps.map((app) => [testHubIdentity(app), ['POST /api/notify', 'POST /api/register-daemon']]));
+    const app = new Hono();
+    app.get('/health', (c) => c.json({ ok: true }));
+    const { injectWebSocket, upgradeWebSocket, wss } = createNodeWebSocket({ app });
+    const host = opts.host ?? '127.0.0.1';
+    // The audience is the hub's own URL; it is only an OIDC audience and a
+    // host for client addresses, neither of which test mode checks.
+    const hub = createHub(app, {
+        pool,
+        logger,
+        audience: `http://${host}`,
+        grants,
+        serviceAccountDomain: TEST_HUB_SA_DOMAIN,
+        appDomain: 'apps.test',
+        allowLocalOrigins: true,
+        upgradeWebSocket,
+        webSocketServer: wss,
+        ...opts.hub,
+    });
+    await hub.start();
+    const server = serve({ fetch: app.fetch, port: opts.port ?? 0, hostname: host });
+    injectWebSocket(server);
+    if (!server.listening)
+        await once(server, 'listening');
+    const url = `http://${host}:${server.address().port}`;
+    let stopped = false;
+    return {
+        url,
+        hub,
+        async stop() {
+            if (stopped)
+                return;
+            stopped = true;
+            await hub.stop();
+            server.closeAllConnections();
+            await new Promise((resolve) => server.close(resolve));
+            await endPool(pool);
+        },
+    };
+}

package/dist/hub-daemon.d.ts

@@ -0,0 +1,83 @@
+/** How long one park lasts at the hub before it answers 204. */
+export declare const HUB_PARK_SECONDS = 30;
+/** The client's bound past the park (design §5.6: wait + 10 s). */
+export declare const HUB_PARK_CLIENT_SLACK_MS = 10000;
+/** The sleep after any hub failure before the next direct request. */
+export declare const HUB_DEGRADED_SLEEP_MS = 2000;
+/** Mints happen at most this often, whatever their outcome. */
+export declare const HUB_MINT_FLOOR_MS: number;
+/** A token is replaced once it is this old (the hub's TTL is one hour). */
+export declare const HUB_TOKEN_REFRESH_MS: number;
+/** Added to the caller's lookback (review S2), and the hub's cap on it. */
+export declare const HUB_LOOKBACK_SLACK_MS = 1000;
+export declare const HUB_LOOKBACK_MAX_MS = 60000;
+/** A daemon id stable per (host, app), in the hub's accepted format. */
+export declare function stableDaemonId(app: string, host?: string): string;
+export interface HubDaemonLogger {
+    info(message: string, meta?: Record<string, unknown>): void;
+    warn(message: string, meta?: Record<string, unknown>): void;
+}
+export interface HubDaemonClientOptions {
+    /** The hub's base URL, e.g. https://hub.apps.snewman.net. */
+    hubUrl: string;
+    /** This daemon's app (log context only: the hub derives the app from the token). */
+    app: string;
+    /** stableDaemonId(app) in production. */
+    daemonId: string;
+    /** Ask the app for a token (its hub-token route, with the daemon's own
+     *  bearer): one attempt, bounded by the caller (design: 10 s). Throws on
+     *  any failure. */
+    mint: (daemonId: string) => Promise<{
+        token: string;
+        ttlSeconds?: number;
+    }>;
+    logger: HubDaemonLogger;
+    parkSeconds?: number;
+    degradedSleepMs?: number;
+    mintFloorMs?: number;
+    refreshAfterMs?: number;
+    /** Injectable for tests. */
+    fetch?: typeof fetch;
+    /** Monotonic milliseconds (tests). */
+    now?: () => number;
+    sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+}
+/** hint: a `work` hint arrived; timeout: the park ran out (204); unavailable:
+ *  the hub failed or there is no token yet (already slept); stopped: the
+ *  caller's signal aborted. The caller's next step is its direct request. */
+export type HubParkOutcome = 'hint' | 'timeout' | 'unavailable' | 'stopped';
+export declare class HubDaemonClient {
+    private readonly base;
+    private readonly opts;
+    private readonly parkSeconds;
+    private readonly degradedSleepMs;
+    private readonly mintFloorMs;
+    private readonly refreshAfterMs;
+    private readonly fetchFn;
+    private readonly now;
+    private readonly sleepFn;
+    private token;
+    private lastMintAttemptAt;
+    private minting;
+    private mintFailures;
+    private degradedSince;
+    /** now() when the last park answered `hint`: the hint behind it is
+     *  already acted on, so no later lookback reaches back past it. */
+    private lastHintAt;
+    constructor(opts: HubDaemonClientOptions);
+    /** Begin the first mint in the background. Never throws. */
+    start(): void;
+    /** True while the hub is failing (or no token could be minted). */
+    get degraded(): boolean;
+    /** The mint in flight, if any (tests). */
+    get pendingMint(): Promise<void> | null;
+    /** Park until a work hint, the park's end, or a failure. `lookbackMs` is
+     *  the time since this iteration's direct request STARTED, on the
+     *  caller's monotonic clock. Never throws. */
+    park(lookbackMs: number, signal?: AbortSignal): Promise<HubParkOutcome>;
+    private usableToken;
+    private maybeMint;
+    private enterDegraded;
+    private leaveDegraded;
+    private degradedSleep;
+}

package/dist/hub-daemon.js

@@ -0,0 +1,214 @@
+// A daemon's client for the connection hub's work hints (design §5.6, as
+// amended by §14.1, §14.3 S3-S5 and §14.4). Dependency-free on purpose: the
+// VPS daemons import only this subpath.
+//
+// The hub only fills idle time. Each loop iteration first makes its direct
+// request to the app (the claim or peek it always made); only when that finds
+// nothing does it park here. park() returns on a `work` hint, after
+// HUB_PARK_SECONDS (the hub answers 204: the bound on a lost hint and the
+// daemon's liveness touch, design §5.6's 30 s timer), or on any hub failure
+// after sleeping HUB_DEGRADED_SLEEP_MS (review S5: a fast failure must not
+// spin the loop, and for Radar every direct request is a claim). Either way
+// the caller's next step is its direct request.
+//
+// Rules this client owns, so the three daemons cannot get them wrong:
+//   - It never sends Authorization: the app's device bearer stays on the
+//     daemon ↔ app path (review S4). The hub token goes in X-Hub-Token.
+//   - One attempt per park, bounded at the park plus 10 s; no retry budget.
+//   - The token is minted off the loop's critical path, at most once per
+//     HUB_MINT_FLOOR_MS whatever the outcome (review S3); until a token
+//     exists the loop runs degraded (direct requests every 2 s).
+//   - After a 401 it never presents that token again until a new mint
+//     (§14.4: the hub's per-address limit on bad tokens is shared by every
+//     daemon on the host).
+//   - The daemon id is stable per (host, app) (§14.4): restarts and retries
+//     overwrite one registration instead of using up the hub's cap of 20.
+//   - One WARN on entering the degraded state, one INFO on leaving it.
+import { createHash } from 'node:crypto';
+import { hostname } from 'node:os';
+/** How long one park lasts at the hub before it answers 204. */
+export const HUB_PARK_SECONDS = 30;
+/** The client's bound past the park (design §5.6: wait + 10 s). */
+export const HUB_PARK_CLIENT_SLACK_MS = 10_000;
+/** The sleep after any hub failure before the next direct request. */
+export const HUB_DEGRADED_SLEEP_MS = 2_000;
+/** Mints happen at most this often, whatever their outcome. */
+export const HUB_MINT_FLOOR_MS = 5 * 60_000;
+/** A token is replaced once it is this old (the hub's TTL is one hour). */
+export const HUB_TOKEN_REFRESH_MS = 50 * 60_000;
+/** Added to the caller's lookback (review S2), and the hub's cap on it. */
+export const HUB_LOOKBACK_SLACK_MS = 1_000;
+export const HUB_LOOKBACK_MAX_MS = 60_000;
+/** A daemon id stable per (host, app), in the hub's accepted format. */
+export function stableDaemonId(app, host = hostname()) {
+    return `d_${createHash('sha256').update(`${host}\n${app}`).digest('base64url').slice(0, 30)}`;
+}
+export class HubDaemonClient {
+    base;
+    opts;
+    parkSeconds;
+    degradedSleepMs;
+    mintFloorMs;
+    refreshAfterMs;
+    fetchFn;
+    now;
+    sleepFn;
+    token = null;
+    lastMintAttemptAt = -Infinity;
+    minting = null;
+    mintFailures = 0;
+    degradedSince = null;
+    /** now() when the last park answered `hint`: the hint behind it is
+     *  already acted on, so no later lookback reaches back past it. */
+    lastHintAt = -Infinity;
+    constructor(opts) {
+        this.opts = opts;
+        this.base = opts.hubUrl.replace(/\/$/, '');
+        this.parkSeconds = opts.parkSeconds ?? HUB_PARK_SECONDS;
+        this.degradedSleepMs = opts.degradedSleepMs ?? HUB_DEGRADED_SLEEP_MS;
+        this.mintFloorMs = opts.mintFloorMs ?? HUB_MINT_FLOOR_MS;
+        this.refreshAfterMs = opts.refreshAfterMs ?? HUB_TOKEN_REFRESH_MS;
+        this.fetchFn = opts.fetch ?? fetch;
+        this.now = opts.now ?? (() => performance.now());
+        this.sleepFn = opts.sleep ?? sleep;
+    }
+    /** Begin the first mint in the background. Never throws. */
+    start() {
+        this.maybeMint();
+    }
+    /** True while the hub is failing (or no token could be minted). */
+    get degraded() {
+        return this.degradedSince !== null;
+    }
+    /** The mint in flight, if any (tests). */
+    get pendingMint() {
+        return this.minting;
+    }
+    /** Park until a work hint, the park's end, or a failure. `lookbackMs` is
+     *  the time since this iteration's direct request STARTED, on the
+     *  caller's monotonic clock. Never throws. */
+    async park(lookbackMs, signal) {
+        if (signal?.aborted)
+            return 'stopped';
+        this.maybeMint();
+        const token = this.usableToken();
+        if (!token) {
+            // Quiet while the very first mint is still in flight; degraded after.
+            if (this.mintFailures > 0 || this.minting === null)
+                this.enterDegraded('no hub token');
+            return this.degradedSleep(signal);
+        }
+        // The lookback (review S2) covers the gap between the direct request and
+        // this park, but never reaches back past the previous `hint` answer: the
+        // hub still remembers that hint, and re-matching it would answer every
+        // park at once for the length of the lookback (a burst of direct
+        // requests, each a claim for Radar). Found by coder's integration test.
+        const sinceHint = Math.max(0, Math.floor(this.now() - this.lastHintAt));
+        const lookback = Math.min(Math.max(0, Math.round(lookbackMs)) + HUB_LOOKBACK_SLACK_MS, HUB_LOOKBACK_MAX_MS, sinceHint);
+        const url = `${this.base}/api/daemon/wait?wait=${this.parkSeconds}&lookbackMs=${lookback}`;
+        const bound = AbortSignal.timeout(this.parkSeconds * 1000 + HUB_PARK_CLIENT_SLACK_MS);
+        const startedAt = this.now();
+        let res;
+        try {
+            res = await this.fetchFn(url, {
+                headers: { 'x-hub-token': token.value },
+                signal: signal ? AbortSignal.any([signal, bound]) : bound,
+            });
+        }
+        catch (error) {
+            if (signal?.aborted)
+                return 'stopped';
+            this.enterDegraded('hub wait failed', { error: error instanceof Error ? error.message : String(error) });
+            return this.degradedSleep(signal);
+        }
+        if (res.status === 200) {
+            await res.json().catch(() => null);
+            this.lastHintAt = this.now();
+            this.leaveDegraded();
+            return 'hint';
+        }
+        await res.body?.cancel().catch(() => { });
+        if (res.status === 204) {
+            this.leaveDegraded();
+            // A copy that is stopping answers at once; don't spin on it. A 204
+            // well before the park's end is that, not a park that ran out.
+            if (this.now() - startedAt < (this.parkSeconds * 1000) / 2 && !signal?.aborted)
+                await this.sleepFn(this.degradedSleepMs, signal);
+            return signal?.aborted ? 'stopped' : 'timeout';
+        }
+        if (res.status === 401) {
+            // Never present this token again (§14.4); a new one only by a mint,
+            // which the floor may still hold back.
+            if (this.token?.value === token.value)
+                this.token = null;
+            this.enterDegraded('hub token refused', { status: 401 });
+            this.maybeMint();
+            return this.degradedSleep(signal);
+        }
+        this.enterDegraded('hub wait refused', { status: res.status });
+        return this.degradedSleep(signal);
+    }
+    usableToken() {
+        if (this.token && this.now() >= this.token.expiresAt)
+            this.token = null;
+        return this.token;
+    }
+    maybeMint() {
+        const t = this.now();
+        const needed = this.token === null || t - this.token.mintedAt >= this.refreshAfterMs;
+        if (!needed || this.minting || t - this.lastMintAttemptAt < this.mintFloorMs)
+            return;
+        this.lastMintAttemptAt = t;
+        this.minting = (async () => {
+            try {
+                const { token, ttlSeconds } = await this.opts.mint(this.opts.daemonId);
+                const mintedAt = this.now();
+                this.token = { value: token, mintedAt, expiresAt: mintedAt + (ttlSeconds ?? 3600) * 1000 };
+                if (this.mintFailures > 0)
+                    this.opts.logger.info('hub token minted', { app: this.opts.app, afterFailures: this.mintFailures });
+                this.mintFailures = 0;
+            }
+            catch (error) {
+                this.mintFailures++;
+                this.opts.logger.warn('hub token mint failed', {
+                    app: this.opts.app,
+                    error: error instanceof Error ? error.message : String(error),
+                    failures: this.mintFailures,
+                    nextAttemptInMs: this.mintFloorMs,
+                });
+            }
+            finally {
+                this.minting = null;
+            }
+        })();
+    }
+    enterDegraded(reason, fields = {}) {
+        if (this.degradedSince !== null)
+            return;
+        this.degradedSince = this.now();
+        this.opts.logger.warn('hub wait unavailable; polling the app directly', { app: this.opts.app, reason, ...fields });
+    }
+    leaveDegraded() {
+        if (this.degradedSince === null)
+            return;
+        this.opts.logger.info('hub wait recovered', { app: this.opts.app, degradedForMs: Math.round(this.now() - this.degradedSince) });
+        this.degradedSince = null;
+    }
+    async degradedSleep(signal) {
+        await this.sleepFn(this.degradedSleepMs, signal);
+        return signal?.aborted ? 'stopped' : 'unavailable';
+    }
+}
+function sleep(ms, signal) {
+    return new Promise((resolve) => {
+        if (signal?.aborted)
+            return resolve();
+        const timer = setTimeout(done, ms);
+        function done() {
+            clearTimeout(timer);
+            signal?.removeEventListener('abort', done);
+            resolve();
+        }
+        signal?.addEventListener('abort', done, { once: true });
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@steve31415/baselib",
-  "version": "3.57.0",
+  "version": "3.58.1",
   "description": "Plasticine new-world shared platform library: logging, auth, service-to-service auth, db, HTTP, sync, app updates",
   "type": "module",
   "license": "MIT",
@@ -69,6 +69,14 @@
       "types": "./dist/hub/index.d.ts",
       "default": "./dist/hub/index.js"
     },
+    "./hub/testing": {
+      "types": "./dist/hub/testing.d.ts",
+      "default": "./dist/hub/testing.js"
+    },
+    "./hub-daemon": {
+      "types": "./dist/hub-daemon.d.ts",
+      "default": "./dist/hub-daemon.js"
+    },
     "./socket-age": {
       "types": "./dist/socket-age.d.ts",
       "default": "./dist/socket-age.js"
@@ -112,7 +120,8 @@
     "pw-logs": "./dist/bin/pw-logs.js",
     "pw-rollback": "./dist/bin/pw-rollback.js",
     "pw-sql": "./dist/bin/pw-sql.js",
-    "pw-code-manifest": "./dist/bin/pw-code-manifest.js"
+    "pw-code-manifest": "./dist/bin/pw-code-manifest.js",
+    "baselib-test-hub": "./dist/bin/test-hub.js"
   },
   "engines": {
     "node": "22.x"
@@ -129,6 +138,7 @@
   "dependencies": {
     "@google-cloud/cloud-sql-connector": "^1.8.2",
     "@hono/node-server": "^1.14.0",
+    "@hono/node-ws": "^1.3.1",
     "@modelcontextprotocol/sdk": "^1.32.1",
     "google-auth-library": "^10.5.0",
     "hono": "^4.7.0",
@@ -138,7 +148,6 @@
     "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",