specrails-desktop 2.0.0

package/server/dist/mobile/mobile-gateway.js

@@ -0,0 +1,285 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MobileGateway = void 0;
+const os_1 = __importDefault(require("os"));
+const https_1 = __importDefault(require("https"));
+const crypto_1 = require("crypto");
+const express_1 = __importDefault(require("express"));
+const ws_1 = require("ws");
+const desktop_db_1 = require("../desktop-db");
+const mobile_tls_1 = require("./mobile-tls");
+const mobile_pairing_1 = require("./mobile-pairing");
+const mobile_router_1 = require("./mobile-router");
+const mobile_ws_1 = require("./mobile-ws");
+const mobile_mdns_1 = require("./mobile-mdns");
+const mobile_devices_1 = require("./mobile-devices");
+const mobile_auth_1 = require("./mobile-auth");
+// Lifecycle owner of the second HTTPS+WSS listener (default :4202), hard-isolated
+// from the main server. Off by default; started on enable or boot-if-enabled.
+const DEFAULT_PORT = 4202;
+const SETTING = {
+    enabled: 'mobile.enabled',
+    port: 'mobile.port',
+    instanceId: 'mobile.desktop_instance_id',
+    name: 'mobile.desktop_name',
+    mdns: 'mobile.mdns_enabled',
+    fingerprint: 'mobile.cert_fingerprint',
+};
+// Legacy fallback — pre-rebrand (Specrails Hub) setting keys. Values are
+// read-migrated to the renamed keys on first access so the stable instance id
+// (which paired phones already store as `hubInstanceId`) survives the rename.
+const LEGACY_SETTING = {
+    instanceId: 'mobile.hub_instance_id',
+    name: 'mobile.hub_name',
+};
+function lanAddresses() {
+    const out = [];
+    const ifaces = os_1.default.networkInterfaces();
+    for (const name of Object.keys(ifaces)) {
+        for (const ni of ifaces[name] ?? []) {
+            if (ni.family === 'IPv4' && !ni.internal)
+                out.push(ni.address);
+        }
+    }
+    return out;
+}
+class MobileGateway {
+    _db;
+    _desktopPort;
+    _broadcast;
+    _bindHost;
+    _cert = null;
+    _server = null;
+    _wss = null;
+    _bridge = null;
+    _pairing = null;
+    _running = false;
+    _boundPort = DEFAULT_PORT;
+    _portOverride;
+    constructor(deps) {
+        this._db = deps.desktopDb;
+        this._desktopPort = deps.desktopPort;
+        this._broadcast = deps.broadcast;
+        this._bindHost = deps.bindHost ?? '0.0.0.0';
+        this._portOverride = deps.port;
+    }
+    get pairing() {
+        return this._pairing;
+    }
+    get bridge() {
+        return this._bridge;
+    }
+    get running() {
+        return this._running;
+    }
+    configuredPort() {
+        if (this._portOverride !== undefined)
+            return this._portOverride;
+        const raw = (0, desktop_db_1.getDesktopSetting)(this._db, SETTING.port);
+        const n = raw ? parseInt(raw, 10) : NaN;
+        return Number.isInteger(n) && n > 0 && n < 65536 ? n : DEFAULT_PORT;
+    }
+    /** Read a setting, falling back to (and one-time migrating from) its
+     *  pre-rebrand key. Legacy fallback — keeps values written by Specrails Hub. */
+    settingWithLegacyFallback(key, legacyKey) {
+        const v = (0, desktop_db_1.getDesktopSetting)(this._db, key);
+        if (v !== undefined)
+            return v;
+        const legacy = (0, desktop_db_1.getDesktopSetting)(this._db, legacyKey);
+        if (legacy !== undefined)
+            (0, desktop_db_1.setDesktopSetting)(this._db, key, legacy);
+        return legacy;
+    }
+    desktopName() {
+        const v = this.settingWithLegacyFallback(SETTING.name, LEGACY_SETTING.name);
+        if (v && v.trim())
+            return v;
+        try {
+            return os_1.default.hostname();
+        }
+        catch {
+            return 'Specrails';
+        }
+    }
+    instanceId() {
+        let id = this.settingWithLegacyFallback(SETTING.instanceId, LEGACY_SETTING.instanceId);
+        if (!id) {
+            id = (0, crypto_1.randomUUID)();
+            (0, desktop_db_1.setDesktopSetting)(this._db, SETTING.instanceId, id);
+        }
+        return id;
+    }
+    mdnsEnabled() {
+        return (0, desktop_db_1.getDesktopSetting)(this._db, SETTING.mdns) !== 'false';
+    }
+    isEnabledSetting() {
+        return (0, desktop_db_1.getDesktopSetting)(this._db, SETTING.enabled) === 'true';
+    }
+    status() {
+        return {
+            enabled: this.isEnabledSetting(),
+            running: this._running,
+            port: this._running ? this._boundPort : this.configuredPort(),
+            certFingerprint: this._cert?.fingerprint ?? (0, desktop_db_1.getDesktopSetting)(this._db, SETTING.fingerprint) ?? null,
+            lanAddresses: lanAddresses(),
+            mdnsEnabled: this.mdnsEnabled(),
+            desktopName: this.desktopName(),
+        };
+    }
+    /** Flip the persisted enable flag + (start|stop). */
+    async setEnabled(enabled) {
+        (0, desktop_db_1.setDesktopSetting)(this._db, SETTING.enabled, enabled ? 'true' : 'false');
+        if (enabled)
+            await this.start();
+        else
+            await this.stop();
+        this._broadcast({ type: 'mobile.gateway_state', running: this._running, port: this._boundPort, timestamp: new Date().toISOString() });
+        return this.status();
+    }
+    /** Idempotent. Loads/creates cert, binds the listener, starts the WS bridge. */
+    async start() {
+        if (this._running)
+            return;
+        // Sliding-expiry sweep on each (re)start.
+        try {
+            (0, mobile_devices_1.sweepExpiredDevices)(this._db);
+        }
+        catch { /* non-fatal */ }
+        this._cert = await (0, mobile_tls_1.loadOrCreateCert)((0, mobile_tls_1.mobileDir)());
+        (0, desktop_db_1.setDesktopSetting)(this._db, SETTING.fingerprint, this._cert.fingerprint);
+        this._pairing = new mobile_pairing_1.PairingManager({
+            certFingerprint: () => this._cert.fingerprint,
+            desktopInstanceId: () => this.instanceId(),
+            desktopName: () => this.desktopName(),
+            port: () => this._boundPort,
+            lanAddresses,
+            createDevice: ({ name, platform, token, certFingerprint }) => {
+                const row = (0, mobile_devices_1.createDevice)(this._db, { name, platform, tokenHash: (0, mobile_devices_1.hashToken)(token), certFingerprint });
+                this._broadcast({ type: 'mobile.device_paired', deviceId: row.id, name: row.name, timestamp: new Date().toISOString() });
+                return row.id;
+            },
+            onClaimed: (device) => {
+                this._broadcast({ type: 'mobile.pair_requested', deviceName: device.name, platform: device.platform, timestamp: new Date().toISOString() });
+            },
+        });
+        const app = (0, express_1.default)();
+        app.use(express_1.default.json({ limit: '256kb' }));
+        app.use((0, mobile_router_1.createMobileRouter)({
+            db: this._db,
+            desktopPort: this._desktopPort,
+            currentFingerprint: () => this._cert.fingerprint,
+            pairing: this._pairing,
+        }));
+        const server = https_1.default.createServer({ cert: this._cert.certPem, key: this._cert.keyPem }, app);
+        const wss = new ws_1.WebSocketServer({ noServer: true });
+        const bridge = new mobile_ws_1.MobileWsBridge();
+        bridge.start();
+        server.on('upgrade', (request, socket, head) => {
+            if ((request.url ?? '').split('?')[0] !== '/mws') {
+                socket.write('HTTP/1.1 404 Not Found\r\nConnection: close\r\n\r\n');
+                socket.destroy();
+                return;
+            }
+            const token = tokenFromUpgrade(request);
+            const device = (0, mobile_auth_1.resolveDevice)(this._db, token, this._cert.fingerprint);
+            if (!device) {
+                socket.write('HTTP/1.1 401 Unauthorized\r\nConnection: close\r\n\r\n');
+                socket.destroy();
+                return;
+            }
+            wss.handleUpgrade(request, socket, head, (ws) => {
+                bridge.attach(ws, device.id);
+            });
+        });
+        const port = this.configuredPort();
+        await new Promise((resolve, reject) => {
+            const onError = (err) => {
+                server.removeListener('listening', onListening);
+                // EADDRINUSE (or any bind error) must NOT crash the sidecar — surface it.
+                reject(new Error(err.code === 'EADDRINUSE' ? `Port ${port} is already in use` : (err.message || 'listen failed')));
+            };
+            const onListening = () => {
+                server.removeListener('error', onError);
+                const addr = server.address();
+                this._boundPort = typeof addr === 'object' && addr ? addr.port : port;
+                resolve();
+            };
+            server.once('error', onError);
+            server.once('listening', onListening);
+            server.listen(port, this._bindHost);
+        });
+        this._server = server;
+        this._wss = wss;
+        this._bridge = bridge;
+        this._running = true;
+        if (this.mdnsEnabled()) {
+            void (0, mobile_mdns_1.advertiseMdns)({
+                name: this.desktopName(),
+                port: this._boundPort,
+                instanceId: this.instanceId(),
+                fingerprint: this._cert.fingerprint,
+            });
+        }
+    }
+    /** Idempotent teardown. */
+    async stop() {
+        await (0, mobile_mdns_1.withdrawMdns)();
+        if (this._bridge) {
+            this._bridge.stop();
+            this._bridge = null;
+        }
+        if (this._wss) {
+            try {
+                this._wss.close();
+            }
+            catch { /* ignore */ }
+            this._wss = null;
+        }
+        if (this._server) {
+            await new Promise((resolve) => this._server.close(() => resolve()));
+            this._server = null;
+        }
+        this._running = false;
+    }
+    /** "Reset mobile identity": new cert + revoke every device + relisten. */
+    async rotateCert() {
+        await (0, mobile_tls_1.rotateCert)((0, mobile_tls_1.mobileDir)());
+        (0, mobile_devices_1.revokeAllDevices)(this._db);
+        const wasRunning = this._running;
+        if (wasRunning) {
+            await this.stop();
+            await this.start();
+        }
+        else {
+            this._cert = await (0, mobile_tls_1.loadOrCreateCert)((0, mobile_tls_1.mobileDir)());
+            (0, desktop_db_1.setDesktopSetting)(this._db, SETTING.fingerprint, this._cert.fingerprint);
+        }
+        this._broadcast({ type: 'mobile.gateway_state', running: this._running, port: this._boundPort, timestamp: new Date().toISOString() });
+        return this.status();
+    }
+}
+exports.MobileGateway = MobileGateway;
+/** Extract a device token from a /mws upgrade: Authorization header (native
+ *  clients can set it) or a token-carrying subprotocol. */
+function tokenFromUpgrade(request) {
+    const fake = { headers: request.headers };
+    const bearer = (0, mobile_auth_1.extractBearer)(fake);
+    if (bearer)
+        return bearer;
+    const proto = request.headers['sec-websocket-protocol'];
+    if (typeof proto === 'string') {
+        for (const part of proto.split(',')) {
+            const p = part.trim();
+            if (p.startsWith('desktop-token.'))
+                return p.slice('desktop-token.'.length).trim();
+            // mobile-app v1 wire compat — do not rename: the phone app (v1.0.0)
+            // carries its device token in a `hub-token.<token>` subprotocol.
+            if (p.startsWith('hub-token.'))
+                return p.slice('hub-token.'.length).trim();
+        }
+    }
+    return null;
+}

package/server/dist/mobile/mobile-mdns.js

@@ -0,0 +1,81 @@
+"use strict";
+// Best-effort mDNS/DNS-SD advertising via @homebridge/ciao (pure-JS, RFC
+// 6762/6763, Windows-safe). Discovery is a SECONDARY convenience — the QR is the
+// primary path — so any failure here is logged and swallowed; the gateway works
+// without it. TXT carries only { id, fp } (never a token or a revealing name).
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.advertiseMdns = advertiseMdns;
+exports.withdrawMdns = withdrawMdns;
+let responder = null;
+let service = null;
+async function advertiseMdns(opts) {
+    try {
+        const mod = (await Promise.resolve().then(() => __importStar(require('@homebridge/ciao'))));
+        const getResponder = mod.getResponder ?? mod.default?.getResponder;
+        if (!getResponder)
+            return false;
+        responder = getResponder();
+        service = responder.createService({
+            name: opts.name,
+            // mobile-app v1 wire compat — mDNS service type is frozen, do not rename.
+            type: 'specrailshub',
+            port: opts.port,
+            txt: { id: opts.instanceId, fp: opts.fingerprint },
+        });
+        await service.advertise();
+        return true;
+    }
+    catch (err) {
+        console.warn('[mobile-mdns] advertise failed (non-fatal):', err instanceof Error ? err.message : err);
+        responder = null;
+        service = null;
+        return false;
+    }
+}
+async function withdrawMdns() {
+    try {
+        if (service)
+            await service.end();
+    }
+    catch { /* ignore */ }
+    try {
+        if (responder)
+            await responder.shutdown();
+    }
+    catch { /* ignore */ }
+    service = null;
+    responder = null;
+}

package/server/dist/mobile/mobile-pairing.js

@@ -0,0 +1,179 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PairingManager = void 0;
+const crypto_1 = require("crypto");
+const auth_1 = require("../auth");
+// In-memory pairing state machine. At most one pairing session is open at a time
+// (the desktop opens it when the user clicks "Pair device"). Sessions, lockout
+// counters, and the one-time token delivery live ONLY in memory — they are voided
+// by a process restart/sleep/self-update, which is acceptable (paired devices
+// survive in desktop.sqlite; an in-progress pair just restarts).
+//
+// Security (verified gaps from the adversarial review):
+//  - secret: 16 random bytes (128-bit), single-use, 60s TTL → no PAKE needed.
+//  - claimId: separate 16-byte handle; the token is delivered EXACTLY ONCE then
+//    scrubbed (a later poll returns approved-without-token).
+//  - lockout: per-IP (5 bad secrets → 60s) AND a global attempt cap (defeats
+//    IPv6 privacy-address rotation) that destroys the session on breach.
+//  - desktop Approve click gates token issuance (QR possession is not enough).
+// 5 minutes: long enough for a manual copy→paste→type flow (e.g. pairing a
+// simulator with no camera) while still single-use + gated by the desktop
+// approval click + a 128-bit secret, so the leaked-QR window stays small.
+const DEFAULT_TTL_MS = 300_000;
+const PER_IP_MAX_FAILS = 5;
+const PER_IP_LOCKOUT_MS = 60_000;
+const GLOBAL_WINDOW_MS = 60_000;
+const GLOBAL_MAX_ATTEMPTS = 20;
+class PairingManager {
+    _session = null;
+    _perIp = new Map();
+    _globalAttempts = [];
+    _deps;
+    constructor(deps) {
+        this._deps = {
+            ...deps,
+            clock: deps.clock ?? (() => Date.now()),
+            genBytes: deps.genBytes ?? ((n) => (0, crypto_1.randomBytes)(n)),
+            ttlMs: deps.ttlMs ?? DEFAULT_TTL_MS,
+        };
+    }
+    now() {
+        return this._deps.clock();
+    }
+    b64url(n) {
+        return this._deps.genBytes(n).toString('base64url');
+    }
+    /** Open (or replace) a pairing session and return the QR payload to render. */
+    createSession() {
+        const now = this.now();
+        const session = {
+            secret: this.b64url(16),
+            claimId: this.b64url(16),
+            exp: now + this._deps.ttlMs,
+            status: 'pending',
+            delivered: false,
+        };
+        this._session = session;
+        this._perIp.clear();
+        this._globalAttempts = [];
+        return {
+            v: 1,
+            // mobile-app v1 wire compat — QR field name `hub` is frozen, do not rename.
+            hub: this._deps.desktopInstanceId(),
+            name: this._deps.desktopName(),
+            addrs: this._deps.lanAddresses(),
+            port: this._deps.port(),
+            fp: this._deps.certFingerprint(),
+            secret: session.secret,
+            claimId: session.claimId,
+            exp: Math.floor(session.exp / 1000),
+        };
+    }
+    isExpired(s) {
+        return this.now() > s.exp && s.status !== 'approved';
+    }
+    /** Phone submits the QR secret. Enforces lockout + single-claim. */
+    claim(secret, device, ip) {
+        const s = this._session;
+        if (!s)
+            return { ok: false, reason: 'no-session' };
+        if (this.isExpired(s)) {
+            this._session = null;
+            return { ok: false, reason: 'expired' };
+        }
+        // Per-IP lockout
+        const rec = this._perIp.get(ip);
+        if (rec && rec.until > this.now())
+            return { ok: false, reason: 'locked' };
+        // Global attempt cap (sliding 60s window) — defeats IPv6 privacy rotation.
+        const now = this.now();
+        this._globalAttempts = this._globalAttempts.filter((t) => now - t < GLOBAL_WINDOW_MS);
+        this._globalAttempts.push(now);
+        if (this._globalAttempts.length > GLOBAL_MAX_ATTEMPTS) {
+            this._session = null;
+            return { ok: false, reason: 'locked' };
+        }
+        if (s.status !== 'pending')
+            return { ok: false, reason: 'already-claimed' };
+        if (!(0, auth_1.safeEqual)(secret, s.secret)) {
+            const next = { count: (rec?.count ?? 0) + 1, until: rec?.until ?? 0 };
+            if (next.count >= PER_IP_MAX_FAILS)
+                next.until = now + PER_IP_LOCKOUT_MS;
+            this._perIp.set(ip, next);
+            return { ok: false, reason: 'invalid' };
+        }
+        s.status = 'claimed';
+        s.device = { name: device.name.slice(0, 80) || 'Unknown device', platform: device.platform };
+        try {
+            this._deps.onClaimed?.(s.device);
+        }
+        catch { /* non-fatal */ }
+        return { ok: true };
+    }
+    /** Desktop approves → issue a per-device token (delivered once via pollStatus). */
+    approve() {
+        const s = this._session;
+        if (!s)
+            return { ok: false, reason: 'no-session' };
+        if (s.status !== 'claimed' || !s.device)
+            return { ok: false, reason: 'not-claimed' };
+        const token = this._deps.genBytes(32).toString('hex');
+        const deviceId = this._deps.createDevice({
+            name: s.device.name,
+            platform: s.device.platform,
+            token,
+            certFingerprint: this._deps.certFingerprint(),
+        });
+        s.approved = {
+            approved: true,
+            deviceToken: token,
+            deviceId,
+            // mobile-app v1 wire compat — `hubName`/`hubInstanceId` field names are
+            // frozen (delivered to the phone via /pair/status), do not rename.
+            hubName: this._deps.desktopName(),
+            hubInstanceId: this._deps.desktopInstanceId(),
+        };
+        s.status = 'approved';
+        return { ok: true };
+    }
+    deny() {
+        if (this._session)
+            this._session.status = 'denied';
+    }
+    cancel() {
+        this._session = null;
+    }
+    /** Desktop UI poll. */
+    getDesktopState() {
+        const s = this._session;
+        if (!s)
+            return null;
+        const status = this.isExpired(s) ? 'expired' : s.status;
+        return { status, claimId: s.claimId, device: s.device };
+    }
+    /** Phone poll. Delivers the token EXACTLY ONCE, then scrubs it. */
+    pollStatus(claimId) {
+        const s = this._session;
+        if (!s || !(0, auth_1.safeEqual)(claimId, s.claimId))
+            return { status: 'expired' };
+        if (s.status === 'approved' && s.approved) {
+            if (!s.delivered) {
+                s.delivered = true;
+                const result = s.approved;
+                // Scrub the token from memory after the single delivery.
+                s.approved = { ...result, deviceToken: '' };
+                return result;
+            }
+            // Already delivered — never hand the token out twice.
+            return { status: 'expired' };
+        }
+        if (this.isExpired(s))
+            return { status: 'expired' };
+        if (s.status === 'denied')
+            return { status: 'denied' };
+        if (s.status === 'claimed')
+            return { status: 'claimed' };
+        return { status: 'pending' };
+    }
+}
+exports.PairingManager = PairingManager;

package/server/dist/mobile/mobile-redact.js

@@ -0,0 +1,53 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stripHome = stripHome;
+exports.redact = redact;
+const os_1 = __importDefault(require("os"));
+// Information-minimisation for everything the gateway hands a phone. Two rules:
+//   1. Drop same-machine keys outright (filesystem paths, db handles).
+//   2. Replace the user's home directory inside any remaining string with `~`
+//      so a `command` like `/specrails:implement #34` keeps its useful shape but
+//      an embedded absolute path (or a stray cwd) leaks no local layout.
+//
+// Applied to EVERY proxied REST JSON body and EVERY outbound WS payload.
+const SENSITIVE_KEYS = new Set(['path', 'db_path', 'dbPath', 'absolutePath', 'cwd', 'filePath', 'projectPath']);
+function homeDir() {
+    try {
+        return os_1.default.homedir();
+    }
+    catch {
+        return '';
+    }
+}
+/** Replace occurrences of the user's home dir with `~` (covers the common leak:
+ *  project paths live under ~/...). Cheap and safe — never mangles normal text. */
+function stripHome(s) {
+    const home = homeDir();
+    if (!home)
+        return s;
+    return s.split(home).join('~');
+}
+/** Deep-redact a JSON-serialisable value: drop sensitive keys, scrub home dir in
+ *  strings. Returns a new structure; never mutates the input. */
+function redact(value) {
+    return _redact(value);
+}
+function _redact(value) {
+    if (typeof value === 'string')
+        return stripHome(value);
+    if (Array.isArray(value))
+        return value.map(_redact);
+    if (value && typeof value === 'object') {
+        const out = {};
+        for (const [k, v] of Object.entries(value)) {
+            if (SENSITIVE_KEYS.has(k))
+                continue;
+            out[k] = _redact(v);
+        }
+        return out;
+    }
+    return value;
+}