@kraki/head 0.1.0 → 0.4.0

package/dist/server.js

@@ -1,40 +1,24 @@
 import { WebSocketServer, WebSocket } from 'ws';
 import { randomBytes, createVerify } from 'crypto';
+import { v4 as uuid } from 'uuid';
 import { GitHubAuthProvider } from './auth.js';
 import { getLogger } from './logger.js';
-/**
- * Import a compact base64 public key to PEM format.
- */
 function importPublicKey(compactKey) {
     const lines = compactKey.match(/.{1,64}/g) ?? [];
     return `-----BEGIN PUBLIC KEY-----\n${lines.join('\n')}\n-----END PUBLIC KEY-----\n`;
 }
-/**
- * Verify a challenge-response signature.
- */
 function verifySignature(nonce, signature, publicKeyPem) {
     const verify = createVerify('SHA256');
     verify.update(nonce);
     return verify.verify(publicKeyPem, signature, 'base64');
 }
 const DEFAULT_MAX_PAYLOAD = 10 * 1024 * 1024;
-const DEFAULT_PING_INTERVAL = 30_000;
-const DEFAULT_PONG_TIMEOUT = 10_000; // 10MB
-/**
- * Basic message validation guard.
- * Checks structural requirements — not full schema validation.
- */
 function isValidMessage(msg) {
     if (typeof msg !== 'object' || msg === null)
         return false;
     const obj = msg;
-    if (typeof obj.type !== 'string' || obj.type.length === 0)
-        return false;
-    if ('payload' in obj && (typeof obj.payload !== 'object' || obj.payload === null))
-        return false;
-    return true;
+    return typeof obj.type === 'string' && obj.type.length > 0;
 }
-/** Validate auth message shape */
 function isValidAuth(msg) {
     if (!msg.device || typeof msg.device !== 'object')
         return false;
@@ -43,39 +27,34 @@ function isValidAuth(msg) {
         return false;
     if (dev.role !== 'tentacle' && dev.role !== 'app')
         return false;
-    return true;
-}
-/** Validate create_session payload */
-function isValidCreateSession(msg) {
-    if (!msg.payload || typeof msg.payload !== 'object')
-        return false;
-    const p = msg.payload;
-    if (typeof p.targetDeviceId !== 'string')
+    if (!msg.auth || typeof msg.auth !== 'object')
         return false;
-    if (typeof p.model !== 'string')
-        return false;
-    if (typeof p.requestId !== 'string')
+    const auth = msg.auth;
+    if (typeof auth.method !== 'string')
         return false;
     return true;
 }
-/** Validate encrypted envelope */
-function isValidEncrypted(msg) {
-    return typeof msg.iv === 'string' && typeof msg.ciphertext === 'string'
-        && typeof msg.tag === 'string' && typeof msg.keys === 'object' && msg.keys !== null;
+function isValidUnicast(msg) {
+    return msg.type === 'unicast' && typeof msg.to === 'string'
+        && typeof msg.blob === 'string' && typeof msg.keys === 'object' && msg.keys !== null;
+}
+function isValidBroadcast(msg) {
+    return msg.type === 'broadcast'
+        && typeof msg.blob === 'string' && typeof msg.keys === 'object' && msg.keys !== null;
 }
 export class HeadServer {
     wss;
-    cm;
-    router;
+    storage;
     options;
+    static PING_INTERVAL = 30_000;
+    // In-memory state
+    connections = new Map();
+    pairingTokens = new Map();
+    userByDevice = new Map();
     clients = new Map();
     pingTimer = null;
-    /** Dedup: track recently seen client message IDs to prevent duplicates */
-    recentClientMsgIds = new Set();
-    dedupCleanupTimer = null;
-    constructor(cm, router, options) {
-        this.cm = cm;
-        this.router = router;
+    constructor(storage, options) {
+        this.storage = storage;
         this.options = options;
         this.wss = new WebSocketServer({
             noServer: true,
@@ -83,40 +62,38 @@ export class HeadServer {
         });
         this.wss.on('connection', (ws, req) => this.onConnection(ws, req));
         this.startPingInterval();
-        this.startDedupCleanup();
     }
-    /** Resolve the auth provider (multi-provider or legacy single). */
+    startPingInterval() {
+        this.pingTimer = setInterval(() => {
+            const msg = JSON.stringify({ type: 'ping' });
+            for (const [deviceId, ws] of this.connections) {
+                try {
+                    if (ws.readyState === WebSocket.OPEN)
+                        ws.send(msg);
+                }
+                catch {
+                    this.removeConnection(deviceId);
+                }
+            }
+        }, HeadServer.PING_INTERVAL);
+    }
+    // --- Auth provider helpers ---
     getAuthProvider() {
         if (this.options.authProviders?.size) {
-            // Return first provider as default (actual selection happens per-request)
             return this.options.authProviders.values().next().value;
         }
         return this.options.authProvider;
     }
-    /** Get supported auth mode names. */
-    getAuthModes() {
-        if (this.options.authModes?.length)
-            return this.options.authModes;
-        if (this.options.authProviders?.size)
-            return [...this.options.authProviders.keys()];
-        return [this.options.authProvider?.name ?? 'open'];
-    }
-    /** Resolve auth provider by mode name (for multi-provider). */
     getAuthProviderForMode(mode) {
         if (mode && this.options.authProviders?.has(mode)) {
             return this.options.authProviders.get(mode);
         }
         return this.getAuthProvider();
     }
-    /** Get the GitHub OAuth client ID if configured (for auth_info_response). */
     getGitHubClientId() {
         const ghProvider = this.findGitHubProvider();
-        if (ghProvider?.oauthConfigured) {
-            return { githubClientId: ghProvider.getClientId() };
-        }
-        return {};
+        return ghProvider?.oauthConfigured ? ghProvider.getClientId() : undefined;
     }
-    /** Find the GitHubAuthProvider in the provider chain (unwrapping throttle). */
     findGitHubProvider() {
         const provider = this.options.authProviders?.get('github') ?? this.options.authProvider;
         if (!provider)
@@ -130,19 +107,7 @@ export class HeadServer {
         }
         return undefined;
     }
-    /** Resolve the channel owner's user info for auth_ok. */
-    getChannelOwnerUser(channelId) {
-        const channel = this.cm.getStorage().getChannel(channelId);
-        if (!channel)
-            return undefined;
-        const user = this.cm.getStorage().getUser(channel.ownerId);
-        if (!user)
-            return undefined;
-        return { id: user.userId, login: user.username, provider: user.provider, email: user.email };
-    }
-    /**
-     * Attach to an HTTP server for upgrade handling.
-     */
+    // --- Connection management ---
     attach(server) {
         server.on('upgrade', (req, socket, head) => {
             this.wss.handleUpgrade(req, socket, head, (ws) => {
@@ -150,23 +115,16 @@ export class HeadServer {
             });
         });
     }
-    /**
-     * Accept a raw WebSocket connection (for testing without HTTP server).
-     */
     acceptConnection(ws) {
         this.onConnection(ws);
     }
     onConnection(ws, req) {
         const ip = req?.socket?.remoteAddress ?? req?.headers['x-forwarded-for']?.toString() ?? 'unknown';
-        const state = { authenticated: false, ip, alive: true };
+        const state = { authenticated: false, ip };
         const logger = getLogger();
         this.clients.set(ws, state);
         logger.debug('WebSocket connected', { ip });
-        ws.on('pong', () => {
-            state.alive = true;
-        });
         ws.on('message', (data) => {
-            state.alive = true;
             try {
                 const msg = JSON.parse(data.toString());
                 if (!isValidMessage(msg)) {
@@ -183,15 +141,15 @@ export class HeadServer {
             }
         });
         ws.on('close', () => {
-            if (state.deviceId && state.channelId) {
-                const device = this.cm.disconnectDevice(state.deviceId);
-                if (device) {
-                    logger.info('Device disconnected', { deviceId: state.deviceId, name: device.name });
-                    this.router.broadcastNotice(state.channelId, {
-                        type: 'head_notice',
-                        event: 'device_offline',
-                        data: { deviceId: state.deviceId },
-                    });
+            if (state.deviceId) {
+                const disconnectedDeviceId = state.deviceId;
+                const disconnectedUserId = state.userId;
+                this.connections.delete(disconnectedDeviceId);
+                this.userByDevice.delete(disconnectedDeviceId);
+                logger.info('Device disconnected', { deviceId: disconnectedDeviceId });
+                // Notify other connected devices that this device left
+                if (disconnectedUserId) {
+                    this.broadcastDeviceLeft(disconnectedUserId, disconnectedDeviceId);
                 }
             }
             this.clients.delete(ws);
@@ -201,32 +159,32 @@ export class HeadServer {
         });
     }
     async onMessage(ws, state, msg) {
-        // Handle ping/pong
-        if (msg.type === 'ping') {
-            ws.send(JSON.stringify({ type: 'pong' }));
-            return;
-        }
-        // Dedup: if client provides a clientMsgId, check for duplicates
-        if (typeof msg.clientMsgId === 'string') {
-            if (this.trackClientMsgId(msg.clientMsgId)) {
-                getLogger().debug('Duplicate message dropped', { clientMsgId: msg.clientMsgId });
-                return;
-            }
-        }
-        // One-shot pairing token request — no device registration, handled before auth
+        // One-shot pairing token request — before auth
         if (msg.type === 'request_pairing_token') {
             await this.handleRequestPairingToken(ws, state, msg);
             return;
         }
-        // Must auth first
+        // Pre-auth: auth_info, auth, auth_response
         if (!state.authenticated) {
             if (msg.type === 'auth_info') {
+                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',
-                    authModes: this.getAuthModes(),
-                    e2e: this.options.e2e,
-                    pairing: this.options.pairingEnabled !== false,
-                    ...this.getGitHubClientId(),
+                    methods,
+                    githubClientId: this.getGitHubClientId(),
                 }));
                 return;
             }
@@ -245,430 +203,451 @@ export class HeadServer {
             }
             return;
         }
-        // Validate type-specific messages
-        if (msg.type === 'encrypted' && !isValidEncrypted(msg)) {
-            this.sendError(ws, 'Invalid encrypted message: iv, ciphertext, tag, keys required');
-            return;
-        }
-        if (msg.type === 'create_session' && !isValidCreateSession(msg)) {
-            this.sendError(ws, 'Invalid create_session: requestId, targetDeviceId, model required');
+        // Authenticated messages
+        if (msg.type === 'create_pairing_token') {
+            this.handleCreatePairingToken(ws, state);
             return;
         }
-        // Handle control messages
-        if (msg.type === 'replay') {
-            const replay = msg;
-            if (!state.deviceId)
+        if (msg.type === 'unicast') {
+            if (!isValidUnicast(msg)) {
+                this.sendError(ws, 'Invalid unicast: to, blob, keys required');
                 return;
-            this.router.replay(state.deviceId, replay.afterSeq, replay.sessionId);
+            }
+            this.handleUnicast(ws, state, msg);
             return;
         }
-        if (msg.type === 'mark_read') {
-            if (!state.channelId)
+        if (msg.type === 'broadcast') {
+            if (!isValidBroadcast(msg)) {
+                this.sendError(ws, 'Invalid broadcast: blob, keys required');
                 return;
-            const { sessionId, seq } = msg;
-            if (sessionId && typeof seq === 'number') {
-                this.cm.getStorage().markRead(state.channelId, sessionId, seq);
-                // Notify other devices so they can sync unread state
-                this.router.broadcastNotice(state.channelId, {
-                    type: 'head_notice',
-                    event: 'read_state_updated',
-                    data: { sessionId, lastSeq: seq },
-                });
             }
+            this.handleBroadcast(state, msg);
             return;
         }
-        if (msg.type === 'create_pairing_token') {
-            this.handleCreatePairingToken(ws, state);
+        if (msg.type === 'update_preferences') {
+            if (state.userId) {
+                const prefs = msg.preferences;
+                if (prefs && typeof prefs === 'object') {
+                    this.storage.updatePreferences(state.userId, prefs);
+                    ws.send(JSON.stringify({ type: 'preferences_updated', preferences: prefs }));
+                }
+            }
             return;
         }
-        if (msg.type === 'delete_session') {
-            this.handleDeleteSession(ws, state, msg);
+        if (msg.type === 'ping') {
+            ws.send(JSON.stringify({ type: 'pong' }));
             return;
         }
-        // Handle producer, consumer, and encrypted messages
-        if (state.deviceId) {
-            this.router.handleMessage(state.deviceId, msg);
+        if (msg.type === 'pong') {
+            return; // silently accept pong responses
         }
+        this.sendError(ws, `Unknown message type: ${msg.type}`);
     }
-    handleCreatePairingToken(ws, state) {
+    // --- Routing ---
+    handleUnicast(ws, state, msg) {
         const logger = getLogger();
-        if (!(this.options.pairingEnabled ?? true)) {
-            this.sendError(ws, 'Pairing is disabled on this relay');
+        const senderUserId = state.userId;
+        if (!senderUserId || !state.deviceId)
+            return;
+        // Verify target belongs to same user
+        const targetDevice = this.storage.getDevice(msg.to);
+        if (!targetDevice || targetDevice.userId !== senderUserId) {
+            logger.warn('Unicast rejected: target not found or wrong user', { from: state.deviceId, to: msg.to });
+            ws.send(JSON.stringify({ type: 'server_error', message: 'Target device not found or offline', ref: msg.ref }));
             return;
         }
-        if (!state.channelId) {
-            this.sendError(ws, 'Not authenticated');
+        const targetWs = this.connections.get(msg.to);
+        if (!targetWs) {
+            logger.debug('Unicast target offline', { to: msg.to });
+            ws.send(JSON.stringify({ type: 'server_error', message: 'Target device not found or offline', ref: msg.ref }));
             return;
         }
-        const token = `pt_${randomBytes(32).toString('hex')}`;
-        const ttl = this.options.pairingTtl ?? 300;
-        const expiresAt = new Date(Date.now() + ttl * 1000).toISOString();
-        this.cm.getStorage().createPairingToken(token, state.channelId, expiresAt);
-        logger.info('Pairing token created', { channelId: state.channelId, ttl });
-        ws.send(JSON.stringify({
-            type: 'pairing_token_created',
-            token,
-            expiresIn: ttl,
-        }));
+        try {
+            if (targetWs.readyState === WebSocket.OPEN) {
+                targetWs.send(JSON.stringify(msg));
+            }
+        }
+        catch {
+            logger.warn('Unicast send failed, removing connection', { to: msg.to });
+            this.removeConnection(msg.to);
+        }
     }
-    handleDeleteSession(ws, state, msg) {
+    handleBroadcast(state, msg) {
         const logger = getLogger();
-        if (!state.channelId) {
-            this.sendError(ws, 'Not authenticated');
+        const senderUserId = state.userId;
+        const senderDeviceId = state.deviceId;
+        if (!senderUserId || !senderDeviceId)
             return;
+        // Find all other connected devices for this user
+        const userDevices = this.storage.getDevicesByUser(senderUserId);
+        for (const device of userDevices) {
+            if (device.id === senderDeviceId)
+                continue;
+            const targetWs = this.connections.get(device.id);
+            if (!targetWs)
+                continue;
+            try {
+                if (targetWs.readyState === WebSocket.OPEN) {
+                    targetWs.send(JSON.stringify(msg));
+                }
+            }
+            catch {
+                logger.warn('Broadcast send failed, removing connection', { to: device.id });
+                this.removeConnection(device.id);
+            }
         }
-        if (!msg.sessionId || typeof msg.sessionId !== 'string') {
-            this.sendError(ws, 'sessionId required for delete_session');
-            return;
+    }
+    removeConnection(deviceId) {
+        const ws = this.connections.get(deviceId);
+        this.connections.delete(deviceId);
+        this.userByDevice.delete(deviceId);
+        if (ws) {
+            try {
+                ws.close();
+            }
+            catch { /* best effort */ }
         }
-        const session = this.cm.getStorage().getSessionById(msg.sessionId);
-        if (!session || session.channelId !== state.channelId) {
-            this.sendError(ws, 'Session not found');
-            return;
+    }
+    sendAuthError(ws, code, message) {
+        ws.send(JSON.stringify({ type: 'auth_error', code, message }));
+    }
+    // --- Auth ---
+    async handleAuth(ws, state, msg) {
+        const logger = getLogger();
+        const { auth } = msg;
+        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 });
+                    this.sendAuthError(ws, 'auth_rejected', result.message);
+                    return;
+                }
+                this.completeAuth(ws, state, result.user, msg, 'github_token');
+                return;
+            }
+            case 'github_oauth': {
+                const provider = this.getAuthProviderForMode('github');
+                const result = await provider.authenticate({ githubCode: auth.code, ip: state.ip });
+                if (!result.ok) {
+                    logger.warn('Auth rejected', { method: 'github_oauth', ip: state.ip, reason: result.message });
+                    this.sendAuthError(ws, '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 });
+                    this.sendAuthError(ws, '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 });
+                    this.sendAuthError(ws, '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}`);
+            }
         }
-        this.cm.deleteSession(msg.sessionId, state.channelId);
-        logger.info('Session deleted', { sessionId: msg.sessionId, channelId: state.channelId });
-        this.router.broadcastNotice(state.channelId, {
-            type: 'head_notice',
-            event: 'session_removed',
-            data: { sessionId: msg.sessionId },
-        });
     }
-    /**
-     * One-shot pairing token request. Validates auth token inline,
-     * creates a pairing token, responds, and requires no device registration.
-     */
-    async handleRequestPairingToken(ws, state, msg) {
+    handlePairingAuth(ws, state, pairingToken, msg) {
         const logger = getLogger();
         if (!(this.options.pairingEnabled ?? true)) {
-            this.sendError(ws, 'Pairing is disabled on this relay');
+            this.sendAuthError(ws, 'pairing_disabled', 'Pairing is disabled.');
             return;
         }
-        if (!msg.token) {
-            this.sendError(ws, 'Token required for pairing request');
+        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;
         }
-        const authResult = await this.getAuthProvider().authenticate({
-            token: msg.token,
-            ip: state.ip,
-        });
-        if (!authResult.ok) {
-            ws.send(JSON.stringify({ type: 'auth_error', message: authResult.message }));
+        // 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 channelId = this.cm.getOrCreateChannel(authResult.user);
-        const token = `pt_${randomBytes(32).toString('hex')}`;
-        const ttl = this.options.pairingTtl ?? 300;
-        const expiresAt = new Date(Date.now() + ttl * 1000).toISOString();
-        this.cm.getStorage().createPairingToken(token, channelId, expiresAt);
-        logger.info('Pairing token created (one-shot)', { channelId, ttl });
-        ws.send(JSON.stringify({
-            type: 'pairing_token_created',
-            token,
-            expiresIn: ttl,
-        }));
+        const authUser = { id: user.userId, login: user.username, provider: user.provider, email: user.email };
+        this.completeAuth(ws, state, authUser, msg, 'pairing');
     }
-    async handleAuth(ws, state, msg) {
+    handleChallengeResponse(ws, state, msg) {
         const logger = getLogger();
-        // Try pairing token auth first
-        if (msg.pairingToken) {
-            this.handlePairingAuth(ws, state, msg);
+        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;
         }
-        // Try challenge-response for returning devices with a known deviceId + publicKey
-        if (msg.device.deviceId && !msg.token && !msg.channelKey && !msg.githubCode) {
-            const device = this.cm.getStorage().getDevice(msg.device.deviceId);
-            if (device && device.publicKey) {
-                // Known device with public key — issue challenge
-                const nonce = randomBytes(32).toString('hex');
-                state.pendingNonce = nonce;
-                state.pendingDeviceId = msg.device.deviceId;
-                state.pendingDeviceInfo = {
-                    encryptionKey: msg.device.encryptionKey,
-                    capabilities: msg.device.capabilities,
-                };
-                logger.debug('Issuing auth challenge', { deviceId: msg.device.deviceId });
-                ws.send(JSON.stringify({ type: 'auth_challenge', nonce }));
-                return;
-            }
+        const device = this.storage.getDevice(deviceId);
+        if (!device || !device.publicKey) {
+            this.sendAuthError(ws, 'device_not_found', 'Device not found');
+            return;
         }
-        // Route to GitHub provider when an OAuth code is provided
-        const githubCode = msg.githubCode;
-        const authProvider = githubCode
-            ? this.getAuthProviderForMode('github')
-            : this.getAuthProvider();
-        const authResult = await authProvider.authenticate({
-            token: msg.token,
-            channelKey: msg.channelKey,
-            githubCode,
-            ip: state.ip,
-        });
-        if (!authResult.ok) {
-            logger.warn('Auth rejected', { ip: state.ip, reason: authResult.message });
-            ws.send(JSON.stringify({ type: 'auth_error', message: authResult.message }));
+        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;
         }
-        const channelId = this.cm.getOrCreateChannel(authResult.user);
-        let deviceId;
+        // Register connection
+        state.authenticated = true;
+        state.deviceId = deviceId;
+        state.userId = user.userId;
+        this.connections.set(deviceId, ws);
+        this.userByDevice.set(deviceId, user.userId);
+        logger.info('Device authenticated via challenge-response', { deviceId, ip: state.ip });
+        const fullUser = this.storage.getUser(user.userId);
+        ws.send(JSON.stringify({
+            type: 'auth_ok',
+            deviceId,
+            authMethod: 'challenge',
+            user: { id: user.userId, login: user.username, provider: user.provider, preferences: fullUser?.preferences },
+            devices: this.getDeviceSummaries(user.userId),
+            githubClientId: this.getGitHubClientId(),
+            relayVersion: this.options.version,
+        }));
+        // Notify other connected devices about the reconnected device
+        this.broadcastDeviceJoined(user.userId, deviceId);
+    }
+    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 {
-            deviceId = this.cm.registerDevice({
-                channelId,
-                name: msg.device.name,
-                role: msg.device.role,
-                send: (data) => {
-                    if (ws.readyState === WebSocket.OPEN)
-                        ws.send(data);
-                },
-                kind: msg.device.kind,
-                publicKey: msg.device.publicKey,
-                encryptionKey: msg.device.encryptionKey,
-                capabilities: msg.device.capabilities,
-                clientDeviceId: msg.device.deviceId,
-            });
+            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 });
-            ws.send(JSON.stringify({ type: 'auth_error', message: err.message }));
+            this.sendAuthError(ws, 'device_registration_failed', err.message);
             return;
         }
         state.authenticated = true;
         state.deviceId = deviceId;
-        state.channelId = channelId;
+        state.userId = user.id;
+        this.connections.set(deviceId, ws);
+        this.userByDevice.set(deviceId, user.id);
         logger.info('Device authenticated', {
             deviceId,
             name: msg.device.name,
             role: msg.device.role,
-            user: authResult.user.login,
+            user: user.login,
             ip: state.ip,
         });
+        const fullUser = this.storage.getUser(user.id);
         ws.send(JSON.stringify({
             type: 'auth_ok',
-            channel: channelId,
             deviceId,
-            e2e: this.options.e2e,
-            devices: this.cm.getDeviceSummaries(channelId),
-            sessions: this.cm.getSessionSummaries(channelId),
-            readState: this.cm.getStorage().getReadState(channelId),
-            user: this.getChannelOwnerUser(channelId),
-            ...this.getGitHubClientId(),
+            authMethod,
+            user: { id: user.id, login: user.login, provider: user.provider, preferences: fullUser?.preferences },
+            devices: this.getDeviceSummaries(user.id),
+            githubClientId: this.getGitHubClientId(),
+            relayVersion: this.options.version,
         }));
-        // Notify other devices
-        this.router.broadcastNotice(channelId, {
-            type: 'head_notice',
-            event: 'device_online',
-            data: {
-                device: {
-                    id: deviceId,
-                    name: msg.device.name,
-                    role: msg.device.role,
-                    kind: msg.device.kind,
-                    publicKey: msg.device.publicKey,
-                    encryptionKey: msg.device.encryptionKey,
-                    capabilities: msg.device.capabilities,
-                    online: true,
-                },
-            },
-        });
+        // Notify other connected devices about the new device
+        this.broadcastDeviceJoined(user.id, deviceId);
     }
-    handlePairingAuth(ws, state, msg) {
+    // --- Pairing tokens (in-memory) ---
+    handleCreatePairingToken(ws, state) {
         const logger = getLogger();
         if (!(this.options.pairingEnabled ?? true)) {
-            ws.send(JSON.stringify({ type: 'auth_error', message: 'Pairing is disabled. Use OAuth to authenticate.' }));
-            return;
-        }
-        const pairingToken = msg.pairingToken;
-        const channelId = this.cm.getStorage().consumePairingToken(pairingToken);
-        if (!channelId) {
-            logger.warn('Pairing auth failed: invalid or expired token', { ip: state.ip });
-            ws.send(JSON.stringify({ type: 'auth_error', message: 'Invalid or expired pairing token' }));
+            this.sendError(ws, 'Pairing is disabled on this relay');
             return;
         }
-        let deviceId;
-        try {
-            deviceId = this.cm.registerDevice({
-                channelId,
-                name: msg.device.name,
-                role: msg.device.role,
-                send: (data) => {
-                    if (ws.readyState === WebSocket.OPEN)
-                        ws.send(data);
-                },
-                kind: msg.device.kind,
-                publicKey: msg.device.publicKey,
-                encryptionKey: msg.device.encryptionKey,
-                capabilities: msg.device.capabilities,
-                clientDeviceId: msg.device.deviceId,
-            });
-        }
-        catch (err) {
-            logger.warn('Device registration failed (pairing)', { ip: state.ip, error: err.message });
-            ws.send(JSON.stringify({ type: 'auth_error', message: err.message }));
+        if (!state.userId) {
+            this.sendError(ws, 'Not authenticated');
             return;
         }
-        state.authenticated = true;
-        state.deviceId = deviceId;
-        state.channelId = channelId;
-        logger.info('Device paired via token', { deviceId, name: msg.device.name, ip: state.ip });
+        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: 'auth_ok',
-            channel: channelId,
-            deviceId,
-            e2e: this.options.e2e,
-            devices: this.cm.getDeviceSummaries(channelId),
-            sessions: this.cm.getSessionSummaries(channelId),
-            readState: this.cm.getStorage().getReadState(channelId),
-            user: this.getChannelOwnerUser(channelId),
-            ...this.getGitHubClientId(),
+            type: 'pairing_token_created',
+            token,
+            expiresIn: ttl,
         }));
-        this.router.broadcastNotice(channelId, {
-            type: 'head_notice',
-            event: 'device_online',
-            data: {
-                device: {
-                    id: deviceId,
-                    name: msg.device.name,
-                    role: msg.device.role,
-                    kind: msg.device.kind,
-                    publicKey: msg.device.publicKey,
-                    encryptionKey: msg.device.encryptionKey,
-                    capabilities: msg.device.capabilities,
-                    online: true,
-                },
-            },
-        });
     }
-    handleChallengeResponse(ws, state, msg) {
+    async handleRequestPairingToken(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) {
-            ws.send(JSON.stringify({ type: 'auth_error', message: 'No pending challenge' }));
+        if (!(this.options.pairingEnabled ?? true)) {
+            this.sendError(ws, 'Pairing is disabled on this relay');
             return;
         }
-        const device = this.cm.getStorage().getDevice(deviceId);
-        if (!device || !device.publicKey) {
-            ws.send(JSON.stringify({ type: 'auth_error', message: 'Device not found' }));
+        if (!msg.token) {
+            this.sendError(ws, 'Token required for pairing request');
             return;
         }
-        // Verify signature
-        const publicKeyPem = importPublicKey(device.publicKey);
-        const valid = verifySignature(nonce, msg.signature, publicKeyPem);
-        if (!valid) {
-            logger.warn('Challenge-response auth failed', { deviceId, ip: state.ip });
-            ws.send(JSON.stringify({ type: 'auth_error', message: 'Invalid signature' }));
-            return;
+        // Try all configured auth providers until one succeeds
+        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;
         }
-        // Use encryptionKey from the auth message (may be new/updated)
-        const encryptionKey = pendingInfo?.encryptionKey ?? device.encryptionKey ?? undefined;
-        let registeredId;
-        try {
-            registeredId = this.cm.registerDevice({
-                channelId: device.channelId,
-                name: device.name,
-                role: device.role,
-                send: (data) => {
-                    if (ws.readyState === WebSocket.OPEN)
-                        ws.send(data);
-                },
-                kind: device.kind ?? undefined,
-                publicKey: device.publicKey ?? undefined,
-                encryptionKey,
-                clientDeviceId: deviceId,
-            });
+        // Fall back to legacy single provider if no authProviders map
+        if (!authResult.ok && this.options.authProvider && !this.options.authProviders?.size) {
+            authResult = await this.options.authProvider.authenticate({ token: msg.token, ip: state.ip });
         }
-        catch (err) {
-            logger.warn('Device registration failed (challenge)', { deviceId, error: err.message });
-            ws.send(JSON.stringify({ type: 'auth_error', message: err.message }));
+        if (!authResult.ok) {
+            this.sendAuthError(ws, 'auth_rejected', authResult.message);
             return;
         }
-        state.authenticated = true;
-        state.deviceId = registeredId;
-        state.channelId = device.channelId;
-        logger.info('Device authenticated via challenge-response', { deviceId, ip: state.ip });
+        // Ensure user exists
+        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: 'auth_ok',
-            channel: device.channelId,
-            deviceId: registeredId,
-            e2e: this.options.e2e,
-            devices: this.cm.getDeviceSummaries(device.channelId),
-            sessions: this.cm.getSessionSummaries(device.channelId),
-            readState: this.cm.getStorage().getReadState(device.channelId),
-            user: this.getChannelOwnerUser(device.channelId),
-            ...this.getGitHubClientId(),
+            type: 'pairing_token_created',
+            token,
+            expiresIn: ttl,
         }));
-        this.router.broadcastNotice(device.channelId, {
-            type: 'head_notice',
-            event: 'device_online',
-            data: {
-                device: {
-                    id: registeredId,
-                    name: device.name,
-                    role: device.role,
-                    kind: device.kind ?? undefined,
-                    publicKey: device.publicKey ?? undefined,
-                    encryptionKey,
-                    online: true,
-                },
-            },
-        });
     }
-    sendError(ws, message) {
-        if (ws.readyState === WebSocket.OPEN) {
-            ws.send(JSON.stringify({ type: 'server_error', message }));
+    // --- Device presence notifications ---
+    broadcastDeviceJoined(userId, newDeviceId) {
+        let device;
+        try {
+            device = this.storage.getDevice(newDeviceId);
         }
-    }
-    startPingInterval() {
-        const interval = this.options.pingInterval ?? DEFAULT_PING_INTERVAL;
-        if (interval <= 0)
+        catch {
             return;
-        const timeout = this.options.pongTimeout ?? DEFAULT_PONG_TIMEOUT;
-        const logger = getLogger();
-        this.pingTimer = setInterval(() => {
-            for (const [ws, state] of this.clients) {
-                if (!state.alive) {
-                    logger.warn('Device ping timeout, terminating', { deviceId: state.deviceId, ip: state.ip });
-                    ws.terminate();
-                    continue;
+        } // 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,
+        };
+        const msg = JSON.stringify({ type: 'device_joined', device: summary });
+        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) {
+                try {
+                    ws.send(msg);
                 }
-                state.alive = false;
-                if (ws.readyState === WebSocket.OPEN) {
-                    ws.ping();
+                catch { /* best effort */ }
+            }
+        }
+    }
+    broadcastDeviceLeft(userId, leftDeviceId) {
+        const msg = JSON.stringify({ type: 'device_left', deviceId: 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) {
+                try {
+                    ws.send(msg);
                 }
+                catch { /* best effort */ }
             }
-        }, interval);
+        }
     }
-    startDedupCleanup() {
-        // Clear dedup set periodically and bound max size
-        this.dedupCleanupTimer = setInterval(() => {
-            this.recentClientMsgIds.clear();
-        }, 5 * 60_000);
+    // --- 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),
+        }));
     }
-    /** Guard against unbounded dedup set growth */
-    trackClientMsgId(id) {
-        if (this.recentClientMsgIds.has(id))
-            return true; // duplicate
-        if (this.recentClientMsgIds.size > 10_000) {
-            this.recentClientMsgIds.clear(); // safety valve
-        }
-        this.recentClientMsgIds.add(id);
-        return false;
+    sendError(ws, message) {
+        if (ws.readyState === WebSocket.OPEN) {
+            ws.send(JSON.stringify({ type: 'server_error', message }));
+        }
     }
-    /**
-     * Close the server and all connections.
-     */
     close() {
         if (this.pingTimer) {
             clearInterval(this.pingTimer);
             this.pingTimer = null;
         }
-        if (this.dedupCleanupTimer) {
-            clearInterval(this.dedupCleanupTimer);
-            this.dedupCleanupTimer = null;
-        }
         for (const ws of this.clients.keys()) {
             ws.close();
         }