@jingyi0605/codingns4dsh 0.1.0

package/data/build/dist/host/relay-tunnel-runtime.js

@@ -0,0 +1,361 @@
+/**
+ * Codingns4DSH Relay Host 运行时。
+ *
+ * 这个模块把 Host 侧真正需要的运行时资源集中起来：DTLS 身份、Host 票据、
+ * Relay 信令 WebSocket 以及每个 Client 独立的 werift PeerConnection。业务层
+ * 只接收已经打开的 DataChannel Carrier，不接触 access token 或信令细节。
+ */
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { RTCCertificate, RTCDtlsTransport, RTCPeerConnection } from 'werift';
+import { acceptWebRtcHost, createHostSignalingTicketRequest, } from '../transport/webrtc-host.js';
+import { DshGateway } from '../transport/dsh-gateway.js';
+import { createDshTransportDebugLogger } from '../transport/debug.js';
+/** Relay Tunnel 规定的 DataChannel label，不允许使用插件自定义值。 */
+export const CODINGNS_TUNNEL_DATA_CHANNEL_LABEL = 'codingns-tunnel';
+/** 文件存储适用于 Host 桌面进程；先写临时文件再 rename，避免半截证书。 */
+export class FileHostDtlsIdentityStore {
+    filePath;
+    constructor(filePath) {
+        this.filePath = filePath;
+        if (!filePath.trim())
+            throw new TypeError('DTLS identity file path 不能为空');
+    }
+    async read() {
+        try {
+            const raw = await readFile(this.filePath, 'utf8');
+            const parsed = JSON.parse(raw);
+            return parseIdentity(parsed);
+        }
+        catch (error) {
+            if (isNodeError(error, 'ENOENT'))
+                return null;
+            throw error;
+        }
+    }
+    async write(identity) {
+        await mkdir(dirname(this.filePath), { recursive: true });
+        const temporaryPath = `${this.filePath}.${process.pid}.tmp`;
+        await writeFile(temporaryPath, `${JSON.stringify(identity)}\n`, { encoding: 'utf8', mode: 0o600 });
+        await rename(temporaryPath, this.filePath);
+    }
+}
+/** 生成一张新的 werift DTLS 证书，并返回控制面约定的 sha-256 指纹。 */
+export async function generateHostDtlsIdentity() {
+    const certificate = await RTCDtlsTransport.SetupCertificate();
+    const fingerprint = formatHostDtlsFingerprint(certificate);
+    const now = new Date().toISOString();
+    return {
+        privateKeyPem: certificate.privateKey,
+        certPem: certificate.certPem,
+        signatureHash: certificate.signatureHash,
+        fingerprint,
+        createdAt: now,
+        updatedAt: now,
+    };
+}
+/** 读取已有身份，否则生成并持久化；指纹因此跨进程重启保持不变。 */
+export async function ensureHostDtlsIdentity(store) {
+    const existing = await store.read();
+    if (existing)
+        return existing;
+    const generated = await generateHostDtlsIdentity();
+    await store.write(generated);
+    return generated;
+}
+export function formatHostDtlsFingerprint(certificate) {
+    const fingerprints = certificate.getFingerprints();
+    const selected = fingerprints.find((item) => item.algorithm.toLowerCase() === 'sha-256') ?? fingerprints[0];
+    if (!selected)
+        throw new Error('DTLS 证书缺少指纹');
+    const value = selected.value.split(':').map((part) => part.trim().toUpperCase().padStart(2, '0')).join(':');
+    return `${selected.algorithm.toLowerCase()} ${value}`;
+}
+/** 同一 Host 进程内只允许一个 Relay runtime，避免热重载留下旧 Gateway 和流。 */
+const activeRelayRuntimes = new Map();
+/**
+ * 启动一个可接收多个 Client 的 Host Relay runtime。
+ * `resources` 若提供，所有 WebSocket、PeerConnection、心跳和换票计时器都会登记。
+ */
+export async function startHostRelayRuntime(options) {
+    if (!options.accessToken.trim())
+        throw new TypeError('Host Relay accessToken 不能为空');
+    if (!options.bindingId?.trim() && options.createTicket === undefined)
+        throw new TypeError('Host Relay bindingId 或 createTicket 必须提供');
+    const bindingId = options.bindingId?.trim() ?? '';
+    const runtimeKey = (options.hostId?.trim() || bindingId) || null;
+    const previousRuntime = runtimeKey === null ? undefined : activeRelayRuntimes.get(runtimeKey);
+    if (previousRuntime)
+        await previousRuntime.close();
+    const debug = options.debug ?? createDshTransportDebugLogger({ side: 'host', component: 'relay-runtime' });
+    const identity = await ensureHostDtlsIdentity(options.dtlsStore);
+    const requestTicket = () => options.createTicket
+        ? options.createTicket({ accessToken: options.accessToken, identity, ...(options.credentialVersion === undefined ? {} : { credentialVersion: options.credentialVersion }) })
+        : options.controlClient.createSignalingTicket(options.accessToken, createHostSignalingTicketRequest({
+            bindingId,
+            hostDtlsFingerprint: identity.fingerprint,
+            ...(options.credentialVersion === undefined ? {} : { credentialVersion: options.credentialVersion }),
+        }));
+    let ticket = await requestTicket();
+    let closed = false;
+    let renewTimer = null;
+    let renewalInFlight = false;
+    let renewalResourceRegistered = false;
+    let acceptor = await createAcceptor(ticket);
+    const gateways = new Map();
+    const scheduleRenewal = () => {
+        if (renewTimer !== null)
+            clearTimeout(renewTimer);
+        if (closed)
+            return;
+        const expiresAt = Date.parse(ticket.expiresAt);
+        const skew = options.ticketRenewSkewMs ?? 30_000;
+        // 信令票据只在 WebSocket 建立时校验。连接仍然存活时不能因为票据
+        // 到期而替换 WebSocket，否则会在客户端 offer/answer 期间丢信令。
+        const signalingOpen = isSignalingOpen(acceptor.signaling);
+        const untilExpiry = Number.isFinite(expiresAt) ? expiresAt - Date.now() : 60_000;
+        const delay = signalingOpen
+            ? Math.min(2_147_000_000, Math.max(30_000, untilExpiry - skew))
+            : Math.max(1_000, Math.min(30_000, untilExpiry - skew));
+        renewTimer = setTimeout(() => { void renew(); }, delay);
+        if (options.resources && !renewalResourceRegistered) {
+            renewalResourceRegistered = true;
+            options.resources.add(() => {
+                if (renewTimer !== null)
+                    clearTimeout(renewTimer);
+                renewTimer = null;
+            });
+        }
+    };
+    const renew = async () => {
+        if (closed || renewalInFlight)
+            return;
+        if (isSignalingOpen(acceptor.signaling)) {
+            scheduleRenewal();
+            return;
+        }
+        renewalInFlight = true;
+        try {
+            const nextTicket = await requestTicket();
+            const previous = acceptor;
+            ticket = nextTicket;
+            acceptor = await createAcceptor(nextTicket);
+            await previous.close();
+            scheduleRenewal();
+        }
+        catch {
+            if (!closed) {
+                renewTimer = setTimeout(() => { void renew(); }, 5_000);
+            }
+        }
+        finally {
+            renewalInFlight = false;
+        }
+    };
+    scheduleRenewal();
+    options.resources?.add(() => runtimeClose());
+    async function createAcceptor(currentTicket) {
+        // acceptWebRtcHost 负责等待 registered；这里必须返回尚未消费注册事件的原始 socket。
+        const socketFactory = options.signalingSocketFactory ?? createRawHostSignalingSocket;
+        return acceptWebRtcHost({
+            signalingTicket: currentTicket,
+            signalingSocketFactory: socketFactory,
+            peerConnectionFactory: options.peerConnectionFactory ?? createWeriftPeerConnectionFactory(identity),
+            channelLabel: CODINGNS_TUNNEL_DATA_CHANNEL_LABEL,
+            debug,
+            onConnection: (session) => {
+                if (!session.carrier)
+                    return;
+                const gateway = new DshGateway({
+                    carrier: session.carrier,
+                    generation: options.generation ?? '1',
+                    hostScope: { hostId: options.hostId ?? bindingId, kind: 'local' },
+                    ...(options.gatewayFeatures === undefined ? {} : { features: options.gatewayFeatures }),
+                    ...(options.dshVersion === undefined ? {} : { dshVersion: options.dshVersion }),
+                    ...(options.gatewayRegistry === undefined ? {} : { registry: options.gatewayRegistry }),
+                    debug,
+                });
+                gateway.start();
+                gateways.set(session.sessionId, gateway);
+                void options.onSession?.({
+                    sessionId: session.sessionId,
+                    peerConnection: session.peerConnection,
+                    get carrier() { return session.carrier; },
+                    close: async () => { await gateway.close(); await session.close(); },
+                    tunnelDomain: currentTicket.tunnelDomain,
+                    gateway,
+                });
+            },
+            onSessionClosed: async (sessionId) => {
+                const gateway = gateways.get(sessionId);
+                gateways.delete(sessionId);
+                await gateway?.close();
+            },
+        });
+    }
+    async function runtimeClose() {
+        if (closed)
+            return;
+        closed = true;
+        if (runtimeKey !== null && activeRelayRuntimes.get(runtimeKey) === registration)
+            activeRelayRuntimes.delete(runtimeKey);
+        if (renewTimer !== null)
+            clearTimeout(renewTimer);
+        renewTimer = null;
+        await acceptor.close();
+        for (const gateway of gateways.values())
+            await gateway.close();
+        gateways.clear();
+    }
+    const registration = { close: runtimeClose };
+    if (runtimeKey !== null)
+        activeRelayRuntimes.set(runtimeKey, registration);
+    return {
+        identity,
+        get ticket() { return ticket; },
+        get acceptor() { return acceptor; },
+        get sessions() { return acceptor.sessions; },
+        close: runtimeClose,
+    };
+}
+function isSignalingOpen(socket) {
+    if (!isRecord(socket) || typeof socket.readyState !== 'number')
+        return true;
+    return socket.readyState === 1;
+}
+/** 为 Host answerer 创建 werift PeerConnection，并适配到 transport 的注入接口。 */
+export function createWeriftPeerConnectionFactory(identity) {
+    return ({ iceServers, iceTransportPolicy }) => {
+        const certificate = identity ? new RTCCertificate(identity.privateKeyPem, identity.certPem, identity.signatureHash) : undefined;
+        const peer = new RTCPeerConnection({ iceServers, iceTransportPolicy, ...(certificate ? { certificates: [certificate] } : {}) });
+        const adapted = {
+            get connectionState() { return peer.connectionState; },
+            get iceConnectionState() { return peer.iceConnectionState; },
+            get onicecandidate() { return peer.onicecandidate; },
+            set onicecandidate(value) { peer.onicecandidate = value; },
+            get ondatachannel() { return peer.ondatachannel; },
+            set ondatachannel(value) { peer.ondatachannel = value; },
+            addEventListener: (type, listener) => { peer.addEventListener(type, listener); },
+            removeEventListener: (type, listener) => { peer.removeEventListener(type, listener); },
+            createAnswer: async () => {
+                const answer = await peer.createAnswer();
+                return { type: 'answer', sdp: answer.sdp };
+            },
+            setRemoteDescription: (description) => peer.setRemoteDescription(description),
+            setLocalDescription: (description) => peer.setLocalDescription(description).then(() => undefined),
+            addIceCandidate: (candidate) => peer.addIceCandidate(candidate),
+            close: () => { void peer.close(); },
+        };
+        return adapted;
+    };
+}
+/** 建立 Host 信令并等待服务端 registered；registered 后每 20 秒发 ping。 */
+export async function createRegisteredHostSignalingSocket(url, options = {}) {
+    const WebSocketCtor = globalThis.WebSocket;
+    if (!WebSocketCtor)
+        throw new Error('当前 Node 运行时没有 WebSocket 实现');
+    const socket = new WebSocketCtor(url);
+    const timeoutMs = options.registrationTimeoutMs ?? 15_000;
+    const heartbeatMs = options.heartbeatIntervalMs ?? 20_000;
+    return new Promise((resolve, reject) => {
+        let timer = setTimeout(() => finish(new Error('等待 Relay registered 超时')), timeoutMs);
+        let heartbeat = null;
+        let done = false;
+        let result = null;
+        const cleanup = () => {
+            if (timer !== null)
+                clearTimeout(timer);
+            if (heartbeat !== null)
+                clearInterval(heartbeat);
+            timer = null;
+            heartbeat = null;
+        };
+        const finish = (error) => {
+            if (done)
+                return;
+            done = true;
+            cleanup();
+            if (error) {
+                try {
+                    socket.close(1000, 'registration_failed');
+                }
+                catch { /* ignore */ }
+                reject(error);
+            }
+            else {
+                heartbeat = heartbeatMs > 0 ? setInterval(() => {
+                    if (socket.readyState === 1)
+                        socket.send(JSON.stringify({ type: 'ping', at: new Date().toISOString() }));
+                }, heartbeatMs) : null;
+                result = {
+                    get readyState() { return socket.readyState; },
+                    send: (data) => socket.send(data),
+                    close: (code, reason) => {
+                        cleanup();
+                        socket.close(code, reason);
+                    },
+                    addEventListener: (type, listener) => socket.addEventListener(type, listener),
+                    removeEventListener: (type, listener) => socket.removeEventListener(type, listener),
+                };
+                resolve(result);
+            }
+        };
+        socket.onmessage = (event) => {
+            let message;
+            try {
+                message = JSON.parse(typeof event.data === 'string' ? event.data : '');
+            }
+            catch {
+                return;
+            }
+            if (isRecord(message) && message.type === 'registered')
+                finish();
+            else if (isRecord(message) && message.type === 'error')
+                finish(new Error(`${String(message.errorCode)}: ${String(message.detail)}`));
+        };
+        socket.onerror = () => {
+            if (done) {
+                cleanup();
+                return;
+            }
+            finish(new Error('Relay 信令 WebSocket 连接失败'));
+        };
+        socket.onclose = () => {
+            if (done) {
+                cleanup();
+                return;
+            }
+            finish(new Error('Relay 信令 WebSocket 已关闭'));
+        };
+    });
+}
+/** 默认运行时使用的原始 WebSocket 工厂，注册握手交给 acceptWebRtcHost 统一处理。 */
+async function createRawHostSignalingSocket(url) {
+    const WebSocketCtor = globalThis.WebSocket;
+    if (!WebSocketCtor)
+        throw new Error('当前 Node 运行时没有 WebSocket 实现');
+    const socket = new WebSocketCtor(url);
+    return socket;
+}
+function parseIdentity(value) {
+    if (!isRecord(value) || typeof value.privateKeyPem !== 'string' || typeof value.certPem !== 'string'
+        || typeof value.fingerprint !== 'string' || typeof value.createdAt !== 'string' || typeof value.updatedAt !== 'string'
+        || !isRecord(value.signatureHash) || typeof value.signatureHash.signature !== 'number' || typeof value.signatureHash.hash !== 'number') {
+        throw new TypeError('DTLS identity 文件格式无效');
+    }
+    return {
+        privateKeyPem: value.privateKeyPem,
+        certPem: value.certPem,
+        fingerprint: value.fingerprint,
+        createdAt: value.createdAt,
+        updatedAt: value.updatedAt,
+        signatureHash: { signature: value.signatureHash.signature, hash: value.signatureHash.hash },
+    };
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isNodeError(value, code) {
+    return value instanceof Error && value.code === code;
+}
+//# sourceMappingURL=relay-tunnel-runtime.js.map

package/data/build/dist/host/remote-web-runtime.d.ts

@@ -0,0 +1,78 @@
+import type { DshGatewayFeature } from '../transport/dsh-gateway.js';
+import { type DshTransportDebugLogger } from '../transport/debug.js';
+/** 远程 DSH Web 资源；正文始终使用二进制，不经 Base64。 */
+export interface DshWebAsset {
+    readonly contentType: string;
+    readonly body: Uint8Array;
+    readonly etag?: string;
+}
+export interface DshWebBoot {
+    readonly dshVersion: string;
+    readonly contentType: string;
+    readonly html: string;
+    readonly entry?: string;
+    readonly styles?: readonly string[];
+    readonly scripts?: readonly string[];
+    readonly capabilities: readonly string[];
+}
+export interface DshWebSession {
+    readonly sessionId: string;
+    readonly workspaceId?: string;
+    readonly dshVersion: string;
+}
+export interface DshWebSocketLike {
+    readonly readyState?: number;
+    send(data: string | Uint8Array): void;
+    close(code?: number, reason?: string): void;
+    addEventListener(type: 'open' | 'message' | 'close' | 'error', listener: (event: Event) => void): void;
+    removeEventListener(type: 'open' | 'message' | 'close' | 'error', listener: (event: Event) => void): void;
+}
+export interface DshWebRuntimeProvider {
+    openSession(input: {
+        readonly workspaceId?: string;
+        readonly sessionId?: string;
+    }): Promise<DshWebSession>;
+    getBoot(session: DshWebSession): Promise<DshWebBoot>;
+    getAsset(session: DshWebSession, path: string): Promise<DshWebAsset>;
+    getPluginManifest(session: DshWebSession): Promise<unknown>;
+    getPluginBundle(session: DshWebSession, pluginId: string, path: string): Promise<DshWebAsset>;
+    openWebSocket(session: DshWebSession, path: string): Promise<DshWebSocketLike>;
+    request?(session: DshWebSession, input: {
+        readonly path: string;
+        readonly method?: string;
+        readonly headers?: readonly [string, string][];
+        readonly body?: string;
+    }): Promise<{
+        readonly status: number;
+        readonly headers: readonly [string, string][];
+        readonly body: string;
+    }>;
+}
+export interface RemoteWebRuntimeFeatureOptions {
+    readonly provider: DshWebRuntimeProvider;
+    readonly maxAssetBytes?: number;
+    readonly debug?: DshTransportDebugLogger;
+}
+/**
+ * 把 Host 自己的 DSH Web 暴露为 DSH Gateway 的 web 频道。
+ *
+ * 这个模块不接受任意 URL，也不把 Host 凭据传给 Client；具体本地 DSH Web
+ * 访问由 provider 完成，便于真实运行时和 Fake 测试分别注入。
+ */
+export declare function createRemoteWebRuntimeFeature(options: RemoteWebRuntimeFeatureOptions): DshGatewayFeature;
+export interface LocalDshWebRuntimeProviderOptions {
+    readonly port: number;
+    readonly dshVersion: string;
+    /** DSH 官方 Web 认证入口；首次请求只用于换取 HttpOnly Cookie。 */
+    readonly authenticatedUrl?: string;
+    readonly fetcher?: typeof fetch;
+    readonly websocketFactory?: (url: string, options?: {
+        readonly headers?: Readonly<Record<string, string>>;
+    }) => DshWebSocketLike;
+    readonly bootPath?: string;
+    readonly pluginManifestPath?: string;
+    readonly allowedPathPrefixes?: readonly string[];
+}
+/** 访问本机 DSH Web 的默认 provider；只允许 loopback 和明确的资源路径。 */
+export declare function createLocalDshWebRuntimeProvider(options: LocalDshWebRuntimeProviderOptions): DshWebRuntimeProvider;
+//# sourceMappingURL=remote-web-runtime.d.ts.map