@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
498 lines (456 loc) • 23.1 kB
text/typescript
/**
* Opt-in SSH log capture for Remote Link tunnels (#7297).
*
* Authority: capture is on only while `<configDir>/link/ssh-capture/control.json` holds an unexpired
* window. Only `ocx link capture start` on this machine writes that file; it is not a config key, so no
* Home sync, management route or remote input can turn capture on. The runtime reads it at each
* tunnel spawn and refuses a control file that is a symlink, not a regular file, or (on POSIX) not
* owner-only and owned by this user.
*
* Lifetime: a window lasts SSH_CAPTURE_DEFAULT_MINUTES unless the operator asks for up to
* SSH_CAPTURE_MAX_MINUTES; a window further away than that maximum reads as off. While a window is
* open, the next ssh attempt of a Home (-R) or Child (-L) tunnel runs with LogLevel=DEBUG1; after
* stop or expiry the next attempt is back at LogLevel=ERROR. A running attempt keeps its level, but
* nothing it prints is stored once the window closed. Each window writes one capture file of at most
* SSH_CAPTURE_FILE_MAX_BYTES; files are deleted SSH_CAPTURE_RETENTION_MS after their last write, and
* at most SSH_CAPTURE_MAX_FILES are kept. Stop removes only the control file, so a capture the
* operator still needs survives until its retention passes.
*
* Content: every stderr line goes through sanitizeSshLine (src/link/ssh-capture-redact.ts), an
* allowlist of ssh line shapes; raw text never reaches disk.
*/
import { constants, lstatSync, mkdirSync, readdirSync, chmodSync, unlinkSync, type Stats } from "node:fs";
import { chmod, lstat, open } from "node:fs/promises";
import { dirname, join } from "node:path";
import { atomicWriteFileNoFollow } from "../config/atomic-write";
import { readBoundedRegularFileSync } from "../lib/bounded-file-read";
import { assertNotRealHomeUnderTest } from "../lib/test-home-guard";
import {
hardenSecretDir, hardenSecretDirAsync, hardenSecretPath, hardenSecretPathAsync, reattributeHardenedSecretPath, windowsSecretAclApplies,
} from "../lib/windows-secret-acl";
import { LINK_ID_PATTERN } from "./ssh-argv";
import { sanitizeSshLine, type SanitizedSshLine } from "./ssh-capture-redact";
export const SSH_CAPTURE_DEFAULT_MINUTES = 15;
export const SSH_CAPTURE_MAX_MINUTES = 60;
export const SSH_CAPTURE_FILE_MAX_BYTES = 1024 * 1024;
export const SSH_CAPTURE_RETENTION_MS = 72 * 60 * 60_000;
export const SSH_CAPTURE_MAX_FILES = 4;
export const SSH_CAPTURE_LOG_LEVEL = "DEBUG1";
const CONTROL_FILE = "control.json";
const CAPTURE_FILE = /^ssh-(\d{13})\.jsonl$/;
const CONTROL_MAX_BYTES = 512;
const QUEUE_MAX = 512;
const TRUNCATION_RESERVE_BYTES = 128;
const TRUNCATION_EVENT = '"event":"capture_truncated"';
const PRUNE_INTERVAL_MS = 60_000;
export type SshCaptureTunnel = "home" | "child";
export interface SshCaptureControl {
readonly version: 1;
readonly startedAt: number;
readonly expiresAt: number;
}
/** What one tunnel spawn gets while capture is on. */
export interface SshCaptureSpawn {
readonly logLevel: typeof SSH_CAPTURE_LOG_LEVEL;
/** Stores the line's sanitized form; returns whether the exit classifier reads the raw line. */
stderrLine(line: string): boolean;
}
export type SshCaptureOpener = (tunnel: SshCaptureTunnel, linkId: string) => SshCaptureSpawn | null;
export interface SshCaptureFileStatus {
name: string;
bytes: number;
lastWriteAt: string;
deleteAfter: string;
}
export interface SshCaptureStatus {
enabled: boolean;
logLevel: typeof SSH_CAPTURE_LOG_LEVEL | "ERROR";
startedAt: string | null;
expiresAt: string | null;
directory: string;
retentionHours: number;
maxMinutes: number;
maxFileBytes: number;
files: SshCaptureFileStatus[];
/** Capture files this call deleted: retention, or the oldest beyond SSH_CAPTURE_MAX_FILES at start. */
removed: number;
}
export class SshCaptureError extends Error {
constructor(message: string) {
super(message);
this.name = "SshCaptureError";
}
}
export function sshCaptureDir(linkDirectory: string): string {
return join(linkDirectory, "ssh-capture");
}
function captureFileName(startedAt: number): string {
return "ssh-" + startedAt + ".jsonl";
}
function isMissing(error: unknown): boolean {
const code = (error as NodeJS.ErrnoException | undefined)?.code;
return code === "ENOENT" || code === "ENOTDIR";
}
function lstatOrNull(path: string): Stats | null {
try { return lstatSync(path); } catch (error) { if (isMissing(error)) return null; throw error; }
}
function isSafeEpoch(value: unknown): value is number {
return typeof value === "number" && Number.isSafeInteger(value) && value >= 1_000_000_000_000 && value < 10_000_000_000_000;
}
/** Owner-only and owned by this user on POSIX; Windows relies on the private ACL the writers apply. */
function privateEnough(stat: Stats, mask: number): boolean {
if (process.platform === "win32") return true;
const uid = typeof process.getuid === "function" ? process.getuid() : undefined;
return (stat.mode & mask) === 0 && (uid === undefined || stat.uid === uid);
}
/** The control window if one is open now, else null. Never throws for a damaged or foreign file. */
export function readSshCaptureControl(dir: string, now: number): SshCaptureControl | null {
try {
const directory = lstatOrNull(dir);
if (!directory || !directory.isDirectory() || directory.isSymbolicLink() || !privateEnough(directory, 0o077)) return null;
const path = join(dir, CONTROL_FILE);
const entry = lstatOrNull(path);
if (!entry || !entry.isFile() || entry.isSymbolicLink() || entry.nlink !== 1 || !privateEnough(entry, 0o077)) return null;
const raw: unknown = JSON.parse(readBoundedRegularFileSync(path, CONTROL_MAX_BYTES).toString("utf8"));
if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
const body = raw as Record<string, unknown>;
const keys = Object.keys(body).sort().join(",");
if (keys !== "expiresAt,startedAt,version" || body.version !== 1 || !isSafeEpoch(body.startedAt) || !isSafeEpoch(body.expiresAt)) return null;
// A window further out than the hard maximum (a wrong clock or a hand edit) reads as off.
if (body.expiresAt <= body.startedAt || now >= body.expiresAt || body.expiresAt - now > SSH_CAPTURE_MAX_MINUTES * 60_000) return null;
return { version: 1, startedAt: body.startedAt, expiresAt: body.expiresAt };
} catch {
return null;
}
}
function listCaptureFiles(dir: string): Array<{ name: string; startedAt: number; bytes: number; mtimeMs: number }> {
let names: string[];
try { names = readdirSync(dir); } catch (error) { if (isMissing(error)) return []; throw error; }
const files: Array<{ name: string; startedAt: number; bytes: number; mtimeMs: number }> = [];
for (const name of names) {
const match = CAPTURE_FILE.exec(name);
if (!match) continue;
const stat = lstatOrNull(join(dir, name));
// Never follow or count anything but a plain single-link file.
if (!stat || !stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1) continue;
files.push({ name, startedAt: Number(match[1]), bytes: stat.size, mtimeMs: stat.mtimeMs });
}
return files.sort((left, right) => left.startedAt - right.startedAt);
}
/**
* Delete capture files whose last write is older than the retention period, and an expired control
* file. Returns the number of capture files removed. Never follows a link.
*/
export function pruneSshCapture(dir: string, now: number): number {
const directory = lstatOrNull(dir);
if (!directory || !directory.isDirectory() || directory.isSymbolicLink()) return 0;
let removed = 0;
for (const file of listCaptureFiles(dir)) {
if (now - file.mtimeMs < SSH_CAPTURE_RETENTION_MS) continue;
try { unlinkSync(join(dir, file.name)); removed += 1; } catch (error) { if (!isMissing(error)) throw error; }
}
const control = lstatOrNull(join(dir, CONTROL_FILE));
if (control && control.isFile() && !control.isSymbolicLink() && readSshCaptureControl(dir, now) === null) {
try { unlinkSync(join(dir, CONTROL_FILE)); } catch (error) { if (!isMissing(error)) throw error; }
}
return removed;
}
function iso(ms: number): string {
return new Date(ms).toISOString();
}
export function sshCaptureStatus(linkDirectory: string, now: number, removed = 0): SshCaptureStatus {
const dir = sshCaptureDir(linkDirectory);
const control = readSshCaptureControl(dir, now);
return {
enabled: control !== null,
logLevel: control ? SSH_CAPTURE_LOG_LEVEL : "ERROR",
startedAt: control ? iso(control.startedAt) : null,
expiresAt: control ? iso(control.expiresAt) : null,
directory: dir,
retentionHours: SSH_CAPTURE_RETENTION_MS / 3_600_000,
maxMinutes: SSH_CAPTURE_MAX_MINUTES,
maxFileBytes: SSH_CAPTURE_FILE_MAX_BYTES,
files: listCaptureFiles(dir).map(file => ({
name: file.name,
bytes: file.bytes,
lastWriteAt: iso(file.mtimeMs),
deleteAfter: iso(file.mtimeMs + SSH_CAPTURE_RETENTION_MS),
})),
removed,
};
}
/** Create the capture directory owner-only, refusing a symlink or a non-directory in its place. */
function ensurePrivateDir(linkDirectory: string): string {
const dir = sshCaptureDir(linkDirectory);
assertNotRealHomeUnderTest(dirname(linkDirectory));
mkdirSync(linkDirectory, { recursive: true, mode: 0o700 });
try { mkdirSync(dir, { mode: 0o700 }); } catch (error) { if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error; }
const stat = lstatSync(dir);
if (stat.isSymbolicLink() || !stat.isDirectory()) throw new SshCaptureError("the SSH capture directory is not a plain directory; remove it and try again");
if (windowsSecretAclApplies()) hardenSecretDir(dir, { required: true });
else {
const uid = typeof process.getuid === "function" ? process.getuid() : undefined;
if (uid !== undefined && stat.uid !== uid) throw new SshCaptureError("the SSH capture directory belongs to another user");
chmodSync(dir, 0o700);
}
return dir;
}
export interface SshCaptureStartOptions {
linkDirectory: string;
now: number;
minutes?: number;
}
/** Open or extend the capture window. Starting while a window is open keeps its capture file. */
export function startSshCapture(options: SshCaptureStartOptions): SshCaptureStatus {
const minutes = options.minutes ?? SSH_CAPTURE_DEFAULT_MINUTES;
if (!Number.isSafeInteger(minutes) || minutes < 1 || minutes > SSH_CAPTURE_MAX_MINUTES) {
throw new SshCaptureError("--minutes must be an integer from 1 to " + SSH_CAPTURE_MAX_MINUTES);
}
if (!isSafeEpoch(options.now)) throw new SshCaptureError("the system clock is not usable for an SSH capture window");
const dir = ensurePrivateDir(options.linkDirectory);
let removed = pruneSshCapture(dir, options.now);
const startedAt = readSshCaptureControl(dir, options.now)?.startedAt ?? options.now;
// Keep room for this window's file: the oldest files beyond the cap go first.
const others = listCaptureFiles(dir).filter(file => file.startedAt !== startedAt);
for (const file of others.slice(0, Math.max(0, others.length - (SSH_CAPTURE_MAX_FILES - 1)))) {
try { unlinkSync(join(dir, file.name)); removed += 1; } catch (error) { if (!isMissing(error)) throw error; }
}
const control: SshCaptureControl = { version: 1, startedAt, expiresAt: options.now + minutes * 60_000 };
const path = join(dir, CONTROL_FILE);
atomicWriteFileNoFollow(path, JSON.stringify(control) + "\n");
if (windowsSecretAclApplies()) hardenSecretPath(path, { required: true });
else chmodSync(path, 0o600);
return sshCaptureStatus(options.linkDirectory, options.now, removed);
}
/** Close the window now. Capture files stay until their retention passes. */
export function stopSshCapture(linkDirectory: string, now: number): SshCaptureStatus {
const dir = sshCaptureDir(linkDirectory);
const directory = lstatOrNull(dir);
if (directory && directory.isDirectory() && !directory.isSymbolicLink()) {
// unlink never follows: a planted link is removed itself, its target untouched.
try { unlinkSync(join(dir, CONTROL_FILE)); } catch (error) { if (!isMissing(error)) throw error; }
}
return sshCaptureStatus(linkDirectory, now, pruneSshCapture(dir, now));
}
/** Apply retention and report. Deletes only capture files past retention and an expired control file. */
export function readSshCaptureStatus(linkDirectory: string, now: number): SshCaptureStatus {
return sshCaptureStatus(linkDirectory, now, pruneSshCapture(sshCaptureDir(linkDirectory), now));
}
type CaptureRecord = {
at: number;
tunnel: SshCaptureTunnel;
linkId?: string;
level?: SanitizedSshLine["level"];
event: string;
text?: string;
count?: number;
dropped?: number;
};
type AppendResult = "written" | "full" | "refused";
/** Append to a capture file through a private no-follow handle, never past the per-file cap. */
async function appendCapture(dir: string, name: string, lines: readonly string[], truncatedLine: string): Promise<AppendResult> {
assertNotRealHomeUnderTest(dirname(dirname(dir)));
// The writer never creates the directory: only an explicit start does.
const directory = await lstat(dir).catch(() => null);
if (!directory || !directory.isDirectory() || directory.isSymbolicLink()) return "refused";
const windows = windowsSecretAclApplies();
if (windows) await hardenSecretDirAsync(dir, { required: true });
else await chmod(dir, 0o700);
const path = join(dir, name);
let file: Awaited<ReturnType<typeof open>> | undefined;
try {
const flags = constants.O_RDWR | constants.O_APPEND | constants.O_CREAT | constants.O_NOFOLLOW | constants.O_NONBLOCK;
file = await open(path, flags, 0o600);
const current = await file.stat();
if (!current.isFile() || current.nlink !== 1) return "refused";
if (windows) await hardenSecretPathAsync(path, { required: true });
else await file.chmod(0o600);
// A marker ends the file for every process, not only the one that wrote it.
if (current.size > 0) {
const length = Math.min(current.size, TRUNCATION_RESERVE_BYTES);
const tail = Buffer.alloc(length);
await file.read(tail, 0, length, current.size - length);
if (tail.toString("utf8").includes(TRUNCATION_EVENT)) return "full";
}
if (current.size >= SSH_CAPTURE_FILE_MAX_BYTES - TRUNCATION_RESERVE_BYTES) {
// Reached without a marker (lines that filled it exactly): end it with the one marker that fits.
if (current.size + Buffer.byteLength(truncatedLine) <= SSH_CAPTURE_FILE_MAX_BYTES) await file.write(truncatedLine);
return "full";
}
let size = current.size;
let data = "";
let full = false;
for (const line of lines) {
const bytes = Buffer.byteLength(line);
if (size + bytes > SSH_CAPTURE_FILE_MAX_BYTES - TRUNCATION_RESERVE_BYTES) { full = true; break; }
data += line;
size += bytes;
}
if (full) data += truncatedLine;
if (data) await file.write(data);
if (windows) {
const written = await file.stat({ bigint: true });
const named = await lstat(path, { bigint: true });
if (!named.isSymbolicLink() && named.dev === written.dev && named.ino === written.ino) {
await file.close();
file = undefined;
reattributeHardenedSecretPath(path);
}
}
return full ? "full" : "written";
} finally {
await file?.close();
}
}
export interface SshCaptureOpenerOptions {
linkDirectory: string;
now?: () => number;
setTimer?: (callback: () => void, ms: number) => ReturnType<typeof setTimeout>;
clearTimer?: (timer: ReturnType<typeof setTimeout>) => void;
}
export interface SshCaptureOpenerWithFlush extends SshCaptureOpener {
/** Wait for queued records; tests and shutdown only. */
flush(): Promise<void>;
/** Apply retention now and arm deletion for the earliest remaining file; runs at process start. */
retain(): void;
}
/**
* The per-directory opener the Home supervisor and the Child tunnel call at each spawn. With no
* capture directory it costs one lstat and returns null; nothing else runs and nothing is written.
*/
export function createSshCaptureOpener(options: SshCaptureOpenerOptions): SshCaptureOpenerWithFlush {
const dir = sshCaptureDir(options.linkDirectory);
const now = options.now ?? Date.now;
const setTimer = options.setTimer ?? ((callback, ms) => setTimeout(callback, ms));
const clearTimer = options.clearTimer ?? (timer => clearTimeout(timer));
const queue: Array<{ startedAt: number; record: CaptureRecord }> = [];
const fullSessions = new Set<number>();
let dropped = 0;
let flight: Promise<void> | undefined;
let lastPrune = Number.NEGATIVE_INFINITY;
let retentionTimer: ReturnType<typeof setTimeout> | undefined;
// Retention must not depend on the process that wrote a file staying alive: every prune, in any
// process, re-arms one unref'd timer for the earliest remaining file's expiry (#7297).
const prune = (): void => {
let earliest = Number.POSITIVE_INFINITY;
try {
pruneSshCapture(dir, now());
for (const file of listCaptureFiles(dir)) earliest = Math.min(earliest, file.mtimeMs);
} catch { /* Retention runs again at the next spawn, command or process start. */ }
if (retentionTimer !== undefined) { clearTimer(retentionTimer); retentionTimer = undefined; }
if (!Number.isFinite(earliest)) return;
const delay = Math.max(0, Math.ceil(earliest + SSH_CAPTURE_RETENTION_MS - now())) + 1_000;
retentionTimer = setTimer(() => { retentionTimer = undefined; prune(); }, Math.min(delay, SSH_CAPTURE_RETENTION_MS + 1_000));
(retentionTimer as { unref?: () => void } | undefined)?.unref?.();
};
const armRetention = prune;
const drain = async (): Promise<void> => {
while (queue.length) {
const batch = queue.splice(0, queue.length);
const overflow = dropped;
dropped = 0;
const sessions = new Map<number, CaptureRecord[]>();
for (const item of batch) sessions.set(item.startedAt, [...(sessions.get(item.startedAt) ?? []), item.record]);
for (const [startedAt, records] of sessions) {
try {
// A stop or an expiry since the line was queued stores nothing more for that window.
const control = readSshCaptureControl(dir, now());
if (!control || control.startedAt !== startedAt || fullSessions.has(startedAt)) continue;
if (overflow) records.push({ at: now(), tunnel: records[0]!.tunnel, event: "queue_overflow", dropped: overflow });
const result = await appendCapture(dir, captureFileName(startedAt), records.map(record => JSON.stringify(record) + "\n"),
JSON.stringify({ at: now(), event: "capture_truncated" }) + "\n");
if (result === "full") fullSessions.add(startedAt);
if (result !== "refused") armRetention();
} catch { /* Best effort: capture never changes a tunnel. */ }
}
}
};
const startWriter = (): void => {
if (flight) return;
flight = drain().finally(() => {
flight = undefined;
if (queue.length) startWriter();
});
};
const push = (control: SshCaptureControl, tunnel: SshCaptureTunnel, linkId: string, line: SanitizedSshLine): void => {
const at = now();
if (at >= control.expiresAt || fullSessions.has(control.startedAt)) return;
const last = queue.at(-1);
const id = LINK_ID_PATTERN.test(linkId) ? linkId : undefined;
if (line.event === "unrecognized" && last && last.startedAt === control.startedAt && last.record.event === "unrecognized"
&& last.record.tunnel === tunnel && last.record.linkId === id) {
last.record.count = (last.record.count ?? 1) + 1;
return;
}
if (queue.length >= QUEUE_MAX) {
// A flood of debug lines must not push out the line that explains a failure: an error-level
// line takes the place of the oldest queued debug or verbose record, counted as dropped.
const evict = line.level === "error" ? queue.findIndex(item => item.record.level !== "error") : -1;
dropped += 1;
if (evict === -1) return;
queue.splice(evict, 1);
}
const record: CaptureRecord = { at, tunnel, ...(id ? { linkId: id } : {}), level: line.level, event: line.event,
...(line.text !== undefined ? { text: line.text } : {}) };
queue.push({ startedAt: control.startedAt, record });
startWriter();
};
const opener = ((tunnel: SshCaptureTunnel, linkId: string): SshCaptureSpawn | null => {
const directory = lstatOrNull(dir);
if (!directory) return null;
const at = now();
if (at - lastPrune >= PRUNE_INTERVAL_MS || at < lastPrune) { lastPrune = at; prune(); }
const control = readSshCaptureControl(dir, at);
if (!control) return null;
// The window this spawn started in; an extension by a later `start` keeps the same startedAt and
// moves expiresAt, so once the cached expiry passes it is re-read (at most once a second).
let current = control;
let lastRefresh = Number.NEGATIVE_INFINITY;
const refresh = (): void => {
const at = now();
if (at < current.expiresAt || (at - lastRefresh < 1_000 && at >= lastRefresh)) return;
lastRefresh = at;
const fresh = readSshCaptureControl(dir, at);
if (fresh && fresh.startedAt === current.startedAt) current = fresh;
};
return {
logLevel: SSH_CAPTURE_LOG_LEVEL,
stderrLine(line: string): boolean {
const sanitized = sanitizeSshLine(line);
try { refresh(); push(current, tunnel, linkId, sanitized); } catch { /* Storage never changes classification. */ }
return sanitized.classify;
},
};
}) as SshCaptureOpenerWithFlush;
opener.flush = async () => { while (flight) await flight; };
opener.retain = () => {
if (!lstatOrNull(dir)) return;
lastPrune = now();
prune();
};
return opener;
}
const defaultOpeners = new Map<string, SshCaptureOpenerWithFlush>();
/** One opener (and one writer queue) per link directory for the life of the process. */
export function defaultSshCaptureOpener(linkDirectory: string): SshCaptureOpener {
return defaultOpenerFor(linkDirectory);
}
function defaultOpenerFor(linkDirectory: string): SshCaptureOpenerWithFlush {
let opener = defaultOpeners.get(linkDirectory);
if (!opener) {
opener = createSshCaptureOpener({ linkDirectory });
defaultOpeners.set(linkDirectory, opener);
}
return opener;
}
/**
* Apply retention at process start, before any tunnel spawns, so files a previous process wrote are
* deleted on time even when this process never spawns a tunnel or writes a capture.
*/
export function retainSshCapture(linkDirectory: string): void {
try { defaultOpenerFor(linkDirectory).retain(); } catch { /* Capture never blocks startup. */ }
}
/** Open capture for one spawn. Any failure means "off": capture can never stop a tunnel from starting. */
export function openSshCapture(opener: SshCaptureOpener, tunnel: SshCaptureTunnel, linkId: string): SshCaptureSpawn | null {
try { return opener(tunnel, linkId); } catch { return null; }
}