@jingyi0605/codingns4dsh 0.1.2 → 0.1.7-rc.3

package/data/build/dist/host/modules/peer-host/host-ws-connector.js

@@ -0,0 +1,108 @@
+import WebSocket from 'ws';
+/** DSH 原生工作台 WebSocket 的固定入口；不接受客户端传入路径。 */
+export const PEER_HOST_REMOTE_WS_PATH = '/ws';
+export class PeerHostConnectorError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'PeerHostConnectorError';
+    }
+}
+/**
+ * 创建当前 Host 到目标 DSH 的 LAN 工作台 connector。
+ *
+ * 目标 URL、access token 和 WebSocket 路径均由 Host 侧生成；Client 只能通过
+ * 上层代理提交 HostScope。目标 DSH 的消息白名单仍由 `PeerHostWsProxyService`
+ * 在双端转发前执行，这里只负责固定端点的认证握手和消息类型的文本适配。
+ */
+export function createPeerHostRemoteConnector(options = {}) {
+    const timeoutMs = options.timeoutMs ?? 5_000;
+    if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0 || timeoutMs > 60_000)
+        throw new TypeError('PeerHost WebSocket connector 超时时间无效');
+    const websocketFactory = options.websocketFactory ?? ((url, init) => new WebSocket(url, { headers: init.headers }));
+    return async (record, accessToken, scope) => {
+        if (record.route.kind !== 'lan')
+            throw new PeerHostConnectorError('PEER_HOST_RELAY_UNAVAILABLE', '中转 PeerHost 暂不支持 Host-to-Host WebSocket');
+        if (accessToken.trim() === '')
+            throw new Error('PeerHost 目标登录态为空');
+        assertScope(scope, record.id);
+        const url = buildRemoteWebSocketUrl(record.route.normalizedOrigin, accessToken);
+        const socket = websocketFactory(url, { headers: { authorization: `Bearer ${accessToken}` } });
+        await waitForOpen(socket, timeoutMs);
+        return adaptSocket(socket);
+    };
+}
+function buildRemoteWebSocketUrl(origin, accessToken) {
+    const url = new URL(PEER_HOST_REMOTE_WS_PATH, origin);
+    url.protocol = url.protocol === 'https:' ? 'wss:' : 'ws:';
+    url.searchParams.set('access_token', accessToken);
+    return url.toString();
+}
+function assertScope(scope, peerHostId) {
+    if (scope.targetHostId !== peerHostId || scope.hostId.trim() === '' || scope.workspaceId.trim() === '' || !Number.isSafeInteger(scope.scopeGeneration) || scope.scopeGeneration < 0)
+        throw new Error('PeerHost connector 作用域无效');
+    if (scope.sessionId !== null && scope.sessionId.trim() === '')
+        throw new Error('PeerHost connector 会话作用域无效');
+}
+async function waitForOpen(socket, timeoutMs) {
+    if (socket.readyState === 1)
+        return;
+    await new Promise((resolve, reject) => {
+        let settled = false;
+        const finish = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            remove(socket, 'open', onOpen);
+            remove(socket, 'error', onError);
+            remove(socket, 'close', onClose);
+            remove(socket, 'unexpected-response', onUnexpectedResponse);
+            if (error === undefined)
+                resolve();
+            else
+                reject(error);
+        };
+        const onOpen = () => finish();
+        const onError = () => finish(new PeerHostConnectorError('PEER_HOST_PROXY_UNREACHABLE', '目标 Host WebSocket 连接失败'));
+        const onClose = () => finish(new PeerHostConnectorError('PEER_HOST_PROXY_UNREACHABLE', '目标 Host WebSocket 在打开前关闭'));
+        const onUnexpectedResponse = (_request, response) => {
+            const code = response.statusCode === 401 || response.statusCode === 403 ? 'PEER_HOST_SESSION_REQUIRED' : 'PEER_HOST_PROXY_UNREACHABLE';
+            finish(new PeerHostConnectorError(code, code === 'PEER_HOST_SESSION_REQUIRED' ? '目标 Host 登录态已失效' : '目标 Host WebSocket 握手失败'));
+        };
+        const timer = setTimeout(() => {
+            socket.terminate?.();
+            finish(new PeerHostConnectorError('PEER_HOST_PROXY_UNREACHABLE', '目标 Host WebSocket 连接超时'));
+        }, timeoutMs);
+        socket.once('open', onOpen);
+        socket.once('error', onError);
+        socket.once('close', onClose);
+        socket.once('unexpected-response', onUnexpectedResponse);
+    });
+}
+function adaptSocket(socket) {
+    return {
+        get readyState() { return socket.readyState; },
+        send(data) { socket.send(data); },
+        close(code, reason) { socket.close(code, reason); },
+        on(event, listener) {
+            if (event === 'message') {
+                socket.on('message', (value, isBinary) => listener(toText(value), isBinary));
+                return;
+            }
+            socket.on(event, (...args) => listener(...args));
+        },
+    };
+}
+function toText(value) {
+    if (typeof value === 'string')
+        return value;
+    if (value instanceof Uint8Array)
+        return new TextDecoder().decode(value);
+    return String(value);
+}
+function remove(socket, event, listener) {
+    socket.off?.(event, listener);
+}
+//# sourceMappingURL=host-ws-connector.js.map

package/data/build/dist/host/modules/peer-host/host-ws-proxy-service.d.ts

@@ -0,0 +1,26 @@
+import type { HostScope, PeerHostErrorCode, PeerHostRecord } from '../../../shared/contracts/peer-host.js';
+import { PeerHostSessionService } from './peer-host-session.js';
+import { PeerHostStore } from './peer-host-store.js';
+export declare const PEER_HOST_WS_CLIENT_MESSAGE_TYPES: Set<string>;
+export declare const PEER_HOST_WS_REMOTE_MESSAGE_TYPES: Set<string>;
+export interface PeerHostSocket {
+    readonly readyState: number;
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+    on(event: 'message' | 'close' | 'error', listener: (...args: any[]) => void): void;
+}
+export type PeerHostRemoteConnector = (record: PeerHostRecord, accessToken: string, scope: HostScope) => Promise<PeerHostSocket>;
+export declare class PeerHostWsProxyError extends Error {
+    readonly code: PeerHostErrorCode;
+    constructor(code: PeerHostErrorCode, message: string);
+}
+/** PeerHost WebSocket 双端代理；只转发带完整作用域的白名单消息。 */
+export declare class PeerHostWsProxyService {
+    private readonly store;
+    private readonly sessions;
+    private readonly connectRemote;
+    constructor(store: PeerHostStore, sessions: PeerHostSessionService, connectRemote: PeerHostRemoteConnector);
+    open(peerHostId: string, client: PeerHostSocket, scope: HostScope): Promise<() => void>;
+    private requireReady;
+}
+//# sourceMappingURL=host-ws-proxy-service.d.ts.map

package/data/build/dist/host/modules/peer-host/host-ws-proxy-service.js

@@ -0,0 +1,159 @@
+import { PEER_HOST_ERROR_CODES } from '../../../shared/contracts/peer-host.js';
+import { PeerHostSessionService } from './peer-host-session.js';
+import { PeerHostStore } from './peer-host-store.js';
+import { PeerHostConnectorError } from './host-ws-connector.js';
+import { peerHostSafeError } from './peer-host-diagnostics.js';
+export const PEER_HOST_WS_CLIENT_MESSAGE_TYPES = new Set([
+    'workbench.subscribe', 'workbench.refresh', 'fileTree.subscribe', 'fileTree.refresh',
+    'git.subscribe', 'git.refresh', 'session.subscribe', 'session.load_older',
+    'session.send', 'session.stop', 'session.permission_reply', 'session.answer',
+    'terminal.subscribe', 'terminal.input', 'terminal.resize', 'terminal.close',
+    'rightTool.subscribe', 'rightTool.refresh', 'rightTool.close',
+]);
+export const PEER_HOST_WS_REMOTE_MESSAGE_TYPES = new Set([
+    'system.connected', 'workbench.snapshot', 'workbench.delta', 'fileTree.snapshot',
+    'git.snapshot', 'session.subscribed', 'session.backfill', 'session.delta',
+    'session.runtime_message', 'session.runtime_status', 'session.activity',
+    'session.permission_request', 'session.error', 'terminal.output', 'terminal.status',
+    'terminal.exit', 'terminal.error', 'rightTool.snapshot', 'rightTool.delta',
+]);
+const OPEN = 1;
+const MAX_QUEUE = 128;
+export class PeerHostWsProxyError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'PeerHostWsProxyError';
+    }
+}
+/** PeerHost WebSocket 双端代理；只转发带完整作用域的白名单消息。 */
+export class PeerHostWsProxyService {
+    store;
+    sessions;
+    connectRemote;
+    constructor(store, sessions, connectRemote) {
+        this.store = store;
+        this.sessions = sessions;
+        this.connectRemote = connectRemote;
+    }
+    async open(peerHostId, client, scope) {
+        const record = await this.requireReady(peerHostId);
+        assertScopeTarget(scope, peerHostId);
+        const accessToken = await this.sessions.getAccessToken(peerHostId);
+        let remote;
+        try {
+            remote = await this.connectRemote(record, accessToken, scope);
+        }
+        catch (error) {
+            if (error instanceof PeerHostConnectorError && error.code === PEER_HOST_ERROR_CODES.SESSION_REQUIRED) {
+                await this.sessions.invalidate(peerHostId);
+                throw new PeerHostWsProxyError(PEER_HOST_ERROR_CODES.SESSION_REQUIRED, '目标 Host 登录态已失效');
+            }
+            if (error instanceof PeerHostConnectorError)
+                throw new PeerHostWsProxyError(error.code, peerHostSafeError(error.code).message);
+            throw new PeerHostWsProxyError(PEER_HOST_ERROR_CODES.PROXY_UNREACHABLE, '目标 Host 代理连接失败');
+        }
+        let closed = false;
+        const remoteQueue = [];
+        const clientQueue = [];
+        const closeBoth = (code = 1000, reason = 'peer host proxy closed') => {
+            if (closed)
+                return;
+            closed = true;
+            if (client.readyState === OPEN)
+                client.close(code, reason);
+            if (remote.readyState === OPEN)
+                remote.close(code, reason);
+        };
+        const sendClientError = (code, message) => {
+            if (client.readyState === OPEN)
+                client.send(JSON.stringify({ type: 'peerHost.error', ...scope, error_code: code, message }));
+        };
+        const forward = (socket, raw, queue) => {
+            if (socket.readyState !== OPEN) {
+                if (queue.length >= MAX_QUEUE) {
+                    queue.shift();
+                    sendClientError(PEER_HOST_ERROR_CODES.PROXY_UNREACHABLE, 'PeerHost 实时消息队列已满');
+                }
+                queue.push(raw);
+                return;
+            }
+            socket.send(raw);
+        };
+        const flush = () => {
+            while (remoteQueue.length > 0 && remote.readyState === OPEN)
+                remote.send(remoteQueue.shift());
+            while (clientQueue.length > 0 && client.readyState === OPEN)
+                client.send(clientQueue.shift());
+        };
+        client.on('message', (data, isBinary) => {
+            if (isBinary === true || typeof data !== 'string') {
+                sendClientError(PEER_HOST_ERROR_CODES.PROXY_PATH_NOT_ALLOWED, 'PeerHost WebSocket 不支持二进制消息');
+                return;
+            }
+            const parsed = parseScopedMessage(data, scope, PEER_HOST_WS_CLIENT_MESSAGE_TYPES);
+            if (parsed.error !== null) {
+                sendClientError(parsed.error.code, parsed.error.message);
+                return;
+            }
+            forward(remote, data, remoteQueue);
+        });
+        remote.on('message', (data, isBinary) => {
+            if (isBinary === true || typeof data !== 'string') {
+                sendClientError(PEER_HOST_ERROR_CODES.RESPONSE_INVALID, 'PeerHost 目标消息格式无效');
+                return;
+            }
+            const parsed = parseScopedMessage(data, scope, PEER_HOST_WS_REMOTE_MESSAGE_TYPES);
+            if (parsed.error !== null) {
+                sendClientError(parsed.error.code, parsed.error.message);
+                return;
+            }
+            forward(client, data, clientQueue);
+        });
+        client.on('close', () => closeBoth());
+        remote.on('close', () => closeBoth(1011, 'target peer host closed'));
+        client.on('error', () => closeBoth(1011, 'client socket failed'));
+        remote.on('error', () => closeBoth(1011, 'target peer host failed'));
+        flush();
+        return () => closeBoth();
+    }
+    async requireReady(peerHostId) {
+        const record = await this.store.get(peerHostId);
+        if (record === null)
+            throw new PeerHostWsProxyError(PEER_HOST_ERROR_CODES.NOT_FOUND, 'PeerHost 不存在');
+        if (record.status !== 'ready')
+            throw new PeerHostWsProxyError(record.status === 'session_required' ? PEER_HOST_ERROR_CODES.SESSION_REQUIRED : PEER_HOST_ERROR_CODES.NOT_READY, 'PeerHost 尚未准备好实时代理');
+        if (record.route.kind !== 'lan')
+            throw new PeerHostWsProxyError(PEER_HOST_ERROR_CODES.RELAY_UNAVAILABLE, '中转 PeerHost 暂不可用');
+        return record;
+    }
+}
+function assertScopeTarget(scope, peerHostId) {
+    if (!scope.hostId || scope.targetHostId !== peerHostId || !scope.workspaceId || !Number.isSafeInteger(scope.scopeGeneration) || scope.scopeGeneration < 0)
+        throw new PeerHostWsProxyError(PEER_HOST_ERROR_CODES.SCOPE_MISMATCH, 'PeerHost WebSocket 作用域不匹配');
+}
+function parseScopedMessage(raw, expected, allowed) {
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch {
+        return { error: new PeerHostWsProxyError(PEER_HOST_ERROR_CODES.RESPONSE_INVALID, 'PeerHost WebSocket 消息不是 JSON') };
+    }
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return { error: new PeerHostWsProxyError(PEER_HOST_ERROR_CODES.RESPONSE_INVALID, 'PeerHost WebSocket 消息格式无效') };
+    const message = value;
+    if (typeof message.type !== 'string' || !allowed.has(message.type))
+        return { error: new PeerHostWsProxyError(PEER_HOST_ERROR_CODES.TOOL_UNSUPPORTED, 'PeerHost WebSocket 消息未加入白名单') };
+    if (requiresSession(message.type) && (typeof message.sessionId !== 'string' || message.sessionId.trim() === ''))
+        return { error: new PeerHostWsProxyError(PEER_HOST_ERROR_CODES.SCOPE_MISMATCH, 'PeerHost 会话消息缺少 sessionId') };
+    const messageSessionId = typeof message.sessionId === 'string' && message.sessionId.trim() !== '' ? message.sessionId : null;
+    if (message.hostId !== expected.hostId || message.targetHostId !== expected.targetHostId || message.workspaceId !== expected.workspaceId || message.scopeGeneration !== expected.scopeGeneration || messageSessionId !== expected.sessionId)
+        return { error: new PeerHostWsProxyError(PEER_HOST_ERROR_CODES.SCOPE_MISMATCH, 'PeerHost WebSocket 消息作用域不匹配') };
+    return { error: null };
+}
+function requiresSession(type) {
+    return type.startsWith('session.');
+}
+//# sourceMappingURL=host-ws-proxy-service.js.map

package/data/build/dist/host/modules/peer-host/peer-host-aggregate-service.d.ts

@@ -0,0 +1,50 @@
+import type { AggregateHostResult } from '../../../shared/contracts/peer-host.js';
+export interface AggregateSessionSource {
+    readonly sessionId: string;
+    readonly title: string;
+    readonly status: string;
+    readonly updatedAt: number;
+}
+export interface AggregateWorkspaceSource {
+    readonly workspaceId: string;
+    readonly displayName: string;
+    readonly sessions: readonly AggregateSessionSource[];
+}
+export interface AggregateHostSource {
+    readonly hostId: string;
+    readonly targetHostId: string | null;
+    readonly hostLabel: string;
+    readonly load: () => Promise<readonly AggregateWorkspaceSource[]>;
+    /** DSH 未提供稳定摘要来源时显式声明降级，不把失败折叠成空数组。 */
+    readonly capability?: {
+        readonly available: boolean;
+        readonly reason: string;
+    };
+}
+/**
+ * 当前 Host 的 workspace/session 摘要来源契约。
+ *
+ * DSH 版本之间的 SessionStore/WorkspaceController 不是稳定公共 API，聚合层
+ * 不直接读取未知对象。Host 只有在完成结构探测后，才能注入这个 source。
+ */
+export interface PeerHostWorkspaceSessionSummarySource {
+    readonly capabilityId: 'peer-host.native-workspace-session-summary';
+    readonly available: boolean;
+    readonly reason?: string;
+    load(signal?: AbortSignal): Promise<readonly AggregateWorkspaceSource[]>;
+}
+/** 将显式 source 转为聚合任务；不可用 source 保留 unsupported 诊断。 */
+export declare function createAggregateHostSource(input: {
+    readonly hostId: string;
+    readonly targetHostId: string | null;
+    readonly hostLabel: string;
+    readonly source: PeerHostWorkspaceSessionSummarySource;
+}): AggregateHostSource;
+/** 并发加载多 Host 摘要；单个目标失败只生成该 Host 的错误节点。 */
+export declare class PeerHostAggregateService {
+    private readonly timeoutMs;
+    constructor(timeoutMs?: number);
+    load(sources: readonly AggregateHostSource[]): Promise<readonly AggregateHostResult[]>;
+    private loadOne;
+}
+//# sourceMappingURL=peer-host-aggregate-service.d.ts.map

package/data/build/dist/host/modules/peer-host/peer-host-aggregate-service.js

@@ -0,0 +1,97 @@
+/** 将显式 source 转为聚合任务；不可用 source 保留 unsupported 诊断。 */
+export function createAggregateHostSource(input) {
+    const source = input.source;
+    return {
+        hostId: input.hostId,
+        targetHostId: input.targetHostId,
+        hostLabel: input.hostLabel,
+        capability: {
+            available: source.available,
+            reason: source.reason?.trim() || (source.available ? '摘要 source 已就绪' : 'Host 未提供稳定 workspace/session 摘要 source'),
+        },
+        load: () => source.load(),
+    };
+}
+/** 并发加载多 Host 摘要；单个目标失败只生成该 Host 的错误节点。 */
+export class PeerHostAggregateService {
+    timeoutMs;
+    constructor(timeoutMs = 5_000) {
+        this.timeoutMs = timeoutMs;
+    }
+    async load(sources) {
+        return Promise.all(sources.map((source) => this.loadOne(source)));
+    }
+    async loadOne(source) {
+        if (source.capability?.available === false) {
+            return {
+                hostId: source.hostId,
+                targetHostId: source.targetHostId,
+                hostLabel: source.hostLabel,
+                availability: 'unsupported',
+                errorCode: null,
+                diagnostic: source.capability.reason,
+                workspaces: [],
+            };
+        }
+        try {
+            const workspaces = await withTimeout(source.load(), this.timeoutMs);
+            return {
+                hostId: source.hostId,
+                targetHostId: source.targetHostId,
+                hostLabel: source.hostLabel,
+                availability: 'ready',
+                errorCode: null,
+                workspaces: workspaces.map((workspace) => toWorkspace(source, workspace)),
+            };
+        }
+        catch (error) {
+            return {
+                hostId: source.hostId,
+                targetHostId: source.targetHostId,
+                hostLabel: source.hostLabel,
+                availability: 'unreachable',
+                errorCode: 'PEER_HOST_UNREACHABLE',
+                workspaces: [],
+            };
+        }
+    }
+}
+function toWorkspace(source, workspace) {
+    return {
+        key: `${source.hostId}:${workspace.workspaceId}`,
+        hostId: source.hostId,
+        targetHostId: source.targetHostId,
+        workspaceId: workspace.workspaceId,
+        displayName: workspace.displayName,
+        hostLabel: source.hostLabel,
+        availability: 'ready',
+        sessions: workspace.sessions.map((session) => ({
+            scope: {
+                hostId: source.hostId,
+                targetHostId: source.targetHostId,
+                workspaceId: workspace.workspaceId,
+                sessionId: session.sessionId,
+                scopeGeneration: 0,
+            },
+            title: session.title,
+            status: session.status,
+            updatedAt: session.updatedAt,
+        })),
+    };
+}
+async function withTimeout(promise, timeoutMs) {
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0)
+        throw new TypeError('摘要超时时间必须为正数');
+    let timer;
+    try {
+        return await Promise.race([
+            promise,
+            new Promise((_, reject) => { timer = setTimeout(() => reject(new Error('PeerHost 摘要超时')), timeoutMs); }),
+        ]);
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+}
+//# sourceMappingURL=peer-host-aggregate-service.js.map

package/data/build/dist/host/modules/peer-host/peer-host-diagnostics.d.ts

@@ -0,0 +1,19 @@
+import type { PeerHostDiagnosticSnapshot, PeerHostErrorCode, PeerHostRecord } from '../../../shared/contracts/peer-host.js';
+export type { PeerHostDiagnosticSnapshot } from '../../../shared/contracts/peer-host.js';
+export interface PeerHostDiagnosticSink {
+    readonly enabled?: boolean;
+    emit(event: string, snapshot: PeerHostDiagnosticSnapshot): void;
+}
+/** 将内部错误转换成稳定错误码和固定文案，禁止回显底层异常正文。 */
+export declare function peerHostSafeError(code: PeerHostErrorCode): Error & {
+    readonly code: PeerHostErrorCode;
+};
+/** 对外诊断字段只保留脱敏 fingerprint；完整地址、ticket 和凭据永远不进入快照。 */
+export declare function toPeerHostDiagnosticSnapshot(record: PeerHostRecord): PeerHostDiagnosticSnapshot;
+export declare function redactFingerprint(value: string | null): string | null;
+/** 默认关闭；即使开启，也只向 sink 发送已验证的诊断快照。 */
+export declare function createPeerHostDiagnosticSink(options?: {
+    readonly enabled?: boolean;
+    readonly sink?: (event: string, snapshot: PeerHostDiagnosticSnapshot) => void;
+}): PeerHostDiagnosticSink;
+//# sourceMappingURL=peer-host-diagnostics.d.ts.map

package/data/build/dist/host/modules/peer-host/peer-host-diagnostics.js

@@ -0,0 +1,54 @@
+import { PEER_HOST_ERROR_CODES } from '../../../shared/contracts/peer-host.js';
+const DEFAULT_MESSAGES = {
+    [PEER_HOST_ERROR_CODES.NOT_FOUND]: 'PeerHost 不存在',
+    [PEER_HOST_ERROR_CODES.NOT_READY]: 'PeerHost 尚未准备好',
+    [PEER_HOST_ERROR_CODES.SESSION_REQUIRED]: '目标 Host 登录态已失效',
+    [PEER_HOST_ERROR_CODES.PROXY_PATH_NOT_ALLOWED]: 'PeerHost 代理路径或方法不受支持',
+    [PEER_HOST_ERROR_CODES.SCOPE_MISMATCH]: 'PeerHost 作用域不匹配',
+    [PEER_HOST_ERROR_CODES.PROXY_UNREACHABLE]: '目标 Host 代理不可达',
+    [PEER_HOST_ERROR_CODES.RESPONSE_INVALID]: '目标 Host 响应无效',
+    [PEER_HOST_ERROR_CODES.TOOL_UNSUPPORTED]: '目标 Host 工具不受支持',
+    [PEER_HOST_ERROR_CODES.INVALID_ROUTE]: 'PeerHost 路由无效',
+    [PEER_HOST_ERROR_CODES.DUPLICATE]: 'PeerHost 路由已存在',
+    [PEER_HOST_ERROR_CODES.PLUGIN_MISSING]: '目标 Host 未安装兼容插件',
+    [PEER_HOST_ERROR_CODES.VERSION_MISMATCH]: '目标 Host 版本不兼容',
+    [PEER_HOST_ERROR_CODES.IDENTITY_CHANGED]: '目标 Host 身份已变化',
+    [PEER_HOST_ERROR_CODES.UNREACHABLE]: '目标 Host 不可达',
+    [PEER_HOST_ERROR_CODES.RELAY_UNAVAILABLE]: '中转 PeerHost 暂不可用',
+    [PEER_HOST_ERROR_CODES.STALE_GENERATION]: 'PeerHost 作用域已过期',
+    [PEER_HOST_ERROR_CODES.AGGREGATE_UNAVAILABLE]: 'PeerHost 摘要暂不可用',
+};
+/** 将内部错误转换成稳定错误码和固定文案，禁止回显底层异常正文。 */
+export function peerHostSafeError(code) {
+    const error = new Error(DEFAULT_MESSAGES[code] ?? 'PeerHost 请求失败');
+    Object.defineProperty(error, 'code', { value: code, enumerable: true });
+    return error;
+}
+/** 对外诊断字段只保留脱敏 fingerprint；完整地址、ticket 和凭据永远不进入快照。 */
+export function toPeerHostDiagnosticSnapshot(record) {
+    return {
+        peerHostId: record.id,
+        routeKind: record.route.kind,
+        status: record.status,
+        lastErrorCode: record.lastErrorCode,
+        lastCheckedAt: record.lastCheckedAt,
+        fingerprint: redactFingerprint(record.fingerprint),
+    };
+}
+export function redactFingerprint(value) {
+    if (value === null || value.length <= 12)
+        return value;
+    return `${value.slice(0, 8)}...${value.slice(-4)}`;
+}
+/** 默认关闭；即使开启，也只向 sink 发送已验证的诊断快照。 */
+export function createPeerHostDiagnosticSink(options = {}) {
+    return {
+        enabled: options.enabled ?? false,
+        emit(event, snapshot) {
+            if (!(options.enabled ?? false))
+                return;
+            options.sink?.(event, snapshot);
+        },
+    };
+}
+//# sourceMappingURL=peer-host-diagnostics.js.map

package/data/build/dist/host/modules/peer-host/peer-host-handshake.d.ts

@@ -0,0 +1,44 @@
+import type { PeerHostErrorCode, PeerHostRecord } from '../../../shared/contracts/peer-host.js';
+import { PeerHostStore } from './peer-host-store.js';
+export declare const PEER_HOST_HANDSHAKE_PATH = "/api/public/host-handshake";
+export interface PeerHostHandshakePayload {
+    readonly productId: string;
+    readonly pluginId: string | null;
+    readonly pluginVersion: string | null;
+    readonly dshVersion: string;
+    readonly apiCompatibility: string;
+    readonly fingerprint: string | null;
+    readonly capabilities: readonly string[];
+}
+export interface PeerHostHandshakeOptions {
+    readonly productId: string;
+    readonly pluginId: string;
+    readonly pluginVersion: string;
+    readonly apiCompatibility: string;
+    readonly isDshVersionSupported: (version: string) => boolean;
+    readonly fetchImpl?: typeof fetch;
+    readonly timeoutMs?: number;
+    readonly now?: () => number;
+}
+/** 目标 Host 握手协调器；只把脱敏结果写回 PeerHostRecord。 */
+export declare class PeerHostHandshakeService {
+    private readonly store;
+    private readonly credentials;
+    private readonly options;
+    private readonly fetchImpl;
+    private readonly timeoutMs;
+    private readonly now;
+    constructor(store: PeerHostStore, credentials: {
+        clear(peerHostId: string): Promise<void>;
+    }, options: PeerHostHandshakeOptions);
+    check(peerHostId: string): Promise<PeerHostRecord>;
+    private fetchHandshake;
+    private resolve;
+    private emptyUpdate;
+    private requireRecord;
+}
+export declare class HandshakeError extends Error {
+    readonly code: PeerHostErrorCode;
+    constructor(code: PeerHostErrorCode, message: string);
+}
+//# sourceMappingURL=peer-host-handshake.d.ts.map