termdock 1.4.173 → 1.4.175

package/dist/server/cli.js

@@ -10,6 +10,12 @@ import { resolve } from 'path';
 // dotenv 不会覆盖已存在的环境变量，因此系统环境变量和命令行参数优先级最高
 loadDotenv({ path: resolve(os.homedir(), '.termdock', '.env'), quiet: true });
 loadDotenv({ path: resolve(process.cwd(), '.env'), quiet: true });
+// Federation commands run before normal server/terminal CLI initialization.
+if (process.argv.slice(2).some(arg => arg === '--federation-pairing' || arg === '--federation-relay')) {
+    const { runFederationCli } = await import('./federation/cli.js');
+    process.exit(await runFederationCli(process.argv.slice(2)));
+}
+import { parseCollaborationCommand, executeCollaborationCommand, COLLAB_HELP } from './agent/collaborationCli.js';
 import fs from 'fs';
 import http from 'http';
 import https from 'https';
@@ -183,7 +189,7 @@ Short commands:
                      Emit one lifecycle/status event from an Agent hook.
   pi                 Same as agent-plugin
   collab status      Show this Session's collaboration groups and peers
-  collab inbox       Read and acknowledge collaboration messages
+  collab inbox       Read messages without acknowledging (see collab --help)
   collab send <session-id> <message>
                      Send a durable message to a related Session
   collab handoff <session-id> <summary>
@@ -678,53 +684,11 @@ function parseArgs(argv) {
             }
         }
         else if (command === 'collab') {
-            const action = (next || 'status');
-            const json = argv.includes('--json');
-            if (action === 'status' || action === 'inbox') {
-                collab = { action, json };
-            }
-            else if (action === 'send' || action === 'handoff' || action === 'reply') {
-                const target = argv[2];
-                const message = argv.slice(3).filter((part) => part !== '--json').join(' ').trim();
-                if (!target || !message) {
-                    console.error(`${ICON.err} ${c.red(`Usage: td collab ${action} <${action === 'reply' ? 'message-id' : 'session-id'}> <message>`)}`);
-                    process.exit(1);
-                }
-                collab = { action, target, message, json };
-            }
-            else if (action === 'add' || action === 'remove') {
-                const groupId = argv[2];
-                const sessionId = argv[3];
-                if (!groupId || !sessionId || groupId.startsWith('-') || sessionId.startsWith('-')) {
-                    console.error(`${ICON.err} ${c.red(`Usage: td collab ${action} <group-id> <session-id>`)}`);
-                    process.exit(1);
-                }
-                collab = { action, groupId, sessionId, json };
-            }
-            else if (action === 'spawn') {
-                const groupId = argv[2];
-                const agentSlug = argv[3];
-                const optionValue = (flag) => {
-                    const index = argv.indexOf(flag);
-                    const value = index >= 0 ? argv[index + 1] : undefined;
-                    return value && !value.startsWith('--') ? value : undefined;
-                };
-                if (!groupId || !agentSlug || groupId.startsWith('-') || agentSlug.startsWith('-')) {
-                    console.error(`${ICON.err} ${c.red('Usage: td collab spawn <group-id> <agent-slug> [--name <name>] [--cwd <path>] [--task <text>]')}`);
-                    process.exit(1);
-                }
-                collab = {
-                    action,
-                    groupId,
-                    agentSlug,
-                    name: optionValue('--name'),
-                    cwd: optionValue('--cwd'),
-                    task: optionValue('--task'),
-                    json,
-                };
+            try {
+                collab = parseCollaborationCommand(argv.slice(1));
             }
-            else {
-                console.error(`${ICON.err} ${c.red('Usage: td collab <status|inbox|send|handoff|reply|add|remove|spawn>')}`);
+            catch (error) {
+                console.error(JSON.stringify({ ok: false, code: 'INVALID_ARGUMENT', error: error instanceof Error ? error.message : String(error) }));
                 process.exit(1);
             }
             argv = [];
@@ -1219,7 +1183,7 @@ async function readStdinText() {
         process.stdin.on('error', reject);
     });
 }
-async function postLocalJson(baseUrl, token, endpoint, payload) {
+async function postLocalJson(baseUrl, token, endpoint, payload, timeoutMs = 30_000) {
     const url = new URL(endpoint, baseUrl);
     const body = JSON.stringify(payload);
     const isHttps = url.protocol === 'https:';
@@ -1244,12 +1208,14 @@ async function postLocalJson(baseUrl, token, endpoint, payload) {
             res.on('data', (chunk) => { responseBody += chunk; });
             res.on('end', () => resolve({ statusCode: res.statusCode ?? 0, body: responseBody }));
         });
+        const timer = setTimeout(() => req.destroy(new Error('Local collaboration request timed out')), timeoutMs);
+        req.on('close', () => clearTimeout(timer));
         req.on('error', reject);
         req.write(body);
         req.end();
     });
 }
-async function getLocalJson(baseUrl, token, endpoint) {
+async function getLocalJson(baseUrl, token, endpoint, timeoutMs = 30_000) {
     const url = new URL(endpoint, baseUrl);
     const isHttps = url.protocol === 'https:';
     const requestImpl = isHttps ? https.request : http.request;
@@ -1271,14 +1237,20 @@ async function getLocalJson(baseUrl, token, endpoint) {
             res.on('data', (chunk) => { responseBody += chunk; });
             res.on('end', () => resolve({ statusCode: res.statusCode ?? 0, body: responseBody }));
         });
+        const timer = setTimeout(() => req.destroy(new Error('Local collaboration request timed out')), timeoutMs);
+        req.on('close', () => clearTimeout(timer));
         req.on('error', reject);
         req.end();
     });
 }
 async function runCollab(command) {
+    if (command.action === 'help') {
+        console.log(COLLAB_HELP);
+        return;
+    }
     const runningState = getRunningState();
     if (!runningState?.localApiToken) {
-        console.error(`${ICON.err} ${c.red('Termdock is not running or its local API token is unavailable.')}`);
+        console.error(JSON.stringify({ ok: false, code: 'SERVICE_UNAVAILABLE', error: 'Termdock is not running or its local API token is unavailable.' }));
         process.exit(1);
     }
     const backendSessionId = process.env.TERMDOCK_BACKEND_SESSION_ID?.trim() || null;
@@ -1299,123 +1271,16 @@ async function runCollab(command) {
         }
     }
     if (!backendSessionId && !tmuxSessionName) {
-        console.error(`${ICON.err} ${c.red('td collab must run inside a Termdock-managed Session.')}`);
+        console.error(JSON.stringify({ ok: false, code: 'SESSION_NOT_FOUND', error: 'td collab must run inside a Termdock-managed Session.' }));
         process.exit(1);
     }
     const context = backendSessionId ? { backendSessionId } : { tmuxSessionName };
-    const contextQuery = new URLSearchParams(Object.entries(context).filter((entry) => typeof entry[1] === 'string')).toString();
     const baseUrl = runningState.localUrl
         ?? `${runningState.scheme ?? 'http'}://${runningState.host === '0.0.0.0' ? 'localhost' : runningState.host}:${runningState.port}`;
-    let response;
-    if (command.action === 'status') {
-        response = await getLocalJson(baseUrl, runningState.localApiToken, `/api/terminal/operations/orchestration/peers?${contextQuery}`);
-    }
-    else if (command.action === 'inbox') {
-        response = await getLocalJson(baseUrl, runningState.localApiToken, `/api/terminal/operations/orchestration/inbox?${contextQuery}&markRead=true`);
-    }
-    else if (command.action === 'reply') {
-        response = await postLocalJson(baseUrl, runningState.localApiToken, '/api/terminal/operations/orchestration/reply', {
-            ...context,
-            messageId: command.target,
-            content: command.message,
-        });
-    }
-    else if (command.action === 'add' || command.action === 'remove') {
-        response = await postLocalJson(baseUrl, runningState.localApiToken, '/api/terminal/operations/orchestration/members', {
-            ...context,
-            groupId: command.groupId,
-            targetSessionId: command.sessionId,
-            action: command.action,
-        });
-    }
-    else if (command.action === 'spawn') {
-        response = await postLocalJson(baseUrl, runningState.localApiToken, '/api/terminal/operations/orchestration/spawn', {
-            ...context,
-            groupId: command.groupId,
-            agentSlug: command.agentSlug,
-            name: command.name,
-            cwd: command.cwd,
-            task: command.task,
-        });
-    }
-    else {
-        response = await postLocalJson(baseUrl, runningState.localApiToken, '/api/terminal/operations/orchestration/send', {
-            ...context,
-            targetSessionId: command.target,
-            message: command.message,
-            kind: command.action === 'handoff' ? 'handoff' : 'message',
-        });
-    }
-    let body = {};
-    try {
-        body = JSON.parse(response.body || '{}');
-    }
-    catch { /* handled below */ }
-    if (response.statusCode < 200 || response.statusCode >= 300) {
-        console.error(`${ICON.err} ${c.red(typeof body.error === 'string' ? body.error : 'Collaboration request failed')}`);
-        process.exit(1);
-    }
-    if (command.json) {
-        console.log(JSON.stringify(body, null, 2));
-        return;
-    }
-    if (command.action === 'status') {
-        const groups = Array.isArray(body.groups) ? body.groups : [];
-        const peers = Array.isArray(body.peers) ? body.peers : [];
-        const sessions = Array.isArray(body.sessions) ? body.sessions : [];
-        const agents = Array.isArray(body.agents) ? body.agents : [];
-        console.log(`${ICON.ok} ${c.green(`Collaboration: ${groups.length} group(s), ${peers.length} peer(s)`)}`);
-        for (const group of groups) {
-            console.log(`  ${c.green(group.name ?? 'Group')} ${c.dim(`[${group.id ?? ''}]`)}`);
-            if (group.sessionIds?.length)
-                console.log(`    ${c.dim(`${group.sessionIds.length} member(s)`)}`);
-        }
-        if (peers.length > 0)
-            console.log(`\n${c.dim('Current group peers:')}`);
-        for (const peer of peers) {
-            console.log(`  ${c.cyan(peer.name ?? peer.sessionId ?? 'Session')} ${c.dim(`[${peer.sessionId ?? ''}]`)}`);
-            console.log(`    ${peer.status ?? 'offline'} · ${peer.capability ?? ''}`);
-            if (peer.currentTask)
-                console.log(`    ${c.dim(peer.currentTask)}`);
-        }
-        for (const group of groups) {
-            const memberIds = new Set(group.sessionIds ?? []);
-            const candidates = sessions.filter((session) => session.sessionId && !memberIds.has(session.sessionId));
-            if (candidates.length > 0) {
-                console.log(`\n${c.dim(`Sessions available to add to ${group.name ?? 'group'} [${group.id ?? ''}]:`)}`);
-                for (const session of candidates) {
-                    console.log(`  ${session.name ?? 'Session'} ${c.dim(`[${session.sessionId ?? ''}]`)} · ${session.status ?? 'offline'}`);
-                    if (session.cwd)
-                        console.log(`    ${c.dim(session.cwd)}`);
-                }
-            }
-        }
-        if (agents.length > 0) {
-            console.log(`\n${c.dim('Agent types available to spawn:')}`);
-            for (const agent of agents)
-                console.log(`  ${agent.displayName ?? agent.slug ?? 'Agent'} ${c.dim(`[${agent.slug ?? ''}]`)}`);
-        }
-        return;
-    }
-    if (command.action === 'inbox') {
-        const messages = Array.isArray(body.messages) ? body.messages : [];
-        if (messages.length === 0) {
-            console.log(`${ICON.ok} ${c.dim('Collaboration inbox is empty.')}`);
-            return;
-        }
-        for (const message of messages) {
-            console.log(`${c.cyan(message.kind ?? 'message')} ${c.dim(`#${message.id ?? ''}`)} from ${message.fromSessionId ?? 'user'}`);
-            console.log(`  ${message.content ?? ''}`);
-        }
-        return;
-    }
-    const success = command.action === 'reply' ? 'Reply sent.'
-        : command.action === 'handoff' ? 'Handoff sent.'
-            : command.action === 'add' ? 'Session added to collaboration group.'
-                : command.action === 'remove' ? 'Session removed from collaboration group.'
-                    : command.action === 'spawn' ? 'Agent Session created and added to collaboration group.'
-                        : 'Message sent.';
-    console.log(`${ICON.ok} ${c.green(success)}`);
+    process.exitCode = await executeCollaborationCommand(command, Object.fromEntries(Object.entries(context).filter((entry) => typeof entry[1] === 'string')), { request: (method, endpoint, body, timeout) => method === 'GET'
+            ? getLocalJson(baseUrl, runningState.localApiToken, endpoint, timeout)
+            : postLocalJson(baseUrl, runningState.localApiToken, endpoint, body, timeout),
+        write: (line) => console.log(line), stdin: readStdinText });
 }
 async function runInjectChangeAudit(source) {
     const raw = source === true
@@ -3458,7 +3323,7 @@ async function main() {
     }
     if (options.collab) {
         await runCollab(options.collab);
-        process.exit(0);
+        return; // Preserve the receipt exit code and allow piped JSON output to drain.
     }
     if (options.pluginInit) {
         if (options.pluginInitJson)

package/dist/server/entry.js

@@ -1,7 +1,14 @@
+import { createOpenAccessRouter } from './federation/openAccess.js';
+import { createPasswordLoginRouter } from './federation/passwordLoginRoutes.js';
 import { apiAccessGate, isTrustedLocalRequest } from './utils/apiAccess.js';
+import { isEncryptedRequest } from './federation/requestContext.js';
+import { createFederationRuntime } from './federation/runtime.js';
+import { RouteAccess } from './federation/routeAccess.js';
+import { RouteInvitationStore } from './federation/routeInvitations.js';
+import { attachRegisteredDirectTargets, verifyDirectTarget } from './federation/directRoutes.js';
+import { secureChannelOriginAllowed } from './federation/originPolicy.js';
+import { RelayRouter } from './federation/relay.js';
 import { assertPublicSecurity, securityHeaders } from './utils/publicSecurity.js';
-import { guardWebSocketSession } from './utils/webSocketSecurity.js';
-import { readTerminalHandshakeDimensions } from './utils/terminalHandshakeDimensions.js';
 import { apiCachePolicy } from './utils/apiCachePolicy.js';
 import 'dotenv/config';
 import express from 'express';
@@ -23,7 +30,7 @@ import { createOnboardingRouter } from './routes/onboarding.js';
 import { createLocalRouter } from './routes/local.js';
 import { csrfProtection } from './utils/csrfProtection.js';
 import { pathValidator } from './utils/pathValidator.js';
-import { isUpgradeRequestAuthenticated, requireAuth, renewSessionMiddleware } from './utils/authProtection.js';
+import { requireAuth, renewSessionMiddleware } from './utils/authProtection.js';
 import { localAccessManager } from './utils/localAccess.js';
 import { isAllowedHost, isUpgradeOriginAllowed, validateHostMiddleware, validateOriginMiddleware, } from './utils/requestSecurity.js';
 import { getCookieSecurityOptions, setSecureCookieMode } from './utils/cookieSecurity.js';
@@ -37,22 +44,6 @@ import { getTermdockVersion, TERMDOCK_CAPABILITIES, TERMDOCK_PROTOCOL_VERSION, }
 import { PORT, DEFAULT_HOST } from './config.js';
 const CLIENT_STATE_COOKIE = 'termdock-client';
 export const DEFAULT_PORT = PORT.backend;
-/** Read one cookie from a raw Cookie header (upgrade requests bypass the
- *  cookie-parser middleware). Values are percent-encoded. */
-function getCookieValue(cookieHeader, name) {
-    if (!cookieHeader)
-        return undefined;
-    const pattern = new RegExp(`(?:^|;\\s*)${name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}=([^;]*)`);
-    const match = cookieHeader.match(pattern);
-    if (!match)
-        return undefined;
-    try {
-        return decodeURIComponent(match[1]);
-    }
-    catch {
-        return match[1];
-    }
-}
 const CLIENT_LOG_DEDUP_WINDOW_MS = 5_000;
 const CLIENT_LOG_RATE_WINDOW_MS = 10_000;
 const CLIENT_LOG_RATE_LIMIT = 120;
@@ -146,6 +137,17 @@ export function createApp(options = {}) {
     app.disable('x-powered-by');
     app.use(securityHeaders);
     app.use(validateHostMiddleware);
+    if (options.secureRequired)
+        app.use('/api/auth/open', createOpenAccessRouter(() => app.locals.passwordRuntime?.serviceId));
+    if (options.secureRequired)
+        app.use('/api/auth/password', createPasswordLoginRouter(() => app.locals.passwordRuntime));
+    app.use('/api', (req, res, next) => {
+        if (!options.secureRequired || isEncryptedRequest(req) || isTrustedLocalRequest(req, options.localApiToken))
+            return next();
+        if (req.method === 'GET' && ['/meta', '/auth/status'].includes(req.path))
+            return next();
+        res.status(426).json({ error: 'Pair this device to use an encrypted connection', code: 'E2EE_REQUIRED' });
+    });
     // Authenticate before allocating request bodies, including future API routes.
     app.use(cookieParser());
     app.use('/api', renewSessionMiddleware);
@@ -393,12 +395,78 @@ export function startServer(options = {}) {
     });
     runtimeMonitor.start();
     const app = createApp({
+        secureRequired: true,
         port: options.onboardingPort ?? port,
         httpsCaPath: options.httpsCaPath,
         localApiToken: options.localApiToken,
         runtimeMonitor,
     });
     const { server, scheme } = createServerForApp(app, options);
+    let entrySubjectAllowed = (_subjectId) => false;
+    let routeInvitations;
+    const routeAccess = new RouteAccess(path.join(homedir(), '.termdock', 'federation', 'routes.json'), Date.now, (subjectId, targetServiceId) => routeInvitations?.allows(subjectId, targetServiceId) === true);
+    const relayRouter = new RelayRouter({
+        authenticate: context => context,
+        allowRegister: (principal, serviceId) => routeAccess.allowRegister(principal, serviceId),
+        allowRoute: (principal, serviceId) => routeAccess.allowRoute(principal, serviceId),
+    });
+    const dynamicDirectTargets = new Map();
+    server.once('close', () => { for (const close of dynamicDirectTargets.values())
+        close(); });
+    try {
+        const detachDirectTargets = attachRegisteredDirectTargets(relayRouter, routeAccess.configuredDirectTargets(), path.join(homedir(), '.termdock', 'federation'));
+        server.once('close', detachDirectTargets);
+    }
+    catch {
+        console.error('Configured direct routes unavailable; target access remains closed.');
+    }
+    server.once('close', () => relayRouter.close());
+    const federation = createFederationRuntime(app, path.join(homedir(), '.termdock', 'federation'), {
+        terminal: handleTerminalWebSocket, control: handleControlWebSocket,
+    }, {
+        listRouteAccess: () => routeInvitations?.list() || [],
+        grantRouteAccess: async (issuerId, targetServiceId, subjectId, url) => {
+            if (!routeInvitations)
+                throw new Error('ROUTE_NOT_AVAILABLE');
+            if (!routeAccess.hasConfiguredTarget(targetServiceId)) {
+                if (!url)
+                    throw new Error('ROUTE_TARGET_NOT_CONFIGURED');
+                const target = { serviceId: targetServiceId, url };
+                await verifyDirectTarget(target);
+                const runtime = await federation;
+                if (!runtime.store.authorize({ subjectId: issuerId, serviceId: runtime.serviceId, action: 'authorization.manage' }).allowed)
+                    throw new Error('AUTHORIZATION_DENIED');
+                routeAccess.addDirectTarget(target);
+                if (!dynamicDirectTargets.has(targetServiceId))
+                    dynamicDirectTargets.set(targetServiceId, attachRegisteredDirectTargets(relayRouter, [target]));
+            }
+            return routeInvitations.grant(issuerId, targetServiceId, subjectId);
+        },
+        revokeRouteAccess: id => routeInvitations?.revoke(id) || false,
+        issueRouteTicket: (subjectId, serviceId) => routeAccess.issueRouteTicket(subjectId, serviceId),
+        hasRouteGrant: (subjectId, serviceId) => routeInvitations?.allows(subjectId, serviceId) === true,
+        createRouteInvitation: (issuerId, serviceId) => {
+            if (!routeInvitations)
+                throw new Error('ROUTE_NOT_AVAILABLE');
+            return routeInvitations.create(issuerId, serviceId);
+        },
+        consumeRouteInvitation: (code, subjectId) => {
+            if (!routeInvitations)
+                throw new Error('ROUTE_NOT_AVAILABLE');
+            return routeInvitations.consume(code, subjectId);
+        },
+    });
+    void federation.then(runtime => {
+        app.locals.passwordRuntime = runtime;
+        entrySubjectAllowed = subjectId => runtime.store.authorize({ subjectId, serviceId: runtime.serviceId, action: 'authorization.manage' }).allowed;
+        routeInvitations = new RouteInvitationStore({
+            filePath: path.join(homedir(), '.termdock', 'federation', 'route-invitations.json'), serviceId: runtime.serviceId,
+            issuerAllowed: subjectId => entrySubjectAllowed(subjectId),
+            targetAvailable: serviceId => routeAccess.hasConfiguredTarget(serviceId) && relayRouter.hasRoute(serviceId),
+        });
+    }).catch(() => console.error('Route invitations unavailable; uninitialized route grants remain denied.'));
+    void federation.catch(() => console.error('Encrypted access initialization failed; business access remains closed.'));
+    server.once('close', () => { void federation.then(runtime => runtime.close()).catch(() => { }); });
     server.headersTimeout = 10_000;
     server.requestTimeout = 120_000;
     server.keepAliveTimeout = 5_000;
@@ -464,14 +532,12 @@ export function startServer(options = {}) {
             zlibDeflateOptions: { level: 6, memLevel: 7 },
         },
     });
-    const WS_PATH_RE = /^\/api\/terminal\/([^/]+)\/ws$/;
-    const CONTROL_WS_PATH = '/api/control/ws';
     server.on('upgrade', (request, socket, head) => {
         if (wss.clients.size >= 256) {
             socket.end('HTTP/1.1 503 Service Unavailable\r\nConnection: close\r\n\r\n');
             return;
         }
-        if (!isAllowedHost(request.headers.host) || !isUpgradeOriginAllowed(request.headers.origin, request.headers.host)) {
+        if (!isAllowedHost(request.headers.host)) {
             socket.write('HTTP/1.1 403 Forbidden\r\nConnection: close\r\n\r\n');
             socket.destroy();
             return;
@@ -485,41 +551,38 @@ export function startServer(options = {}) {
             return;
         }
         const pathname = url.pathname;
-        // Reject the upgrade before the WebSocket handshake completes if auth
-        // is enabled and the client cookie is missing/expired. We respond with
-        // a real HTTP 401 so the browser surfaces a useful error. Applied to
-        // both per-terminal and control paths.
-        const cookieHeader = request.headers.cookie;
-        if (!isUpgradeRequestAuthenticated(typeof cookieHeader === 'string' ? cookieHeader : undefined)) {
-            socket.write('HTTP/1.1 401 Unauthorized\r\nConnection: close\r\n\r\n');
-            socket.destroy();
+        if (pathname === '/api/federation/relay') {
+            // Native relay peers have no Origin. Authenticate explicitly before upgrade.
+            if (scheme !== 'https' || (request.headers.origin && !isUpgradeOriginAllowed(request.headers.origin, request.headers.host))) {
+                socket.end('HTTP/1.1 403 Forbidden\r\nConnection: close\r\n\r\n');
+                return;
+            }
+            const principal = routeAccess.authenticate(request.headers.authorization, url.searchParams.get('routeToken'));
+            if (!principal) {
+                socket.end('HTTP/1.1 401 Unauthorized\r\nConnection: close\r\n\r\n');
+                return;
+            }
+            wss.handleUpgrade(request, socket, head, ws => {
+                void relayRouter.attach(ws, principal).then(attached => { if (attached)
+                    ws.send(JSON.stringify({ type: 'ready' })); });
+            });
             return;
         }
-        // Control WS: server-pushed global client-state events. One per browser.
-        if (pathname === CONTROL_WS_PATH) {
-            const clientId = crypto.randomUUID();
+        if (pathname === '/api/federation/secure') {
+            // This exception applies only to the cookie-independent Noise handshake.
+            // Target pinning and device authorization remain mandatory inside it.
+            if (!secureChannelOriginAllowed(request.headers.origin, () => isUpgradeOriginAllowed(request.headers.origin, request.headers.host))) {
+                socket.end('HTTP/1.1 403 Forbidden\r\nConnection: close\r\n\r\n');
+                return;
+            }
             wss.handleUpgrade(request, socket, head, (ws) => {
-                handleControlWebSocket(ws, clientId);
-                guardWebSocketSession(ws, cookieHeader);
+                void federation.then(runtime => runtime.accept(ws, { allowOpenAccess: !!request.headers.origin && isUpgradeOriginAllowed(request.headers.origin, request.headers.host) })).catch(() => ws.close(1011, 'Encrypted access unavailable'));
             });
             return;
         }
-        // Per-terminal WS: bidirectional I/O for a single terminal session.
-        const match = pathname.match(WS_PATH_RE);
-        if (!match) {
-            socket.destroy();
-            return;
-        }
-        const sessionId = match[1];
-        const clientId = crypto.randomUUID();
-        const pushClientId = getCookieValue(cookieHeader, CLIENT_STATE_COOKIE);
-        // 短线重连时客户端会带上 ?since=<lastSeq>，让服务端只补发增量。
-        const sinceParam = url.searchParams.get('since');
-        const sinceSeq = sinceParam ? Math.max(0, Number.parseInt(sinceParam, 10) || 0) : 0;
-        wss.handleUpgrade(request, socket, head, (ws) => {
-            handleTerminalWebSocket(ws, sessionId, clientId, { sinceSeq, pushClientId, streamEpoch: url.searchParams.get('epoch') ?? undefined, flowControl: url.searchParams.get('flow') === '2', independentTmux: url.searchParams.get('transport') === 'tmux-client', outputActive: url.searchParams.get('active') !== '0' }, readTerminalHandshakeDimensions(url.searchParams));
-            guardWebSocketSession(ws, cookieHeader);
-        });
+        // Business WebSockets have no plaintext fallback after pairing migration.
+        socket.end('HTTP/1.1 426 Upgrade Required\r\nConnection: close\r\n\r\n');
+        return;
     });
     server.listen(port, host, () => {
         const displayHost = host === '0.0.0.0' ? 'localhost' : host;

package/dist/server/federation/accessPolicy.js

@@ -0,0 +1,122 @@
+const METHODS = new Set(['GET', 'HEAD', 'POST', 'PUT', 'PATCH', 'DELETE']);
+export function canonicalApiPath(path) {
+    if (typeof path !== 'string' || !path.startsWith('/api/') || /[\\\x00-\x20\x7f#]/.test(path))
+        return null;
+    const pathname = path.split('?')[0];
+    if (pathname.includes('//'))
+        return null;
+    try {
+        const segments = pathname.split('/').map((segment, index) => {
+            if (index === 0 || (segment === '' && index === pathname.split('/').length - 1))
+                return segment;
+            const value = decodeURIComponent(segment);
+            // Decode exactly once. Never allow an encoded separator, traversal segment,
+            // control byte, invalid UTF-8 or a second escape layer to change routing.
+            if (!value || value === '.' || value === '..' || /[\\/\x00-\x1f\x7f]/.test(value) || /%[a-f0-9]{2}/i.test(value))
+                throw new Error('Ambiguous API path');
+            return value;
+        });
+        const canonical = segments.join('/');
+        if (canonical.endsWith('/') && !canonical.startsWith('/api/terminal/fs/preview/'))
+            return null;
+        return canonical;
+    }
+    catch {
+        return null;
+    }
+}
+const pathOnly = canonicalApiPath;
+/** Restricts a full-service tunnel to business APIs, excluding authentication,
+ * local-only operations and recursive federation/bootstrap endpoints. */
+export function isBusinessApiPath(method, path) {
+    if (!METHODS.has(method))
+        return false;
+    const pathname = pathOnly(path);
+    if (!pathname)
+        return false;
+    return !/^\/api\/(?:auth|local|federation|onboarding|csrf)(?:\/|$)/i.test(pathname);
+}
+const fileReads = new Set(['list', 'watch', 'search', 'read', 'git-blob', 'eda-preview', 'eda-inspect', 'blob', 'video', 'download', 'diff', 'diff-files', 'untracked-files', 'git-context', 'git-bundle', 'change-audit', 'branch-diff', 'commit-diff', 'git-recent-commits', 'branch-audit', 'git-action/status', 'local-open-availability']);
+const filePosts = new Set(['git-action', 'apply-hunk', 'upload', 'open-in-file-browser']);
+const settings = new Set(['settings', 'toolbar-presets', 'program-detection', 'context-draft']);
+const serviceReads = new Set(['update', 'auto-title/catalog', 'agent-hooks', 'agent-launchers', 'agent-plugins', 'quota', 'tmux/status', 'tmux/sessions', 'agent-resume-history']);
+const reservedSessionIds = new Set(['fs', 'settings', 'client-state', 'session-inventory', 'operations', 'tmux', 'create', 'force-kill', 'serialize-state', 'agent-resume-history', 'toolbar-presets', 'context-draft', 'program-detection', 'update', 'quota', 'agent-hooks', 'agent-launchers', 'agent-plugins', 'agent-plugin-icon', 'auto-title', 'directory-suggestions']);
+export function resolveAccessRequest(method, path) {
+    if (!isBusinessApiPath(method, path))
+        return null;
+    const pathname = pathOnly(path);
+    const read = method === 'GET' || method === 'HEAD';
+    if (/^\/api\/notifications\/(status|subscribe|preferences|unsubscribe)$/.test(pathname)) {
+        if (read && pathname.endsWith('/status'))
+            return { action: 'service.view' };
+        if (method === 'POST' && !pathname.endsWith('/status'))
+            return { action: 'service.configure' };
+        return null;
+    }
+    const prefix = '/api/terminal/';
+    if (!pathname.startsWith(prefix))
+        return null;
+    const route = pathname.slice(prefix.length);
+    if (route.startsWith('fs/')) {
+        const op = route.slice(3);
+        if (read && (fileReads.has(op) || /^preview\/.+/.test(op)))
+            return { action: 'file.read' };
+        if ((method === 'POST' && filePosts.has(op)) || (method === 'DELETE' && ['file', 'change-audit', 'branch-audit'].includes(op)) || (method === 'GET' && op === 'cancel-slot'))
+            return { action: 'file.write' };
+        return null;
+    }
+    if (read && route === 'session-inventory')
+        return { action: 'service.view', metadata: 'session-inventory' };
+    if (read && route === 'client-state')
+        return { action: 'service.view', metadata: 'global-client-state' };
+    if (settings.has(route)) {
+        if (read)
+            return { action: 'service.view' };
+        if (method === 'PUT' || (method === 'DELETE' && route === 'program-detection'))
+            return { action: 'service.configure' };
+        return null;
+    }
+    if (read && serviceReads.has(route))
+        return { action: 'service.view' };
+    if (read && route === 'directory-suggestions')
+        return { action: 'file.read' };
+    if (method === 'POST' && route === 'create')
+        return { action: 'service.create-session' };
+    const session = /^([^/]+)(?:\/(health|attach|stream|input|resize|tmux|restart|agent-resume))?$/.exec(route);
+    if (session && !reservedSessionIds.has(session[1].toLowerCase())) {
+        const sessionId = session[1];
+        const op = session[2];
+        if (read && ['health', 'attach', 'stream', 'agent-resume'].includes(op))
+            return { action: 'session.view', sessionId };
+        if (method === 'POST' && op === 'input')
+            return { action: 'session.input', sessionId };
+        if (method === 'POST' && op === 'resize')
+            return { action: 'session.resize', sessionId };
+        if (method === 'DELETE' && !op)
+            return { action: 'session.terminate', sessionId };
+        // tmux switch-session can reach other backends; restart/agent-resume accept
+        // launch configuration. Their unrestricted bodies require service authority.
+        if (method === 'POST' && ['tmux', 'restart', 'agent-resume'].includes(op))
+            return { action: 'service.configure' };
+    }
+    // Complex operations manipulate global state or accept additional resource IDs.
+    // An unregistered operation intentionally receives no custom-grant mapping.
+    return null;
+}
+/** WS control mapping; caller must bind sessionId to the opened channel. */
+export function terminalMessageAction(type) {
+    switch (type) {
+        case 'input':
+        case 'focus':
+        case 'agent-review-ack': return 'session.input';
+        case 'resize': return 'session.resize';
+        case 'tmux': return 'service.configure';
+        case 'ping':
+        case 'viewing':
+        case 'output-subscription':
+        case 'output-ack': return 'session.view';
+        // Legacy flow-control can pause the shared PTY; grant only to controllers.
+        case 'flow-control': return 'session.input';
+        default: return null;
+    }
+}