@kraki/head 0.20.0 → 0.20.2

package/dist/server.js

@@ -1,68 +1,16 @@
-import { RemoteAuthBackend } from './remote-auth-backend.js';
 import { WebSocketServer, WebSocket } from 'ws';
-import { randomBytes, createVerify } from 'crypto';
-import { v4 as uuid } from 'uuid';
+import { metrics } from './metrics.js';
 import { HEAD_PULSE_TARGET } from '@kraki/protocol';
-import { parseVoiceWordOps } from './voice-vocabulary.js';
-import { PulseHub, PULSE_ACK_EVERY_BYTES } from './pulse-hub.js';
-import { GitHubAuthProvider } from './auth.js';
+import { PulseHub } from './pulse-hub.js';
+import { LocalAuthBackend } from './local-auth-backend.js';
 import { getLogger } from './logger.js';
 import { trace, fp } from './trace.js';
 import { clientIp } from './client-ip.js';
-/** Custom Words has its own channel (`auth_ok.voiceVocabulary` and
- *  `voice_vocabulary_updated`). Never ship it inside generic preferences: that
- *  would duplicate it on every auth and broadcast it on every theme change. */
-function publicPreferences(prefs) {
-    if (!prefs || !('voiceVocabulary' in prefs))
-        return prefs;
-    const { voiceVocabulary: _omitted, ...rest } = prefs;
-    return rest;
-}
-function importPublicKey(compactKey) {
-    const lines = compactKey.match(/.{1,64}/g) ?? [];
-    return `-----BEGIN PUBLIC KEY-----\n${lines.join('\n')}\n-----END PUBLIC KEY-----\n`;
-}
-function verifySignature(nonce, signature, publicKeyPem) {
-    const verify = createVerify('SHA256');
-    verify.update(nonce);
-    return verify.verify(publicKeyPem, signature, 'base64');
-}
-const DEFAULT_VOICE_LEASE_TTL_SEC = 86_400;
-const DEFAULT_VOICE_DAILY_QUOTA_SEC = 7_200;
-const MIN_VOICE_LEASE_GRANT_SEC = 1;
-const VALID_VOICE_RESOURCES = new Set(['voice/doubao']);
-const DEFAULT_MAX_PAYLOAD = 10 * 1024 * 1024;
-const DEFAULT_AUTH_TIMEOUT_MS = 15_000;
-const DEFAULT_LOGIN_SCREEN_AUTH_TIMEOUT_MS = 10 * 60_000;
-const MAX_MULTICAST_TARGETS = 64;
-/** How often the liveness sweep runs (ms). Faster than the 30s ping timer so
- *  device_pending detection latency tracks the recipient's ping cadence
- *  (~10s), not the slower liveness check cadence. */
-const LIVENESS_SWEEP_INTERVAL_MS = 2_500;
-/** Grace period after ping before broadcasting device_pending (ms).
- *  Overridable via PONG_GRACE_MS environment variable. */
-const PONG_GRACE_MS = Math.max(1_000, parseInt(process.env.PONG_GRACE_MS ?? '8000', 10) || 8_000);
-function isValidMessage(msg) {
-    if (typeof msg !== 'object' || msg === null)
-        return false;
-    const obj = msg;
-    return typeof obj.type === 'string' && obj.type.length > 0;
-}
-function isValidAuth(msg) {
-    if (!msg.device || typeof msg.device !== 'object')
-        return false;
-    const dev = msg.device;
-    if (typeof dev.name !== 'string' || typeof dev.role !== 'string')
-        return false;
-    if (dev.role !== 'tentacle' && dev.role !== 'app')
-        return false;
-    if (!msg.auth || typeof msg.auth !== 'object')
-        return false;
-    const auth = msg.auth;
-    if (typeof auth.method !== 'string')
-        return false;
-    return true;
-}
+import { handleControlMessage, firePushPreview } from './server/account-control.js';
+import { handleAuth, handleChallengeResponse, handleCreatePairingToken, handleRequestPairingToken } from './server/auth-flow.js';
+import { broadcastDeviceJoined, broadcastDeviceLeft, broadcastDevicePending } from './server/presence.js';
+import { handleRequestVoiceLease } from './server/voice-lease.js';
+import { DEFAULT_MAX_PAYLOAD, DEFAULT_AUTH_TIMEOUT_MS, DEFAULT_LOGIN_SCREEN_AUTH_TIMEOUT_MS, MAX_MULTICAST_TARGETS, MAX_WS_BUFFERED_BYTES, LIVENESS_SWEEP_INTERVAL_MS, PONG_GRACE_MS, isValidMessage, isValidAuth } from './server/shared.js';
 export class HeadServer {
     wss;
     storage;
@@ -70,7 +18,7 @@ export class HeadServer {
     static PING_INTERVAL = 30_000;
     // In-memory state
     connections = new Map();
-    pairingTokens = new Map();
+    authBackend;
     userByDevice = new Map();
     clients = new Map();
     pingTimer = null;
@@ -81,6 +29,21 @@ export class HeadServer {
     constructor(storage, options) {
         this.storage = storage;
         this.options = options;
+        // One auth implementation for every deployment: without an explicit
+        // backend (standalone tests, self-hosted defaults) the server builds the
+        // same LocalAuthBackend production uses from its providers.
+        this.authBackend = options.authBackend ?? new LocalAuthBackend({
+            storage,
+            // A single `authProvider` answers every token method, as it always has.
+            authProviders: options.authProviders
+                ?? (options.authProvider
+                    ? new Map(['open', 'apikey', 'github'].map((method) => [method, options.authProvider]))
+                    : new Map()),
+            pairingEnabled: options.pairingEnabled,
+            pairingTtl: options.pairingTtl,
+            pushManager: options.pushManager,
+            region: options.region,
+        });
         this.wss = new WebSocketServer({
             noServer: true,
             maxPayload: options.maxPayload ?? DEFAULT_MAX_PAYLOAD,
@@ -117,6 +80,7 @@ export class HeadServer {
                 if (state && !state.isAlive) {
                     // Missed last pong — connection is dead. Log diagnostic timing so
                     // post-mortems can tell network drop from event-loop block.
+                    metrics().inc('conn.pongTimeout');
                     getLogger().info('Terminating stale connection (no pong)', {
                         deviceId,
                         msSincePingSent: state.lastPingSentAt ? now - state.lastPingSentAt : null,
@@ -154,10 +118,7 @@ export class HeadServer {
                 }
             }
             // Sweep expired pairing tokens
-            for (const [token, data] of this.pairingTokens) {
-                if (now > data.expiresAt)
-                    this.pairingTokens.delete(token);
-            }
+            this.authBackend.sweepPairingTokens?.();
             // Periodic health snapshot — ALWAYS on (not trace-gated). Cheap (one line
             // / 30s) and is the canary for the OOM / event-loop-stall class of bugs
             // that recurred across the pulse PRs. rss/heap from process.memoryUsage;
@@ -168,6 +129,9 @@ export class HeadServer {
                 durableRows = this.storage.rawDb.prepare('SELECT COUNT(*) AS n FROM pulse_outbox').get().n;
             }
             catch { /* table may not exist yet */ }
+            const metricsNow = metrics();
+            metricsNow.lastHealthAt = Date.now();
+            const loop = metricsNow.takeLoopDelay();
             getLogger().info('health', {
                 conns: this.connections.size,
                 endpoints: this.pulseHub.endpointCount(),
@@ -175,7 +139,8 @@ export class HeadServer {
                 rssMb: Math.round(mem.rss / 1048576),
                 heapUsedMb: Math.round(mem.heapUsed / 1048576),
                 heapTotalMb: Math.round(mem.heapTotal / 1048576),
-                evlLagMs: undefined,
+                evlLagMs: loop?.p99Ms,
+                evlMaxMs: loop?.maxMs,
             });
         }, HeadServer.PING_INTERVAL);
     }
@@ -206,7 +171,7 @@ export class HeadServer {
                 continue;
             state.pendingLivenessBroadcast = true;
             getLogger().debug('Broadcasting device_pending (pong overdue)', { deviceId });
-            this.broadcastDevicePending(state.userId, deviceId);
+            broadcastDevicePending(this, state.userId, deviceId);
         }
     }
     /** A missing pong alone does not prove a dead link: when the downlink is
@@ -226,22 +191,6 @@ export class HeadServer {
     }
     // ── End liveness sweep ──────────────────────────────────
     // --- Auth provider helpers ---
-    getAuthProvider() {
-        if (this.options.authProviders?.size) {
-            return this.options.authProviders.values().next().value;
-        }
-        return this.options.authProvider;
-    }
-    getAuthProviderForMode(mode) {
-        if (mode && this.options.authProviders?.has(mode)) {
-            return this.options.authProviders.get(mode);
-        }
-        return this.getAuthProvider();
-    }
-    getGitHubClientId() {
-        const ghProvider = this.findGitHubProvider();
-        return ghProvider?.oauthConfigured ? ghProvider.getClientId() : undefined;
-    }
     getVapidPublicKey() {
         return this.options.pushManager?.getVapidPublicKey();
     }
@@ -261,19 +210,6 @@ export class HeadServer {
             return undefined;
         return { brokerUrl: url, resource: 'voice/doubao' };
     }
-    findGitHubProvider() {
-        const provider = this.options.authProviders?.get('github') ?? this.options.authProvider;
-        if (!provider)
-            return undefined;
-        if (provider instanceof GitHubAuthProvider)
-            return provider;
-        if ('inner' in provider) {
-            const inner = provider.inner;
-            if (inner instanceof GitHubAuthProvider)
-                return inner;
-        }
-        return undefined;
-    }
     // --- Connection management ---
     attach(server) {
         server.on('upgrade', (req, socket, head) => {
@@ -313,6 +249,11 @@ export class HeadServer {
         logger.debug('WebSocket connected', { ip });
         ws.on('pong', () => { this.onPongReceived(state); });
         ws.on('message', (data) => {
+            // An evicted socket stays open until its close handshake completes;
+            // nothing it sends may act for the device (its Pulse stream now
+            // belongs to the replacement connection).
+            if (state.evicted)
+                return;
             state.lastInboundAt = Date.now();
             try {
                 const msg = JSON.parse(data.toString());
@@ -329,7 +270,9 @@ export class HeadServer {
                 this.sendError(ws, 'Invalid JSON');
             }
         });
+        metrics().inc('conn.opened');
         ws.on('close', (code, reason) => {
+            metrics().inc('conn.closed');
             if (state.authTimer)
                 clearTimeout(state.authTimer);
             const reasonStr = reason?.toString?.() || '';
@@ -353,7 +296,7 @@ export class HeadServer {
                         closeReason: reasonStr,
                     });
                     if (disconnectedUserId) {
-                        this.broadcastDeviceLeft(disconnectedUserId, disconnectedDeviceId);
+                        broadcastDeviceLeft(this, disconnectedUserId, disconnectedDeviceId);
                     }
                 }
                 else {
@@ -382,44 +325,20 @@ export class HeadServer {
     async onMessage(ws, state, msg) {
         // One-shot pairing token request — before auth
         if (msg.type === 'request_pairing_token') {
-            await this.handleRequestPairingToken(ws, state, msg);
+            await handleRequestPairingToken(this, ws, state, msg);
             return;
         }
         // Pre-auth: auth_info, auth, auth_response
         if (!state.authenticated) {
             if (msg.type === 'auth_info') {
                 this.armAuthTimer(ws, state, this.options.loginScreenAuthTimeoutMs ?? DEFAULT_LOGIN_SCREEN_AUTH_TIMEOUT_MS);
-                if (this.options.authBackend) {
-                    const info = this.options.authBackend.getAuthInfo();
-                    ws.send(JSON.stringify({
-                        type: 'auth_info_response',
-                        methods: info.methods,
-                        githubClientId: info.githubClientId,
-                        vapidPublicKey: info.vapidPublicKey ?? this.getVapidPublicKey(),
-                    }));
-                }
-                else {
-                    const methods = [];
-                    if (this.options.authProviders?.has('github')) {
-                        methods.push('github_token');
-                        const ghProvider = this.findGitHubProvider();
-                        if (ghProvider?.oauthConfigured)
-                            methods.push('github_oauth');
-                    }
-                    if (this.options.authProviders?.has('apikey'))
-                        methods.push('apikey');
-                    if (this.options.authProviders?.has('open'))
-                        methods.push('open');
-                    if (this.options.pairingEnabled !== false)
-                        methods.push('pairing');
-                    methods.push('challenge');
-                    ws.send(JSON.stringify({
-                        type: 'auth_info_response',
-                        methods,
-                        githubClientId: this.getGitHubClientId(),
-                        vapidPublicKey: this.getVapidPublicKey(),
-                    }));
-                }
+                const info = this.authBackend.getAuthInfo();
+                ws.send(JSON.stringify({
+                    type: 'auth_info_response',
+                    methods: info.methods,
+                    githubClientId: info.githubClientId,
+                    vapidPublicKey: info.vapidPublicKey ?? this.getVapidPublicKey(),
+                }));
                 return;
             }
             if (msg.type === 'auth') {
@@ -427,10 +346,10 @@ export class HeadServer {
                     this.sendError(ws, 'Invalid auth message: device.name and device.role required');
                     return;
                 }
-                await this.handleAuth(ws, state, msg);
+                await handleAuth(this, ws, state, msg);
             }
             else if (msg.type === 'auth_response' && state.pendingNonce) {
-                this.handleChallengeResponse(ws, state, msg);
+                handleChallengeResponse(this, ws, state, msg);
             }
             else {
                 this.sendError(ws, 'Must authenticate first');
@@ -439,7 +358,7 @@ export class HeadServer {
         }
         // Authenticated messages
         if (msg.type === 'create_pairing_token') {
-            this.handleCreatePairingToken(ws, state);
+            await handleCreatePairingToken(this, ws, state);
             return;
         }
         if (msg.type === 'unicast') {
@@ -465,8 +384,16 @@ export class HeadServer {
                 // endpoint/disk-growth amplifier from a single client.
                 if (to !== '' && to !== HEAD_PULSE_TARGET) {
                     const target = this.storage.getDevice(to);
-                    if (!target || target.userId !== state.userId) {
+                    // Same account, and only across roles (app ⇄ tentacle): no feature
+                    // sends app→app or tentacle→tentacle, so such a frame is not trusted.
+                    const sender = this.storage.getDevice(state.deviceId);
+                    if (!target || target.userId !== state.userId || !sender || target.role === sender.role) {
                         this.sendError(ws, 'unicast target is not reachable');
+                        // Still consume the frame on the sender's stream, forwarding it
+                        // nowhere: an unconsumed seq would never be ACKed, the sender would
+                        // retransmit it (with the same target) forever, and every later
+                        // seq on that stream would wait behind it.
+                        this.pulseHub.onPulseEnvelope(state.deviceId, { pulse: msg.pulse, to: [] });
                         return;
                     }
                 }
@@ -502,18 +429,20 @@ export class HeadServer {
                 this.sendError(ws, `multicast target count must be between 1 and ${MAX_MULTICAST_TARGETS}`);
                 return;
             }
-            for (const targetId of requested) {
+            const allowed = requested.filter((targetId) => {
                 const target = this.storage.getDevice(targetId);
-                if (targetId === state.deviceId
-                    || targetId === HEAD_PULSE_TARGET
-                    || !target
-                    || target.userId !== state.userId
-                    || target.role !== 'app') {
-                    this.sendError(ws, 'multicast contains a forbidden target');
-                    return;
-                }
-            }
-            const onlineTargets = requested.filter((targetId) => this.connections.has(targetId));
+                return targetId !== state.deviceId
+                    && targetId !== HEAD_PULSE_TARGET
+                    && !!target
+                    && target.userId === state.userId
+                    && target.role === 'app';
+            });
+            // Forbidden targets are dropped, not the frame: the frame must still be
+            // consumed on the sender's stream (see the unicast branch), and the
+            // allowed targets still get it.
+            if (allowed.length < requested.length)
+                this.sendError(ws, 'multicast contains a forbidden target');
+            const onlineTargets = allowed.filter((targetId) => this.connections.has(targetId));
             this.pulseHub.onPulseEnvelope(state.deviceId, {
                 pulse: msg.pulse,
                 to: onlineTargets,
@@ -526,8 +455,10 @@ export class HeadServer {
             if (typeof msg.pulse === 'string' && state.deviceId) {
                 // A pushPreview may ride the same pulse envelope — fire it for offline
                 // devices (the reliable message itself is delivered by the hub).
-                if (msg.pushPreview)
-                    this.firePushPreview(state, msg.pushPreview);
+                // Push previews are tentacle-originated (same rule as dispatch_push).
+                if (msg.pushPreview && this.storage.getDevice(state.deviceId)?.role === 'tentacle') {
+                    firePushPreview(this, state, msg.pushPreview);
+                }
                 this.pulseHub.onPulseEnvelope(state.deviceId, { pulse: msg.pulse });
                 return;
             }
@@ -536,10 +467,10 @@ export class HeadServer {
         }
         // Relay-terminated control ops (update_preferences / remove_device /
         // (un)register_push_token). Arrive via pulse deliver-to-self (deliverPulseToSelf).
-        if (this.handleControlMessage(ws, state, msg))
+        if (handleControlMessage(this, ws, state, msg))
             return;
         if (msg.type === 'request_voice_lease') {
-            this.handleRequestVoiceLease(ws, state, msg);
+            handleRequestVoiceLease(this, ws, state, msg);
             return;
         }
         if (msg.type === 'ping') {
@@ -553,113 +484,6 @@ export class HeadServer {
         this.sendError(ws, `Unknown message type: ${msg.type}`);
     }
     // --- Voice lease issuance ---
-    handleRequestVoiceLease(ws, state, msg) {
-        const logger = getLogger();
-        const userId = state.userId;
-        const deviceId = state.deviceId;
-        if (!userId || !deviceId) {
-            ws.send(JSON.stringify({
-                type: 'voice_lease_denied',
-                reason: 'invalid_request',
-                detail: 'Not authenticated',
-            }));
-            return;
-        }
-        const issuer = this.options.leaseIssuer;
-        if (!issuer) {
-            this.sendControlToDevice(deviceId, {
-                type: 'voice_lease_denied',
-                reason: 'not_entitled',
-                detail: 'Voice lease issuance is not enabled on this head',
-            });
-            return;
-        }
-        // Validate request shape.
-        const requestedDeviceId = typeof msg.deviceId === 'string' ? msg.deviceId : undefined;
-        const requestedResource = typeof msg.resource === 'string' ? msg.resource : undefined;
-        if (!requestedDeviceId || !requestedResource) {
-            this.sendControlToDevice(deviceId, {
-                type: 'voice_lease_denied',
-                reason: 'invalid_request',
-                detail: 'Missing deviceId or resource',
-            });
-            return;
-        }
-        // Lease may only be requested for the authenticated device — no proxying.
-        if (requestedDeviceId !== deviceId) {
-            this.sendControlToDevice(deviceId, {
-                type: 'voice_lease_denied',
-                reason: 'invalid_request',
-                detail: 'deviceId does not match authenticated device',
-            });
-            return;
-        }
-        if (!VALID_VOICE_RESOURCES.has(requestedResource)) {
-            this.sendControlToDevice(deviceId, {
-                type: 'voice_lease_denied',
-                reason: 'invalid_request',
-                detail: `Unknown resource: ${String(requestedResource)}`,
-            });
-            return;
-        }
-        // A lease is a long-lived credential for this device; the audio budget
-        // is granted incrementally by usage reports, charged to the UTC day the
-        // audio is used. So issuance only checks that anything is left today.
-        const nowSec = Math.floor(Date.now() / 1000);
-        const dailyCap = this.options.voiceDailyQuotaSec ?? DEFAULT_VOICE_DAILY_QUOTA_SEC;
-        this.storage.revokePendingVoiceLeases(userId, deviceId, requestedResource, nowSec);
-        const accountedToday = this.storage.voiceSecondsAccountedToday(userId, nowSec);
-        if (dailyCap - accountedToday < MIN_VOICE_LEASE_GRANT_SEC) {
-            logger.info('Voice lease denied: daily quota exhausted', {
-                userId, deviceId, accountedToday, dailyCap,
-            });
-            this.sendControlToDevice(deviceId, {
-                type: 'voice_lease_denied',
-                reason: 'quota_exhausted',
-                detail: `Daily quota reached (${accountedToday}/${dailyCap}s)`,
-            });
-            return;
-        }
-        const ttl = this.options.voiceLeaseTtlSec ?? DEFAULT_VOICE_LEASE_TTL_SEC;
-        // Signed ceiling for one lease: all the UTC days it can span. The real
-        // limit is the daily grant Head hands out on each usage report.
-        const grant = dailyCap * (Math.ceil(ttl / 86_400) + 1);
-        const lease = issuer.issue({
-            userId,
-            deviceId,
-            quotaSeconds: grant,
-            ttlSeconds: ttl,
-            resource: requestedResource,
-            nowUnixSec: nowSec,
-        });
-        try {
-            this.storage.recordVoiceLease({
-                jti: lease.payload.jti,
-                userId,
-                deviceId,
-                resource: requestedResource,
-                quotaSeconds: grant,
-                issuedAtUnixSec: lease.payload.iat,
-                expiresAtUnixSec: lease.payload.exp,
-            });
-        }
-        catch (err) {
-            logger.error('Voice lease persist failed', {
-                userId, deviceId, jti: lease.payload.jti, error: err.message,
-            });
-            this.sendControlToDevice(deviceId, {
-                type: 'voice_lease_denied',
-                reason: 'invalid_request',
-                detail: 'Lease persistence failed',
-            });
-            return;
-        }
-        logger.info('Voice lease issued', {
-            userId, deviceId, jti: lease.payload.jti,
-            quotaSeconds: grant, ttlSec: ttl, accountedToday, dailyCap,
-        });
-        this.sendControlToDevice(deviceId, { type: 'voice_lease_grant', lease });
-    }
     // --- Routing ---
     /** Send a pulse frame (control or forwarded data) to a device's socket, as a
      *  minimal unicast envelope carrying only the `pulse` field. Returns true if
@@ -670,9 +494,20 @@ export class HeadServer {
         trace('HUB-TX-WS', { to: deviceId, online, pulseB64Len: pulseB64.length });
         if (!online)
             return false;
+        // Backpressure: a connected but stalled client would otherwise grow the
+        // socket's send buffer without bound. Drop the connection instead; every
+        // reliable frame is still in the pulse outbox and resends on reconnect.
+        if (ws.bufferedAmount > MAX_WS_BUFFERED_BYTES) {
+            metrics().inc('conn.stalledClosed');
+            getLogger().warn('Closing stalled connection (send buffer full)', { deviceId, bufferedBytes: ws.bufferedAmount });
+            ws.terminate();
+            return false;
+        }
         // `to` lets the receiver's own pulse layer know which stream this is; blob
         // is empty because the payload (if any) is inside the pulse frame.
         ws.send(JSON.stringify({ type: 'unicast', to: deviceId, pulse: pulseB64, blob: '', keys: {} }));
+        metrics().inc('pulse.frames.out');
+        metrics().inc('pulse.bytes.out', pulseB64.length);
         return true;
     }
     /** Send a head-ORIGINATED control message to a device reliably over pulse
@@ -717,99 +552,7 @@ export class HeadServer {
         }
         // handleControlMessage whitelists the 4 relay-terminated types and returns
         // false for anything else, so the self-channel cannot tunnel unicast/auth/etc.
-        this.handleControlMessage(ws, state, msg);
-    }
-    /** The relay-terminated control ops, callable from BOTH the raw-WS dispatch
-     *  (onMessage) and the pulse deliver-to-self path. Returns true if handled. */
-    handleControlMessage(ws, state, msg) {
-        switch (msg.type) {
-            case 'update_preferences':
-                this.handleUpdatePreferences(ws, state, msg);
-                return true;
-            case 'update_voice_vocabulary':
-                this.handleUpdateVoiceVocabulary(state, msg);
-                return true;
-            case 'remove_device':
-                this.handleRemoveDevice(ws, state, msg.deviceId);
-                return true;
-            case 'register_push_token':
-                this.handleRegisterPushToken(ws, state, msg);
-                return true;
-            case 'unregister_push_token':
-                this.handleUnregisterPushToken(ws, state, msg);
-                return true;
-            case 'dispatch_push': {
-                const sender = state.deviceId ? this.storage.getDevice(state.deviceId) : undefined;
-                const payload = msg.payload;
-                if (sender?.role !== 'tentacle' || !payload?.preview)
-                    return true;
-                this.firePushPreview(state, payload.preview);
-                return true;
-            }
-            default: return false;
-        }
-    }
-    /** Persist a preferences update and echo the merged result to the sender + the
-     *  user's other online devices. */
-    handleUpdatePreferences(ws, state, msg) {
-        if (!state.userId)
-            return;
-        const prefs = msg.preferences;
-        if (!prefs || typeof prefs !== 'object')
-            return;
-        this.storage.updatePreferences(state.userId, prefs);
-        // Read back the full merged preferences
-        const fullUser = this.storage.getUser(state.userId);
-        const merged = publicPreferences(fullUser?.preferences ?? prefs);
-        const confirmation = { type: 'preferences_updated', preferences: merged };
-        // Confirm to the sender + fan out to the user's other devices — all over pulse.
-        if (state.deviceId)
-            this.sendControlToDevice(state.deviceId, confirmation);
-        const userDevices = (() => {
-            try {
-                return this.storage.getDevicesByUser(state.userId);
-            }
-            catch {
-                return [];
-            }
-        })();
-        for (const d of userDevices) {
-            if (d.id === state.deviceId)
-                continue;
-            const other = this.connections.get(d.id);
-            if (!other || other.readyState !== WebSocket.OPEN)
-                continue;
-            this.sendControlToDevice(d.id, confirmation);
-        }
-    }
-    /** Account data, not session data: no tentacle is involved. The sender
-     *  always gets the resulting list back (its acknowledgement); other online
-     *  apps of the account get it only when something was applied. */
-    handleUpdateVoiceVocabulary(state, msg) {
-        if (!state.userId || !state.deviceId)
-            return;
-        const requestId = typeof msg.requestId === 'string' ? msg.requestId.slice(0, 64) : undefined;
-        const ops = parseVoiceWordOps(msg.ops);
-        let words;
-        try {
-            words = ops?.length
-                ? this.storage.updateVoiceVocabulary(state.userId, ops)
-                : this.storage.getVoiceVocabulary(state.userId);
-        }
-        catch (err) {
-            // Pulse self-delivery has no outer try/catch. No reply: the client keeps
-            // the ops in its outbox and retries.
-            getLogger().warn('Voice vocabulary update failed', { error: err.message });
-            return;
-        }
-        this.sendControlToDevice(state.deviceId, { type: 'voice_vocabulary_updated', requestId, words });
-        if (!ops?.length)
-            return;
-        for (const d of this.storage.getDevicesByUser(state.userId)) {
-            if (d.id !== state.deviceId && d.role === 'app' && this.connections.get(d.id)?.readyState === WebSocket.OPEN) {
-                this.sendControlToDevice(d.id, { type: 'voice_vocabulary_updated', words });
-            }
-        }
+        handleControlMessage(this, ws, state, msg);
     }
     /** Fan-out targets for a pulse broadcast from `fromDevice`: all OTHER
      *  ONLINE devices of the same user. Offline devices are excluded because
@@ -839,46 +582,6 @@ export class HeadServer {
         }
         return targets;
     }
-    /** Notify offline devices from a pushPreview side-channel. The preview rides the
-     *  same pulse broadcast envelope as the reliable message. */
-    firePushPreview(state, pushPreview) {
-        const senderUserId = state.userId;
-        const senderDeviceId = state.deviceId;
-        if (!senderUserId || !senderDeviceId || !pushPreview) {
-            trace('PUSH-SKIP', { reason: !senderUserId ? 'no-user' : !senderDeviceId ? 'no-device' : 'no-preview' });
-            return;
-        }
-        // Online native clients that post their own notifications (macOS) get the
-        // same encrypted preview over their live connection.
-        for (const token of this.storage.getPushTokensForOfflineDevices(senderUserId, [])) {
-            if (token.provider !== 'local' || token.deviceId === senderDeviceId)
-                continue;
-            if (!this.connections.has(token.deviceId))
-                continue;
-            const key = pushPreview.keys[token.deviceId];
-            if (!key)
-                continue;
-            this.sendControlToDevice(token.deviceId, { type: 'notification_preview', payload: { blob: pushPreview.blob, key } });
-            trace('PUSH-LOCAL', { deviceId: token.deviceId });
-        }
-        if (!this.options.pushManager) {
-            trace('PUSH-SKIP', { reason: 'no-pushmgr' });
-            return;
-        }
-        const onlineDeviceIds = [senderDeviceId];
-        let offlineCount = 0;
-        for (const device of this.storage.getDevicesByUser(senderUserId)) {
-            if (device.id === senderDeviceId)
-                continue;
-            if (this.connections.get(device.id))
-                onlineDeviceIds.push(device.id);
-            else
-                offlineCount++;
-        }
-        trace('PUSH-FIRE', { sender: senderDeviceId, onlineCount: onlineDeviceIds.length, offlineCount, previewKeys: Object.keys(pushPreview.keys) });
-        this.options.pushManager.sendToOfflineDevices(senderUserId, onlineDeviceIds, pushPreview)
-            .catch(err => getLogger().warn('Push notification send failed', { error: err.message }));
-    }
     removeConnection(deviceId) {
         const ws = this.connections.get(deviceId);
         const userId = this.userByDevice.get(deviceId);
@@ -911,680 +614,16 @@ export class HeadServer {
                 this.storage.touchDeviceLastSeen(deviceId);
             }
             catch { /* storage may be closed */ }
-            this.broadcastDeviceLeft(userId, deviceId);
-        }
-    }
-    sendAuthError(ws, code, message, redirect, deviceId) {
-        if (ws.readyState === WebSocket.OPEN) {
-            ws.send(JSON.stringify({ type: 'auth_error', code, message, ...(redirect && { redirect }), ...(deviceId && { deviceId }) }));
+            broadcastDeviceLeft(this, userId, deviceId);
         }
     }
     // --- Auth ---
-    async handleAuth(ws, state, msg) {
-        state.pulseProgressAck = msg.device?.pulseProgressAck === true;
-        const logger = getLogger();
-        const { auth } = msg;
-        // If auth backend is configured, delegate everything to it
-        if (this.options.authBackend) {
-            if (auth.method === 'challenge') {
-                // Challenge is multi-step — start here, verify in handleChallengeResponse
-                const result = await this.options.authBackend.startChallenge(auth.deviceId, msg.device.encryptionKey, this.options.region);
-                if (!result.ok) {
-                    this.sendAuthError(ws, result.code, result.message, result.code === 'wrong_region' ? result.redirect : undefined);
-                    return;
-                }
-                state.pendingNonce = result.nonce;
-                state.pendingDeviceId = result.deviceId;
-                state.pendingDeviceInfo = { encryptionKey: msg.device.encryptionKey };
-                state.pendingAuthMethod = 'challenge';
-                logger.debug('Issuing auth challenge (via backend)', { deviceId: auth.deviceId });
-                ws.send(JSON.stringify({ type: 'auth_challenge', nonce: result.nonce }));
-                return;
-            }
-            const result = await this.options.authBackend.authenticate(auth, msg.device, this.options.region);
-            this.handleBackendAuthResult(ws, state, result);
-            return;
-        }
-        // Legacy: inline auth (no backend configured)
-        switch (auth.method) {
-            case 'pairing': {
-                this.handlePairingAuth(ws, state, auth.token, msg);
-                return;
-            }
-            case 'challenge': {
-                const device = this.storage.getDevice(auth.deviceId);
-                if (device && device.publicKey) {
-                    const nonce = randomBytes(32).toString('hex');
-                    state.pendingNonce = nonce;
-                    state.pendingDeviceId = auth.deviceId;
-                    state.pendingDeviceInfo = { encryptionKey: msg.device.encryptionKey };
-                    state.pendingAuthMethod = 'challenge';
-                    logger.debug('Issuing auth challenge', { deviceId: auth.deviceId });
-                    ws.send(JSON.stringify({ type: 'auth_challenge', nonce }));
-                    return;
-                }
-                this.sendAuthError(ws, 'unknown_device', 'Unknown device');
-                return;
-            }
-            case 'github_token': {
-                const provider = this.getAuthProviderForMode('github');
-                const result = await provider.authenticate({ token: auth.token, ip: state.ip });
-                if (!result.ok) {
-                    logger.warn('Auth rejected', { method: 'github_token', ip: state.ip, reason: result.message });
-                    // A GitHub outage or network error is not a bad credential (G4).
-                    this.sendAuthError(ws, result.retryable ? 'service_unavailable' : 'auth_rejected', result.message);
-                    return;
-                }
-                this.completeAuth(ws, state, result.user, msg, 'github_token');
-                return;
-            }
-            case 'github_oauth': {
-                const provider = this.getAuthProviderForMode('github');
-                const oauthAuth = auth;
-                const result = await provider.authenticate({
-                    githubCode: oauthAuth.code,
-                    codeVerifier: typeof oauthAuth.codeVerifier === 'string' ? oauthAuth.codeVerifier : undefined,
-                    redirectUri: typeof oauthAuth.redirectUri === 'string' ? oauthAuth.redirectUri : undefined,
-                    ip: state.ip,
-                });
-                if (!result.ok) {
-                    logger.warn('Auth rejected', { method: 'github_oauth', ip: state.ip, reason: result.message });
-                    // A GitHub outage or network error is not a bad credential (G4).
-                    this.sendAuthError(ws, result.retryable ? 'service_unavailable' : 'auth_rejected', result.message);
-                    return;
-                }
-                this.completeAuth(ws, state, result.user, msg, 'github_oauth');
-                return;
-            }
-            case 'apikey': {
-                const provider = this.getAuthProviderForMode('apikey');
-                const result = await provider.authenticate({ token: auth.key, ip: state.ip });
-                if (!result.ok) {
-                    logger.warn('Auth rejected', { method: 'apikey', ip: state.ip, reason: result.message });
-                    // A GitHub outage or network error is not a bad credential (G4).
-                    this.sendAuthError(ws, result.retryable ? 'service_unavailable' : 'auth_rejected', result.message);
-                    return;
-                }
-                this.completeAuth(ws, state, result.user, msg, 'apikey');
-                return;
-            }
-            case 'open': {
-                const provider = this.getAuthProviderForMode('open');
-                const result = await provider.authenticate({ token: auth.sharedKey, ip: state.ip });
-                if (!result.ok) {
-                    logger.warn('Auth rejected', { method: 'open', ip: state.ip, reason: result.message });
-                    // A GitHub outage or network error is not a bad credential (G4).
-                    this.sendAuthError(ws, result.retryable ? 'service_unavailable' : 'auth_rejected', result.message);
-                    return;
-                }
-                this.completeAuth(ws, state, result.user, msg, 'open');
-                return;
-            }
-            default: {
-                const method = auth.method;
-                this.sendAuthError(ws, 'unknown_auth_method', `Unknown auth method: ${method}`);
-            }
-        }
-    }
-    handlePairingAuth(ws, state, pairingToken, msg) {
-        const logger = getLogger();
-        if (!(this.options.pairingEnabled ?? true)) {
-            this.sendAuthError(ws, 'pairing_disabled', 'Pairing is disabled.');
-            return;
-        }
-        const tokenData = this.pairingTokens.get(pairingToken);
-        if (!tokenData || tokenData.expiresAt < Date.now()) {
-            if (tokenData)
-                this.pairingTokens.delete(pairingToken);
-            logger.warn('Pairing auth failed: invalid or expired token', { ip: state.ip });
-            this.sendAuthError(ws, 'invalid_pairing_token', 'Invalid or expired pairing token');
-            return;
-        }
-        // Consume token (single-use)
-        this.pairingTokens.delete(pairingToken);
-        const user = this.storage.getUser(tokenData.userId);
-        if (!user) {
-            this.sendAuthError(ws, 'user_not_found', 'User not found');
-            return;
-        }
-        const authUser = { id: user.userId, login: user.username, provider: user.provider, email: user.email };
-        this.completeAuth(ws, state, authUser, msg, 'pairing');
-    }
-    handleChallengeResponse(ws, state, msg) {
-        const logger = getLogger();
-        const deviceId = state.pendingDeviceId;
-        const nonce = state.pendingNonce;
-        const pendingInfo = state.pendingDeviceInfo;
-        state.pendingNonce = undefined;
-        state.pendingDeviceId = undefined;
-        state.pendingDeviceInfo = undefined;
-        if (!deviceId || !nonce) {
-            this.sendAuthError(ws, 'no_pending_challenge', 'No pending challenge');
-            return;
-        }
-        // If auth backend is configured, delegate verification
-        if (this.options.authBackend) {
-            this.options.authBackend.verifyChallenge(deviceId, nonce, msg.signature, pendingInfo?.encryptionKey, this.options.region).then(result => {
-                this.handleBackendAuthResult(ws, state, result);
-            }).catch(err => {
-                // A thrown error means the auth backend itself was unreachable / timed
-                // out (network, 5xx, abort) — NOT that the signature was invalid. A
-                // deterministic auth failure comes back as a resolved AuthError outcome
-                // above. Reporting this as auth_rejected made the arm treat a transient
-                // backend outage as a permanent credential failure and wipe the paired
-                // device, forcing a full re-pair. Surface it as auth_unavailable so the
-                // client retries instead of destroying a valid session.
-                logger.error('Auth backend verifyChallenge failed', { error: err.message });
-                this.sendAuthError(ws, 'service_unavailable', 'Authentication service unavailable');
-            });
-            return;
-        }
-        // Legacy: inline challenge verification
-        const device = this.storage.getDevice(deviceId);
-        if (!device || !device.publicKey) {
-            this.sendAuthError(ws, 'device_not_found', 'Device not found');
-            return;
-        }
-        const publicKeyPem = importPublicKey(device.publicKey);
-        const valid = verifySignature(nonce, msg.signature, publicKeyPem);
-        if (!valid) {
-            logger.warn('Challenge-response auth failed', { deviceId, ip: state.ip });
-            this.sendAuthError(ws, 'invalid_signature', 'Invalid signature');
-            return;
-        }
-        // Update encryption key if provided
-        const encryptionKey = pendingInfo?.encryptionKey ?? device.encryptionKey ?? undefined;
-        this.storage.upsertDevice(deviceId, device.userId, device.name, device.role, device.kind ?? undefined, device.publicKey ?? undefined, encryptionKey);
-        const user = this.storage.getUser(device.userId);
-        if (!user) {
-            this.sendAuthError(ws, 'user_not_found', 'User not found');
-            return;
-        }
-        // Register connection
-        state.authenticated = true;
-        state.authenticatedAt = Date.now();
-        if (state.authTimer) {
-            clearTimeout(state.authTimer);
-            state.authTimer = undefined;
-        }
-        state.deviceId = deviceId;
-        state.userId = user.userId;
-        this.evictPreviousConnection(deviceId, ws);
-        this.connections.set(deviceId, ws);
-        this.userByDevice.set(deviceId, user.userId);
-        trace('DEV-CONNECT', { device: deviceId, user: user.userId, auth: 'challenge' });
-        logger.info('Device authenticated via challenge-response', { deviceId, ip: state.ip });
-        this.completeAuthHandshake(ws, {
-            deviceId,
-            userId: user.userId,
-            user: {
-                id: user.userId,
-                login: user.username,
-                provider: user.provider,
-                email: user.email,
-            },
-            authMethod: 'challenge',
-        });
-    }
-    /**
-     * Handle a result from AuthBackend — registers connection state and sends response.
-     * Used for both initial auth and challenge-response verification.
-     */
-    handleBackendAuthResult(ws, state, result) {
-        const logger = getLogger();
-        if (!result.ok) {
-            const redirect = result.code === 'wrong_region' ? result.redirect : undefined;
-            const deviceId = result.code === 'wrong_region' ? result.deviceId : undefined;
-            this.sendAuthError(ws, result.code, result.message, redirect, deviceId);
-            return;
-        }
-        // Register connection
-        state.authenticated = true;
-        state.authenticatedAt = Date.now();
-        if (state.authTimer) {
-            clearTimeout(state.authTimer);
-            state.authTimer = undefined;
-        }
-        state.deviceId = result.deviceId;
-        state.userId = result.userId;
-        this.evictPreviousConnection(result.deviceId, ws);
-        this.connections.set(result.deviceId, ws);
-        this.userByDevice.set(result.deviceId, result.userId);
-        trace('DEV-CONNECT', { device: result.deviceId, user: result.userId, auth: 'backend' });
-        logger.info('Device authenticated (via backend)', {
-            deviceId: result.deviceId,
-            user: result.user.login,
-            method: result.authMethod,
-            ip: state.ip,
-        });
-        // Mirror user + devices into local storage so edge-local operations
-        // (broadcastDeviceJoined, getDeviceSummaries, etc.) work even when auth
-        // is delegated to a remote backend.
-        try {
-            this.storage.upsertUser(result.user.id, result.user.login, result.user.provider, result.user.email);
-            for (const d of result.devices) {
-                try {
-                    this.storage.upsertDevice(d.id, result.userId, d.name, d.role, d.kind ?? undefined, d.publicKey ?? undefined, d.encryptionKey ?? undefined);
-                }
-                catch (err) {
-                    logger.warn('Failed to mirror device locally', { deviceId: d.id, error: err.message });
-                }
-            }
-        }
-        catch (err) {
-            logger.warn('Failed to mirror user locally', { userId: result.userId, error: err.message });
-        }
-        this.completeAuthHandshake(ws, {
-            deviceId: result.deviceId,
-            userId: result.userId,
-            user: result.user,
-            authMethod: result.authMethod,
-            devices: result.devices,
-            githubClientId: result.githubClientId,
-            vapidPublicKey: result.vapidPublicKey,
-        });
-    }
-    /**
-     * Common post-auth completion logic, used by every auth path.
-     *
-     * Responsibilities:
-     *  - Read user preferences from local storage and merge into the user object.
-     *  - Flush any locally-queued pending messages for this device (offline-queue).
-     *  - Build and send the `auth_ok` response.
-     *  - Broadcast `device_joined` to the user's other connected devices.
-     *
-     * Each caller is responsible for path-specific work BEFORE calling this:
-     * validating credentials, persisting user/device records, setting up
-     * ClientState, populating `connections` / `userByDevice` maps, and logging
-     * the path-specific "authenticated via X" line.
-     *
-     * Centralising the tail eliminates a class of bugs where new auth paths
-     * (notably the multi-region delegated-backend path) silently diverge from
-     * the established post-auth flow.
-     */
-    completeAuthHandshake(ws, params) {
-        // Merge preferences. Local storage takes precedence (it captures per-edge
-        // overrides the backend might not know about), but fall back to the
-        // backend-supplied preferences if local has none — e.g. on a user's very
-        // first auth to this edge, before upsertUser has been called or when the
-        // backend is the canonical source of truth.
-        //
-        // Why this matters: storage.upsertUser only writes username/provider/email,
-        // NOT preferences. So a brand-new user record reads back with
-        // preferences=undefined. Without this fallback, backend preferences would
-        // be silently dropped at every first auth.
-        const fullUser = this.storage.getUser(params.userId);
-        const userResponse = {
-            ...params.user,
-            preferences: publicPreferences(fullUser?.preferences ?? params.user.preferences),
-        };
-        // Devices list. If the caller provided one (edge mode), recompute online
-        // status against our current connections map. Otherwise derive locally.
-        const devices = params.devices
-            ? params.devices.map(d => ({ ...d, online: this.connections.has(d.id) }))
-            : this.getDeviceSummaries(params.userId);
-        const deviceRole = devices.find((device) => device.id === params.deviceId)?.role
-            ?? this.storage.getDevice(params.deviceId)?.role;
-        ws.send(JSON.stringify({
-            type: 'auth_ok',
-            deviceId: params.deviceId,
-            authMethod: params.authMethod,
-            user: userResponse,
-            devices,
-            githubClientId: params.githubClientId ?? this.getGitHubClientId(),
-            vapidPublicKey: params.vapidPublicKey ?? this.getVapidPublicKey(),
-            relayVersion: this.options.version,
-            pulseAckBytes: PULSE_ACK_EVERY_BYTES,
-            // Apps only: a tentacle has no use for the user's word list.
-            ...(deviceRole === 'app' && { voiceVocabulary: this.storage.getVoiceVocabulary(params.userId) }),
-            ...(this.getVoiceCapability() && { voice: this.getVoiceCapability() }),
-        }));
-        // Clients only accept Pulse envelopes after processing auth_ok. Starting
-        // the endpoint before auth_ok loses the initial hello, leaving peerEpoch
-        // empty and making a later relay restart indistinguishable from the first
-        // connection. That stale recvCursor then drops the restarted seq=1..N as
-        // duplicates. Keep this ordering centralized for every auth path.
-        //
-        // Apps have explicit reconnect authorities (fresh session_list,
-        // subscription snapshot, and history ranges). If their HELLO carries a new
-        // process epoch, fence the preceding process's non-durable downlink so the
-        // new UI cannot animate through old live events. Tentacle downlinks carry
-        // commands and retain ordinary Pulse resume semantics across process epochs.
-        this.pulseHub.onDeviceConnected(params.deviceId, {
-            discardPreviousProcessNonDurable: deviceRole === 'app',
-        });
-        this.broadcastDeviceJoined(params.userId, params.deviceId);
-    }
-    /**
-     * A device is about to register `ws` as its connection. If the SAME device id
-     * already had a socket, that older socket is now orphaned: once we overwrite
-     * the map entry its close handler hits the reconnect-guard and skips cleanup,
-     * and the ping timer (which only walks `connections`) never visits it again.
-     * It would sit in `clients` holding its ClientState until TCP finally gives
-     * up. Retire both the WebSocket and its Pulse link explicitly before the new
-     * connection is installed.
-     *
-     * Must be called BEFORE `connections.set(deviceId, ws)`.
-     */
-    evictPreviousConnection(deviceId, ws) {
-        const previous = this.connections.get(deviceId);
-        if (!previous || previous === ws)
-            return;
-        getLogger().info('Replacing existing connection for device', { deviceId });
-        // The old close callback will see the replacement in `connections` and skip
-        // its guarded cleanup. Publish the Pulse disconnect here so capability and
-        // connection-scoped state cannot leak across the replacement boundary.
-        this.pulseHub.onDeviceDisconnected(deviceId);
-        this.clients.delete(previous);
-        try {
-            previous.terminate();
-        }
-        catch { /* best effort */ }
-    }
-    completeAuth(ws, state, user, msg, authMethod) {
-        const logger = getLogger();
-        // Persist user
-        this.storage.upsertUser(user.id, user.login, user.provider, user.email);
-        // Register device
-        const deviceId = msg.device.deviceId ?? `dev_${uuid().slice(0, 12)}`;
-        try {
-            this.storage.upsertDevice(deviceId, user.id, msg.device.name, msg.device.role, msg.device.kind, msg.device.publicKey, msg.device.encryptionKey);
-        }
-        catch (err) {
-            logger.warn('Device registration failed', { ip: state.ip, error: err.message });
-            this.sendAuthError(ws, 'device_registration_failed', err.message);
-            return;
-        }
-        state.authenticated = true;
-        state.authenticatedAt = Date.now();
-        if (state.authTimer) {
-            clearTimeout(state.authTimer);
-            state.authTimer = undefined;
-        }
-        state.deviceId = deviceId;
-        state.userId = user.id;
-        this.evictPreviousConnection(deviceId, ws);
-        this.connections.set(deviceId, ws);
-        this.userByDevice.set(deviceId, user.id);
-        trace('DEV-CONNECT', { device: deviceId, user: user.id, auth: 'inline' });
-        logger.info('Device authenticated', {
-            deviceId,
-            name: msg.device.name,
-            role: msg.device.role,
-            user: user.login,
-            ip: state.ip,
-        });
-        this.completeAuthHandshake(ws, {
-            deviceId,
-            userId: user.id,
-            user: {
-                id: user.id,
-                login: user.login,
-                provider: user.provider,
-                email: user.email,
-            },
-            authMethod,
-        });
-    }
     // --- Pairing tokens (in-memory) ---
-    handleCreatePairingToken(ws, state) {
-        const logger = getLogger();
-        if (!(this.options.pairingEnabled ?? true)) {
-            this.sendError(ws, 'Pairing is disabled on this relay');
-            return;
-        }
-        if (!state.userId) {
-            this.sendError(ws, 'Not authenticated');
-            return;
-        }
-        if (this.options.authBackend) {
-            try {
-                const result = this.options.authBackend.createPairingToken(state.userId);
-                logger.info('Pairing token created (via backend)', { userId: state.userId });
-                ws.send(JSON.stringify({ type: 'pairing_token_created', token: result.token, expiresIn: result.expiresIn }));
-            }
-            catch {
-                // Remote backend needs async — fall through to error
-                this.sendError(ws, 'Pairing not available in remote mode');
-            }
-            return;
-        }
-        const token = `pt_${randomBytes(32).toString('hex')}`;
-        const ttl = this.options.pairingTtl ?? 300;
-        this.pairingTokens.set(token, {
-            userId: state.userId,
-            expiresAt: Date.now() + ttl * 1000,
-        });
-        logger.info('Pairing token created', { userId: state.userId, ttl });
-        ws.send(JSON.stringify({
-            type: 'pairing_token_created',
-            token,
-            expiresIn: ttl,
-        }));
-    }
-    async handleRequestPairingToken(ws, state, msg) {
-        const logger = getLogger();
-        if (!(this.options.pairingEnabled ?? true)) {
-            this.sendError(ws, 'Pairing is disabled on this relay');
-            return;
-        }
-        if (!msg.token) {
-            this.sendError(ws, 'Token required for pairing request');
-            return;
-        }
-        // If auth backend is configured, delegate
-        if (this.options.authBackend) {
-            const result = await this.options.authBackend.requestPairingToken(msg.token, state.ip);
-            if (!result.ok) {
-                this.sendAuthError(ws, result.code, result.message);
-                return;
-            }
-            logger.info('Pairing token created (one-shot, via backend)', { userId: result.userId });
-            ws.send(JSON.stringify({
-                type: 'pairing_token_created',
-                token: result.pairingToken,
-                expiresIn: result.expiresIn,
-            }));
-            return;
-        }
-        // Legacy: inline pairing token creation
-        let authResult = { ok: false, message: 'No auth provider accepted the token' };
-        for (const provider of (this.options.authProviders?.values() ?? [])) {
-            authResult = await provider.authenticate({ token: msg.token, ip: state.ip });
-            if (authResult.ok)
-                break;
-        }
-        if (!authResult.ok && this.options.authProvider && !this.options.authProviders?.size) {
-            authResult = await this.options.authProvider.authenticate({ token: msg.token, ip: state.ip });
-        }
-        if (!authResult.ok) {
-            this.sendAuthError(ws, 'auth_rejected', authResult.message);
-            return;
-        }
-        this.storage.upsertUser(authResult.user.id, authResult.user.login, authResult.user.provider, authResult.user.email);
-        const token = `pt_${randomBytes(32).toString('hex')}`;
-        const ttl = this.options.pairingTtl ?? 300;
-        this.pairingTokens.set(token, {
-            userId: authResult.user.id,
-            expiresAt: Date.now() + ttl * 1000,
-        });
-        logger.info('Pairing token created (one-shot)', { userId: authResult.user.id, ttl });
-        ws.send(JSON.stringify({
-            type: 'pairing_token_created',
-            token,
-            expiresIn: ttl,
-        }));
-    }
     // --- Device presence notifications ---
-    handleRemoveDevice(ws, state, targetDeviceId) {
-        const logger = getLogger();
-        if (!state.userId || !state.deviceId) {
-            this.sendError(ws, 'Not authenticated');
-            return;
-        }
-        if (!targetDeviceId || typeof targetDeviceId !== 'string') {
-            this.sendError(ws, 'Missing deviceId');
-            return;
-        }
-        const targetDevice = this.storage.getDevice(targetDeviceId);
-        if (!targetDevice || targetDevice.userId !== state.userId) {
-            this.sendError(ws, 'Device not found');
-            return;
-        }
-        // Only allow removing offline devices (zombie cleanup)
-        if (this.connections.has(targetDeviceId)) {
-            this.sendError(ws, 'Cannot remove an online device');
-            return;
-        }
-        this.storage.deleteDevice(targetDeviceId);
-        this.storage.deletePushTokensForDevice(targetDeviceId);
-        // Drop the device's pulse endpoint + persisted outbox/snapshot/capability
-        // rows too. Otherwise they outlive the device record forever, and
-        // recoverOnBoot faithfully rebuilds an endpoint for a device that can
-        // never authenticate again.
-        this.pulseHub.forgetDevice(targetDeviceId);
-        logger.info('Device removed', { deviceId: targetDeviceId, byDevice: state.deviceId });
-        // Edge mode: the account service owns the device list and every auth
-        // mirrors it back here, so the removal must reach it too (otherwise the
-        // device reappears after the next reconnect).
-        const remote = this.options.authBackend;
-        if (remote instanceof RemoteAuthBackend) {
-            const userId = state.userId;
-            remote.removeDevice(userId, targetDeviceId).then((ok) => {
-                if (!ok)
-                    logger.warn('Account service did not remove device', { deviceId: targetDeviceId });
-            }).catch((err) => {
-                logger.warn('Failed to remove device at account service', { deviceId: targetDeviceId, error: err.message });
-            });
-        }
-        // Broadcast removal to all remaining user devices
-        this.broadcastDeviceRemoved(state.userId, targetDeviceId);
-    }
+    // --- Account deletion ---
+    /** Users whose deletion is in flight (a double tap must not run it twice). */
+    deletingAccounts = new Set();
     // --- Push token management ---
-    handleRegisterPushToken(ws, state, msg) {
-        const logger = getLogger();
-        if (!state.userId || !state.deviceId) {
-            this.sendError(ws, 'Not authenticated');
-            return;
-        }
-        const payload = msg.payload;
-        if (!payload || typeof payload.token !== 'string' || typeof payload.provider !== 'string') {
-            this.sendError(ws, 'Invalid push token: payload.token and payload.provider required');
-            return;
-        }
-        this.storage.upsertPushToken(state.deviceId, payload.provider, payload.token, payload.environment, payload.bundleId);
-        // Clean up push tokens from stale devices (offline >24h) to prevent
-        // duplicate notifications from abandoned PWA installs on the same phone.
-        const onlineDeviceIds = Array.from(this.connections.keys());
-        const pruned = this.storage.deleteStaleUserPushTokens(state.userId, state.deviceId, onlineDeviceIds);
-        if (pruned > 0) {
-            logger.info('Pruned stale push tokens', { userId: state.userId, count: pruned });
-        }
-        logger.info('Push token registered', { deviceId: state.deviceId, provider: payload.provider });
-        if (state.deviceId) {
-            this.sendControlToDevice(state.deviceId, { type: 'push_token_registered', payload: { provider: payload.provider } });
-        }
-    }
-    handleUnregisterPushToken(ws, state, msg) {
-        const logger = getLogger();
-        if (!state.userId || !state.deviceId) {
-            this.sendError(ws, 'Not authenticated');
-            return;
-        }
-        const payload = msg.payload;
-        if (!payload || typeof payload.provider !== 'string') {
-            this.sendError(ws, 'Invalid unregister: payload.provider required');
-            return;
-        }
-        this.storage.deletePushToken(state.deviceId, payload.provider);
-        logger.info('Push token unregistered', { deviceId: state.deviceId, provider: payload.provider });
-    }
-    broadcastDeviceRemoved(userId, removedDeviceId) {
-        let userDevices;
-        try {
-            userDevices = this.storage.getDevicesByUser(userId);
-        }
-        catch {
-            return;
-        }
-        for (const d of userDevices) {
-            const ws = this.connections.get(d.id);
-            if (!ws || ws.readyState !== WebSocket.OPEN)
-                continue;
-            this.sendPresenceToDevice(d.id, { type: 'device_removed', deviceId: removedDeviceId });
-        }
-    }
-    broadcastDeviceJoined(userId, newDeviceId) {
-        let device;
-        try {
-            device = this.storage.getDevice(newDeviceId);
-        }
-        catch {
-            return;
-        } // Storage may be closed during shutdown
-        if (!device)
-            return;
-        const summary = {
-            id: device.id,
-            name: device.name,
-            role: device.role,
-            kind: device.kind ?? undefined,
-            publicKey: device.publicKey ?? undefined,
-            encryptionKey: device.encryptionKey ?? undefined,
-            online: true,
-            lastSeen: device.lastSeen,
-            createdAt: device.createdAt,
-        };
-        let userDevices;
-        try {
-            userDevices = this.storage.getDevicesByUser(userId);
-        }
-        catch {
-            return;
-        }
-        for (const d of userDevices) {
-            if (d.id === newDeviceId)
-                continue;
-            const ws = this.connections.get(d.id);
-            if (!ws || ws.readyState !== WebSocket.OPEN)
-                continue;
-            this.sendPresenceToDevice(d.id, { type: 'device_joined', device: summary });
-        }
-    }
-    broadcastDeviceLeft(userId, leftDeviceId) {
-        let userDevices;
-        try {
-            userDevices = this.storage.getDevicesByUser(userId);
-        }
-        catch {
-            return;
-        } // Storage may be closed during shutdown
-        for (const d of userDevices) {
-            if (d.id === leftDeviceId)
-                continue;
-            const ws = this.connections.get(d.id);
-            if (!ws || ws.readyState !== WebSocket.OPEN)
-                continue;
-            this.sendPresenceToDevice(d.id, { type: 'device_left', deviceId: leftDeviceId });
-        }
-    }
-    broadcastDevicePending(userId, pendingDeviceId) {
-        let userDevices;
-        try {
-            userDevices = this.storage.getDevicesByUser(userId);
-        }
-        catch {
-            return;
-        }
-        for (const d of userDevices) {
-            if (d.id === pendingDeviceId)
-                continue;
-            const ws = this.connections.get(d.id);
-            if (!ws || ws.readyState !== WebSocket.OPEN)
-                continue;
-            this.sendPresenceToDevice(d.id, { type: 'device_pending', deviceId: pendingDeviceId });
-        }
-    }
     /** Handle pong from either protocol-level or JSON pong.
      *  Re-promotes to device_joined if we already broadcast device_pending.
      *  Guards against stale pongs from replaced connections (reconnect race). */
@@ -1606,30 +645,32 @@ export class HeadServer {
             const activeWs = this.connections.get(state.deviceId);
             const activeState = activeWs ? this.clients.get(activeWs) : null;
             if (activeState === state) {
-                this.broadcastDeviceJoined(state.userId, state.deviceId);
+                broadcastDeviceJoined(this, state.userId, state.deviceId);
             }
         }
     }
     // --- Helpers ---
-    getDeviceSummaries(userId) {
-        const stored = this.storage.getDevicesByUser(userId);
-        return stored.map(d => ({
-            id: d.id,
-            name: d.name,
-            role: d.role,
-            kind: d.kind ?? undefined,
-            publicKey: d.publicKey ?? undefined,
-            encryptionKey: d.encryptionKey ?? undefined,
-            online: this.connections.has(d.id),
-            lastSeen: d.lastSeen,
-            createdAt: d.createdAt,
-        }));
-    }
     sendError(ws, message) {
         if (ws.readyState === WebSocket.OPEN) {
             ws.send(JSON.stringify({ type: 'server_error', message }));
         }
     }
+    /** Live gauges for `/internal/metrics` (counts only). */
+    getGauges() {
+        let durableRows = -1;
+        try {
+            durableRows = this.storage.rawDb.prepare('SELECT COUNT(*) AS n FROM pulse_outbox').get().n;
+        }
+        catch { /* table may not exist yet */ }
+        const mem = process.memoryUsage();
+        return {
+            connections: this.connections.size,
+            endpoints: this.pulseHub.endpointCount(),
+            durableRows,
+            rssMb: Math.round(mem.rss / 1048576),
+            heapUsedMb: Math.round(mem.heapUsed / 1048576),
+        };
+    }
     getStats() {
         const onlineUserIds = new Set();
         const connectionList = [];
@@ -1652,8 +693,9 @@ export class HeadServer {
             });
         }
         const allUsers = this.storage.getAllUsers();
+        const devicesByUser = this.storage.getAllDevicesByUser();
         const registeredUsers = allUsers.map(u => {
-            const devices = this.storage.getDevicesByUser(u.userId);
+            const devices = devicesByUser.get(u.userId) ?? [];
             return {
                 userId: u.userId,
                 username: u.username,