@kraki/head 0.20.0 → 0.20.1

package/dist/server.js

@@ -1,11 +1,9 @@
 import { RemoteAuthBackend } from './remote-auth-backend.js';
 import { WebSocketServer, WebSocket } from 'ws';
-import { randomBytes, createVerify } from 'crypto';
-import { v4 as uuid } from 'uuid';
-import { HEAD_PULSE_TARGET } from '@kraki/protocol';
+import { HEAD_PULSE_TARGET, ACCOUNT_DELETED_CLOSE_CODE, DEVICE_REPLACED_CLOSE_CODE } 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 { LocalAuthBackend } from './local-auth-backend.js';
 import { getLogger } from './logger.js';
 import { trace, fp } from './trace.js';
 import { clientIp } from './client-ip.js';
@@ -18,15 +16,6 @@ function publicPreferences(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;
@@ -35,6 +24,8 @@ 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;
+/** Send-buffer ceiling per socket before a stalled client is disconnected. */
+const MAX_WS_BUFFERED_BYTES = 32 * 1024 * 1024;
 /** 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. */
@@ -70,7 +61,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 +72,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,
@@ -154,10 +160,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;
@@ -226,22 +229,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 +248,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 +287,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());
@@ -389,37 +368,13 @@ export class HeadServer {
         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') {
@@ -439,7 +394,7 @@ export class HeadServer {
         }
         // Authenticated messages
         if (msg.type === 'create_pairing_token') {
-            this.handleCreatePairingToken(ws, state);
+            await this.handleCreatePairingToken(ws, state);
             return;
         }
         if (msg.type === 'unicast') {
@@ -465,7 +420,10 @@ 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');
                         return;
                     }
@@ -526,8 +484,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)
+                // Push previews are tentacle-originated (same rule as dispatch_push).
+                if (msg.pushPreview && this.storage.getDevice(state.deviceId)?.role === 'tentacle') {
                     this.firePushPreview(state, msg.pushPreview);
+                }
                 this.pulseHub.onPulseEnvelope(state.deviceId, { pulse: msg.pulse });
                 return;
             }
@@ -670,6 +630,14 @@ 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) {
+            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: {} }));
@@ -732,6 +700,9 @@ export class HeadServer {
             case 'remove_device':
                 this.handleRemoveDevice(ws, state, msg.deviceId);
                 return true;
+            case 'delete_account':
+                void this.handleDeleteAccount(ws, state);
+                return true;
             case 'register_push_token':
                 this.handleRegisterPushToken(ws, state, msg);
                 return true;
@@ -924,11 +895,21 @@ export class HeadServer {
         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) {
+        // One auth attempt per socket at a time: a second `auth` while the first
+        // is awaiting its backend would register the device twice.
+        if (state.authInFlight || state.pendingNonce) {
+            // Ignored rather than answered with auth_error: clients treat auth
+            // errors as credential failures, and this one is just a duplicate.
+            logger.warn('Ignoring duplicate auth while one is in progress', { ip: state.ip });
+            return;
+        }
+        state.authInFlight = true;
+        try {
             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);
+                const result = await this.authBackend.startChallenge(auth.deviceId, msg.device.encryptionKey, this.options.region);
+                if (!this.socketStillAuthenticating(ws, state))
+                    return;
                 if (!result.ok) {
                     this.sendAuthError(ws, result.code, result.message, result.code === 'wrong_region' ? result.redirect : undefined);
                     return;
@@ -937,118 +918,24 @@ export class HeadServer {
                 state.pendingDeviceId = result.deviceId;
                 state.pendingDeviceInfo = { encryptionKey: msg.device.encryptionKey };
                 state.pendingAuthMethod = 'challenge';
-                logger.debug('Issuing auth challenge (via backend)', { deviceId: auth.deviceId });
+                logger.debug('Issuing auth challenge', { 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);
+            const result = await this.authBackend.authenticate(auth, msg.device, this.options.region, state.ip);
+            if (!this.socketStillAuthenticating(ws, state))
+                return;
             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}`);
-            }
+        finally {
+            state.authInFlight = false;
         }
     }
-    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');
+    /** After an awaited auth step: is this socket still open, still ours and
+     *  still unauthenticated? The auth deadline may have closed it meanwhile;
+     *  registering a dead socket would evict the device's live connection. */
+    socketStillAuthenticating(ws, state) {
+        return ws.readyState === WebSocket.OPEN && this.clients.get(ws) === state && !state.authenticated;
     }
     handleChallengeResponse(ws, state, msg) {
         const logger = getLogger();
@@ -1062,68 +949,25 @@ export class HeadServer {
             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 });
+        state.authInFlight = true;
+        this.authBackend.verifyChallenge(deviceId, nonce, msg.signature, pendingInfo?.encryptionKey, this.options.region).then(result => {
+            if (!this.socketStillAuthenticating(ws, state))
+                return;
+            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 });
+            if (this.socketStillAuthenticating(ws, state)) {
                 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',
+            }
+        }).finally(() => {
+            state.authInFlight = false;
         });
     }
     /**
@@ -1231,7 +1075,7 @@ export class HeadServer {
             authMethod: params.authMethod,
             user: userResponse,
             devices,
-            githubClientId: params.githubClientId ?? this.getGitHubClientId(),
+            githubClientId: params.githubClientId ?? this.authBackend.getAuthInfo().githubClientId,
             vapidPublicKey: params.vapidPublicKey ?? this.getVapidPublicKey(),
             relayVersion: this.options.version,
             pulseAckBytes: PULSE_ACK_EVERY_BYTES,
@@ -1275,59 +1119,26 @@ export class HeadServer {
         // its guarded cleanup. Publish the Pulse disconnect here so capability and
         // connection-scoped state cannot leak across the replacement boundary.
         this.pulseHub.onDeviceDisconnected(deviceId);
+        const previousState = this.clients.get(previous);
+        if (previousState)
+            previousState.evicted = true;
         this.clients.delete(previous);
+        // Say why (a bare terminate() reads as a network drop, and a client that
+        // reconnects on it evicts this new connection in turn). Force the TCP
+        // teardown shortly after in case the old peer never completes the close.
         try {
-            previous.terminate();
+            previous.close(DEVICE_REPLACED_CLOSE_CODE, 'replaced');
         }
         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;
+        const force = setTimeout(() => { try {
+            previous.terminate();
         }
-        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,
-        });
+        catch { /* already gone */ } }, 2_000);
+        force.unref?.();
+        previous.once('close', () => clearTimeout(force));
     }
     // --- Pairing tokens (in-memory) ---
-    handleCreatePairingToken(ws, state) {
+    async handleCreatePairingToken(ws, state) {
         const logger = getLogger();
         if (!(this.options.pairingEnabled ?? true)) {
             this.sendError(ws, 'Pairing is disabled on this relay');
@@ -1337,30 +1148,23 @@ export class HeadServer {
             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 });
+        try {
+            // A remote (edge) backend creates tokens on the account service.
+            const backend = this.authBackend;
+            const result = backend.createPairingTokenAsync
+                ? await backend.createPairingTokenAsync(state.userId)
+                : backend.createPairingToken(state.userId);
+            if (!result?.token)
+                throw new Error('no token returned');
+            logger.info('Pairing token created', { userId: state.userId });
+            if (ws.readyState === WebSocket.OPEN) {
                 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,
-        }));
+        catch (err) {
+            logger.warn('Pairing token creation failed', { userId: state.userId, error: err.message });
+            this.sendError(ws, 'Pairing is temporarily unavailable');
+        }
     }
     async handleRequestPairingToken(ws, state, msg) {
         const logger = getLogger();
@@ -1372,47 +1176,18 @@ export class HeadServer {
             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,
-            }));
+        const result = await this.authBackend.requestPairingToken(msg.token, state.ip);
+        if (ws.readyState !== WebSocket.OPEN)
             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);
+        if (!result.ok) {
+            this.sendAuthError(ws, result.code, result.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 });
+        logger.info('Pairing token created (one-shot)', { userId: result.userId });
         ws.send(JSON.stringify({
             type: 'pairing_token_created',
-            token,
-            expiresIn: ttl,
+            token: result.pairingToken,
+            expiresIn: result.expiresIn,
         }));
     }
     // --- Device presence notifications ---
@@ -1447,7 +1222,7 @@ export class HeadServer {
         // 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;
+        const remote = this.authBackend;
         if (remote instanceof RemoteAuthBackend) {
             const userId = state.userId;
             remote.removeDevice(userId, targetDeviceId).then((ok) => {
@@ -1460,6 +1235,65 @@ export class HeadServer {
         // 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();
+    /**
+     * Delete the requesting user's account: at the account store (the account
+     * service in edge mode) and in this relay's own storage and pulse state.
+     * Then tell every connected device and close it. Devices that were offline
+     * get `auth_error` code `account_deleted` when they next connect.
+     */
+    async handleDeleteAccount(ws, state) {
+        const logger = getLogger();
+        const userId = state.userId;
+        const deviceId = state.deviceId;
+        if (!userId || !deviceId) {
+            this.sendError(ws, 'Not authenticated');
+            return;
+        }
+        if (this.storage.getDevice(deviceId)?.role !== 'app') {
+            this.sendError(ws, 'Only the Kraki app can delete the account');
+            return;
+        }
+        if (this.deletingAccounts.has(userId))
+            return;
+        this.deletingAccounts.add(userId);
+        try {
+            const deviceIds = new Set(this.storage.getDevicesByUser(userId).map((d) => d.id));
+            if (this.authBackend.deleteAccount) {
+                for (const id of await this.authBackend.deleteAccount(userId))
+                    deviceIds.add(id);
+            }
+            // This relay's own rows (the edge mirror; already gone when the
+            // account store is this relay's storage).
+            for (const id of this.storage.deleteUser(userId))
+                deviceIds.add(id);
+            logger.info('Account deleted', { userId, devices: deviceIds.size, byDevice: deviceId });
+            for (const id of deviceIds) {
+                const socket = this.connections.get(id);
+                if (socket) {
+                    // Detach before closing so the close handler doesn't announce
+                    // device_left or touch the deleted rows.
+                    this.connections.delete(id);
+                    this.userByDevice.delete(id);
+                    this.clients.delete(socket);
+                    if (socket.readyState === WebSocket.OPEN) {
+                        socket.send(JSON.stringify({ type: 'account_deleted' }));
+                        socket.close(ACCOUNT_DELETED_CLOSE_CODE, 'account_deleted');
+                    }
+                }
+                this.pulseHub.forgetDevice(id);
+            }
+        }
+        catch (err) {
+            logger.error('Account deletion failed', { userId, error: err.message });
+            this.sendError(ws, 'Could not delete the account. Try again.');
+        }
+        finally {
+            this.deletingAccounts.delete(userId);
+        }
+    }
     // --- Push token management ---
     handleRegisterPushToken(ws, state, msg) {
         const logger = getLogger();
@@ -1475,7 +1309,11 @@ export class HeadServer {
         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());
+        // Only this user's devices matter; passing every connection on the relay
+        // made each registration O(global connections) in SQL parameters.
+        const onlineDeviceIds = this.storage.getDevicesByUser(state.userId)
+            .map((d) => d.id)
+            .filter((id) => this.connections.has(id));
         const pruned = this.storage.deleteStaleUserPushTokens(state.userId, state.deviceId, onlineDeviceIds);
         if (pruned > 0) {
             logger.info('Pruned stale push tokens', { userId: state.userId, count: pruned });
@@ -1652,8 +1490,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,