@steve31415/baselib 3.25.0 → 3.27.0

package/README.md

@@ -5,7 +5,7 @@ What it provides and why: `docs/SPEC.md`. How it's put together:
 `docs/IMPL.md`. Full design rationale with alternatives:
 `~/migration/research/base-services-design.md`.
 
-Server subpath exports: `config`, `log`, `auth`, `s2s`, `db`, `http`, `sync`,
+Server subpath exports: `config`, `log`, `auth`, `oauth-resource`, `s2s`, `db`, `http`, `sync`,
 `app-update`, `llm`, `email`, and `twitter`. Browser exports: `log-browser`, `rum`,
 `slow-fetch`, `sync-browser`, and `app-update-browser`.
 

package/dist/http.d.ts

@@ -5,6 +5,16 @@ import type { Logger } from './log-core.js';
  *  identity); /health excluded. Entry-point detail beyond this (key
  *  parameters, outcomes) is the handler's job per OPERATIONS.md. */
 export declare function requestLogging(logger: Logger): import("hono").MiddlewareHandler<any, string, {}, Response>;
+/** The address of the client that connected to Google's edge, read from
+ *  X-Forwarded-For — for per-source rate limits, never for authorization.
+ *  Google appends to whatever the client sent, so only the tail can be
+ *  trusted: through the fleet load balancer the header ends
+ *  `<client>,<load balancer>` (Google's Application Load Balancer docs: it
+ *  "does not verify any IP addresses that precede" those two), and a request
+ *  made straight to the service's run.app URL ends `<client>`. `canonicalHost`
+ *  is the app's public host: a request for any other host did not come
+ *  through the load balancer. */
+export declare function forwardedClientIp(c: Context, canonicalHost: string): string;
 export declare function addHealth(app: Hono): void;
 /** app.onError handler: log with full context, return a plain 500. */
 export declare function errorHandler(logger: Logger): (err: Error, c: Context) => (Response & import("hono").TypedResponse<{

package/dist/http.js

@@ -25,6 +25,23 @@ export function requestLogging(logger) {
         });
     });
 }
+/** The address of the client that connected to Google's edge, read from
+ *  X-Forwarded-For — for per-source rate limits, never for authorization.
+ *  Google appends to whatever the client sent, so only the tail can be
+ *  trusted: through the fleet load balancer the header ends
+ *  `<client>,<load balancer>` (Google's Application Load Balancer docs: it
+ *  "does not verify any IP addresses that precede" those two), and a request
+ *  made straight to the service's run.app URL ends `<client>`. `canonicalHost`
+ *  is the app's public host: a request for any other host did not come
+ *  through the load balancer. */
+export function forwardedClientIp(c, canonicalHost) {
+    const hops = (c.req.header('x-forwarded-for') ?? '')
+        .split(',')
+        .map((hop) => hop.trim())
+        .filter(Boolean);
+    const viaLoadBalancer = (c.req.header('host') ?? '').toLowerCase() === canonicalHost.toLowerCase();
+    return hops.at(viaLoadBalancer ? -2 : -1) ?? 'unknown';
+}
 export function addHealth(app) {
     app.get('/health', (c) => c.json({
         ok: true,

package/dist/oauth-resource.d.ts

@@ -0,0 +1,85 @@
+import type { Context } from 'hono';
+import type { UserAccessPolicy, UserRole } from './auth.js';
+import type { Logger } from './log-core.js';
+import { serviceFetch } from './s2s.js';
+/** The exact shape of an access token: the prefix plus 32 random bytes in
+ *  base64url. Anything else is refused before any cache or network work. */
+export declare const ACCESS_TOKEN_PATTERN: RegExp;
+/** A user acting through a connector, limited to the scopes they approved. */
+export interface ConnectorUser {
+    type: 'connector';
+    email: string;
+    name?: string;
+    userId?: string;
+    role: UserRole;
+    scopes: ReadonlySet<string>;
+    /** The OAuth client the user approved (e.g. Claude's client ID URL). */
+    clientId: string;
+    /** The consent this token descends from; revoking it kills the token. */
+    grantId: string;
+}
+declare module 'hono' {
+    interface ContextVariableMap {
+        connector: ConnectorUser;
+    }
+}
+export interface ConnectorResourceOptions {
+    /** This endpoint's exact public URL, e.g. https://notes.apps.snewman.net/mcp
+     *  — the OAuth resource tokens must have been issued for. */
+    resource: string;
+    /** Every scope this resource defines (advertised in metadata and
+     *  challenges). */
+    scopes: readonly string[];
+    /** Base URL of the auth service (the authorization server). */
+    authUrl?: string;
+}
+export interface RequireConnectorUserOptions extends ConnectorResourceOptions {
+    /** Which users this app admits — the same policy as requireIdentity. */
+    userAccess?: UserAccessPolicy;
+    logger?: Logger;
+    /** Per-user request ceiling (default 600/min). */
+    rateLimitPerMin?: number;
+    /** Injectable for tests: performs the introspection call for one token. */
+    introspect?: (token: string) => Promise<Response>;
+    cache?: {
+        hitMs?: number;
+        missMs?: number;
+        maxEntries?: number;
+    };
+    /** Uncached tokens one source address may have introspected per minute
+     *  (default 60). A connector's own traffic needs one per token per cache
+     *  window, so this only ever binds on a stream of unknown tokens. */
+    introspectionsPerSourcePerMin?: number;
+    now?: () => number;
+}
+/** The introspection call itself: s2s OIDC to the auth service, bounded in
+ *  time including the ID-token mint. */
+export declare function introspectAtAuth(authUrl: string, token: string, fetcher?: typeof serviceFetch): Promise<Response>;
+/** Where the RFC 9728 document for `resource` is served: the well-known
+ *  prefix inserted before the resource's path. Built from configuration,
+ *  never from the request URL (which is http:// behind the load balancer). */
+export declare function resourceMetadataUrl(resource: string): string;
+/** The RFC 9728 protected-resource metadata document. */
+export declare function protectedResourceMetadata(opts: ConnectorResourceOptions): {
+    resource: string;
+    authorization_servers: string[];
+    scopes_supported: string[];
+    bearer_methods_supported: string[];
+};
+/** 403 that asks the client to re-run consent for more scope. The challenge
+ *  names every scope of the resource, because a client does not reliably
+ *  carry earlier scopes into a step-up. */
+export declare function insufficientScope(c: Context, opts: ConnectorResourceOptions): Response & import("hono").TypedResponse<{
+    error: string;
+}, 403, "json">;
+export declare function requireConnectorUser(opts: RequireConnectorUserOptions): import("hono").MiddlewareHandler<any, string, {}, (Response & import("hono").TypedResponse<{
+    error: string;
+}, 401, "json">) | (Response & import("hono").TypedResponse<{
+    error: string;
+    code: string;
+    email: string;
+}, 403, "json">) | (Response & import("hono").TypedResponse<{
+    error: string;
+}, 429, "json">) | (Response & import("hono").TypedResponse<{
+    error: string;
+}, 503, "json">)>;

package/dist/oauth-resource.js

@@ -0,0 +1,257 @@
+// Resource-server side of the fleet's OAuth access tokens — the credential a
+// connector (claude.ai's MCP client) presents on a user's behalf.
+//
+// The auth service is the authorization server: it shows the consent page and
+// issues opaque `pwat_…` access tokens bound to exactly one resource (an
+// app's MCP endpoint URL) and a scope list. An app that serves such an
+// endpoint mounts requireConnectorUser() on that route ONLY. It is
+// deliberately separate from requireIdentity(): a connector token must never
+// be admitted on an app's ordinary user routes, so it produces its own
+// context variable (`connector`) and never sets `identity` or `user`.
+//
+// Resolution, in order:
+//   1. Test bypass (AUTH_MODE=test): X-Test-Connector-User (+ -Role, -Scope).
+//      Credential verification is bypassed; the access policy and the app's
+//      scope checks still run.
+//   2. Authorization: Bearer pwat_… → introspection at the auth service over
+//      s2s OIDC, cached in-instance (5 min hits, capped by the token's own
+//      expiry / 30 s misses, bounded LRU). Introspections are budgeted per
+//      source address, so a stream of junk tokens costs the auth service a
+//      bounded number of calls and costs other callers nothing.
+//
+// Failure mapping matters to the client. A 401 makes it discard its token and
+// re-run sign-in, so 401 is reserved for "this token is not valid here".
+// Anything that is OUR fault or the auth service's (unreachable, slow, any
+// non-200, a malformed answer) is 503 and is never cached.
+import { createHash } from 'node:crypto';
+import { createMiddleware } from 'hono/factory';
+import { ACCESS_DENIED_CODE, DEFAULT_AUTH_URL, userAllowed } from './auth.js';
+import { authMode } from './config.js';
+import { forwardedClientIp } from './http.js';
+import { RateLimiter, serviceFetch } from './s2s.js';
+/** The exact shape of an access token: the prefix plus 32 random bytes in
+ *  base64url. Anything else is refused before any cache or network work. */
+export const ACCESS_TOKEN_PATTERN = /^pwat_[A-Za-z0-9_-]{43}$/;
+const INTROSPECT_TIMEOUT_MS = 5_000;
+/** The introspection call itself: s2s OIDC to the auth service, bounded in
+ *  time including the ID-token mint. */
+export function introspectAtAuth(authUrl, token, fetcher = serviceFetch) {
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error('introspection timed out')), INTROSPECT_TIMEOUT_MS);
+    });
+    const call = fetcher(`${authUrl}/api/oauth/introspect`, {
+        audience: authUrl,
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ token }),
+        signal: AbortSignal.timeout(INTROSPECT_TIMEOUT_MS),
+    });
+    return Promise.race([call, timeout]).finally(() => clearTimeout(timer));
+}
+function authBase(opts) {
+    return (opts.authUrl ?? DEFAULT_AUTH_URL).replace(/\/$/, '');
+}
+/** Where the RFC 9728 document for `resource` is served: the well-known
+ *  prefix inserted before the resource's path. Built from configuration,
+ *  never from the request URL (which is http:// behind the load balancer). */
+export function resourceMetadataUrl(resource) {
+    const url = new URL(resource);
+    const path = url.pathname === '/' ? '' : url.pathname;
+    return `${url.origin}/.well-known/oauth-protected-resource${path}`;
+}
+/** The RFC 9728 protected-resource metadata document. */
+export function protectedResourceMetadata(opts) {
+    return {
+        resource: opts.resource,
+        authorization_servers: [authBase(opts)],
+        scopes_supported: [...opts.scopes],
+        bearer_methods_supported: ['header'],
+    };
+}
+function challenge(opts, error) {
+    return [
+        ...(error ? [`error="${error}"`] : []),
+        `resource_metadata="${resourceMetadataUrl(opts.resource)}"`,
+        `scope="${opts.scopes.join(' ')}"`,
+    ].join(', ');
+}
+function unauthorized(c, opts, error) {
+    c.header('www-authenticate', `Bearer ${challenge(opts, error)}`);
+    c.header('cache-control', 'no-store');
+    return c.json({ error: error ?? 'unauthorized' }, 401);
+}
+/** 403 that asks the client to re-run consent for more scope. The challenge
+ *  names every scope of the resource, because a client does not reliably
+ *  carry earlier scopes into a step-up. */
+export function insufficientScope(c, opts) {
+    c.header('www-authenticate', `Bearer ${challenge(opts, 'insufficient_scope')}`);
+    c.header('cache-control', 'no-store');
+    return c.json({ error: 'insufficient_scope' }, 403);
+}
+/** A Map in insertion order doubles as an LRU: a hit is re-inserted, and the
+ *  oldest key is dropped when full. Unauthenticated callers choose the keys,
+ *  so the bound is what keeps them from growing the process. */
+class LruCache {
+    maxEntries;
+    entries = new Map();
+    constructor(maxEntries) {
+        this.maxEntries = maxEntries;
+    }
+    get(key, now) {
+        const entry = this.entries.get(key);
+        if (!entry)
+            return undefined;
+        this.entries.delete(key);
+        if (entry.expires <= now)
+            return undefined;
+        this.entries.set(key, entry);
+        return entry;
+    }
+    set(key, entry) {
+        this.entries.delete(key);
+        this.entries.set(key, entry);
+        if (this.entries.size > this.maxEntries) {
+            this.entries.delete(this.entries.keys().next().value);
+        }
+    }
+}
+function parseRole(value) {
+    return value === 'owner' || value === 'invited' ? value : undefined;
+}
+function parseScopes(value) {
+    return new Set(typeof value === 'string' ? value.split(' ').filter(Boolean) : []);
+}
+function nonEmptyString(value) {
+    return typeof value === 'string' && value.length > 0;
+}
+export function requireConnectorUser(opts) {
+    const policy = opts.userAccess ?? 'owner';
+    const hitMs = opts.cache?.hitMs ?? 300_000;
+    const missMs = opts.cache?.missMs ?? 30_000;
+    const cache = new LruCache(opts.cache?.maxEntries ?? 1_000);
+    const now = opts.now ?? Date.now;
+    const limiter = new RateLimiter(opts.rateLimitPerMin ?? 600);
+    const sourceBudget = new RateLimiter(opts.introspectionsPerSourcePerMin ?? 60);
+    const resourceHost = new URL(opts.resource).host;
+    const introspect = opts.introspect ?? ((token) => introspectAtAuth(authBase(opts), token));
+    const unavailable = (c) => {
+        c.header('cache-control', 'no-store');
+        return c.json({ error: 'auth service unavailable' }, 503);
+    };
+    const rateLimited = (c) => {
+        c.header('cache-control', 'no-store');
+        return c.json({ error: 'rate limit exceeded' }, 429);
+    };
+    return createMiddleware(async (c, next) => {
+        const admit = (user) => {
+            if (!userAllowed(policy, user)) {
+                opts.logger?.warn('connector user access denied', {
+                    email: user.email,
+                    policy,
+                    path: c.req.path,
+                });
+                c.header('cache-control', 'no-store');
+                return c.json({ error: 'not enabled for this account', code: ACCESS_DENIED_CODE, email: user.email }, 403);
+            }
+            if (!limiter.allow(user.email)) {
+                opts.logger?.warn('connector rate limit exceeded', { email: user.email, path: c.req.path });
+                return rateLimited(c);
+            }
+            // A copy per request: the cached identity is shared, and a Set typed
+            // read-only is still mutable at runtime.
+            c.set('connector', { ...user, scopes: new Set(user.scopes) });
+            return next();
+        };
+        if (authMode() === 'test') {
+            const email = c.req.header('x-test-connector-user');
+            if (!email)
+                return unauthorized(c, opts);
+            const scope = c.req.header('x-test-connector-scope');
+            return admit({
+                type: 'connector',
+                email,
+                role: parseRole(c.req.header('x-test-connector-role')) ?? 'invited',
+                scopes: scope === undefined ? new Set(opts.scopes) : parseScopes(scope),
+                clientId: 'test-client',
+                grantId: 'test-grant',
+            });
+        }
+        const header = c.req.header('authorization');
+        if (!header)
+            return unauthorized(c, opts);
+        const token = header.match(/^Bearer\s+(\S+)\s*$/i)?.[1];
+        // A bearer of any other shape — including a service's OIDC token — is not
+        // ours to verify and is never forwarded or logged.
+        if (!token || !ACCESS_TOKEN_PATTERN.test(token))
+            return unauthorized(c, opts, 'invalid_token');
+        const key = createHash('sha256').update(token).digest('hex');
+        const cached = cache.get(key, now());
+        if (cached)
+            return cached.user ? admit(cached.user) : unauthorized(c, opts, 'invalid_token');
+        const reject = () => {
+            cache.set(key, { expires: now() + missMs });
+            return unauthorized(c, opts, 'invalid_token');
+        };
+        // Spent before the call, on every uncached token whatever the answer, so
+        // concurrent junk cannot overshoot it. Over budget is a 429, never a 401:
+        // a client holding a good token must not be told to discard it.
+        if (!sourceBudget.allow(forwardedClientIp(c, resourceHost))) {
+            opts.logger?.warn('connector introspection budget exhausted', { path: c.req.path });
+            return rateLimited(c);
+        }
+        let res;
+        try {
+            res = await introspect(token);
+        }
+        catch (err) {
+            opts.logger?.error('auth service unreachable for introspection', { error: err });
+            return unavailable(c);
+        }
+        if (res.status !== 200) {
+            opts.logger?.error('connector token introspection failed', { meta_status: res.status });
+            return unavailable(c);
+        }
+        const data = (await res.json().catch(() => null));
+        // Only an explicit `active: false` means "not valid". Any other answer
+        // without `active: true` is a protocol fault: fail closed, loudly, and
+        // without caching, so a broken auth service cannot sign every user out.
+        if (data?.active === false)
+            return reject();
+        if (data?.active !== true || Array.isArray(data)) {
+            opts.logger?.error('connector introspection answer is malformed');
+            return unavailable(c);
+        }
+        if (data.resource !== opts.resource) {
+            // The auth service only answers `active` to the resource's own service
+            // account, so this is reachable only by the always-admitted agent
+            // identity in development. Not valid here either way.
+            opts.logger?.warn('connector token is for another resource', { resource: data.resource });
+            return reject();
+        }
+        const role = parseRole(data.role);
+        const expMs = typeof data.exp === 'number' ? data.exp * 1000 : NaN;
+        if (!role ||
+            !nonEmptyString(data.email) ||
+            !nonEmptyString(data.client_id) ||
+            !nonEmptyString(data.grant_id) ||
+            !Number.isFinite(expMs)) {
+            opts.logger?.error('connector introspection answer is malformed');
+            return unavailable(c);
+        }
+        if (expMs <= now())
+            return reject();
+        const user = {
+            type: 'connector',
+            email: data.email,
+            name: typeof data.name === 'string' ? data.name : undefined,
+            userId: typeof data.user_id === 'string' ? data.user_id : undefined,
+            role,
+            scopes: parseScopes(data.scope),
+            clientId: data.client_id,
+            grantId: data.grant_id,
+        };
+        cache.set(key, { expires: Math.min(now() + hitMs, expMs), user });
+        return admit(user);
+    });
+}

package/dist/s2s.d.ts

@@ -25,6 +25,7 @@ export declare class RateLimiter {
     private windows;
     constructor(perMinute: number);
     allow(key: string): boolean;
+    private evict;
 }
 export interface S2sOptions {
     /** This service's canonical URL, e.g. https://auth.apps.snewman.net — the

package/dist/s2s.js

@@ -47,6 +47,8 @@ export function grantAllows(grants, email, method, path) {
 // loops and mischief, not a precision tool (per-instance state only).
 export class RateLimiter {
     perMinute;
+    // Insertion order is window-start order (a restarted window is re-inserted),
+    // so the oldest window is always first.
     windows = new Map();
     constructor(perMinute) {
         this.perMinute = perMinute;
@@ -55,13 +57,31 @@ export class RateLimiter {
         const now = Date.now();
         const w = this.windows.get(key);
         if (!w || now - w.start >= 60_000) {
+            this.windows.delete(key);
+            this.evict(now);
             this.windows.set(key, { start: now, count: 1 });
-            return true;
+            return this.perMinute >= 1;
         }
         w.count++;
         return w.count <= this.perMinute;
     }
+    // Keys can be chosen by unauthenticated callers (a per-IP limiter on a
+    // public endpoint), so finished windows are dropped as new ones arrive and
+    // the map never exceeds RATE_LIMITER_MAX_KEYS: past that the oldest live
+    // window is forgotten, which only ever relaxes the limit for that key.
+    evict(now) {
+        for (const [key, w] of this.windows) {
+            if (now - w.start < 60_000 && this.windows.size < RATE_LIMITER_MAX_KEYS)
+                return;
+            this.windows.delete(key);
+        }
+    }
 }
+const RATE_LIMITER_MAX_KEYS = 10_000;
+/** The auth service's OAuth token families (access, refresh, authorization
+ *  code). They are opaque, never Google ID tokens, and are admitted only by
+ *  oauth-resource.ts's middleware on an app's connector route. */
+const CONNECTOR_TOKEN = /^pw(?:at|rt|ac)_/;
 /** `message` with every occurrence of `token` — and of each of its
  *  dot-separated segments of 8+ chars, since some verifier messages quote a
  *  single segment — replaced by `<token>`, then truncated. */
@@ -85,6 +105,12 @@ export async function resolveS2sCaller(opts, headers, method, path) {
         const m = headers.authorization?.match(/^Bearer (.+)$/i);
         if (!m)
             return { failure: { status: 401, error: 'missing bearer token' } };
+        if (CONNECTOR_TOKEN.test(m[1])) {
+            // A connector token on a route that takes service callers: refused here
+            // so it never reaches the verifier, whose errors quote the token.
+            opts.logger?.warn('connector token presented on a service route', { path });
+            return { failure: { status: 401, error: 'invalid token' } };
+        }
         try {
             const client = opts.verifyClient ?? defaultVerifyClient();
             const ticket = await client.verifyIdToken({ idToken: m[1], audience: opts.audience });

package/dist/sync-browser/client.d.ts

@@ -145,6 +145,7 @@ export declare class SyncClient<B, C extends EventBody, S extends EventBody, Sum
     private halted;
     private refetchInFlight;
     private probeInFlight;
+    private probeRequested;
     private resyncTimes;
     /** Forward-gap events delivered while a resync is reconciling; drained
      * after the bootstrap installs. Non-null exactly while reconciling. */
@@ -200,6 +201,7 @@ export declare class SyncClient<B, C extends EventBody, S extends EventBody, Sum
     private onBecameVisible;
     private onOnline;
     private wakeConnection;
+    private logConnectTimeout;
     /** Drops the current socket, if any, without treating it as an outage, and
      * connects at once. */
     private replaceSocket;
@@ -226,6 +228,12 @@ export declare class SyncClient<B, C extends EventBody, S extends EventBody, Sum
      * (once per return); anything else takes the ladder. */
     private takeQuickRetry;
     private scheduleReconnect;
+    /** One HTTP round trip while the visible socket is down: delivers pending
+     * events (`postEvents`), then catches up — which applies their echoes, so
+     * the writes confirm — and doubles as the session probe (an expired
+     * session halts through the auth state). A WebSocket handshake can be
+     * stuck for minutes behind another one in the browser's per-IP queue while
+     * HTTP works at once (notes, 2026-10-01), so writes must not wait for it. */
     private probeSession;
     private startOutage;
     /** ERROR only after OUTAGE_ESCALATE_MS of visible, on-time outage; re-armed

package/dist/sync-browser/client.js

@@ -27,6 +27,14 @@ const RETURN_REPORT_TIMEOUT_MS = 15_000;
  * without reaching the server, while HTTP works at once; the ladder's 1 s
  * step then made every such return take 1.5-2 s (reader, 2026-09-26). */
 const RETURN_QUICK_RETRY_MS = 250;
+/** A handshake that takes at least this long to open, or to fail on its own,
+ * is logged (INFO): it either sat in the browser's per-IP handshake queue or
+ * stalled itself. Chrome runs one WebSocket handshake per server IP:port at a
+ * time, across every tab and hostname; all fleet apps share the load
+ * balancer's IP, so one stalled handshake holds every app's sockets until it
+ * resolves (notes, 2026-10-01: four minutes). Fast failures (offline) are
+ * not logged. */
+const SLOW_HANDSHAKE_MS = 3_000;
 const SOCKET_CONNECTING = 0;
 const SOCKET_OPEN = 1;
 class LifecycleAbort {
@@ -71,6 +79,7 @@ export class SyncClient {
     halted = false;
     refetchInFlight = false;
     probeInFlight = false;
+    probeRequested = false;
     resyncTimes = [];
     /** Forward-gap events delivered while a resync is reconciling; drained
      * after the bootstrap installs. Non-null exactly while reconciling. */
@@ -105,6 +114,7 @@ export class SyncClient {
         backgroundCatchups: 0,
         backgroundCatchupFailures: 0,
         backgroundSocketAttempts: 0,
+        httpPostedEvents: 0,
     };
     constructor(options) {
         this.options = options;
@@ -222,6 +232,11 @@ export class SyncClient {
         this.options.store.applyOptimistic(event);
         this.armFailureTimer(event.eventGuid);
         this.trySend(entry);
+        // A visible page in an outage delivers over HTTP at once rather than
+        // waiting for a handshake that may be stuck behind another one.
+        if (!this.isHidden() && this.outageStartedAt !== null && this.socket?.readyState !== SOCKET_OPEN) {
+            void this.probeSession();
+        }
         this.updatePendingState();
         this.options.onSafetyChange?.();
     }
@@ -301,6 +316,7 @@ export class SyncClient {
             backgroundCatchups: now.backgroundCatchups - since.backgroundCatchups,
             backgroundCatchupFailures: now.backgroundCatchupFailures - since.backgroundCatchupFailures,
             backgroundSocketAttempts: now.backgroundSocketAttempts - since.backgroundSocketAttempts,
+            httpPostedEvents: now.httpPostedEvents - since.httpPostedEvents,
         };
     }
     onBecameHidden() {
@@ -379,12 +395,25 @@ export class SyncClient {
         // closing is gone too. Waiting on either routes the returning user
         // through the watchdog's close and a full backoff step (16-30 s of
         // "Reconnecting…" observed on reader, 2026-09-24).
-        if (socket?.readyState === SOCKET_CONNECTING &&
-            this.options.runtime.now() - this.socketCreatedAt < CONNECT_WATCHDOG_MS) {
-            return;
+        if (socket?.readyState === SOCKET_CONNECTING) {
+            const socketAgeMs = this.options.runtime.now() - this.socketCreatedAt;
+            if (socketAgeMs < CONNECT_WATCHDOG_MS)
+                return;
+            // Its watchdog never ran: a throttled or frozen hidden page, the case
+            // that can hold the browser's handshake queue past 10 s.
+            this.logConnectTimeout(socketAgeMs, { replacedOnReturn: true });
         }
         this.replaceSocket();
     }
+    logConnectTimeout(socketAgeMs, extra = {}) {
+        this.options.logger.info('sync connect timeout', {
+            socketAgeMs,
+            lateMs: Math.max(0, socketAgeMs - CONNECT_WATCHDOG_MS),
+            createdHidden: this.socketCreatedHidden,
+            hidden: this.isHidden(),
+            ...extra,
+        });
+    }
     /** Drops the current socket, if any, without treating it as an outage, and
      * connects at once. */
     replaceSocket() {
@@ -422,9 +451,12 @@ export class SyncClient {
         this.socketOpenedAt = null;
         if (this.socketCreatedHidden)
             this.counters.backgroundSocketAttempts++;
+        let killedByWatchdog = false;
         this.watchdogTimer = this.options.runtime.setTimeout(() => {
             if (socket.readyState !== SOCKET_OPEN) {
                 this.counters.watchdogKills++;
+                killedByWatchdog = true;
+                this.logConnectTimeout(this.options.runtime.now() - this.socketCreatedAt);
                 socket.close();
             }
         }, CONNECT_WATCHDOG_MS);
@@ -437,6 +469,14 @@ export class SyncClient {
                 this.options.runtime.clearTimeout(this.watchdogTimer);
             this.watchdogTimer = null;
             this.socketOpenedAt = this.now();
+            const openMs = this.socketOpenedAt - this.socketCreatedAt;
+            if (openMs >= SLOW_HANDSHAKE_MS) {
+                this.options.logger.info('sync connect slow', {
+                    openMs,
+                    createdHidden: this.socketCreatedHidden,
+                    hidden: this.isHidden(),
+                });
+            }
             this.cancelBackgroundTick();
             this.sendConnect();
             this.pingTimer = this.options.runtime.setInterval(() => this.sendRaw({ type: 'ping' }), PING_INTERVAL_MS);
@@ -462,6 +502,15 @@ export class SyncClient {
             this.socket = null;
             if (this.halted || this.disposed)
                 return;
+            const socketAgeMs = this.now() - this.socketCreatedAt;
+            if (this.socketOpenedAt === null && !killedByWatchdog && socketAgeMs >= SLOW_HANDSHAKE_MS) {
+                this.options.logger.info('sync connect failed', {
+                    socketAgeMs,
+                    closeCode: event.code,
+                    createdHidden: this.socketCreatedHidden,
+                    hidden: this.isHidden(),
+                });
+            }
             if (event.code === CLOSE_NO_USER) {
                 this.options.authState.markBlocked();
                 this.halt();
@@ -550,6 +599,8 @@ export class SyncClient {
             if (this.stopBeforeStoreMutation())
                 return;
             for (const outcome of outcomes) {
+                if (outcome.status !== 'rejected')
+                    this.counters.httpPostedEvents++;
                 if (outcome.status === 'rejected') {
                     this.handleRejection({
                         type: 'rejection',
@@ -729,8 +780,9 @@ export class SyncClient {
         const delay = Math.ceil(delayMs / 1000);
         this.reconnectAttempts++;
         this.totalAttempts++;
-        if (this.reconnectAttempts >= PROBE_AFTER_ATTEMPTS)
+        if (this.reconnectAttempts >= PROBE_AFTER_ATTEMPTS || this.unsettledPending().length > 0) {
             void this.probeSession();
+        }
         let remaining = delay;
         this.publish({ kind: 'reconnecting', pending: this.pendingCount(), inSeconds: remaining });
         this.countdownTimer = this.options.runtime.setInterval(() => {
@@ -747,11 +799,25 @@ export class SyncClient {
             this.connect();
         }, delayMs);
     }
+    /** One HTTP round trip while the visible socket is down: delivers pending
+     * events (`postEvents`), then catches up — which applies their echoes, so
+     * the writes confirm — and doubles as the session probe (an expired
+     * session halts through the auth state). A WebSocket handshake can be
+     * stuck for minutes behind another one in the browser's per-IP queue while
+     * HTTP works at once (notes, 2026-10-01), so writes must not wait for it. */
     async probeSession() {
-        if (this.halted || this.disposed || this.probeInFlight)
+        if (this.halted || this.disposed)
             return;
+        if (this.probeInFlight) {
+            this.probeRequested = true;
+            return;
+        }
         this.probeInFlight = true;
+        this.probeRequested = false;
         try {
+            await this.postPendingOverHttp();
+            if (this.stopBeforeStoreMutation())
+                return;
             const result = await this.abortable((signal) => this.options.fetchCatchup(this.options.store.currentSeq(), signal));
             if (this.stopBeforeStoreMutation())
                 return;
@@ -771,6 +837,11 @@ export class SyncClient {
         finally {
             this.probeInFlight = false;
         }
+        // Something was submitted while this probe was in flight; deliver it
+        // too, unless the socket came back in the meantime.
+        if (this.probeRequested && this.socket?.readyState !== SOCKET_OPEN && !this.isHidden()) {
+            void this.probeSession();
+        }
     }
     startOutage(closeCode, wasClean = false) {
         if (this.outageStartedAt !== null)
@@ -1126,6 +1197,7 @@ export class SyncClient {
                 hiddenMs: delta?.hiddenMs,
                 watchdogKills: delta?.watchdogKills,
                 backgroundCatchups: delta?.backgroundCatchups,
+                httpPostedEvents: delta?.httpPostedEvents,
                 freezes: delta?.freezes,
                 resumes: delta?.resumes,
             };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@steve31415/baselib",
-  "version": "3.25.0",
+  "version": "3.27.0",
   "description": "Plasticine new-world shared platform library: logging, auth, service-to-service auth, db, HTTP, sync, app updates",
   "type": "module",
   "license": "MIT",
@@ -37,6 +37,10 @@
       "types": "./dist/auth.d.ts",
       "default": "./dist/auth.js"
     },
+    "./oauth-resource": {
+      "types": "./dist/oauth-resource.d.ts",
+      "default": "./dist/oauth-resource.js"
+    },
     "./db": {
       "types": "./dist/db.d.ts",
       "default": "./dist/db.js"