dsh-plugin-dshm 0.0.0-stage → 0.1.1

package/lib/discovery/interfaces.js

@@ -0,0 +1,24 @@
+import net from 'node:net';
+import os from 'node:os';
+export function isTailscale(address) {
+    if (address.toLowerCase().startsWith('fd7a:115c:a1e0:'))
+        return true;
+    if (net.isIP(address) !== 4)
+        return false;
+    const [a, b] = address.split('.').map(Number);
+    return a === 100 && b >= 64 && b <= 127;
+}
+export function isPrivateAddress(address, allowLoopback = false) {
+    if (net.isIP(address) === 6)
+        return (allowLoopback && address === '::1') || /^(fc|fd)/i.test(address);
+    if (net.isIP(address) !== 4)
+        return false;
+    const [a, b] = address.split('.').map(Number);
+    return (allowLoopback && a === 127) || a === 10 || (a === 172 && b >= 16 && b <= 31) || (a === 192 && b === 168) || isTailscale(address);
+}
+export function privateInterfaces(mode = 'all-private') {
+    return [...new Set(Object.values(os.networkInterfaces()).flatMap(entries => (entries ?? [])
+            .filter(entry => !entry.internal && isPrivateAddress(entry.address) && (mode === 'all-private' || (mode === 'tailscale' ? isTailscale(entry.address) : !isTailscale(entry.address))))
+            .map(entry => entry.address)))].sort();
+}
+export const endpoint = (address, port) => `${net.isIP(address) === 6 ? `[${address}]` : address}:${port}`;

package/lib/errors.d.ts

@@ -0,0 +1,5 @@
+export declare class DmpError extends Error {
+    readonly code: string;
+    readonly details?: Record<string, unknown> | undefined;
+    constructor(code: string, message?: string, details?: Record<string, unknown> | undefined);
+}

package/lib/errors.js

@@ -0,0 +1,10 @@
+export class DmpError extends Error {
+    code;
+    details;
+    constructor(code, message = code, details) {
+        super(message);
+        this.code = code;
+        this.details = details;
+        this.name = 'DmpError';
+    }
+}

package/lib/host/local.d.ts

@@ -0,0 +1,5 @@
+import type { HostControls } from './types.js';
+export declare function startLocalControl(directory: string, controls: HostControls): Promise<{
+    close(): Promise<void>;
+}>;
+export declare function localRequest<T>(directory: string, method: 'GET' | 'POST', route: string, body?: unknown): Promise<T>;

package/lib/host/local.js

@@ -0,0 +1,122 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import http from 'node:http';
+import path from 'node:path';
+import { writePrivate } from '../pairing/state.js';
+function record(directory) {
+    const value = JSON.parse(fs.readFileSync(path.join(directory, 'control.json'), 'utf8'));
+    if (!Number.isInteger(value.pid) || typeof value.socket !== 'string' || typeof value.token !== 'string' || value.token.length !== 64)
+        throw new Error('Invalid local bridge control record');
+    return value;
+}
+function equal(left, right) {
+    const a = Buffer.from(left), b = Buffer.from(right);
+    return a.length === b.length && crypto.timingSafeEqual(a, b);
+}
+export async function startLocalControl(directory, controls) {
+    const file = path.join(directory, 'control.json');
+    if (fs.existsSync(file)) {
+        const old = record(directory);
+        let live = true;
+        try {
+            process.kill(old.pid, 0);
+        }
+        catch (error) {
+            if (error.code === 'ESRCH')
+                live = false;
+        }
+        if (live)
+            throw new Error('A bridge already owns this home; use its existing host controls');
+    }
+    const token = crypto.randomBytes(32).toString('hex');
+    const suffix = crypto.randomBytes(6).toString('hex');
+    const socket = process.platform === 'win32' ? `\\\\.\\pipe\\dshm-${suffix}` : path.join(directory, `control-${suffix}.sock`);
+    const server = http.createServer(async (req, res) => {
+        res.setHeader('Content-Type', 'application/json');
+        res.setHeader('Cache-Control', 'no-store');
+        if (!equal(req.headers.authorization ?? '', `Bearer ${token}`)) {
+            res.writeHead(401);
+            res.end('{"error":"unauthorized"}');
+            return;
+        }
+        const reply = (code, value) => { res.writeHead(code); res.end(JSON.stringify(value)); };
+        try {
+            if (req.method === 'GET' && req.url === '/status') {
+                reply(200, controls.status());
+                return;
+            }
+            if (req.method === 'GET' && req.url === '/devices') {
+                reply(200, { devices: controls.devices() });
+                return;
+            }
+            if (req.method !== 'POST') {
+                reply(404, { error: 'not-found' });
+                return;
+            }
+            let body = '';
+            for await (const chunk of req) {
+                body += String(chunk);
+                if (Buffer.byteLength(body) > 4096) {
+                    reply(413, { error: 'too-large' });
+                    return;
+                }
+            }
+            const input = JSON.parse(body || '{}');
+            if (!input || typeof input !== 'object' || Array.isArray(input)) {
+                reply(400, { error: 'invalid-params' });
+                return;
+            }
+            if (req.url === '/pair' && !Object.keys(input).length) {
+                reply(200, await controls.pair());
+                return;
+            }
+            if (req.url === '/cancel' && !Object.keys(input).length) {
+                controls.cancelPair();
+                reply(200, {});
+                return;
+            }
+            if (req.url === '/revoke' && Object.keys(input).length === 1 && typeof input.deviceId === 'string') {
+                reply(200, { revoked: controls.revoke(input.deviceId) });
+                return;
+            }
+            reply(400, { error: 'invalid-params' });
+        }
+        catch {
+            reply(500, { error: 'host-control-failed' });
+        }
+    });
+    server.requestTimeout = 5000;
+    server.headersTimeout = 5000;
+    await new Promise((resolve, reject) => { server.once('error', reject); server.listen(socket, () => { server.off('error', reject); resolve(); }); });
+    if (process.platform !== 'win32')
+        fs.chmodSync(socket, 0o600);
+    writePrivate(file, JSON.stringify({ pid: process.pid, socket, token }));
+    return { async close() {
+            await new Promise(resolve => server.close(() => resolve()));
+            if (fs.existsSync(file) && equal(record(directory).token, token))
+                fs.rmSync(file);
+            if (process.platform !== 'win32')
+                fs.rmSync(socket, { force: true });
+        } };
+}
+export async function localRequest(directory, method, route, body) {
+    const { socket, token } = record(directory);
+    return new Promise((resolve, reject) => {
+        const request = http.request({ socketPath: socket, path: route, method, headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' }, timeout: 6000 }, res => {
+            let text = '';
+            res.on('data', chunk => { text += String(chunk); if (Buffer.byteLength(text) > 1024 * 1024)
+                request.destroy(new Error('Oversized host control response')); });
+            res.on('end', () => { try {
+                if (res.statusCode !== 200)
+                    throw new Error('Host control request failed');
+                resolve(JSON.parse(text));
+            }
+            catch (error) {
+                reject(error);
+            } });
+        });
+        request.on('timeout', () => request.destroy(new Error('Host control timed out')));
+        request.on('error', reject);
+        request.end(body === undefined ? undefined : JSON.stringify(body));
+    });
+}

package/lib/host/tailscale.d.ts

@@ -0,0 +1,43 @@
+import { existsSync } from 'node:fs';
+export type TailscaleState = 'unsupported' | 'not-installed' | 'needs-login' | 'needs-approval' | 'stopped' | 'starting' | 'running' | 'offline' | 'unavailable';
+export interface TailscaleStatus {
+    platform: 'macos' | 'windows' | 'other';
+    state: TailscaleState;
+    canOpenApp: boolean;
+    addresses: string[];
+}
+export interface RemoteSetupStatus extends TailscaleStatus {
+    bridgeListening: boolean;
+    connectedDevices: number;
+}
+interface Installation {
+    cli: string;
+    app?: string;
+}
+interface Adapter {
+    platform: NodeJS.Platform;
+    installation(): Installation | undefined;
+    read(cli: string): Promise<string>;
+    open(app: string): Promise<void>;
+    now(): number;
+}
+export declare function findInstallation(platform: NodeJS.Platform, env?: NodeJS.ProcessEnv, exists?: typeof existsSync): Installation | undefined;
+/** Only allowlisted state leaves this boundary; CLI data is never logged or stored. */
+export declare function parseStatus(text: string): Pick<TailscaleStatus, 'state' | 'addresses'>;
+export declare function createTailscaleControls(adapter?: Adapter): {
+    status(fresh?: boolean): Promise<TailscaleStatus>;
+    open(): Promise<void>;
+};
+/** Ready-to-pair is based on a current bound address, never just an installed app. */
+export declare function createRemoteControls(server: {
+    addresses: string[];
+    devices(): {
+        connectedVia?: string;
+    }[];
+    refreshInterfaces(): Promise<void>;
+}, tailscale: ReturnType<typeof createTailscaleControls>, pair: () => Promise<import('./types.js').HostPairing>): {
+    remoteSetup: (fresh?: boolean) => Promise<RemoteSetupStatus>;
+    openTailscale: () => Promise<void>;
+    pairRemote(): Promise<import("./types.js").HostPairing | undefined>;
+};
+export {};

package/lib/host/tailscale.js

@@ -0,0 +1,137 @@
+import { execFile, spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { isIP } from 'node:net';
+import path from 'node:path';
+import { isTailscale } from '../discovery/interfaces.js';
+// Do not search cwd/PATH for a program invoked by privileged host UI controls.
+export function findInstallation(platform, env = process.env, exists = existsSync) {
+    if (platform === 'darwin') {
+        const app = '/Applications/Tailscale.app', cli = `${app}/Contents/MacOS/Tailscale`;
+        return exists(cli) ? { cli, ...(exists(app) ? { app } : {}) } : undefined;
+    }
+    if (platform === 'win32') {
+        const root = env.ProgramFiles ?? 'C:\\Program Files';
+        if (!path.win32.isAbsolute(root) || root.startsWith('\\\\'))
+            return;
+        const cli = path.win32.join(root, 'Tailscale', 'tailscale.exe');
+        const app = path.win32.join(root, 'Tailscale', 'tailscale-ipn.exe');
+        return exists(cli) ? { cli, ...(exists(app) ? { app } : {}) } : undefined;
+    }
+}
+function readStatus(cli) {
+    return new Promise((resolve, reject) => {
+        execFile(cli, ['status', '--json', '--peers=false'], { encoding: 'utf8', timeout: 4000, maxBuffer: 256 * 1024, windowsHide: true }, (error, stdout) => {
+            // Even failures can contain a login URL. Never propagate native errors.
+            if (error)
+                reject(new Error('Tailscale status unavailable'));
+            else
+                resolve(stdout);
+        });
+    });
+}
+function openApp(app) {
+    return new Promise((resolve, reject) => {
+        if (process.platform === 'darwin') {
+            execFile('/usr/bin/open', ['-a', app], { timeout: 4000, maxBuffer: 4096 }, error => error ? reject(new Error('Could not open Tailscale')) : resolve());
+        }
+        else {
+            // The official tray app outlives this request; never kill it on a UI timeout.
+            const child = spawn(app, [], { detached: true, stdio: 'ignore', windowsHide: false });
+            child.once('error', () => reject(new Error('Could not open Tailscale')));
+            child.once('spawn', () => { child.unref(); resolve(); });
+        }
+    });
+}
+const object = (value) => value && typeof value === 'object' && !Array.isArray(value) ? value : undefined;
+/** Only allowlisted state leaves this boundary; CLI data is never logged or stored. */
+export function parseStatus(text) {
+    const invalid = { state: 'unavailable', addresses: [] };
+    if (Buffer.byteLength(text) > 256 * 1024)
+        return { ...invalid, addresses: [] };
+    let value;
+    try {
+        value = object(JSON.parse(text));
+    }
+    catch {
+        return { ...invalid, addresses: [] };
+    }
+    if (!value)
+        return { ...invalid, addresses: [] };
+    const self = object(value.Self);
+    const known = { NeedsLogin: 'needs-login', NeedsMachineAuth: 'needs-approval', Stopped: 'stopped', Starting: 'starting', NoState: 'starting' };
+    if (typeof value.BackendState !== 'string')
+        return { ...invalid, addresses: [] };
+    if (value.BackendState !== 'Running')
+        return { state: Object.hasOwn(known, value.BackendState) ? known[value.BackendState] : 'unavailable', addresses: [] };
+    if (self?.KeyExpired === true)
+        return { state: 'needs-login', addresses: [] };
+    if (self?.Online === false)
+        return { state: 'offline', addresses: [] };
+    if (self?.Online !== true || !Array.isArray(value.TailscaleIPs))
+        return { ...invalid, addresses: [] };
+    const addresses = [...new Set(value.TailscaleIPs.filter((ip) => typeof ip === 'string' && Boolean(isIP(ip)) && isTailscale(ip)))].slice(0, 8);
+    return { state: addresses.length ? 'running' : 'starting', addresses };
+}
+export function createTailscaleControls(adapter = {
+    platform: process.platform, installation: () => findInstallation(process.platform), read: readStatus, open: openApp, now: Date.now,
+}) {
+    let cached, expires = 0, pending;
+    const platform = adapter.platform === 'darwin' ? 'macos' : adapter.platform === 'win32' ? 'windows' : 'other';
+    return {
+        async status(fresh = false) {
+            if (!fresh && cached && adapter.now() < expires)
+                return cached;
+            if (pending)
+                return pending;
+            pending = (async () => {
+                const base = { platform, canOpenApp: false, addresses: [] };
+                if (platform === 'other')
+                    return { ...base, state: 'unsupported' };
+                try {
+                    const installation = adapter.installation();
+                    if (!installation)
+                        return { ...base, state: 'not-installed' };
+                    const present = { ...base, canOpenApp: Boolean(installation.app) };
+                    try {
+                        return { ...present, ...parseStatus(await adapter.read(installation.cli)) };
+                    }
+                    catch {
+                        return { ...present, state: 'unavailable' };
+                    }
+                }
+                catch {
+                    return { ...base, state: 'unavailable' };
+                }
+            })();
+            try {
+                cached = await pending;
+                expires = adapter.now() + 5000;
+                return cached;
+            }
+            finally {
+                pending = undefined;
+            }
+        },
+        async open() {
+            const installation = adapter.installation();
+            if (!installation?.app)
+                throw new Error('Tailscale app unavailable');
+            await adapter.open(installation.app);
+            expires = 0;
+        },
+    };
+}
+/** Ready-to-pair is based on a current bound address, never just an installed app. */
+export function createRemoteControls(server, tailscale, pair) {
+    const remoteSetup = async (fresh = false) => {
+        const status = await tailscale.status(fresh);
+        return { ...status, bridgeListening: status.state === 'running' && status.addresses.some(address => server.addresses.includes(address)),
+            connectedDevices: server.devices().filter(device => device.connectedVia === 'tailscale').length };
+    };
+    return { remoteSetup, openTailscale: () => tailscale.open(), async pairRemote() {
+            await server.refreshInterfaces();
+            if (!(await remoteSetup(true)).bridgeListening)
+                return;
+            return pair();
+        } };
+}

package/lib/host/types.d.ts

@@ -0,0 +1,40 @@
+import type { Device, HostInfo } from '../protocol/dmp.js';
+import type { RemoteSetupStatus } from './tailscale.js';
+export type HostDevice = Omit<Device, 'current'> & {
+    connected: boolean;
+    connectedVia?: 'lan' | 'tailscale' | 'other';
+};
+export interface HostStatus {
+    host: HostInfo;
+    bridgeVersion: string;
+    dshVersion: string;
+    dshStatus: string;
+    addresses: string[];
+    port: number;
+    connectedDevices: number;
+    pairing: {
+        active: boolean;
+        expiresAt?: string;
+    };
+    discovery: {
+        state: string;
+        serviceName: string;
+        error?: string;
+    };
+    guidance: string[];
+}
+export interface HostPairing {
+    url: string;
+    svg: string;
+    expiresAt: string;
+}
+export interface HostControls {
+    status(): HostStatus;
+    pair(): Promise<HostPairing>;
+    cancelPair(): void;
+    devices(): HostDevice[];
+    revoke(id: string): boolean;
+    remoteSetup(): Promise<RemoteSetupStatus>;
+    openTailscale(): Promise<void>;
+    pairRemote(): Promise<HostPairing | undefined>;
+}

package/lib/host/types.js

@@ -0,0 +1 @@
+export {};

package/lib/index.d.ts

@@ -0,0 +1,30 @@
+export { inject } from './projection/index.js';
+export declare const name = "dshm-bridge";
+/** Trusted in-process host controls; never exposed as an unauthenticated route. */
+export declare function getRunningBridge(stateDir: string): ({
+    identity: import("./types.js").ServerIdentity;
+    fingerprint: string;
+    readonly port: number;
+    readonly addresses: string[];
+    setCapabilities: (caps: import("./types.js").ServerIdentity["caps"]) => void;
+    readonly pairingUrl: string | undefined;
+    readonly pairingExpiresAt: string | undefined;
+    cancelPairing: () => void;
+    devices: () => {
+        connectedVia?: "lan" | "tailscale" | "other" | undefined;
+        connected: boolean;
+        lastSeenAt?: string | undefined;
+        deviceId: string;
+        name: string;
+        model: string;
+        secureEnclave: boolean;
+        pairedAt: string;
+    }[];
+    openPairing: () => string;
+    revoke: (deviceId: string, defer?: boolean) => boolean;
+    refreshInterfaces: () => Promise<void>;
+    close(): Promise<void>;
+} & {
+    diagnostics: () => unknown;
+}) | undefined;
+export declare function apply(context: unknown, input?: unknown): Promise<void>;

package/lib/index.js

@@ -0,0 +1,98 @@
+import QRCode from 'qrcode';
+import { createAdvertiser } from './discovery/advertiser.js';
+import { startLocalControl } from './host/local.js';
+import { createTailscaleControls, createRemoteControls } from './host/tailscale.js';
+import { installHostRoutes } from './projection/host.js';
+import { readFileSync } from 'node:fs';
+import { DmpError } from './errors.js';
+import { parseConfig } from './config.js';
+import { createMethods, CreationLedger, capabilities } from './methods/index.js';
+import { startServer } from './server/index.js';
+import { createProjectionHost, onDispose } from './projection/index.js';
+import { PushController } from './push/controller.js';
+export { inject } from './projection/index.js';
+export const name = 'dshm-bridge';
+const packageVersion = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+if (typeof packageVersion !== 'string' || !packageVersion.length)
+    throw new Error('Missing bridge package version');
+const running = new Map();
+/** Trusted in-process host controls; never exposed as an unauthenticated route. */
+export function getRunningBridge(stateDir) { return running.get(stateDir); }
+export async function apply(context, input) {
+    const config = parseConfig(input);
+    const projection = await createProjectionHost(context);
+    const ledger = new CreationLedger();
+    let server;
+    let discovery;
+    let local;
+    let push;
+    let pushSetupFailures = 0;
+    try {
+        server = await startServer({ stateDir: config.stateDir, port: config.port, bindMode: config.bindMode,
+            onAuthenticated: deviceId => push?.connected(deviceId),
+            onRevoked: deviceId => push?.revoke(deviceId),
+            onAddresses: async (addresses, port) => { await discovery?.update({ hostId: server.identity.host.hostId, name: server.identity.host.name, addresses, port }); },
+            addresses: config.addresses, pairing: config.pairOnStart, quiet: config.quiet,
+            version: packageVersion, dshVersion: projection.version, dshStatus: projection.status, caps: projection.status === 'ok' ? capabilities : [],
+            async connect(methodContext) {
+                if (projection.status !== 'ok')
+                    return {
+                        async request(method) {
+                            if (method !== 'host.info')
+                                throw new DmpError(projection.status === 'incompatible' ? 'dsh-incompatible' : 'dsh-unavailable');
+                            return { result: { host: methodContext.identity.host, bridgeVersion: methodContext.identity.version,
+                                    dshVersion: projection.version, dshStatus: projection.status, caps: [], time: new Date().toISOString() } };
+                        },
+                        dispose() { },
+                    };
+                const peer = await projection.connect(methodContext.deviceId);
+                return createMethods(peer, { ...methodContext, get push() { return push; } }, ledger);
+            }, });
+        if (config.pushProxyUrl && projection.status === 'ok') {
+            try {
+                push = new PushController({ stateDir: config.stateDir, proxyUrl: config.pushProxyUrl,
+                    hostId: server.identity.host.hostId, projection,
+                    connected: id => server.devices().some(device => device.deviceId === id && device.connected),
+                    devices: () => server.devices().map(device => device.deviceId),
+                    capability: enabled => server.setCapabilities(enabled ? [...capabilities, 'push'] : capabilities),
+                });
+                await push.start();
+            }
+            catch {
+                pushSetupFailures++;
+                await push?.close();
+                push = undefined;
+            }
+        }
+        discovery = await createAdvertiser({ hostId: server.identity.host.hostId, name: server.identity.host.name, addresses: server.addresses, port: server.port });
+        const tailscale = createTailscaleControls();
+        const pair = async () => { const url = server.openPairing(); return { url, svg: await QRCode.toString(url, { type: 'svg', errorCorrectionLevel: 'M', margin: 4 }), expiresAt: server.pairingExpiresAt }; };
+        const controls = {
+            status: () => ({ host: server.identity.host, bridgeVersion: packageVersion, dshVersion: projection.version, dshStatus: projection.status, addresses: server.addresses, port: server.port, connectedDevices: server.devices().filter(device => device.connected).length, pairing: { active: Boolean(server.pairingUrl), ...(server.pairingExpiresAt ? { expiresAt: server.pairingExpiresAt } : {}) }, discovery: discovery.status(), guidance: process.platform === 'darwin' ? ['Allow DeepSeek Harness under System Settings → Privacy & Security → Local Network. If you run dsh web in a terminal, allow that terminal too.'] : process.platform === 'win32' ? ['Allow DeepSeek Harness on Private networks when Windows Firewall asks. Keep Public networks disabled.'] : [] }),
+            pair,
+            cancelPair: () => server.cancelPairing(), devices: () => server.devices(), revoke: id => server.revoke(id),
+            ...createRemoteControls(server, tailscale, pair),
+        };
+        installHostRoutes(context, controls);
+        local = await startLocalControl(config.stateDir, controls);
+    }
+    catch (error) {
+        await push?.close();
+        await local?.close();
+        await discovery?.close();
+        if (server)
+            await server.close();
+        await projection.dispose();
+        throw error;
+    }
+    running.set(config.stateDir, { ...server, get port() { return server.port; }, get addresses() { return server.addresses; },
+        get pairingUrl() { return server.pairingUrl; }, diagnostics: () => ({ ...projection.diagnostics?.(), ...(config.pushProxyUrl ? { push: { ...push?.counters, setupFailures: pushSetupFailures } } : {}) }) });
+    onDispose(context, async () => {
+        running.delete(config.stateDir);
+        await push?.close();
+        await local?.close();
+        await discovery?.close();
+        await server.close();
+        await projection.dispose();
+    });
+}

package/lib/methods/index.d.ts

@@ -0,0 +1,9 @@
+import type { ConnectionMethods, DmpObject, MethodContext, ProjectionPeer } from '../types.js';
+export declare const capabilities: string[];
+/** Remove oldest complete display groups until a snapshot/page fits. */
+export declare function fitPage(result: DmpObject): DmpObject;
+export declare class CreationLedger {
+    private entries;
+    create(deviceId: string, params: DmpObject, peer: ProjectionPeer): Promise<DmpObject>;
+}
+export declare function createMethods(peer: ProjectionPeer, context: MethodContext, ledger: CreationLedger): ConnectionMethods;