termdock 1.4.365 → 1.4.367

package/dist/server/agent/sessionSearchStore.js

@@ -1,10 +1,11 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import { getSessionPresentation } from '../utils/sessionDisplayName.js';
 const MAX_LOG_BYTES = 2 * 1024 * 1024;
 const LOG_SEGMENT_BYTES = MAX_LOG_BYTES / 2;
 const DEFAULT_MAX_TOTAL_BYTES = 64 * 1024 * 1024;
-const DEFAULT_MAX_SESSIONS = 50;
-const DEFAULT_MAX_AGE_MS = 30 * 24 * 60 * 60_000;
+const DEFAULT_MAX_SESSIONS = 1000;
+const DEFAULT_MAX_AGE_MS = 365 * 24 * 60 * 60_000;
 const BUDGET_MAINTENANCE_INTERVAL_MS = 10 * 60_000;
 const ANSI_PATTERN = /[\u001B\u009B][[\]()#;?]*(?:(?:(?:[a-zA-Z\d]*(?:;[-a-zA-Z\d\/#&.:=?%@~_]+)*)?\u0007)|(?:(?:\d{1,4}(?:[;:]\d{0,4})*)?[\dA-PR-TZcf-nq-uy=><~]))/g;
 function clean(value) {
@@ -49,16 +50,21 @@ export class SessionSearchStore {
         if (!this.flushTimer)
             this.flushTimer = setTimeout(() => this.flush(), 750);
     }
+    list() { return [...this.metadata.values()].map(entry => ({ ...entry })); }
+    get(sessionId) {
+        const entry = this.metadata.get(sessionId);
+        return entry ? { ...entry } : null;
+    }
     search(query, limit = 30) {
         this.flush();
         const needle = query.trim().toLocaleLowerCase();
         if (!needle)
             return [...this.metadata.values()].sort((a, b) => b.updatedAt - a.updatedAt)
-                .slice(0, Math.max(1, Math.min(limit, 100))).map(metadata => ({ ...metadata, snippet: '', matchCount: 0 }));
+                .slice(0, Math.max(1, Math.min(limit, 5000))).map(metadata => ({ ...metadata, snippet: '', matchCount: 0 }));
         const results = [];
         for (const metadata of this.metadata.values()) {
             const text = this.readLog(metadata.sessionId);
-            const searchable = `${metadata.title}\n${metadata.cwd}\n${metadata.agentSlug ?? ''}\n${text}`;
+            const searchable = `${metadata.title}\n${metadata.cwd}\n${metadata.agentSlug ?? ''}\n${metadata.sessionId}\n${metadata.agentNativeSessionId ?? ''}\n${text}`;
             const lower = searchable.toLocaleLowerCase();
             const first = lower.indexOf(needle);
             if (first < 0)
@@ -69,11 +75,11 @@ export class SessionSearchStore {
                 count += 1;
                 cursor += needle.length;
             }
-            const sourceStart = Math.max(0, first - 100);
-            const sourceEnd = Math.min(searchable.length, first + needle.length + 180);
-            results.push({ ...metadata, snippet: searchable.slice(sourceStart, sourceEnd).replace(/\s+/g, ' ').trim(), matchCount: count });
+            const outputMatch = text.toLocaleLowerCase().indexOf(needle);
+            const snippet = outputMatch < 0 ? '' : text.slice(Math.max(0, outputMatch - 100), outputMatch + needle.length + 180).replace(/\s+/g, ' ').trim();
+            results.push({ ...metadata, snippet, matchCount: count });
         }
-        return results.sort((a, b) => b.updatedAt - a.updatedAt).slice(0, Math.max(1, Math.min(limit, 100)));
+        return results.sort((a, b) => b.updatedAt - a.updatedAt).slice(0, Math.max(1, Math.min(limit, 5000)));
     }
     flush() {
         if (this.flushTimer)
@@ -149,10 +155,8 @@ export class SessionSearchStore {
                 continue;
             }
             totalBytes -= file.size;
-            if (!file.previous) {
-                this.metadata.delete(file.sessionId);
-                changed = true;
-            }
+            // Output has a separate disk budget. Keep names and recovery metadata
+            // searchable after bulky terminal logs have been rotated away.
         }
         if (changed) {
             this.metadataDirty = true;
@@ -165,7 +169,11 @@ export class SessionSearchStore {
             const parsed = JSON.parse(fs.readFileSync(this.metadataPath(), 'utf8'));
             for (const item of parsed.sessions ?? []) {
                 if (item && typeof item.sessionId === 'string')
-                    this.metadata.set(item.sessionId, item);
+                    this.metadata.set(item.sessionId, { ...item, title: /^(?:tmux:|remote:|wt-)/i.test(item.title)
+                            ? getSessionPresentation({ name: item.title, cwd: item.cwd }).displayName : item.title,
+                        titleSource: /^(?:tmux:|remote:|wt-)/i.test(item.title) ? 'default' : item.titleSource,
+                        mode: item.mode ?? (item.title.startsWith('tmux:') ? 'tmux' : undefined),
+                        tmuxSessionName: item.tmuxSessionName ?? (item.title.startsWith('tmux:') ? item.title.slice(5) : undefined) });
             }
             this.lastMetadataWriteAt = Date.now();
         }
@@ -195,6 +203,10 @@ export class SessionSearchStore {
         return !previous
             || previous.backendSessionId !== next.backendSessionId
             || previous.title !== next.title
+            || previous.titleSource !== next.titleSource
+            || previous.closedAt !== next.closedAt
+            || previous.mode !== next.mode
+            || previous.tmuxSessionName !== next.tmuxSessionName
             || previous.cwd !== next.cwd
             || previous.agentSlug !== next.agentSlug
             || previous.agentNativeSessionId !== next.agentNativeSessionId;

package/dist/server/agent/sessionViewModeRoutes.js

@@ -46,17 +46,24 @@ export class SessionViewModeStore {
         return next;
     }
 }
-export function sessionViewModeRoutes(store, resolve) {
+export function sessionViewModeRoutes(store, resolve, eligibility, onSave) {
     const router = Router();
-    router.route('/:sessionId/view-mode').get((req, res) => {
+    router.route('/:sessionId/view-mode').get(async (req, res) => {
         const id = encryptedRequestSubject(req) && resolve(req.params.sessionId);
         if (!id) {
             res.status(404).json({ error: '会话不可用' });
             return;
         }
-        res.setHeader('Cache-Control', 'no-store');
-        res.json(store.get(id) || { mode: null, updatedAt: 0 });
-    }).put((req, res) => {
+        try {
+            const chatEligibility = req.query.chatEligibility === '1' && eligibility
+                ? await eligibility(id, typeof req.query.command === 'string' ? req.query.command.slice(0, 8192) : undefined) : undefined;
+            res.setHeader('Cache-Control', 'no-store');
+            res.json({ ...(store.get(id) || { mode: null, updatedAt: 0 }), ...(chatEligibility ? { chatEligibility } : {}) });
+        }
+        catch {
+            res.status(503).json({ error: '暂时无法识别当前程序，请重试' });
+        }
+    }).put(async (req, res) => {
         const id = encryptedRequestSubject(req) && resolve(req.params.sessionId);
         if (!id) {
             res.status(404).json({ error: '会话不可用' });
@@ -66,7 +73,14 @@ export function sessionViewModeRoutes(store, resolve) {
             res.status(400).json({ error: '显示模式无效' });
             return;
         }
-        res.json(store.set(id, req.body.mode));
+        try {
+            const preference = store.set(id, req.body.mode);
+            await onSave?.(id, preference.mode);
+            res.json(preference);
+        }
+        catch {
+            res.status(503).json({ error: '显示模式未保存，请重试' });
+        }
     });
     return router;
 }

package/dist/server/agent/terminalEchoProbe.js

@@ -0,0 +1,35 @@
+import { randomBytes } from 'node:crypto';
+/** A printable delivery header, retained as part of the same message. Never
+ * submit a test task, send editing keys, or infer that the Agent consumed it. */
+export async function probeTerminalEcho(input) {
+    const timeoutMs = input.timeoutMs ?? 1500;
+    const read = async (ms) => {
+        let timer;
+        try {
+            return await Promise.race([input.read(), new Promise((_, reject) => {
+                    timer = setTimeout(() => reject(new Error('TERMINAL_INPUT_ECHO_UNCONFIRMED')), Math.max(1, ms));
+                })]);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    };
+    const before = await read(timeoutMs);
+    let marker;
+    do {
+        marker = `td.${randomBytes(6).toString('hex')}`;
+    } while (before.includes(marker));
+    input.assertCurrent?.('before_paste');
+    await input.write(`[${marker}] `);
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        input.assertCurrent?.('before_paste');
+        // Wrapped lines are equivalent; the fresh random marker cannot match old
+        // terminal history. Capture failures stop the operation too.
+        if ((await read(deadline - Date.now())).replace(/\r?\n/g, '').includes(marker))
+            return;
+        if (Date.now() >= deadline)
+            throw new Error('TERMINAL_INPUT_ECHO_UNCONFIRMED');
+        await new Promise(resolve => setTimeout(resolve, 50));
+    }
+}

package/dist/server/entry.js

@@ -2,7 +2,7 @@ import { IntegrationRuntime, integrationSocketPath } from './agent/integrationSe
 import { CollaborationService } from './agent/collaborationService.js';
 import { X509Certificate } from 'node:crypto';
 import { CollaborationPeerTransport, connectCollaborationRpc } from './agent/collaborationPeerTransport.js';
-import { collaborationStore, collaborationTaskStore, deliverPeerCollaboration, collaborationLocalActivity, collaborationDirectorySessions, todoWebhookRouter, prepareCollaborationTaskWorker, integrationSessionAdapter } from './routes/terminal.js';
+import { collaborationStore, collaborationTaskStore, deliverPeerCollaboration, collaborationLocalActivity, collaborationDirectorySessions, todoWebhookRouter, prepareCollaborationTaskWorker, integrationSessionAdapter, restoreSharedFederationSession } from './routes/terminal.js';
 import { CollaborationTaskService } from './agent/collaborationTaskService.js';
 import { setPushTargetPeerId } from './notifications/pushService.js';
 import { desktopServiceTargets } from './federation/desktopTargets.js';
@@ -494,7 +494,7 @@ export function startServer(options = {}) {
     let federationServiceId = '';
     let activeRouteIds = () => [];
     const desktopTargets = () => desktopServiceTargets(homedir(), federationServiceId);
-    const routeAccess = new RouteAccess(path.join(homedir(), '.termdock', 'federation', 'routes.json'), Date.now, (subjectId, targetServiceId) => routeInvitations?.allows(subjectId, targetServiceId) === true || collaborationTransport?.canRoute(subjectId, targetServiceId) === true, desktopTargets, () => activeRouteIds());
+    const routeAccess = new RouteAccess(path.join(homedir(), '.termdock', 'federation', 'routes.json'), Date.now, (subjectId, targetServiceId) => routeInvitations?.allows(subjectId, targetServiceId) === true || collaborationTransport?.canRoute(subjectId, targetServiceId) === true || collaborationService?.canRoute(subjectId, targetServiceId) === true, desktopTargets, () => activeRouteIds());
     const relayRouter = new RelayRouter({
         requirePasswordProtectedTargets: true,
         isLocalTarget: id => id === federationServiceId,
@@ -518,6 +518,8 @@ export function startServer(options = {}) {
         terminal: handleTerminalWebSocket, control: handleControlWebSocket, android: handleAndroidWebSocket, computer: handleComputerWebSocket,
     }, {
         webTransport: webTransportDescriptor,
+        sessionAttachmentDirectory: path.join(homedir(), '.termdock', 'chat-attachments'),
+        restoreSharedSession: restoreSharedFederationSession,
         resolveSessionId: resolveStableFederationSessionId,
         collaborationConnected: (subjectId, rpc) => {
             const channels = collaborationChannels.get(subjectId) ?? new Set();
@@ -580,7 +582,7 @@ export function startServer(options = {}) {
             return routeAccess.issueRouteTicket(subjectId, serviceId);
         },
         issueSelfRelayTicket: (serviceId) => routeAccess.issueSelfRelayTicket(serviceId),
-        hasRouteGrant: (subjectId, serviceId) => routeInvitations?.allows(subjectId, serviceId) === true || collaborationTransport?.canRoute(subjectId, serviceId) === true,
+        hasRouteGrant: (subjectId, serviceId) => routeInvitations?.allows(subjectId, serviceId) === true || collaborationTransport?.canRoute(subjectId, serviceId) === true || collaborationService?.canRoute(subjectId, serviceId) === true,
         createRouteInvitation: (issuerId, serviceId) => {
             if (!routeInvitations)
                 throw new Error('ROUTE_NOT_AVAILABLE');
@@ -609,6 +611,21 @@ export function startServer(options = {}) {
                 throw new Error('WAITING_FOR_PEER_CONNECTION');
             return connectCollaborationRpc(runtime.identity, peer, undefined, packet => receiveCollaboration(peer.serviceId, packet));
         };
+        const connectVia = async (peer, via) => {
+            const entry = await connectCollaborationRpc(runtime.identity, via);
+            try {
+                const ticket = await entry.request({ type: 'route-ticket', serviceId: peer.serviceId });
+                if (typeof ticket.routeToken !== 'string')
+                    throw new Error('ROUTE_UNAVAILABLE');
+                const url = new URL('/api/federation/relay', via.origin.replace(/^https:/, 'wss:'));
+                url.searchParams.set('routeToken', ticket.routeToken);
+                // TLS authenticates the entry; Noise pins the final destination.
+                return await connectCollaborationRpc(runtime.identity, { ...via, serviceId: peer.serviceId }, url.href, packet => receiveCollaboration(peer.serviceId, packet));
+            }
+            finally {
+                entry.close();
+            }
+        };
         collaborationTransport = new CollaborationPeerTransport({
             reverse: reverseCollaboration,
             file: path.join(homedir(), '.termdock', 'federation', 'collaboration-peers.json'), serviceId: runtime.serviceId,
@@ -617,19 +634,7 @@ export function startServer(options = {}) {
             connect: async (peer, via) => {
                 if (!via)
                     return connectPeer(peer);
-                const entry = await connectCollaborationRpc(runtime.identity, via);
-                try {
-                    const ticket = await entry.request({ type: 'route-ticket', serviceId: peer.serviceId });
-                    if (typeof ticket.routeToken !== 'string')
-                        throw new Error('ROUTE_UNAVAILABLE');
-                    const url = new URL('/api/federation/relay', via.origin.replace(/^https:/, 'wss:'));
-                    url.searchParams.set('routeToken', ticket.routeToken);
-                    // TLS authenticates the entry; Noise pins the final destination.
-                    return await connectCollaborationRpc(runtime.identity, { ...via, serviceId: peer.serviceId }, url.href, packet => receiveCollaboration(peer.serviceId, packet));
-                }
-                finally {
-                    entry.close();
-                }
+                return connectVia(peer, via);
             },
         });
         app.locals.collaborationTransport = collaborationTransport;
@@ -642,7 +647,23 @@ export function startServer(options = {}) {
         app.locals.collaborationNode = { serviceId: runtime.serviceId, ...(caFingerprint256 ? { caFingerprint256 } : {}) };
         collaborationService = new CollaborationService({ file: path.join(homedir(), '.termdock', 'federation', 'collaboration-services.json'),
             store: collaborationStore, transport: collaborationTransport, node: () => app.locals.collaborationNode,
-            sessions: collaborationDirectorySessions, reverse: reverseCollaboration, connect: connectPeer,
+            sessions: collaborationDirectorySessions, deliver: deliverPeerCollaboration, reverse: reverseCollaboration,
+            connect: async (peer) => {
+                try {
+                    return await connectPeer(peer);
+                }
+                catch (directError) {
+                    for (const via of collaborationService?.routeNodes() ?? []) {
+                        if (via.serviceId === peer.serviceId)
+                            continue;
+                        try {
+                            return await connectVia(peer, via);
+                        }
+                        catch { /* Try the next authorized encrypted entry. */ }
+                    }
+                    throw directError;
+                }
+            },
             tasks: {
                 receive: (peer, packet) => app.locals.collaborationTasks.receive(peer, packet),
                 heads: ids => app.locals.collaborationTasks?.heads(ids) ?? [],

package/dist/server/federation/accessPolicy.js

@@ -90,10 +90,13 @@ export function resolveAccessRequest(method, path) {
         return { action: 'file.read' };
     if (method === 'POST' && route === 'create')
         return { action: 'service.create-session' };
-    const attachment = /^([^/]+)\/chat\/attachments$/.exec(route);
+    const attachment = /^([^/]+)\/chat\/attachments(?:\/recording)?$/.exec(route);
     if (method === 'POST' && attachment && !reservedSessionIds.has(attachment[1].toLowerCase()))
         return { action: 'session.input', sessionId: attachment[1] };
     const chatState = /^([^/]+)\/chat\/[^/]+\/state$/.exec(route);
+    const chatViewed = /^([^/]+)\/chat\/viewed$/.exec(route);
+    if (method === 'POST' && chatViewed && !reservedSessionIds.has(chatViewed[1].toLowerCase()))
+        return { action: 'session.view', sessionId: chatViewed[1] };
     if (method === 'PUT' && chatState && !reservedSessionIds.has(chatState[1].toLowerCase()))
         return { action: 'session.input', sessionId: chatState[1] };
     const session = /^([^/]+)(?:\/(health|attach|stream|input|resize|tmux|restart|agent-resume|chat|view-mode))?$/.exec(route);
@@ -120,13 +123,13 @@ export function resolveAccessRequest(method, path) {
     return null;
 }
 /** WS control mapping; caller must bind sessionId to the opened channel. */
-export function terminalMessageAction(type) {
+export function terminalMessageAction(type, action) {
     switch (type) {
         case 'input':
         case 'focus':
         case 'agent-review-ack': return 'session.input';
         case 'resize': return 'session.resize';
-        case 'tmux': return 'service.configure';
+        case 'tmux': return action === 'copy-selection' ? 'session.view' : 'service.configure';
         case 'ping':
         case 'viewing':
         case 'output-subscription':

package/dist/server/federation/runtime.js

@@ -3,6 +3,7 @@ import { SessionSharingPresence } from './sessionSharing.js';
 import { collaborationSessionDisplayName } from '../utils/sessionDisplayName.js';
 import { mergeShareResources } from '../shared/shareResources.js';
 import { canonicalShareDirectories, computerResource, resourceHttpAllowed } from './resourceAccess.js';
+import { attachmentReadRoot, sessionAttachmentRoot } from './sessionAttachmentAccess.js';
 import { CollaborationRpc } from '../agent/collaborationPeerTransport.js';
 import { PasswordBootstrapServer } from './passwordBootstrap.js';
 import { DeviceProfiles } from './deviceProfiles.js';
@@ -192,13 +193,14 @@ export async function createFederationRuntime(app, directory, handlers, options
             const send = (packet) => channel.send(packet);
             const check = (action, sessionId) => { if (!allowed(subjectId, action, sessionId))
                 throw new Error('AUTHORIZATION_DENIED'); };
+            const attachmentRoot = (head) => attachmentReadRoot(options.sessionAttachmentDirectory, context.relayed && !relayPasswordConfigured() ? [] : store.listEffective({ subjectId, serviceId }), id => options.resolveSessionId?.(id) || id, String(head.method), String(head.path));
             const httpAllowed = (head) => {
                 if (context.relayed)
                     requireRelayPassword();
                 if (typeof head.method !== 'string' || typeof head.path !== 'string' || !isBusinessApiPath(head.method, head.path))
                     throw new Error('API_NOT_ALLOWED');
                 const policy = resolveAccessRequest(head.method, head.path);
-                if (!full(subjectId) && !resourceHttpAllowed(resources(subjectId), head.method, head.path)) {
+                if (!full(subjectId) && !resourceHttpAllowed(resources(subjectId), head.method, head.path) && !attachmentRoot(head)) {
                     if (!policy)
                         throw new Error('API_NOT_ALLOWED');
                     check(policy.action, policy.sessionId);
@@ -216,8 +218,10 @@ export async function createFederationRuntime(app, directory, handlers, options
                 };
                 try {
                     httpAllowed(operation.head);
+                    const attachment = attachmentRoot(operation.head);
+                    const requestResources = mergeShareResources([resources(subjectId), attachment ? { directories: [{ path: attachment, access: 'read' }] } : undefined]);
                     const headers = new Headers({ 'x-termdock-inner': internalToken, 'x-termdock-device': subjectId,
-                        'x-termdock-full-service': full(subjectId) ? '1' : '0', 'x-termdock-resources': JSON.stringify(resources(subjectId)) });
+                        'x-termdock-full-service': full(subjectId) ? '1' : '0', 'x-termdock-resources': JSON.stringify(requestResources) });
                     const supplied = operation.head.headers;
                     if (supplied && typeof supplied === 'object')
                         for (const [name, value] of Object.entries(supplied)) {
@@ -419,7 +423,17 @@ export async function createFederationRuntime(app, directory, handlers, options
                         send({ type: 'result', id: packet.id, subjectId, serviceId, fullService: full(subjectId), grants, httpWindow: MAX_TRANSFER_WINDOW, binaryChunks: true, relayAuthorizationErrors: true, relaySelfTargetGuard: true, webTransport: options.webTransport?.() });
                     }
                     else if (packet.type === 'session-list') {
-                        const inventory = await sessionInventory();
+                        let inventory = await sessionInventory();
+                        if (options.restoreSharedSession && !full(subjectId)) {
+                            let restored = false;
+                            for (const session of inventory) {
+                                if (session.backendSessionId || typeof session.sessionId !== 'string' || !allowed(subjectId, 'session.view', session.sessionId))
+                                    continue;
+                                restored = await options.restoreSharedSession(session.sessionId).catch(() => false) || restored;
+                            }
+                            if (restored)
+                                inventory = await sessionInventory();
+                        }
                         const displayGrants = store.listEffective({ subjectId, serviceId }).filter(grant => grant.actions.includes('session.view')).reverse().sort((a, b) => b.createdAt - a.createdAt);
                         const seen = new Set();
                         const items = inventory.flatMap(session => {
@@ -431,6 +445,7 @@ export async function createFederationRuntime(app, directory, handlers, options
                             const displayGrant = displayGrants.find(grant => grant.scope.kind === 'service' || grant.scope.sessionIds.some(matches));
                             const appearance = Object.entries(displayGrant?.sessionAppearance || {}).find(([id]) => matches(id))?.[1];
                             return [{ sessionId, ...(typeof session.sessionId === 'string' ? { sourceSessionId: session.sessionId } : {}),
+                                    ...(options.sessionAttachmentDirectory ? { attachmentRoot: sessionAttachmentRoot(options.sessionAttachmentDirectory, typeof session.sessionId === 'string' ? session.sessionId : options.resolveSessionId?.(sessionId) || sessionId) } : {}),
                                     name: appearance?.name || collaborationSessionDisplayName({ ...session, name: typeof session.name === 'string' ? session.name : sessionId }), ...(appearance?.icon ? { icon: appearance.icon } : {}), live: session.live === true,
                                     canWrite: allowed(subjectId, 'session.input', sessionId), canResize: allowed(subjectId, 'session.resize', sessionId) }];
                         });
@@ -710,7 +725,7 @@ export async function createFederationRuntime(app, directory, handlers, options
                                 throw new Error('ACTION_NOT_ALLOWED');
                         }
                         else if (item.sessionId) {
-                            const action = terminalMessageAction(data.type);
+                            const action = terminalMessageAction(data.type, data.action);
                             if (!action)
                                 throw new Error('ACTION_NOT_ALLOWED');
                             check(action, action.startsWith('session.') ? item.sessionId : undefined);

package/dist/server/federation/sessionAttachmentAccess.js

@@ -0,0 +1,45 @@
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+import { canonicalApiPath } from './accessPolicy.js';
+import { resourceHttpAllowed } from './resourceAccess.js';
+export function sessionAttachmentRoot(directory, sessionId) {
+    return path.resolve(directory, createHash('sha256').update(sessionId).digest('hex'));
+}
+/** Session viewing includes only existing attachment file reads. It never
+ * grants directory discovery, arbitrary file access or attachment mutation. */
+export function attachmentReadRoot(directory, grants, normalize, method, requestPath) {
+    if (!directory || !['GET', 'HEAD'].includes(method))
+        return;
+    const pathname = canonicalApiPath(requestPath);
+    if (!pathname)
+        return;
+    const prefix = '/api/terminal/fs/';
+    if (!pathname.startsWith(prefix))
+        return;
+    const operation = pathname.slice(prefix.length);
+    if (!['blob', 'read', 'video', 'download'].includes(operation) && !operation.startsWith('preview/'))
+        return;
+    const url = new URL(requestPath, 'http://inner');
+    let requested;
+    if (operation.startsWith('preview/')) {
+        const parts = operation.slice(8).split('/');
+        if (/^[0-9a-f]{32}$/.test(parts[0]))
+            parts.shift();
+        requested = '/' + parts.join('/');
+    }
+    else {
+        if (url.searchParams.getAll('path').length !== 1)
+            return;
+        requested = url.searchParams.get('path');
+    }
+    const base = path.resolve(directory);
+    const relative = path.relative(base, path.resolve(requested));
+    const [hash, ...file] = relative.split(path.sep);
+    if (!/^[a-f0-9]{64}$/.test(hash) || !file.length)
+        return;
+    const root = path.join(base, hash);
+    if (!grants.some(grant => (grant.actions.includes('session.view') || grant.actions.includes('service:*'))
+        && (grant.scope.kind === 'service' || grant.scope.sessionIds.some(id => sessionAttachmentRoot(base, normalize(id)) === root))))
+        return;
+    return resourceHttpAllowed({ directories: [{ path: root, access: 'read' }] }, method, requestPath) ? root : undefined;
+}

package/dist/server/onboarding-theme.css

@@ -0,0 +1 @@
+:root{--background:#100F0F;--foreground:#CECDC3;--surface:#282726;--surface-2:#343331;--muted-foreground:#878580;--border:#403E3C;--primary:#879A39;--primary-foreground:#100F0F;--warning:#D0A215;--accent:#4385BE;}@media(prefers-color-scheme:light){:root{--background:#FFFCF0;--foreground:#100F0F;--surface:#E6E4D9;--surface-2:#DAD8CE;--muted-foreground:#575653;--border:#CECDC3;--primary:#66800B;--primary-foreground:#FFFCF0;--warning:#AD8301;--accent:#205EA6;}}

package/dist/server/onboardingPage.js

@@ -0,0 +1,65 @@
+import { randomBytes, X509Certificate } from 'node:crypto';
+import fs from 'node:fs';
+import { loadOnboardingTheme } from './utils/onboardingTheme.js';
+export function onboardingFingerprint(caCertPath) {
+    try {
+        return caCertPath ? new X509Certificate(fs.readFileSync(caCertPath)).fingerprint256 : null;
+    }
+    catch {
+        return null;
+    }
+}
+function escapeHtml(value) {
+    return value.replace(/[&<>"']/g, character => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[character]);
+}
+const instructions = {
+    ios: { label: 'iPhone / iPad', steps: ['请用 Safari 下载。打开「设置 → 已下载描述文件」，按提示安装。', '打开「设置 → 通用 → 关于本机 → 证书信任设置」，为此根证书开启完全信任。', '回到此页面，点下方「继续访问」。'] },
+    mac: { label: 'Mac', steps: ['下载后打开证书，按提示导入「钥匙串访问」。', '在钥匙串中找到刚导入的证书，双击打开「信任」，将安全套接字层（SSL）设为「始终信任」，按系统提示确认。', '回到此页面，点下方「继续访问」。'] },
+    windows: { label: 'Windows', steps: ['下载后打开证书，选择「安装证书 → 当前用户」。', '选择「将所有的证书都放入下列存储」，浏览并选择「受信任的根证书颁发机构」，核对来源后确认。', '回到此页面，点下方「继续访问」。'] },
+    android: { label: 'Android', steps: ['下载证书后，打开系统设置中的「安全」或「安全与隐私」。', '找到「更多安全设置 → 加密与凭据 → 安装证书 → CA 证书」，选择下载的文件并确认。不同品牌的菜单名称可能不同。', '回到浏览器点「继续访问」。如果浏览器仍不信任，请让分享者提供受信任的 HTTPS 域名链接。'] },
+    other: { label: 'Linux / 其他设备', steps: ['下载证书，在浏览器的「设置 → 隐私与安全 → 证书」中找到证书管理。', '将证书导入受信任的证书颁发机构，核对来源后允许验证网站。浏览器使用系统证书库时，请在系统证书管理中导入。', '回到此页面，点下方「继续访问」。'] },
+};
+/** Public installation guidance only. No business API, identity or session is loaded over HTTP. */
+export function sendOnboardingPage(req, res, options) {
+    const fingerprint = onboardingFingerprint(options.caCertPath);
+    if (!fingerprint) {
+        res.status(503).type('text').send('证书暂不可用，请联系分享者重新生成链接。');
+        return;
+    }
+    let target;
+    try {
+        target = new URL(`http://${req.headers.host}`);
+        if (target.username || target.password || target.pathname !== '/')
+            throw new Error('Invalid host');
+        target.protocol = 'https:';
+        target.port = String(options.httpsPort);
+        target.pathname = '/';
+    }
+    catch {
+        res.status(400).type('text').send('连接地址无效，请向分享者索取新链接。');
+        return;
+    }
+    const nonce = randomBytes(18).toString('base64');
+    const ua = req.headers['user-agent'] || '';
+    const device = /iPhone|iPad|iPod/.test(ua) || (/Macintosh/.test(ua) && /Mobile/.test(ua)) ? 'ios' : /Android/.test(ua) ? 'android' : /Windows/.test(ua) ? 'windows' : /Macintosh/.test(ua) ? 'mac' : 'other';
+    res.setHeader('Cache-Control', 'no-store');
+    res.setHeader('Referrer-Policy', 'no-referrer');
+    res.setHeader('X-Content-Type-Options', 'nosniff');
+    res.setHeader('Content-Security-Policy', `default-src 'none'; style-src 'nonce-${nonce}'; script-src 'nonce-${nonce}'; base-uri 'none'; frame-ancestors 'none'; form-action 'none'`);
+    res.type('html').send(`<!doctype html><html lang="zh-CN"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1,viewport-fit=cover"><meta name="referrer" content="no-referrer"><title>安全连接 · Termdock</title><style nonce="${nonce}">
+${loadOnboardingTheme()}
+*{box-sizing:border-box}body{margin:0;background:var(--background);color:var(--foreground);font:15px/1.6 system-ui,-apple-system,sans-serif}main{width:min(100%,580px);margin:0 auto;padding:28px 20px max(24px,env(safe-area-inset-bottom))}header p{margin:0;color:var(--muted-foreground);font-size:13px;letter-spacing:.04em}h1{font-size:26px;line-height:1.3;margin:10px 0}p{margin:8px 0}.intro{color:var(--muted-foreground)}.host{overflow-wrap:anywhere;color:var(--foreground)}.notice{border-left:3px solid var(--warning);padding:2px 12px;margin:18px 0;font-size:13px}.notice p{margin:4px 0}section{background:var(--surface);border:1px solid var(--border);border-radius:14px;padding:16px;margin:14px 0}h2{font-size:17px;margin:0 0 8px}.row{display:flex;gap:12px;align-items:center;justify-content:space-between;flex-wrap:wrap}select{max-width:100%;border:1px solid var(--border);background:var(--surface-2);color:var(--foreground);border-radius:8px;padding:8px;font:inherit;font-size:14px;min-height:44px}ol{padding-left:22px;font-size:14px;margin:12px 0}li{padding-left:3px;margin:7px 0}a.action{display:flex;align-items:center;justify-content:center;min-height:46px;padding:10px 14px;border-radius:9px;text-decoration:none;font-weight:600;border:1px solid var(--border);color:var(--foreground)}a.primary{background:var(--primary);color:var(--primary-foreground);border-color:var(--primary)}a:focus-visible,select:focus-visible,summary:focus-visible{outline:2px solid var(--accent);outline-offset:3px}small,.muted{color:var(--muted-foreground);font-size:13px}details{font-size:13px;margin:16px 0}summary{cursor:pointer;min-height:36px;display:list-item}code{display:block;word-break:break-all;background:var(--surface);border-radius:8px;padding:10px;user-select:all;font-size:12px}#download-status:empty{display:none}[hidden]{display:none!important}footer{color:var(--muted-foreground);font-size:12px}@media(max-width:420px){main{padding:20px 16px max(20px,env(safe-area-inset-bottom))}h1{font-size:24px}section{padding:14px}}
+</style></head><body><main><header><p>TERMDOCK · 首次连接</p><h1>先建立安全连接</h1><p class="intro">这台设备使用自己的安全证书。安装并信任后，浏览器才能正常验证它，分享内容将通过 HTTPS 打开。通常只需设置一次。</p></header>
+<div class="notice"><p><strong>仅为你信任的分享者安装。</strong>根证书的信任范围不限于本次分享，也会影响其他网站的证书验证。不确定来源时，请先停止并联系分享者。</p></div>
+<section><div class="row"><h2>1. 下载并安装证书</h2><label><span class="muted">你的设备 </span><select id="device" aria-label="你的设备">${Object.entries(instructions).map(([key, value]) => `<option value="${key}"${key === device ? ' selected' : ''}>${value.label}</option>`).join('')}</select></label></div>
+${Object.entries(instructions).map(([key, value]) => `<ol data-device="${key}"${key === device ? '' : ' hidden'}>${value.steps.map(step => `<li>${escapeHtml(step)}</li>`).join('')}</ol>`).join('')}
+<a id="download" class="action primary" href="/onboarding/ca.crt" download="termdock-ca.crt">下载证书</a><p id="download-status" class="muted" role="status"></p></section>
+<section><h2>2. 返回这里，继续访问</h2><p class="muted">已在系统中完成信任，或以前安装过此证书？可以直接继续。</p><a id="continue" class="action" href="${escapeHtml(target.href)}">继续访问</a><p class="muted">若仍出现证书错误，请返回检查是否已开启信任，不必跳过浏览器警告。</p></section>
+<details><summary>核对证书与安全说明</summary><p>此引导页通过 HTTP 提供，无法单凭这个页面确认设备身份。请通过你已信任的对话渠道，与分享者核对以下 SHA-256 指纹后再安装。</p><code>${escapeHtml(fingerprint)}</code><p>目标地址：<span class="host">${escapeHtml(target.origin)}</span></p><p>下载证书不会自动获得系统信任，也不会自动接受分享邀请。进入 HTTPS 页面后，仍按原分享权限验证。</p><p>不再需要时，可在系统或浏览器的证书管理中移除此根证书；iPhone / iPad 可删除对应的描述文件。</p></details><footer>HTTP 仅用于安装引导。此页不加载终端、聊天或文件内容。</footer></main>
+<script nonce="${nonce}">
+const device=document.getElementById('device');device.addEventListener('change',()=>{document.querySelectorAll('[data-device]').forEach(list=>{list.hidden=list.dataset.device!==device.value;});});
+const next=document.getElementById('continue');const destination=new URL(next.href);if(location.hash.startsWith('#termdock-invite=')&&location.hash.length<=8250)destination.hash=location.hash;next.href=destination.href;
+next.addEventListener('click',event=>{if(event.ctrlKey||event.metaKey||event.shiftKey||event.altKey)return;event.preventDefault();history.replaceState(null,'',location.pathname);location.replace(destination.href);});
+document.getElementById('download').addEventListener('click',()=>{document.getElementById('download-status').textContent='下载已发起。请完成上面的系统安装与信任步骤，再继续访问。';document.getElementById('download').classList.remove('primary');next.classList.add('primary');});
+</script></body></html>`);
+}

package/dist/server/onboardingServer.js

@@ -3,8 +3,12 @@ import { createServer } from 'http';
 import fs from 'fs';
 import { createOnboardingRouter } from './routes/onboarding.js';
 import { getLanIPv4Addresses } from './utils/localAccess.js';
+import path from 'node:path';
+import { TERMDOCK_DIR, readJsonFile, writeJsonStateAtomic } from './utils/termdockState.js';
+import { onboardingFingerprint, sendOnboardingPage } from './onboardingPage.js';
 let activeServer = null;
 let activeUrl = null;
+let activeFingerprint = null;
 function canStart(options) {
     return Boolean(options.caCertPath && fs.existsSync(options.caCertPath));
 }
@@ -14,6 +18,9 @@ export function startOnboardingServer(options) {
         return { server: null, url: null };
     }
     const app = express();
+    app.disable('x-powered-by');
+    app.use((_req, res, next) => { res.setHeader('Cache-Control', 'no-store'); res.setHeader('Referrer-Policy', 'no-referrer'); next(); });
+    app.get(['/', '/connect'], (req, res) => sendOnboardingPage(req, res, options));
     app.use('/onboarding', createOnboardingRouter({ port: options.httpsPort, caCertPath: options.caCertPath }));
     app.get('/ca', (_req, res) => {
         if (!options.caCertPath || !fs.existsSync(options.caCertPath)) {
@@ -21,20 +28,35 @@ export function startOnboardingServer(options) {
             return;
         }
         res.setHeader('Content-Type', 'application/x-x509-ca-cert');
-        res.setHeader('Content-Disposition', 'attachment; filename="rootCA.pem"');
+        res.setHeader('Content-Disposition', 'attachment; filename="termdock-ca.crt"');
         res.send(fs.readFileSync(options.caCertPath));
     });
     const server = createServer(app);
+    const portFile = path.join(TERMDOCK_DIR, `onboarding-${options.httpsPort}.json`);
+    const savedPort = readJsonFile(portFile)?.port;
+    const preferredPort = Number.isInteger(savedPort) && savedPort > 1024 && savedPort <= 65535 ? savedPort : 0;
+    let retriedPort = false;
     server.on('error', (error) => {
+        if (error.code === 'EADDRINUSE' && preferredPort && !retriedPort && !server.listening) {
+            retriedPort = true;
+            server.listen(0, '0.0.0.0');
+            return;
+        }
         console.warn('[onboarding] HTTP setup server failed:', error);
     });
     server.once('listening', () => {
         const address = server.address();
         const port = address?.port ?? null;
         const host = getLanIPv4Addresses()[0] ?? 'localhost';
-        activeUrl = port ? `http://${host}:${port}/ca` : null;
+        activeUrl = port ? `http://${host}:${port}/connect` : null;
+        activeFingerprint = onboardingFingerprint(options.caCertPath);
+        if (port)
+            try {
+                writeJsonStateAtomic(portFile, { port });
+            }
+            catch { /* Read-only installations can still offer a temporary setup port. */ }
     });
-    server.listen(0, '0.0.0.0');
+    server.listen(preferredPort, '0.0.0.0');
     activeServer = server;
     return { server, get url() { return activeUrl; } };
 }
@@ -47,7 +69,9 @@ export function stopOnboardingServer() {
     }
     activeServer = null;
     activeUrl = null;
+    activeFingerprint = null;
 }
 export function getOnboardingServerUrl() {
     return activeUrl;
 }
+export function getOnboardingCertificateFingerprint() { return activeFingerprint; }

package/dist/server/routes/onboarding.js

@@ -3,7 +3,7 @@ import fs from 'fs';
 import { localAccessManager } from '../utils/localAccess.js';
 function sendCaCertificate(res, caCertPath) {
     res.setHeader('Content-Type', 'application/x-x509-ca-cert');
-    res.setHeader('Content-Disposition', 'attachment; filename="rootCA.pem"');
+    res.setHeader('Content-Disposition', 'attachment; filename="termdock-ca.crt"');
     res.send(fs.readFileSync(caCertPath));
 }
 export function createOnboardingRouter(options = {}) {