@jingyi0605/codingns4dsh 0.1.0

package/data/build/dist/host/credential-store.js

@@ -0,0 +1,114 @@
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+/**
+ * 测试用内存实现。
+ * 不提供持久化或加密语义，不能用于生产；用于阶段 2 状态机单元测试。
+ */
+export class InMemoryCodingNsCredentialStore {
+    record = null;
+    async read() {
+        return this.record ? { ...this.record } : null;
+    }
+    async write(record) {
+        this.record = { ...record };
+    }
+    async clear() {
+        this.record = null;
+    }
+}
+/** Host 侧 refresh token 的文件存储；文件权限限制为当前用户可读写。 */
+export class FileCodingNsCredentialStore {
+    filePath;
+    constructor(filePath) {
+        this.filePath = filePath;
+        if (!filePath.trim())
+            throw new TypeError('Codingns4DSH credential file path 不能为空');
+    }
+    async read() {
+        try {
+            const value = JSON.parse(await readFile(this.filePath, 'utf8'));
+            return parseHostCredential(value);
+        }
+        catch (error) {
+            if (isNodeError(error, 'ENOENT'))
+                return null;
+            throw error;
+        }
+    }
+    async write(record) {
+        await mkdir(dirname(this.filePath), { recursive: true, mode: 0o700 });
+        const temporary = `${this.filePath}.${process.pid}.tmp`;
+        await writeFile(temporary, `${JSON.stringify(record)}\n`, { encoding: 'utf8', mode: 0o600 });
+        await rename(temporary, this.filePath);
+    }
+    async clear() {
+        try {
+            const { unlink } = await import('node:fs/promises');
+            await unlink(this.filePath);
+        }
+        catch (error) {
+            if (!isNodeError(error, 'ENOENT'))
+                throw error;
+        }
+    }
+}
+export class InMemoryDshDeviceCredentialStore {
+    record = null;
+    async read() { return this.record ? { ...this.record } : null; }
+    async write(record) { this.record = { ...record }; }
+    async clear() { this.record = null; }
+}
+export class FileDshDeviceCredentialStore {
+    filePath;
+    constructor(filePath) {
+        this.filePath = filePath;
+        if (!filePath.trim())
+            throw new TypeError('DSH device credential file path 不能为空');
+    }
+    async read() {
+        try {
+            const value = JSON.parse(await readFile(this.filePath, 'utf8'));
+            return parseDshCredential(value);
+        }
+        catch (error) {
+            if (isNodeError(error, 'ENOENT'))
+                return null;
+            throw error;
+        }
+    }
+    async write(record) {
+        await mkdir(dirname(this.filePath), { recursive: true, mode: 0o700 });
+        const temporary = `${this.filePath}.${process.pid}.tmp`;
+        await writeFile(temporary, `${JSON.stringify(record)}\n`, { encoding: 'utf8', mode: 0o600 });
+        await rename(temporary, this.filePath);
+    }
+    async clear() {
+        try {
+            const { unlink } = await import('node:fs/promises');
+            await unlink(this.filePath);
+        }
+        catch (error) {
+            if (!isNodeError(error, 'ENOENT'))
+                throw error;
+        }
+    }
+}
+function parseHostCredential(value) {
+    if (!isRecord(value) || typeof value.controlBaseUrl !== 'string' || typeof value.accountId !== 'string' || typeof value.refreshToken !== 'string' || typeof value.refreshTokenExpiresAt !== 'string' || (typeof value.deviceId !== 'string' && value.deviceId !== null) || typeof value.savedAt !== 'string') {
+        throw new Error('Codingns4DSH credential 文件格式无效');
+    }
+    return { controlBaseUrl: value.controlBaseUrl, accountId: value.accountId, refreshToken: value.refreshToken, refreshTokenExpiresAt: value.refreshTokenExpiresAt, deviceId: value.deviceId, savedAt: value.savedAt };
+}
+function parseDshCredential(value) {
+    if (!isRecord(value) || typeof value.deviceId !== 'string' || typeof value.deviceCredential !== 'string' || typeof value.credentialVersion !== 'number' || !Number.isInteger(value.credentialVersion) || value.credentialVersion < 1 || typeof value.dtlsFingerprint !== 'string' || (typeof value.tunnelDomain !== 'string' && value.tunnelDomain !== null) || typeof value.displayName !== 'string' || typeof value.savedAt !== 'string') {
+        throw new Error('DSH device credential 文件格式无效');
+    }
+    return { deviceId: value.deviceId, deviceCredential: value.deviceCredential, credentialVersion: value.credentialVersion, dtlsFingerprint: value.dtlsFingerprint, tunnelDomain: value.tunnelDomain, displayName: value.displayName, savedAt: value.savedAt };
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isNodeError(error, code) {
+    return error instanceof Error && 'code' in error && error.code === code;
+}
+//# sourceMappingURL=credential-store.js.map

package/data/build/dist/host/debug.d.ts

@@ -0,0 +1,79 @@
+import type { DebugConfig } from '../shared/contracts/debug-config.js';
+import type { TerminalProcessInstance, TerminalProcessLaunchResult } from '../shared/contracts/terminal-process.js';
+import type { TerminalProcessService } from './terminal/terminal-process-service.js';
+export interface DebugPortProcess {
+    readonly pid: number;
+    readonly startToken: string;
+    readonly command: string | null;
+    readonly cwd: string | null;
+}
+export interface DebugPortInspector {
+    inspect(port: number): Promise<DebugPortProcess | null>;
+    terminate(process: DebugPortProcess): Promise<void>;
+}
+export interface DebugProxyBinding {
+    readonly id: string;
+    readonly slug: string;
+    readonly url: string;
+    readonly workspaceId: string;
+    readonly profileId: string;
+    readonly instanceId: string;
+    readonly port: number;
+}
+export interface DebugWorkspaceServiceOptions {
+    readonly resolveWorkspaceRoot: (workspaceId: string) => string | null;
+    readonly terminalProcesses: TerminalProcessService;
+    readonly portInspector?: DebugPortInspector;
+}
+export interface DebugPortCheck {
+    readonly id: string;
+    readonly workspaceId: string;
+    readonly profileId: string;
+    readonly port: number;
+    readonly listening: boolean;
+    readonly process: DebugPortProcess | null;
+    readonly checkedAt: string;
+}
+/** Spec003 的最小 Host 服务：配置、PTY 启动、端口检查和代理绑定。 */
+export declare class DebugWorkspaceService {
+    private readonly options;
+    private readonly portInspector;
+    private readonly checks;
+    private readonly bindings;
+    private readonly bindingProcesses;
+    constructor(options: DebugWorkspaceServiceOptions);
+    getConfig(workspaceId: string): Promise<DebugConfig>;
+    saveConfig(workspaceId: string, value: unknown): Promise<DebugConfig>;
+    /** 更新一个已有启动项；运行中的实例继续使用启动时的旧参数。 */
+    updateProfile(workspaceId: string, profileId: string, value: unknown): Promise<DebugConfig>;
+    /** 删除一个启动项；有活动实例时拒绝删除，避免留下无法管理的终端进程。 */
+    deleteProfile(workspaceId: string, profileId: string): Promise<DebugConfig>;
+    launch(input: {
+        workspaceId: string;
+        profileId: string;
+        dshSessionId?: string;
+        cols: number;
+        rows: number;
+    }): Promise<TerminalProcessLaunchResult>;
+    listInstances(workspaceId?: string): readonly TerminalProcessInstance[];
+    getInstance(instanceId: string): TerminalProcessInstance | undefined;
+    stop(instanceId: string): Promise<TerminalProcessInstance>;
+    checkPort(workspaceId: string, profileId: string): Promise<DebugPortCheck>;
+    terminatePort(workspaceId: string, checkId: string): Promise<DebugPortCheck>;
+    /** 只结束端口对应的业务进程，不触碰 tmux/ConPTY 终端运行时。 */
+    killPortProcess(workspaceId: string, checkId: string): Promise<DebugPortCheck>;
+    enableProxy(workspaceId: string, profileId: string, instanceId: string): Promise<DebugProxyBinding>;
+    disableProxy(workspaceId: string, bindingId: string): Promise<void>;
+    getProxy(bindingId: string): DebugProxyBinding | null;
+    /** 由插件自己的 Fetch 路由调用；不接受任意 Host、端口或 URL。 */
+    handleProxyRequest(request: Request): Promise<Response>;
+    private workspaceRoot;
+    private revokeBindings;
+    private configFilename;
+}
+/** Node 平台的最小端口观察器；具体系统命令只留在这一层。 */
+export declare class NodeDebugPortInspector implements DebugPortInspector {
+    inspect(port: number): Promise<DebugPortProcess | null>;
+    terminate(processInfo: DebugPortProcess): Promise<void>;
+}
+//# sourceMappingURL=debug.d.ts.map

package/data/build/dist/host/debug.js

@@ -0,0 +1,295 @@
+import { randomUUID } from 'node:crypto';
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { join, isAbsolute, normalize } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { EMPTY_DEBUG_CONFIG, parseDebugConfig } from '../shared/contracts/debug-config.js';
+/** Spec003 的最小 Host 服务：配置、PTY 启动、端口检查和代理绑定。 */
+export class DebugWorkspaceService {
+    options;
+    portInspector;
+    checks = new Map();
+    bindings = new Map();
+    bindingProcesses = new Map();
+    constructor(options) {
+        this.options = options;
+        this.portInspector = options.portInspector ?? new NodeDebugPortInspector();
+    }
+    async getConfig(workspaceId) {
+        const filename = this.configFilename(workspaceId);
+        try {
+            return parseDebugConfig(JSON.parse(await readFile(filename, 'utf8')));
+        }
+        catch (error) {
+            if (isMissingFile(error))
+                return EMPTY_DEBUG_CONFIG;
+            throw error;
+        }
+    }
+    async saveConfig(workspaceId, value) {
+        const config = parseDebugConfig(value);
+        const filename = this.configFilename(workspaceId);
+        await mkdir(join(this.workspaceRoot(workspaceId), '.codingns'), { recursive: true, mode: 0o700 });
+        const temporary = `${filename}.${process.pid}.tmp`;
+        await writeFile(temporary, `${JSON.stringify(config, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+        await rename(temporary, filename);
+        return config;
+    }
+    /** 更新一个已有启动项；运行中的实例继续使用启动时的旧参数。 */
+    async updateProfile(workspaceId, profileId, value) {
+        const current = await this.getConfig(workspaceId);
+        if (!current.profiles.some((profile) => profile.id === profileId))
+            throw new Error(`Spec003 配置项不存在: ${profileId}`);
+        const parsed = parseDebugConfig({ version: 1, profiles: [value] });
+        const profile = parsed.profiles[0];
+        if (profile === undefined || profile.id !== profileId)
+            throw new Error('更新配置项 ID 不匹配');
+        return this.saveConfig(workspaceId, {
+            version: 1,
+            profiles: current.profiles.map((item) => item.id === profileId ? profile : item),
+        });
+    }
+    /** 删除一个启动项；有活动实例时拒绝删除，避免留下无法管理的终端进程。 */
+    async deleteProfile(workspaceId, profileId) {
+        const current = await this.getConfig(workspaceId);
+        if (!current.profiles.some((profile) => profile.id === profileId))
+            throw new Error(`Spec003 配置项不存在: ${profileId}`);
+        if (this.options.terminalProcesses.listInstances(workspaceId).some((instance) => instance.profileId === profileId && isActive(instance.state))) {
+            throw new Error('配置项仍有活动进程，请先停止后再删除');
+        }
+        await this.options.terminalProcesses.deleteProfile(workspaceId, profileId);
+        return this.saveConfig(workspaceId, { version: 1, profiles: current.profiles.filter((profile) => profile.id !== profileId) });
+    }
+    async launch(input) {
+        const config = await this.getConfig(input.workspaceId);
+        const profile = findProfile(config, input.profileId);
+        await this.options.terminalProcesses.createProfile({
+            id: profile.id,
+            workspaceId: input.workspaceId,
+            name: profile.name,
+            cwdRelative: profile.cwdRelative,
+            command: profile.command,
+            args: profile.args,
+            env: profile.env,
+            shell: profile.shell,
+            runtimeType: profile.runtimeType,
+            runtimeMode: 'pty',
+        });
+        return this.options.terminalProcesses.launch({
+            workspaceId: input.workspaceId,
+            profileId: profile.id,
+            ...(input.dshSessionId === undefined ? {} : { dshSessionId: input.dshSessionId }),
+            cols: input.cols,
+            rows: input.rows,
+            commandMode: 'shell-input',
+        });
+    }
+    listInstances(workspaceId) { return this.options.terminalProcesses.listInstances(workspaceId); }
+    getInstance(instanceId) { return this.options.terminalProcesses.getInstance(instanceId); }
+    async stop(instanceId) {
+        const stopped = await this.options.terminalProcesses.stop(instanceId);
+        for (const binding of this.bindings.values()) {
+            if (binding.instanceId === instanceId) {
+                this.bindings.delete(binding.id);
+                this.bindingProcesses.delete(binding.id);
+            }
+        }
+        return stopped;
+    }
+    async checkPort(workspaceId, profileId) {
+        const profile = findProfile(await this.getConfig(workspaceId), profileId);
+        if (profile.port === null)
+            throw new Error('配置项没有声明端口');
+        const process = await this.portInspector.inspect(profile.port);
+        const check = {
+            id: randomUUID(), workspaceId, profileId, port: profile.port,
+            listening: process !== null, process, checkedAt: new Date().toISOString(),
+        };
+        this.checks.set(check.id, check);
+        return check;
+    }
+    async terminatePort(workspaceId, checkId) {
+        return this.killPortProcess(workspaceId, checkId);
+    }
+    /** 只结束端口对应的业务进程，不触碰 tmux/ConPTY 终端运行时。 */
+    async killPortProcess(workspaceId, checkId) {
+        const check = this.checks.get(checkId);
+        if (check === undefined || check.workspaceId !== workspaceId)
+            throw new Error('端口检查结果不存在或已失效');
+        if (Date.now() - Date.parse(check.checkedAt) > 60_000) {
+            this.checks.delete(checkId);
+            throw new Error('端口检查结果已过期，请重新检查');
+        }
+        const current = await this.portInspector.inspect(check.port);
+        if (!sameProcess(check.process, current))
+            throw new Error('端口监听进程已变化，请重新检查');
+        if (current === null) {
+            this.checks.delete(checkId);
+            return { ...check, listening: false, process: null, checkedAt: new Date().toISOString() };
+        }
+        await this.portInspector.terminate(current);
+        this.checks.delete(checkId);
+        this.revokeBindings(workspaceId, check.profileId, check.port);
+        return { ...check, listening: false, process: null, checkedAt: new Date().toISOString() };
+    }
+    async enableProxy(workspaceId, profileId, instanceId) {
+        const profile = findProfile(await this.getConfig(workspaceId), profileId);
+        if (!profile.proxy.enabled || profile.port === null)
+            throw new Error('配置项未启用代理或没有端口');
+        const instance = this.getInstance(instanceId);
+        if (instance === undefined || instance.workspaceId !== workspaceId || instance.profileId !== profileId || !isActive(instance.state))
+            throw new Error('运行实例不存在或未运行');
+        const process = await this.portInspector.inspect(profile.port);
+        if (process === null)
+            throw new Error('配置端口当前未监听');
+        if (instance.pid !== null && process.pid !== instance.pid)
+            throw new Error('配置端口未由当前运行实例监听');
+        const slug = randomUUID().replaceAll('-', '');
+        const binding = {
+            id: randomUUID(), slug, url: `/api/codingns/debug-proxy?slug=${encodeURIComponent(slug)}`,
+            workspaceId, profileId, instanceId, port: profile.port,
+        };
+        this.bindings.set(binding.id, binding);
+        this.bindingProcesses.set(binding.id, process);
+        return binding;
+    }
+    async disableProxy(workspaceId, bindingId) {
+        const binding = this.bindings.get(bindingId) ?? null;
+        if (binding === null || binding.workspaceId !== workspaceId)
+            throw new Error('代理绑定不存在');
+        this.bindings.delete(bindingId);
+        this.bindingProcesses.delete(bindingId);
+    }
+    getProxy(bindingId) { return this.bindings.get(bindingId) ?? null; }
+    /** 由插件自己的 Fetch 路由调用；不接受任意 Host、端口或 URL。 */
+    async handleProxyRequest(request) {
+        const requestUrl = new URL(request.url);
+        const slug = requestUrl.searchParams.get('slug');
+        const binding = slug === null ? undefined : [...this.bindings.values()].find((item) => item.slug === slug);
+        if (binding === undefined)
+            return new Response('代理绑定不存在', { status: 404 });
+        if (isUpgradeRequest(request.headers))
+            return new Response('WebSocket 代理未由 DSH Fetch 接口提供', { status: 501 });
+        const instance = this.getInstance(binding.instanceId);
+        if (instance === undefined || instance.workspaceId !== binding.workspaceId || !isActive(instance.state)) {
+            this.bindings.delete(binding.id);
+            this.bindingProcesses.delete(binding.id);
+            return new Response('运行实例已停止', { status: 404 });
+        }
+        const process = await this.portInspector.inspect(binding.port);
+        const expectedProcess = this.bindingProcesses.get(binding.id);
+        if (process === null || expectedProcess === undefined || !sameProcess(expectedProcess, process) || (instance.pid !== null && process.pid !== instance.pid)) {
+            this.bindings.delete(binding.id);
+            this.bindingProcesses.delete(binding.id);
+            return new Response('端口监听身份已变化', { status: 404 });
+        }
+        const targetPath = requestUrl.searchParams.get('path') ?? '/';
+        let parsedPath;
+        try {
+            parsedPath = new URL(targetPath, 'http://127.0.0.1');
+        }
+        catch {
+            return new Response('代理路径非法', { status: 400 });
+        }
+        if (parsedPath.origin !== 'http://127.0.0.1' || !parsedPath.pathname.startsWith('/'))
+            return new Response('代理路径非法', { status: 400 });
+        const upstreamHeaders = new Headers();
+        request.headers.forEach((value, key) => { if (!HOP_BY_HOP_HEADERS.has(key.toLowerCase()) && key.toLowerCase() !== 'host')
+            upstreamHeaders.set(key, value); });
+        const init = { method: request.method, headers: upstreamHeaders, redirect: 'manual', signal: request.signal };
+        if (request.method !== 'GET' && request.method !== 'HEAD')
+            init.body = await request.arrayBuffer();
+        let response;
+        try {
+            response = await fetch(`http://127.0.0.1:${binding.port}${parsedPath.pathname}${parsedPath.search}`, init);
+        }
+        catch (error) {
+            return new Response(error instanceof Error ? error.message : '上游服务不可达', { status: 502 });
+        }
+        const responseHeaders = new Headers();
+        response.headers.forEach((value, key) => { if (!HOP_BY_HOP_HEADERS.has(key.toLowerCase()))
+            responseHeaders.set(key, value); });
+        const location = response.headers.get('location');
+        if (location !== null)
+            responseHeaders.set('location', rewriteLocation(location, binding.url));
+        return new Response(response.body, { status: response.status, statusText: response.statusText, headers: responseHeaders });
+    }
+    workspaceRoot(workspaceId) {
+        const root = this.options.resolveWorkspaceRoot(workspaceId);
+        if (root === null || !isAbsolute(root))
+            throw new Error('Workspace 根目录不可用');
+        return normalize(root);
+    }
+    revokeBindings(workspaceId, profileId, port) {
+        for (const binding of this.bindings.values()) {
+            if (binding.workspaceId !== workspaceId || binding.profileId !== profileId || binding.port !== port)
+                continue;
+            this.bindings.delete(binding.id);
+            this.bindingProcesses.delete(binding.id);
+        }
+    }
+    configFilename(workspaceId) { return join(this.workspaceRoot(workspaceId), '.codingns', 'debug.json'); }
+}
+const HOP_BY_HOP_HEADERS = new Set(['connection', 'keep-alive', 'proxy-authenticate', 'proxy-authorization', 'te', 'trailer', 'transfer-encoding', 'upgrade']);
+function isUpgradeRequest(headers) { return headers.get('upgrade')?.toLowerCase() === 'websocket'; }
+function rewriteLocation(location, proxyUrl) {
+    try {
+        const parsed = new URL(location, 'http://127.0.0.1');
+        if (parsed.hostname !== '127.0.0.1' && parsed.hostname !== 'localhost')
+            return location;
+        return `${proxyUrl}&path=${encodeURIComponent(`${parsed.pathname}${parsed.search}`)}`;
+    }
+    catch {
+        return location;
+    }
+}
+/** Node 平台的最小端口观察器；具体系统命令只留在这一层。 */
+export class NodeDebugPortInspector {
+    async inspect(port) {
+        const result = process.platform === 'win32'
+            ? spawnSync('netstat', ['-ano', '-p', 'tcp'], { encoding: 'utf8', windowsHide: true })
+            : spawnSync('lsof', ['-nP', `-iTCP:${port}`, '-sTCP:LISTEN', '-Fpct'], { encoding: 'utf8' });
+        if (result.status !== 0 && result.stdout.trim() === '')
+            return null;
+        const pid = process.platform === 'win32' ? parseWindowsPid(result.stdout, port) : parsePosixPid(result.stdout);
+        if (pid === null)
+            return null;
+        const details = spawnSync(process.platform === 'win32' ? 'powershell' : 'ps', process.platform === 'win32'
+            ? ['-NoProfile', '-Command', `(Get-Process -Id ${pid}).Path`]
+            : ['-o', 'lstart=,command=', '-p', String(pid)], { encoding: 'utf8', windowsHide: true });
+        const lines = details.stdout.trim().split(/\s{2,}|\n/u).map((line) => line.trim()).filter(Boolean);
+        const startToken = lines[0] ?? '';
+        if (startToken === '')
+            return null;
+        return { pid, startToken, command: lines.slice(1).join(' ') || null, cwd: null };
+    }
+    async terminate(processInfo) {
+        if (processInfo.startToken.trim() === '')
+            throw new Error('无法确认进程启动身份');
+        process.kill(processInfo.pid, 'SIGTERM');
+    }
+}
+function findProfile(config, profileId) {
+    const profile = config.profiles.find((item) => item.id === profileId);
+    if (profile === undefined)
+        throw new Error(`Spec003 配置项不存在: ${profileId}`);
+    return profile;
+}
+function sameProcess(left, right) {
+    return left === null ? right === null : right !== null && left.pid === right.pid && left.startToken === right.startToken;
+}
+function isActive(state) { return state === 'starting' || state === 'running' || state === 'stopping'; }
+function isMissingFile(error) { return typeof error === 'object' && error !== null && 'code' in error && error.code === 'ENOENT'; }
+function parsePosixPid(output) {
+    const match = output.match(/(?:^|\n)p(\d+)(?:\n|$)/u);
+    return match?.[1] === undefined ? null : Number(match[1]);
+}
+function parseWindowsPid(output, port) {
+    const suffix = `:${port}`;
+    for (const line of output.split(/\r?\n/u)) {
+        const fields = line.trim().split(/\s+/u);
+        if (fields[1]?.endsWith(suffix) && fields[3] === 'LISTENING')
+            return Number(fields[4]) || null;
+    }
+    return null;
+}
+//# sourceMappingURL=debug.js.map

package/data/build/dist/host/dsh-device-runtime.d.ts

@@ -0,0 +1,39 @@
+import type { FeatureResourceScope } from '../shared/contracts/feature.js';
+import type { DshDeviceCredentialRecord, DshDeviceSummary } from '../shared/contracts/dsh-device.js';
+import type { CodingNsControlApiClient } from './control-api-client.js';
+import { type DshDeviceCredentialStore } from './credential-store.js';
+import { startHostRelayRuntime, type HostDtlsIdentityStore, type HostRelayRuntime } from './relay-tunnel-runtime.js';
+import type { DshGatewayFeature } from '../transport/dsh-gateway.js';
+import type { DshTransportDebugLogger } from '../transport/debug.js';
+export interface DshHostDeviceRuntimeOptions {
+    readonly controlClient: Pick<CodingNsControlApiClient, 'registerDshDevice' | 'listDshDevices' | 'heartbeatDshDevice' | 'createDshRelayTicket'>;
+    readonly accessToken: string;
+    /** 认证续期后动态读取最新 access token；未提供时沿用 accessToken。 */
+    readonly accessTokenProvider?: () => string | null;
+    readonly credentialStore?: DshDeviceCredentialStore;
+    readonly dtlsStore?: HostDtlsIdentityStore;
+    readonly displayName?: string;
+    readonly protocolVersion?: string;
+    /** 当前 DSH 宿主的真实版本，用于 Relay Transport 握手。 */
+    readonly dshVersion?: string;
+    readonly capabilities?: readonly string[];
+    readonly resources?: Pick<FeatureResourceScope, 'add'>;
+    readonly signalingSocketFactory?: Parameters<typeof startHostRelayRuntime>[0]['signalingSocketFactory'];
+    readonly peerConnectionFactory?: Parameters<typeof startHostRelayRuntime>[0]['peerConnectionFactory'];
+    readonly gatewayFeatures?: readonly DshGatewayFeature[];
+    readonly heartbeatIntervalMs?: number;
+    readonly onRuntime?: (runtime: HostRelayRuntime) => void | Promise<void>;
+    readonly debug?: DshTransportDebugLogger;
+}
+export interface DshHostDeviceRuntime {
+    readonly credential: DshDeviceCredentialRecord;
+    readonly device: DshDeviceSummary;
+    readonly runtime: HostRelayRuntime;
+    stop(): Promise<void>;
+}
+/**
+ * 注册一个独立的 DSH 设备并启动 Host Relay runtime。
+ * 这里不读取或写入 Codingns4DSH binding，设备凭据也与 refresh token 分文件保存。
+ */
+export declare function startDshHostDeviceRuntime(options: DshHostDeviceRuntimeOptions): Promise<DshHostDeviceRuntime>;
+//# sourceMappingURL=dsh-device-runtime.d.ts.map

package/data/build/dist/host/dsh-device-runtime.js

@@ -0,0 +1,118 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { FileDshDeviceCredentialStore, } from './credential-store.js';
+import { ensureHostDtlsIdentity, FileHostDtlsIdentityStore, startHostRelayRuntime, } from './relay-tunnel-runtime.js';
+/**
+ * 注册一个独立的 DSH 设备并启动 Host Relay runtime。
+ * 这里不读取或写入 Codingns4DSH binding，设备凭据也与 refresh token 分文件保存。
+ */
+export async function startDshHostDeviceRuntime(options) {
+    if (!options.accessToken.trim())
+        throw new TypeError('DSH Host accessToken 不能为空');
+    const getAccessToken = () => {
+        const token = options.accessTokenProvider === undefined ? options.accessToken : options.accessTokenProvider();
+        if (typeof token !== 'string' || !token.trim())
+            throw new Error('DSH Host accessToken 已失效');
+        return token;
+    };
+    const credentialStore = options.credentialStore ?? new FileDshDeviceCredentialStore(defaultDshCredentialPath());
+    const dtlsStore = options.dtlsStore ?? new FileHostDtlsIdentityStore(defaultDtlsPath());
+    const identity = await ensureHostDtlsIdentity(dtlsStore);
+    let credential = await credentialStore.read();
+    let device;
+    if (credential === null || credential.dtlsFingerprint !== identity.fingerprint) {
+        const request = {
+            displayName: options.displayName?.trim() || 'DSH Host',
+            devicePublicKey: identity.certPem,
+            dtlsFingerprint: identity.fingerprint,
+            protocolVersion: options.protocolVersion ?? 'dsh-envelope-v1',
+            capabilities: [...(options.capabilities ?? ['rpc', 'pty', 'file', 'web'])],
+        };
+        const registered = await options.controlClient.registerDshDevice(getAccessToken(), request);
+        credential = {
+            deviceId: registered.device.dshDeviceId ?? registered.device.deviceId ?? (() => { throw new Error('DSH 注册响应缺少设备标识'); })(),
+            deviceCredential: registered.deviceCredential,
+            credentialVersion: registered.credentialVersion,
+            dtlsFingerprint: identity.fingerprint,
+            tunnelDomain: registered.device.tunnelDomain ?? null,
+            displayName: registered.device.displayName,
+            savedAt: new Date().toISOString(),
+        };
+        await credentialStore.write(credential);
+        device = registered.device;
+    }
+    else {
+        const listed = await options.controlClient.listDshDevices(getAccessToken());
+        device = listed.devices.find((candidate) => (candidate.dshDeviceId ?? candidate.deviceId) === credential.deviceId) ?? {
+            dshDeviceId: credential.deviceId,
+            deviceId: credential.deviceId,
+            displayName: credential.displayName,
+            protocolVersion: options.protocolVersion ?? 'dsh-envelope-v1',
+            capabilities: [...(options.capabilities ?? [])],
+            dtlsFingerprint: credential.dtlsFingerprint,
+            ...(credential.tunnelDomain === null ? {} : { tunnelDomain: credential.tunnelDomain }),
+            status: 'active',
+            online: false,
+            lastHeartbeatAt: null,
+            createdAt: credential.savedAt,
+            updatedAt: credential.savedAt,
+        };
+    }
+    if (credential === null)
+        throw new Error('DSH 设备凭据初始化失败');
+    const savedCredential = credential;
+    await options.controlClient.heartbeatDshDevice(getAccessToken(), savedCredential.deviceId, savedCredential.deviceCredential);
+    const runtimeOptions = {
+        controlClient: { createSignalingTicket: async () => { throw new Error('DSH runtime 必须使用 DSH ticket'); } },
+        createTicket: ({ identity: material, credentialVersion }) => requestDshTicket(options.controlClient, getAccessToken(), savedCredential, material.fingerprint, credentialVersion),
+        accessToken: options.accessToken,
+        bindingId: savedCredential.deviceId,
+        credentialVersion: savedCredential.credentialVersion,
+        dtlsStore,
+        hostId: savedCredential.deviceId,
+        ...(options.resources === undefined ? {} : { resources: options.resources }),
+        ...(options.signalingSocketFactory === undefined ? {} : { signalingSocketFactory: options.signalingSocketFactory }),
+        ...(options.peerConnectionFactory === undefined ? {} : { peerConnectionFactory: options.peerConnectionFactory }),
+        ...(options.gatewayFeatures === undefined ? {} : { gatewayFeatures: options.gatewayFeatures }),
+        ...(options.dshVersion === undefined ? {} : { dshVersion: options.dshVersion }),
+        ...(options.debug === undefined ? {} : { debug: options.debug }),
+    };
+    const runtime = await startHostRelayRuntime(runtimeOptions);
+    let stopped = false;
+    const interval = options.heartbeatIntervalMs === 0 ? null : setInterval(() => {
+        if (stopped)
+            return;
+        void Promise.resolve()
+            .then(() => options.controlClient.heartbeatDshDevice(getAccessToken(), savedCredential.deviceId, savedCredential.deviceCredential))
+            .catch(() => undefined);
+    }, options.heartbeatIntervalMs ?? 30_000);
+    const stop = async () => {
+        if (stopped)
+            return;
+        stopped = true;
+        if (interval !== null)
+            clearInterval(interval);
+        await runtime.close();
+    };
+    options.resources?.add(stop);
+    await options.onRuntime?.(runtime);
+    return { credential: savedCredential, device, runtime, stop };
+}
+async function requestDshTicket(client, accessToken, credential, fingerprint, credentialVersion) {
+    const response = await client.createDshRelayTicket(accessToken, {
+        dshDeviceId: credential.deviceId,
+        deviceCredential: credential.deviceCredential,
+        hostDtlsFingerprint: fingerprint,
+        credentialVersion: credentialVersion ?? credential.credentialVersion,
+        role: 'host',
+    });
+    return {
+        ...response,
+        bindingId: response.dshDeviceId,
+        tunnelDomain: response.tunnelDomain ?? response.dshDeviceId,
+        credentialVersion: response.credentialVersion,
+    };
+}
+function defaultDshCredentialPath() { return join(homedir(), '.config', 'codingns4dsh', 'device-credential.json'); }
+function defaultDtlsPath() { return join(homedir(), '.config', 'codingns4dsh', 'dtls-identity.json'); }
+//# sourceMappingURL=dsh-device-runtime.js.map

package/data/build/dist/host/dsh-gateway-feature.d.ts

@@ -0,0 +1,5 @@
+import type { CodingNsRpcTable } from './rpc-table.js';
+import type { DshGatewayFeature } from '../transport/dsh-gateway.js';
+/** 将 Host 已登记的 RPC 命名空间接到 DSH Gateway。 */
+export declare function createDshRpcGatewayFeature(rpc: CodingNsRpcTable): DshGatewayFeature;
+//# sourceMappingURL=dsh-gateway-feature.d.ts.map