@danneillouven/remote-workspace 0.0.0-stage → 0.1.0

package/runtime/server/src/modules/ssh/ssh-config.js

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

package/runtime/server/src/modules/ssh/ssh-connection-manager.js

@@ -0,0 +1,190 @@
+import { Semaphore } from "../../lib/concurrency.js";
+import { AppError } from "../../lib/errors.js";
+import { connectSsh } from "./ssh-connection.js";
+const MAX_STDERR_BYTES = 64 * 1024;
+const MAX_BACKOFF_MS = 30_000;
+// OpenSSH's default MaxSessions is 10 channels per connection; SFTP holds one.
+const MAX_CONCURRENT_EXEC = 4;
+/**
+ * Owns the shared "control" SSH connection used for SFTP and short-lived exec
+ * channels (Git). Terminals use dedicated connections so a misbehaving shell
+ * cannot starve or tear down filesystem and Git access.
+ *
+ * The connection is opened lazily, reused across requests, and re-established
+ * on the next request after a drop. Repeated failures back off exponentially
+ * so a down host is not hammered by every UI request.
+ */
+export class SshConnectionManager {
+    #config;
+    #logger;
+    #execLimiter = new Semaphore(MAX_CONCURRENT_EXEC);
+    #client = null;
+    #connecting = null;
+    #sftp = null;
+    #status = 'idle';
+    #error = null;
+    #failures = 0;
+    #retryAt = 0;
+    #disposed = false;
+    constructor(config, logger) {
+        this.#config = config;
+        this.#logger = logger;
+    }
+    get config() {
+        return this.#config;
+    }
+    getStatus() {
+        return { status: this.#status, error: this.#error };
+    }
+    async getClient() {
+        if (this.#disposed)
+            throw new AppError('REMOTE_UNAVAILABLE', 'Server is shutting down.');
+        if (this.#client)
+            return this.#client;
+        if (this.#connecting)
+            return this.#connecting;
+        if (Date.now() < this.#retryAt) {
+            throw new AppError('REMOTE_UNAVAILABLE', this.#error ?? 'SSH connection unavailable.');
+        }
+        this.#connecting = this.#connect();
+        try {
+            return await this.#connecting;
+        }
+        finally {
+            this.#connecting = null;
+        }
+    }
+    async #connect() {
+        this.#status = 'connecting';
+        try {
+            const client = await connectSsh(this.#config, this.#logger);
+            client.on('close', () => this.#handleClose(client));
+            this.#client = client;
+            this.#status = 'connected';
+            this.#error = null;
+            this.#failures = 0;
+            this.#retryAt = 0;
+            this.#logger.info({ host: this.#config.host, port: this.#config.port }, 'ssh control connection established');
+            return client;
+        }
+        catch (error) {
+            this.#failures += 1;
+            this.#retryAt = Date.now() + Math.min(MAX_BACKOFF_MS, 1000 * 2 ** (this.#failures - 1));
+            this.#status = 'error';
+            this.#error = error instanceof AppError ? error.message : 'SSH connection failed.';
+            this.#logger.warn({ host: this.#config.host, failures: this.#failures, reason: this.#error }, 'ssh connect failed');
+            throw error;
+        }
+    }
+    #handleClose(client) {
+        if (this.#client !== client)
+            return;
+        this.#client = null;
+        this.#sftp = null;
+        if (!this.#disposed) {
+            this.#status = 'error';
+            this.#error = 'SSH connection lost. It will be re-established on the next request.';
+            this.#logger.warn({ host: this.#config.host }, 'ssh control connection closed');
+        }
+    }
+    async getSftp() {
+        const client = await this.getClient();
+        if (!this.#sftp) {
+            const pending = new Promise((resolve, reject) => {
+                client.sftp((error, sftp) => {
+                    if (error) {
+                        reject(new AppError('REMOTE_UNAVAILABLE', 'Failed to open SFTP session. Is the sftp subsystem enabled?', { cause: error }));
+                        return;
+                    }
+                    sftp.on('close', () => {
+                        if (this.#sftp === pending)
+                            this.#sftp = null;
+                    });
+                    resolve(sftp);
+                });
+            });
+            this.#sftp = pending;
+            pending.catch(() => {
+                if (this.#sftp === pending)
+                    this.#sftp = null;
+            });
+        }
+        return this.#sftp;
+    }
+    /** Run a command through the remote user's login shell on the control connection. */
+    exec(command, options) {
+        return this.#execLimiter.run(async () => {
+            const client = await this.getClient();
+            return new Promise((resolve, reject) => {
+                client.exec(command, (error, stream) => {
+                    if (error) {
+                        reject(new AppError('REMOTE_UNAVAILABLE', 'Failed to start remote command.', { cause: error }));
+                        return;
+                    }
+                    const stdout = [];
+                    const stderr = [];
+                    let stdoutBytes = 0;
+                    let stderrBytes = 0;
+                    let stdoutTruncated = false;
+                    let timedOut = false;
+                    let exitCode = null;
+                    let signal = null;
+                    const timer = setTimeout(() => {
+                        timedOut = true;
+                        stream.close();
+                    }, options.timeoutMs);
+                    stream.on('data', (chunk) => {
+                        if (stdoutTruncated)
+                            return;
+                        const room = options.maxOutputBytes - stdoutBytes;
+                        if (chunk.length > room) {
+                            stdout.push(chunk.subarray(0, room));
+                            stdoutBytes += room;
+                            stdoutTruncated = true;
+                            stream.close();
+                            return;
+                        }
+                        stdout.push(chunk);
+                        stdoutBytes += chunk.length;
+                    });
+                    stream.stderr.on('data', (chunk) => {
+                        if (stderrBytes >= MAX_STDERR_BYTES)
+                            return;
+                        stderr.push(chunk);
+                        stderrBytes += chunk.length;
+                    });
+                    stream.on('exit', (code, signalName) => {
+                        exitCode = typeof code === 'number' ? code : null;
+                        signal = signalName ?? null;
+                    });
+                    if (options.input !== undefined)
+                        stream.end(options.input);
+                    stream.on('close', () => {
+                        clearTimeout(timer);
+                        if (timedOut) {
+                            reject(new AppError('TIMEOUT', 'Remote command timed out.'));
+                            return;
+                        }
+                        resolve({ exitCode, signal, stdout: Buffer.concat(stdout), stderr: Buffer.concat(stderr), stdoutTruncated });
+                    });
+                });
+            });
+        });
+    }
+    /** Drop the current control connection (if any) and connect again immediately. */
+    async reconnect() {
+        this.#failures = 0;
+        this.#retryAt = 0;
+        const current = this.#client;
+        this.#client = null;
+        this.#sftp = null;
+        current?.end();
+        await this.getClient();
+    }
+    dispose() {
+        this.#disposed = true;
+        this.#client?.end();
+        this.#client = null;
+        this.#sftp = null;
+    }
+}

package/runtime/server/src/modules/ssh/ssh-connection.js

@@ -0,0 +1,93 @@
+import { Client } from 'ssh2';
+import { AppError } from "../../lib/errors.js";
+import { describeHostKeyRejection, loadHostKeyVerifier } from "./host-key-verifier.js";
+/** User-facing message for transport-level failures (DNS, refused, timeouts), or null. */
+export function networkErrorMessage(error, host, port, target = `${host}:${port}`) {
+    if (error.level === 'client-timeout' || error.code === 'ETIMEDOUT')
+        return `Timed out connecting to ${target}.`;
+    if (error.code === 'ECONNREFUSED')
+        return `Connection refused by ${host}:${port}. Is sshd running?`;
+    if (error.code === 'ENOTFOUND' || error.code === 'EAI_AGAIN')
+        return `Cannot resolve SSH host ${host}.`;
+    if (error.code === 'EHOSTUNREACH' || error.code === 'ENETUNREACH')
+        return `SSH host ${host} is unreachable. Is Tailscale connected?`;
+    return null;
+}
+function toConnectionError(error, rejection, config) {
+    const target = `${config.username}@${config.host}:${config.port}`;
+    let message;
+    if (rejection) {
+        message = describeHostKeyRejection(rejection, config);
+    }
+    else if (error.level === 'client-authentication') {
+        message = config.password
+            ? `SSH authentication failed for ${target}. Check the username and password.`
+            : `SSH authentication failed for ${target}. Check the username and that the public key is in ~/.ssh/authorized_keys on the host.`;
+    }
+    else if (/privateKey|passphrase/i.test(error.message)) {
+        message = 'The SSH private key could not be parsed.';
+    }
+    else {
+        message = networkErrorMessage(error, config.host, config.port, target) ?? `SSH connection to ${target} failed.`;
+    }
+    return new AppError('REMOTE_UNAVAILABLE', message, { cause: error });
+}
+/**
+ * Open and authenticate one SSH connection with mandatory host-key verification.
+ * The returned client always has an 'error' listener so late transport errors
+ * cannot crash the process; callers observe failures through 'close'.
+ */
+export async function connectSsh(config, logger) {
+    const verifier = await loadHostKeyVerifier(config).catch((error) => {
+        throw new AppError('REMOTE_UNAVAILABLE', 'Cannot read the known_hosts file.', { cause: error });
+    });
+    return new Promise((resolve, reject) => {
+        const client = new Client();
+        let rejection = null;
+        let settled = false;
+        client.on('error', (error) => {
+            if (!settled) {
+                settled = true;
+                reject(toConnectionError(error, rejection, config));
+                return;
+            }
+            logger.warn({ err: { message: error.message, level: error.level, code: error.code } }, 'ssh connection error');
+        });
+        client.once('ready', () => {
+            settled = true;
+            resolve(client);
+        });
+        // Servers such as macOS's sshd ask for passwords through keyboard-interactive prompts.
+        client.on('keyboard-interactive', (_name, _instructions, _lang, prompts, finish) => {
+            finish(prompts.map(() => config.password ?? ''));
+        });
+        client.once('close', () => {
+            if (!settled) {
+                settled = true;
+                reject(new AppError('REMOTE_UNAVAILABLE', `SSH connection to ${config.host} closed during handshake.`));
+            }
+        });
+        client.connect({
+            host: config.host,
+            port: config.port,
+            username: config.username,
+            privateKey: config.privateKey ?? undefined,
+            passphrase: config.passphrase ?? undefined,
+            password: config.password ?? undefined,
+            tryKeyboard: config.password !== null,
+            agent: config.agentSocket ?? undefined,
+            readyTimeout: config.readyTimeoutMs,
+            keepaliveInterval: config.keepaliveIntervalMs,
+            keepaliveCountMax: 3,
+            algorithms: verifier.acceptedAlgorithms.length > 0
+                ? { serverHostKey: verifier.acceptedAlgorithms }
+                : undefined,
+            hostVerifier: (key) => {
+                const result = verifier.verify(key);
+                if (!result.ok)
+                    rejection = result.reason;
+                return result.ok;
+            },
+        });
+    });
+}

package/runtime/server/src/modules/store/app-store.js

@@ -0,0 +1,138 @@
+import { chmodSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { z } from 'zod';
+import { portLinkSchema } from "../../../../src/schema/workspace.js";
+const storedHostSchema = z.object({
+    id: z.uuid(),
+    name: z.string(),
+    host: z.string(),
+    port: z.number().int(),
+    username: z.string(),
+    auth: z.discriminatedUnion('type', [
+        // Private key lives in keys/<id>, never in state.json.
+        z.object({ type: z.literal('managed-key'), source: z.enum(['generated', 'imported', 'password']), publicKey: z.string() }),
+        z.object({ type: z.literal('key-file'), path: z.string() }),
+        z.object({ type: z.literal('agent') }),
+    ]),
+    // The host public key the user chose to trust (base64 SSH wire format).
+    hostKey: z.object({ keyType: z.string(), key: z.string() }),
+    createdAt: z.string(),
+});
+const storedWorkspaceSchema = z.object({
+    id: z.uuid(),
+    name: z.string(),
+    hostId: z.uuid().nullable(),
+    root: z.string(),
+    ports: z.array(portLinkSchema).default([]),
+    createdAt: z.string(),
+});
+const storedSessionSchema = z.object({
+    hash: z.string().regex(/^[a-f0-9]{64}$/),
+    createdAt: z.number().finite(),
+    expiresAt: z.number().finite(),
+    lastActiveAt: z.number().finite(),
+});
+const storedStateSchema = z.object({
+    version: z.literal(1),
+    auth: z.object({ passwordHash: z.string() }).nullable(),
+    hosts: z.array(storedHostSchema),
+    workspaces: z.array(storedWorkspaceSchema),
+    sessions: z.array(storedSessionSchema).default([]),
+});
+export class StoreError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'StoreError';
+    }
+}
+const EMPTY_STATE = { version: 1, auth: null, hosts: [], workspaces: [], sessions: [] };
+const PRIVATE_FILE = 0o600;
+const PRIVATE_DIR = 0o700;
+function errnoCode(error) {
+    return error.code;
+}
+/** Write via a temp file + rename so a crash never leaves a half-written file. */
+function writePrivateFile(file, content) {
+    const temp = `${file}.${process.pid}.tmp`;
+    writeFileSync(temp, content, { mode: PRIVATE_FILE });
+    chmodSync(temp, PRIVATE_FILE);
+    renameSync(temp, file);
+}
+function ensurePrivateDir(dir) {
+    mkdirSync(dir, { recursive: true, mode: PRIVATE_DIR });
+    // Tighten a pre-existing directory too: it holds private keys.
+    if ((statSync(dir).mode & 0o077) !== 0)
+        chmodSync(dir, PRIVATE_DIR);
+}
+/**
+ * Persistent server state in DATA_DIR (0700):
+ *   state.json      password hash, hosts, projects, hashed sessions (0600)
+ *   keys/<hostId>   private keys generated or imported in the UI (0600)
+ *
+ * Writes are synchronous and atomic. Nothing in here is ever sent to the
+ * browser verbatim — services map it to public summaries.
+ */
+export class AppStore {
+    dataDir;
+    #state;
+    constructor(dataDir, state) {
+        this.dataDir = dataDir;
+        this.#state = state;
+    }
+    static open(dataDir) {
+        try {
+            ensurePrivateDir(dataDir);
+            ensurePrivateDir(path.join(dataDir, 'keys'));
+        }
+        catch (error) {
+            throw new StoreError(`Cannot create the data directory ${dataDir} (${errnoCode(error) ?? 'unknown error'}).`, { cause: error });
+        }
+        const statePath = path.join(dataDir, 'state.json');
+        let state = EMPTY_STATE;
+        try {
+            const parsed = storedStateSchema.safeParse(JSON.parse(readFileSync(statePath, 'utf8')));
+            if (!parsed.success)
+                throw new StoreError(`${statePath} is not a valid Remote Workspace state file.`);
+            state = parsed.data;
+        }
+        catch (error) {
+            if (error instanceof StoreError)
+                throw error;
+            if (errnoCode(error) !== 'ENOENT')
+                throw new StoreError(`Cannot read ${statePath}.`, { cause: error });
+        }
+        // Old session-secret files are intentionally ignored. Legacy signed cookies cannot authenticate.
+        return new AppStore(dataDir, state);
+    }
+    get state() {
+        return this.#state;
+    }
+    /** Apply a change to a copy of the state, validate it, and persist it atomically. */
+    update(mutate) {
+        const draft = structuredClone(this.#state);
+        mutate(draft);
+        const next = storedStateSchema.parse(draft);
+        writePrivateFile(path.join(this.dataDir, 'state.json'), `${JSON.stringify(next, null, 2)}\n`);
+        this.#state = next;
+    }
+    #keyPath(hostId) {
+        // Host ids are validated UUIDs, so this cannot leave the keys directory.
+        z.uuid().parse(hostId);
+        return path.join(this.dataDir, 'keys', hostId);
+    }
+    writePrivateKey(hostId, pem) {
+        writePrivateFile(this.#keyPath(hostId), pem.endsWith('\n') ? pem : `${pem}\n`);
+    }
+    readPrivateKey(hostId) {
+        return readFileSync(this.#keyPath(hostId));
+    }
+    deletePrivateKey(hostId) {
+        rmSync(this.#keyPath(hostId), { force: true });
+    }
+    writeSetupToken(token) {
+        writePrivateFile(path.join(this.dataDir, 'setup-token'), `${token}\n`);
+    }
+    deleteSetupToken() {
+        rmSync(path.join(this.dataDir, 'setup-token'), { force: true });
+    }
+}

package/runtime/server/src/modules/terminal/output-buffer.js

@@ -0,0 +1,54 @@
+/**
+ * Bounded byte buffer holding the most recent terminal output, replayed to a
+ * client that re-attaches (e.g. after a page reload or network drop). Oldest
+ * bytes are discarded once `limit` is exceeded, so memory per session is fixed.
+ */
+export class OutputBuffer {
+    #limit;
+    #chunks = [];
+    #size = 0;
+    #trimmed = false;
+    constructor(limit) {
+        this.#limit = limit;
+    }
+    get size() {
+        return this.#size;
+    }
+    append(chunk) {
+        if (chunk.length === 0)
+            return;
+        if (chunk.length >= this.#limit) {
+            this.#chunks = [Buffer.from(chunk.subarray(chunk.length - this.#limit))];
+            this.#size = this.#limit;
+            this.#trimmed = true;
+            return;
+        }
+        this.#chunks.push(chunk);
+        this.#size += chunk.length;
+        while (this.#size > this.#limit) {
+            const first = this.#chunks[0];
+            const excess = this.#size - this.#limit;
+            if (first.length <= excess) {
+                this.#chunks.shift();
+                this.#size -= first.length;
+            }
+            else {
+                this.#chunks[0] = first.subarray(excess);
+                this.#size -= excess;
+            }
+            this.#trimmed = true;
+        }
+    }
+    /**
+     * Buffered output. After trimming, the replay starts at the first line
+     * boundary so it does not begin in the middle of an escape sequence or a
+     * multi-byte character.
+     */
+    snapshot() {
+        const data = Buffer.concat(this.#chunks, this.#size);
+        if (!this.#trimmed)
+            return data;
+        const newline = data.indexOf(0x0a);
+        return newline !== -1 && newline < 64 * 1024 ? data.subarray(newline + 1) : data;
+    }
+}

package/runtime/server/src/modules/terminal/pty.js

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

package/runtime/server/src/modules/terminal/ssh-pty-provider.js

@@ -0,0 +1,91 @@
+import { EventEmitter } from 'node:events';
+import { AppError } from "../../lib/errors.js";
+import { quoteShellArg } from "../../lib/shell-quote.js";
+import { connectSsh } from "../ssh/ssh-connection.js";
+class SshPty {
+    #client;
+    #channel;
+    #events = new EventEmitter();
+    #exit = { exitCode: null, signal: null };
+    #exited = false;
+    constructor(client, channel) {
+        this.#client = client;
+        this.#channel = channel;
+        const emitData = (chunk) => this.#events.emit('data', chunk);
+        channel.on('data', emitData);
+        channel.stderr.on('data', emitData);
+        channel.on('exit', (code, signal) => {
+            this.#exit = { exitCode: typeof code === 'number' ? code : null, signal: signal ?? null };
+        });
+        channel.on('close', () => this.#finish());
+        // A dropped connection (network loss, remote reboot) ends the session too.
+        client.on('close', () => this.#finish());
+    }
+    #finish() {
+        if (this.#exited)
+            return;
+        this.#exited = true;
+        this.#client.end();
+        this.#events.emit('exit', this.#exit);
+    }
+    write(data) {
+        if (!this.#exited)
+            this.#channel.write(data);
+    }
+    resize({ cols, rows }) {
+        if (!this.#exited)
+            this.#channel.setWindow(rows, cols, 0, 0);
+    }
+    pause() {
+        this.#channel.pause();
+    }
+    resume() {
+        this.#channel.resume();
+    }
+    kill() {
+        if (this.#exited)
+            return;
+        // Closing the channel makes sshd hang up the PTY (SIGHUP to the shell's
+        // process group); ending the connection guarantees nothing lingers.
+        this.#channel.close();
+        this.#client.end();
+    }
+    onData(listener) {
+        this.#events.on('data', listener);
+    }
+    onExit(listener) {
+        this.#events.once('exit', listener);
+    }
+}
+/**
+ * Spawns interactive login shells over SSH. Each terminal gets its own SSH
+ * connection, isolating terminals from each other and from SFTP/Git traffic.
+ */
+export class SshPtyProvider {
+    #config;
+    #options;
+    #logger;
+    constructor(config, options, logger) {
+        this.#config = config;
+        this.#options = options;
+        this.#logger = logger;
+    }
+    async spawn({ cols, rows }) {
+        const client = await connectSsh(this.#config, this.#logger);
+        // An exec request with a PTY (rather than a bare `shell` request) lets the
+        // shell start in the workspace; `exec $SHELL -l` keeps it a normal
+        // interactive login shell, as with a plain `ssh host`.
+        const command = `cd -- ${quoteShellArg(this.#options.startDirectory)} 2>/dev/null; exec "$SHELL" -l`;
+        const pty = { term: this.#options.term, cols, rows, width: 0, height: 0 };
+        return new Promise((resolve, reject) => {
+            client.exec(command, { pty }, (error, channel) => {
+                if (error) {
+                    client.end();
+                    reject(new AppError('TERMINAL_UNAVAILABLE', 'The SSH server refused to open an interactive shell.', { cause: error }));
+                    return;
+                }
+                resolve(new SshPty(client, channel));
+            });
+        });
+    }
+}

package/runtime/server/src/modules/terminal/terminal-manager.js

@@ -0,0 +1,70 @@
+import { AppError } from "../../lib/errors.js";
+import { TerminalSession } from "./terminal-session.js";
+/** Registry of live terminal sessions across all projects; enforces the session limit and reaps orphans. */
+export class TerminalManager {
+    #resolveProvider;
+    #options;
+    #logger;
+    #sessions = new Map();
+    #starting = 0;
+    constructor(resolveProvider, options, logger) {
+        this.#resolveProvider = resolveProvider;
+        this.#options = options;
+        this.#logger = logger;
+    }
+    async create(workspaceId, size) {
+        const provider = this.#resolveProvider(workspaceId);
+        if (this.#sessions.size + this.#starting >= this.#options.maxSessions) {
+            throw new AppError('TERMINAL_LIMIT', `At most ${this.#options.maxSessions} terminals can be open at once (across all projects).`);
+        }
+        this.#starting += 1;
+        try {
+            const pty = await provider.spawn(size);
+            const session = new TerminalSession(pty, {
+                workspaceId,
+                replayBufferBytes: this.#options.replayBufferBytes,
+                orphanTimeoutMs: this.#options.orphanTimeoutMs,
+                onExpire: (expired) => {
+                    this.#logger.info({ sessionId: expired.id }, 'terminal session expired without a client');
+                    this.terminate(expired.id);
+                },
+            });
+            this.#sessions.set(session.id, session);
+            this.#logger.info({ sessionId: session.id, workspaceId, sessions: this.#sessions.size }, 'terminal session started');
+            return session;
+        }
+        finally {
+            this.#starting -= 1;
+        }
+    }
+    get(id) {
+        return this.#sessions.get(id);
+    }
+    list() {
+        return [...this.#sessions.values()].map((session) => ({
+            id: session.id,
+            workspaceId: session.workspaceId,
+            status: session.status,
+            attached: session.attached,
+            createdAt: session.createdAt.toISOString(),
+        }));
+    }
+    terminate(id) {
+        const session = this.#sessions.get(id);
+        if (!session)
+            return false;
+        this.#sessions.delete(id);
+        session.terminate();
+        this.#logger.info({ sessionId: id, sessions: this.#sessions.size }, 'terminal session terminated');
+        return true;
+    }
+    terminateWorkspace(workspaceId) {
+        for (const session of [...this.#sessions.values()])
+            if (session.workspaceId === workspaceId)
+                this.terminate(session.id);
+    }
+    terminateAll() {
+        for (const id of [...this.#sessions.keys()])
+            this.terminate(id);
+    }
+}