firedrill-run 2.2.5 → 3.0.0

package/dist/cli/src/native/companion-ipc.js

@@ -0,0 +1,473 @@
+/**
+ * Local IPC between the Firedrill companion process and other CLI processes of
+ * the same OS user (Plan20 section 3.6).
+ *
+ * Transport
+ *  - POSIX: a Unix domain socket inside the private 0700 state directory. When
+ *    that path exceeds the platform sun_path limit (non-production profile
+ *    directories are long), a private 0700 directory owned by this user under
+ *    the OS temporary directory is used instead. Anything at the socket path
+ *    that is not a stale socket owned by this user is refused, never removed.
+ *  - Windows: a per-user named pipe `\\.\pipe\firedrill-<sha256(user, home, origin) prefix>`.
+ *    libuv creates the first pipe instance exclusively, so a pre-created
+ *    (squatted) name makes the companion refuse to start.
+ *  - Frames: 4-byte big-endian length + UTF-8 JSON, at most 64 KiB, one request
+ *    per connection, 5 s I/O timeout (20 s for access-token so an in-memory
+ *    refresh round-trip can finish).
+ *
+ * Authentication
+ *  - A random 32-byte session nonce is written to a 0600 file (exclusive create)
+ *    in the private state directory and removed on shutdown.
+ *  - The nonce never crosses the socket. Each request carries a fresh client
+ *    challenge and HMAC-SHA256(nonce, request); each response carries
+ *    HMAC-SHA256(nonce, challenge + payload). Both sides compare in constant
+ *    time, so a process that only squats the endpoint learns nothing and cannot
+ *    forge a response. Request challenges are single-use within a companion.
+ *
+ * Trust model (honest scope)
+ *  - This protects the session against other OS users and against endpoint
+ *    squatting. It is NOT a defense against malware running as the same user:
+ *    such a process can read the 0600 nonce file, connect, and obtain the
+ *    short-lived access token, exactly as it could read an unlocked OS store.
+ *  - On Windows the nonce file relies on the user-profile ACL (no POSIX modes).
+ *  - Tokens are never logged, printed or written to disk by this module.
+ */
+import { connect, createServer } from 'node:net';
+import { createHash, createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
+import { lstat, open, readFile, unlink, chmod } from 'node:fs/promises';
+import { homedir, tmpdir, userInfo } from 'node:os';
+import { join } from 'node:path';
+import { Buffer } from 'node:buffer';
+import { CliError, API_ORIGIN } from '../http.js';
+import { ensurePrivateDirectory, privateDirectory } from '../credentials.js';
+import { bootstrapProcessLock } from '../bootstrap-process-lock.js';
+export const COMPANION_PROTOCOL = 'firedrill.companion-ipc.v1';
+export const COMPANION_MAX_FRAME_BYTES = 64 * 1024;
+export const COMPANION_IO_TIMEOUT_MS = 5000;
+export const COMPANION_TOKEN_TIMEOUT_MS = 20000;
+export const COMPANION_OPERATIONS = ['status', 'access-token', 'shutdown'];
+const PIPE_PREFIX = '\\\\.\\pipe\\';
+const NONCE_HEX = /^[a-f0-9]{64}$/;
+const CHALLENGE = /^[A-Za-z0-9_-]{43}$/;
+const PROOF = /^[a-f0-9]{64}$/;
+const ERROR_CODE = /^[a-z][a-z0-9_]{0,79}$/;
+const unavailable = () => new CliError('companion_unavailable', 'No Firedrill companion is running for this platform and user. Nothing was requested.', 2);
+const unsafe = () => new CliError('companion_path_unsafe', 'The companion socket or nonce path is not a private item owned by this OS user. It was left untouched and nothing was requested.', 2);
+const unverified = () => new CliError('companion_unverified', 'The local companion could not prove it holds this session. No credential was used.', 2);
+const protocolError = () => new CliError('companion_protocol_invalid', 'The companion exchange was malformed or oversized. No credential was used.', 2);
+function sunPathLimit() {
+    // sun_path is 104 bytes on macOS/BSD and 108 on Linux, including the NUL.
+    return process.platform === 'linux' ? 107 : 103;
+}
+function windowsUser() {
+    try {
+        return userInfo().username;
+    }
+    catch {
+        return process.env.USERNAME ?? '';
+    }
+}
+async function endpoints() {
+    const directory = await privateDirectory();
+    const nonce = join(directory, 'companion.nonce'), lock = join(directory, 'companion.lock');
+    if (process.platform === 'win32') {
+        const digest = createHash('sha256').update('firedrill.companion-pipe.v1\0').update(windowsUser()).update('\0')
+            .update(homedir()).update('\0').update(API_ORIGIN).digest('hex').slice(0, 32);
+        return { directory, nonce, lock, socket: `${PIPE_PREFIX}firedrill-${digest}`, windows: true };
+    }
+    const primary = join(directory, 'companion.sock');
+    if (Buffer.byteLength(primary) <= sunPathLimit())
+        return { directory, nonce, lock, socket: primary, windows: false };
+    const uid = process.getuid ? process.getuid() : 0;
+    const short = join(tmpdir(), `firedrill-${uid}-${createHash('sha256').update(directory).digest('hex').slice(0, 12)}`);
+    const socket = join(short, 's');
+    if (Buffer.byteLength(socket) > sunPathLimit())
+        throw new CliError('companion_socket_path_too_long', 'The companion socket path exceeds this platform limit. Set TMPDIR to a shorter private directory. No companion endpoint was opened.', 2);
+    await ensurePrivateDirectory(short);
+    return { directory, nonce, lock, socket, windows: false };
+}
+function ownedByUser(stat) {
+    return !process.getuid || stat.uid === process.getuid();
+}
+function hmac(nonce, ...parts) {
+    const mac = createHmac('sha256', nonce);
+    for (const part of parts)
+        mac.update(part).update('\0');
+    return mac.digest('hex');
+}
+function sameHex(a, b) {
+    const left = Buffer.from(a, 'hex'), right = Buffer.from(b, 'hex');
+    return left.length === 32 && right.length === 32 && timingSafeEqual(left, right);
+}
+function encodeFrame(value) {
+    const body = Buffer.from(JSON.stringify(value), 'utf8');
+    if (body.length > COMPANION_MAX_FRAME_BYTES)
+        throw protocolError();
+    const header = Buffer.alloc(4);
+    header.writeUInt32BE(body.length, 0);
+    return Buffer.concat([header, body]);
+}
+/** Read exactly one length-prefixed frame. Extra bytes, oversize frames and timeouts fail. */
+function readFrame(socket, timeoutMs, signal) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let received = 0, expected = -1, settled = false;
+        const finish = (error, value) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            signal?.removeEventListener('abort', onAbort);
+            socket.off('data', onData);
+            socket.off('end', onEnd);
+            socket.off('error', onError);
+            socket.off('close', onEnd);
+            if (error) {
+                socket.destroy();
+                reject(error);
+            }
+            else
+                resolve(value);
+        };
+        const onAbort = () => finish(signal?.reason instanceof Error ? signal.reason : new CliError('companion_cancelled', 'The companion request was cancelled. No credential was used.', 130));
+        const onError = () => finish(unavailable());
+        const onEnd = () => finish(protocolError());
+        const onData = (chunk) => {
+            received += chunk.length;
+            chunks.push(chunk);
+            if (received > COMPANION_MAX_FRAME_BYTES + 4)
+                return finish(protocolError());
+            const all = Buffer.concat(chunks);
+            if (expected < 0 && all.length >= 4) {
+                expected = all.readUInt32BE(0);
+                if (expected < 2 || expected > COMPANION_MAX_FRAME_BYTES)
+                    return finish(protocolError());
+            }
+            if (expected >= 0 && all.length >= 4 + expected) {
+                if (all.length !== 4 + expected)
+                    return finish(protocolError());
+                try {
+                    finish(null, JSON.parse(all.subarray(4).toString('utf8')));
+                }
+                catch {
+                    finish(protocolError());
+                }
+            }
+        };
+        const timer = setTimeout(() => finish(new CliError('companion_timeout', 'The companion did not answer in time. No credential was used.', 2)), timeoutMs);
+        if (signal?.aborted)
+            return onAbort();
+        signal?.addEventListener('abort', onAbort, { once: true });
+        socket.on('data', onData);
+        socket.once('end', onEnd);
+        socket.once('error', onError);
+        socket.once('close', onEnd);
+    });
+}
+async function readNonce(path) {
+    let stat;
+    try {
+        stat = await lstat(path);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            throw unavailable();
+        throw unsafe();
+    }
+    if (!stat.isFile() || stat.isSymbolicLink() || !ownedByUser(stat) || stat.size !== 64
+        || process.platform !== 'win32' && (stat.mode & 0o077) !== 0)
+        throw unsafe();
+    const text = (await readFile(path, 'utf8')).trim();
+    if (!NONCE_HEX.test(text))
+        throw unsafe();
+    return Buffer.from(text, 'hex');
+}
+/** True when a companion nonce exists for this platform and user (it may be stale). */
+export async function companionPresent() {
+    const { nonce } = await endpoints();
+    try {
+        await lstat(nonce);
+        return true;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return false;
+        throw unsafe();
+    }
+}
+function connectTo(socketPath, signal) {
+    return new Promise((resolve, reject) => {
+        const socket = connect({ path: socketPath });
+        const timer = setTimeout(() => { socket.destroy(); reject(unavailable()); }, COMPANION_IO_TIMEOUT_MS);
+        const onAbort = () => { clearTimeout(timer); socket.destroy(); reject(new CliError('companion_cancelled', 'The companion request was cancelled. No credential was used.', 130)); };
+        if (signal?.aborted)
+            return onAbort();
+        signal?.addEventListener('abort', onAbort, { once: true });
+        socket.once('connect', () => { clearTimeout(timer); signal?.removeEventListener('abort', onAbort); resolve(socket); });
+        // Persistent listener: a reset after connect must not become an unhandled 'error'.
+        socket.on('error', () => { clearTimeout(timer); signal?.removeEventListener('abort', onAbort); socket.destroy(); reject(unavailable()); });
+    });
+}
+export async function companionRequest(op, signal) {
+    if (!COMPANION_OPERATIONS.includes(op))
+        throw protocolError();
+    signal?.throwIfAborted();
+    const where = await endpoints();
+    const nonce = await readNonce(where.nonce);
+    try {
+        if (!where.windows) {
+            let stat;
+            try {
+                stat = await lstat(where.socket);
+            }
+            catch (error) {
+                if (error.code === 'ENOENT')
+                    throw unavailable();
+                throw unsafe();
+            }
+            if (!stat.isSocket() || !ownedByUser(stat))
+                throw unsafe();
+        }
+        const challenge = randomBytes(32).toString('base64url');
+        const socket = await connectTo(where.socket, signal);
+        try {
+            socket.write(encodeFrame({ protocol: COMPANION_PROTOCOL, op, challenge,
+                proof: hmac(nonce, 'request', COMPANION_PROTOCOL, op, challenge) }));
+            const frame = await readFrame(socket, op === 'access-token' ? COMPANION_TOKEN_TIMEOUT_MS : COMPANION_IO_TIMEOUT_MS, signal);
+            const response = frame;
+            if (!response || typeof response !== 'object' || response.protocol !== COMPANION_PROTOCOL
+                || typeof response.payload !== 'string' || typeof response.proof !== 'string' || !PROOF.test(response.proof))
+                throw protocolError();
+            if (!sameHex(response.proof, hmac(nonce, 'response', COMPANION_PROTOCOL, op, challenge, response.payload)))
+                throw unverified();
+            let payload;
+            try {
+                payload = JSON.parse(response.payload);
+            }
+            catch {
+                throw protocolError();
+            }
+            if (!payload || typeof payload !== 'object')
+                throw protocolError();
+            if (payload.ok !== true) {
+                const error = payload.error;
+                if (!error || typeof error.code !== 'string' || !ERROR_CODE.test(error.code) || typeof error.message !== 'string'
+                    || error.message.length > 1000)
+                    throw protocolError();
+                const exitCode = typeof error.exit_code === 'number' && Number.isInteger(error.exit_code) && error.exit_code >= 1 && error.exit_code <= 130 ? error.exit_code : 1;
+                throw new CliError(error.code, error.message, exitCode);
+            }
+            const result = payload.result;
+            if (!result || typeof result !== 'object')
+                throw protocolError();
+            if (op === 'access-token') {
+                if (typeof result.access_token !== 'string' || !result.access_token || result.access_token.length > 16384
+                    || !Number.isSafeInteger(result.expires_at))
+                    throw protocolError();
+                return { access_token: result.access_token, expires_at: result.expires_at };
+            }
+            if (op === 'shutdown') {
+                if (result.stopped !== true)
+                    throw protocolError();
+                return { stopped: true };
+            }
+            if (result.protocol !== COMPANION_PROTOCOL || (result.mode !== 'persistent' && result.mode !== 'session')
+                || !Number.isSafeInteger(result.pid) || typeof result.started_at !== 'string' || result.origin !== API_ORIGIN
+                || typeof result.signed_in !== 'boolean')
+                throw protocolError();
+            return result;
+        }
+        finally {
+            socket.destroy();
+        }
+    }
+    finally {
+        nonce.fill(0);
+    }
+}
+async function removeStaleSocket(path) {
+    let stat;
+    try {
+        stat = await lstat(path);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return;
+        throw unsafe();
+    }
+    if (!stat.isSocket() || !ownedByUser(stat))
+        throw unsafe();
+    const live = await connectTo(path).then(socket => { socket.destroy(); return true; }, () => false);
+    if (live)
+        throw new CliError('companion_already_running', 'A Firedrill companion is already serving this platform and user. No second companion was started.', 2);
+    await unlink(path);
+}
+async function removeOwnedFile(path) {
+    let stat;
+    try {
+        stat = await lstat(path);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return;
+        throw unsafe();
+    }
+    if (!stat.isFile() || stat.isSymbolicLink() || !ownedByUser(stat))
+        throw unsafe();
+    await unlink(path);
+}
+/**
+ * Start the companion IPC server in this process. Holds a process-lifetime lock
+ * so only one companion serves a platform origin per user. The caller (the
+ * companion command) wires SIGINT/SIGTERM/SIGHUP to handle.close('signal').
+ */
+export async function startCompanionServer(options) {
+    const where = await endpoints();
+    let lock;
+    try {
+        lock = await bootstrapProcessLock(where.lock);
+    }
+    catch {
+        throw new CliError('companion_already_running', 'A Firedrill companion is already running for this platform and user, or local coordination is unavailable. No second companion was started.', 2);
+    }
+    const nonce = randomBytes(32);
+    const startedAt = new Date().toISOString();
+    const seen = new Set();
+    const sockets = new Set();
+    let server = null;
+    let closing = null, nonceWritten = false, listening = false;
+    let resolveClosed = () => { };
+    const closed = new Promise(resolve => { resolveClosed = resolve; });
+    let started = false;
+    const close = (reason = 'shutdown') => closing ??= (async () => {
+        // A companion that never started serving keeps its process credentials;
+        // once it served, every close ends the volatile session.
+        if (started) {
+            try {
+                await options.handlers.erase();
+            }
+            catch { /* Memory-only; references are dropped by the handler. */ }
+        }
+        for (const socket of sockets)
+            socket.destroy();
+        if (server)
+            await new Promise(resolve => server?.close(() => resolve()));
+        nonce.fill(0);
+        if (nonceWritten)
+            await removeOwnedFile(where.nonce).catch(() => { });
+        // Only a socket this process bound is ours to remove; a failed start must
+        // never delete a live companion's endpoint.
+        if (!where.windows && listening) {
+            await lstat(where.socket).then(stat => stat.isSocket() && ownedByUser(stat) ? unlink(where.socket) : undefined, () => { }).catch(() => { });
+        }
+        await lock.close().catch(() => { });
+        resolveClosed();
+        try {
+            options.onShutdown?.(reason);
+        }
+        catch { /* Caller hook must not block cleanup. */ }
+    })();
+    lock.signal.addEventListener('abort', () => { void close('lock-lost'); }, { once: true });
+    const respond = (socket, op, challenge, payload) => {
+        const text = JSON.stringify(payload);
+        socket.end(encodeFrame({ protocol: COMPANION_PROTOCOL, payload: text, proof: hmac(nonce, 'response', COMPANION_PROTOCOL, op, challenge, text) }));
+    };
+    const handle = async (socket) => {
+        sockets.add(socket);
+        socket.on('error', () => { socket.destroy(); });
+        socket.once('close', () => sockets.delete(socket));
+        let request;
+        try {
+            request = await readFrame(socket, COMPANION_IO_TIMEOUT_MS);
+        }
+        catch {
+            socket.destroy();
+            return;
+        }
+        const value = request;
+        if (!value || typeof value !== 'object' || value.protocol !== COMPANION_PROTOCOL || typeof value.op !== 'string'
+            || !COMPANION_OPERATIONS.includes(value.op) || typeof value.challenge !== 'string'
+            || !CHALLENGE.test(value.challenge) || typeof value.proof !== 'string' || !PROOF.test(value.proof)
+            || !sameHex(value.proof, hmac(nonce, 'request', COMPANION_PROTOCOL, value.op, value.challenge))
+            || seen.has(value.challenge)) {
+            socket.destroy();
+            return;
+        }
+        seen.add(value.challenge);
+        if (seen.size > 4096)
+            seen.delete(seen.values().next().value);
+        const op = value.op, challenge = value.challenge;
+        if (closing) {
+            respond(socket, op, challenge, { ok: false, error: { code: 'companion_stopping', message: 'The companion is stopping. No credential was returned.', exit_code: 2 } });
+            return;
+        }
+        const abort = new AbortController();
+        const timer = setTimeout(() => abort.abort(), COMPANION_TOKEN_TIMEOUT_MS);
+        socket.once('close', () => abort.abort());
+        try {
+            if (op === 'status') {
+                const summary = await options.handlers.status();
+                respond(socket, op, challenge, { ok: true, result: { protocol: COMPANION_PROTOCOL, mode: options.mode, pid: process.pid,
+                        started_at: startedAt, origin: API_ORIGIN, signed_in: summary.signed_in, state: summary.state,
+                        subject: summary.subject, expires_at: summary.expires_at } });
+            }
+            else if (op === 'access-token') {
+                const token = await options.handlers.accessToken(abort.signal);
+                respond(socket, op, challenge, { ok: true, result: { access_token: token.access_token, expires_at: token.expires_at } });
+            }
+            else {
+                socket.once('finish', () => { void close('shutdown'); });
+                socket.once('close', () => { void close('shutdown'); });
+                respond(socket, op, challenge, { ok: true, result: { stopped: true } });
+            }
+        }
+        catch (error) {
+            // Only this client's own CliError codes/messages cross the socket; never raw errors.
+            respond(socket, op, challenge, { ok: false, error: error instanceof CliError && ERROR_CODE.test(error.code)
+                    ? { code: error.code, message: error.message.slice(0, 1000), exit_code: error.exitCode }
+                    : { code: 'companion_operation_failed', message: 'The companion could not complete the request. No credential was returned.', exit_code: 1 } });
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    };
+    try {
+        if (!where.windows)
+            await removeStaleSocket(where.socket);
+        else {
+            const live = await connectTo(where.socket).then(socket => { socket.destroy(); return true; }, () => false);
+            if (live)
+                throw new CliError('companion_already_running', 'A Firedrill companion is already serving this platform and user. No second companion was started.', 2);
+        }
+        // We hold the companion lock and no live endpoint answered: any nonce left is stale.
+        await removeOwnedFile(where.nonce);
+        server = createServer({ allowHalfOpen: false, pauseOnConnect: false }, socket => { void handle(socket); });
+        server.maxConnections = 16;
+        await new Promise((resolve, reject) => {
+            server?.once('error', error => reject(error.code === 'EADDRINUSE'
+                ? new CliError('companion_already_running', 'The companion endpoint is already in use. No second companion was started.', 2)
+                : new CliError('companion_listen_failed', 'The companion endpoint could not be opened. No local access was granted.', 2)));
+            server?.listen({ path: where.socket, readableAll: false, writableAll: false }, () => { listening = true; resolve(); });
+        });
+        server.on('error', () => { void close('exit'); });
+        if (!where.windows)
+            await chmod(where.socket, 0o600);
+        const file = await open(where.nonce, 'wx', 0o600);
+        nonceWritten = true;
+        try {
+            await file.writeFile(nonce.toString('hex'), 'utf8');
+            await file.sync();
+        }
+        finally {
+            await file.close();
+        }
+        if (!where.windows)
+            await chmod(where.nonce, 0o600);
+        started = true;
+    }
+    catch (error) {
+        await close('exit');
+        throw error;
+    }
+    return { endpoint: where.socket, closed, close };
+}