@songsid/agend 2.1.4 → 2.1.5-beta.10

package/dist/web-terminal.d.ts

@@ -0,0 +1,336 @@
+/**
+ * Web terminal session: one command, one tmux pane, one browser, a few minutes.
+ *
+ * This is the core of remote `/login` and `/install-cli` (v2.1.5). The fleet
+ * starts exactly one command inside a *dedicated* tmux server and hands the
+ * admin a browser terminal onto that single pane. Nothing here interprets the
+ * CLI's screens or presses keys on the user's behalf — the human is the TUI's
+ * interpreter, so every CLI's every login flow works without per-CLI modelling.
+ *
+ * Security shape (design doc §3):
+ *   - scope: the browser never gets a tmux client. Input goes through
+ *     `send-keys -H` to this one pane; the pane runs `sh -c "<command>"` and
+ *     dies when the command exits. No shell is reachable.
+ *   - token gate: the URL carries no secret (sid is a path, not a credential).
+ *     A separate one-time access token — delivered over the authenticated chat
+ *     channel — is verified in constant time; three failures destroy the
+ *     session. Success yields a session-bound cookie.
+ *   - TTL: the session ends when the process exits, when the TTL lapses, on
+ *     lockout, or on cancel. Ending always kills the tmux server.
+ *   - observation: the fleet reads the pane (capture-pane) to post the device
+ *     URL/code into chat and to judge success/failure — read-only.
+ *
+ * Output streaming uses `pipe-pane` into a FIFO we hold open O_RDWR (never
+ * EOF, nothing on disk). The pane is created running a placeholder and the
+ * real command is started with `respawn-pane -k` *after* the pipe is attached,
+ * so the very first bytes are captured (verified live: new-session + pipe-pane
+ * loses the first line; placeholder + respawn does not).
+ */
+import { EventEmitter } from "node:events";
+export interface WebTerminalObserve {
+    /** Overrides the generic https matcher when the CLI prints several URLs. */
+    urlPattern?: RegExp;
+    /** One-time device code shown next to the URL. First capture group wins. */
+    codePattern?: RegExp;
+    /** Pane text that proves the command achieved its purpose (login done). */
+    successPattern?: RegExp;
+    /** Known failure strings → human wording + suggested next step. */
+    failures?: Array<{
+        pattern: RegExp;
+        message: string;
+        suggest?: "relogin" | "check-args" | "retry";
+    }>;
+}
+export interface WebTerminalSpec {
+    kind: "login" | "install";
+    backend: string;
+    /** The one shell command the pane will run (`sh -c`). */
+    command: string;
+    cwd: string;
+    ttlMs: number;
+    cols?: number;
+    rows?: number;
+    observe?: WebTerminalObserve;
+    requester: {
+        adapterId: string;
+        userId: string;
+        chatId: string;
+        threadId?: string;
+    };
+}
+export type WebTerminalEndReason = "exit" | "ttl" | "cancel" | "token_lockout" | "error";
+export interface WebTerminalResult {
+    ok: boolean;
+    reason: WebTerminalEndReason;
+    exitCode?: number;
+    /** Last non-empty pane lines (evidence), or the failure mapping's message. */
+    detail: string;
+    suggest?: "relogin" | "check-args" | "retry";
+    /** The dedicated tmux server could NOT be confirmed dead — operator attention needed. */
+    cleanupFailed?: boolean;
+}
+export interface WebTerminalEvents {
+    /** Device URL (+ code) appeared in the pane — post to chat (spoiler). Once per distinct URL. */
+    onHint?(url: string, code: string | null): void | Promise<void>;
+    /** Terminal state, exactly once. */
+    onDone(result: WebTerminalResult): void | Promise<void>;
+    /** Audit trail (eventLog). Never receives the token or cookie. */
+    onAudit?(event: string, fields: Record<string, unknown>): void;
+}
+/** A browser attached over WebSocket, as the session sees it. */
+export interface TerminalClient {
+    send(data: Buffer | string): void;
+    close(code: number, reason: string): void;
+}
+export interface TerminalLogger {
+    debug(obj: unknown, msg?: string): void;
+    info(obj: unknown, msg?: string): void;
+    warn(obj: unknown, msg?: string): void;
+}
+/** The tmux operations a session needs — injectable for unit tests. */
+export interface TerminalBackend {
+    start(opts: {
+        socket: string;
+        command: string;
+        cwd: string;
+        cols: number;
+        rows: number;
+        onOutput: (chunk: Buffer) => void;
+        /** Aborted by finish(): no stage may leave a resource behind once this fires. */
+        signal?: AbortSignal;
+    }): Promise<void>;
+    sendInput(socket: string, bytes: Buffer): Promise<void>;
+    resize(socket: string, cols: number, rows: number): Promise<void>;
+    /** Plain-text pane content (joined wrapped lines), for observation and evidence. */
+    capture(socket: string): Promise<string>;
+    paneStatus(socket: string): Promise<{
+        alive: boolean;
+        exitCode?: number;
+    } | null>;
+    /** Resolves only when the server is confirmed gone; rejects when it may still be alive. */
+    kill(socket: string): Promise<void>;
+}
+export declare const ACCESS_TOKEN_LENGTH = 20;
+export declare const MAX_TOKEN_ATTEMPTS = 3;
+export declare const MAX_TTL_MS: number;
+export declare const DEFAULT_COLS = 120;
+export declare const DEFAULT_ROWS = 36;
+export declare const MIN_COLS = 20, MAX_COLS = 250, MIN_ROWS = 5, MAX_ROWS = 100;
+/** Bytes of browser input allowed to wait for tmux before the session is ended as wedged (B4). */
+export declare const MAX_PENDING_INPUT_BYTES: number;
+/** Queued tmux operations allowed to wait (input batches + at most one resize); more means tmux is stuck. */
+export declare const MAX_PENDING_JOBS = 64;
+/** Consecutive failed pane probes before the session is ended as unreachable. */
+export declare const MAX_PROBE_FAILURES = 3;
+/** 20 base32 chars = 100 bits of entropy (13 random bytes, the last 4 bits truncated). */
+export declare function generateAccessToken(bytes?: Buffer): string;
+/** Evidence for a failure report: the last `n` non-empty lines, bounded. */
+export declare function nonEmptyTail(text: string, n?: number, maxLen?: number): string;
+export declare class WebTerminalSession extends EventEmitter {
+    readonly spec: WebTerminalSpec;
+    private readonly events;
+    private readonly backend;
+    private readonly logger;
+    private readonly now;
+    readonly sid: string;
+    readonly socketName: string;
+    readonly createdAt: number;
+    expiresAt: number;
+    state: "created" | "running" | "finished";
+    private accessToken;
+    private tokenAttempts;
+    private cookieValue;
+    private readonly replay;
+    private replayBytes;
+    private replayTruncated;
+    private client;
+    private ttlTimer;
+    private pollTimer;
+    private polling;
+    private finishing;
+    /** The backend.start() in flight, so finish() can wait for it to settle before its one confirmed kill. */
+    private startInFlight;
+    /** Aborted by finish(): the backend checks it after every stage and tears down anything it created. */
+    private readonly startAbort;
+    private sentUrls;
+    private successSeenAt;
+    /** Consecutive polls where tmux could not even be asked — a vanished server must not idle until TTL. */
+    private probeFailures;
+    /** Geometry most recently requested by the browser (queued, frozen or applied) — the only dedupe key. */
+    private lastRequested;
+    /** Single FIFO for input + resize: browser order is pane order (B4). */
+    private ioQueue;
+    private pendingInputBytes;
+    private pendingJobCount;
+    /** Input bytes not yet handed to a running job: consecutive frames coalesce into one tmux paste. */
+    private pendingBatch;
+    /**
+     * The resize job at the TAIL of the queue, still open for coalescing. Only
+     * while no input has been queued after it may a newer resize update it;
+     * input freezes it (a resize is a barrier and must stay in its FIFO slot).
+     */
+    private tailResize;
+    private cols;
+    private rows;
+    constructor(spec: WebTerminalSpec, events: WebTerminalEvents, backend: TerminalBackend, logger: TerminalLogger, now?: () => number);
+    /** The one-time access token, readable only until it is redeemed or the session ends. */
+    peekAccessToken(): string | null;
+    get ttlRemainingMs(): number;
+    start(): Promise<void>;
+    /**
+     * Redeem the one-time access token. Constant-time compare; three failures
+     * destroy the session (URL + attempts = suspected leak). Success returns the
+     * cookie value the HTTP layer sets; the token is gone from memory afterwards.
+     */
+    redeemToken(candidate: string): {
+        result: "ok";
+        cookie: string;
+    } | {
+        result: "bad";
+        remaining: number;
+    } | {
+        result: "used" | "locked" | "finished";
+    };
+    checkCookie(value: string | undefined): boolean;
+    /** Attach the (single) browser; replays buffered output first. Returns a detach function. */
+    attachClient(client: TerminalClient): () => void;
+    /** Bytes queued for the pane but not yet delivered. */
+    get pendingInput(): number;
+    /** Queued tmux operations not yet started (tests: must stay small under any input pattern). */
+    get pendingJobs(): number;
+    /**
+     * Queue browser input for the pane. Strictly ordered with resize.
+     * Consecutive input frames coalesce into ONE paste (a resize is a barrier),
+     * so the number of tmux operations is bounded by the number of barriers,
+     * not by the number of keystrokes. Returns false when the session is not
+     * running. A backlog beyond MAX_PENDING_INPUT_BYTES / MAX_PENDING_JOBS
+     * means tmux is wedged: the session ENDS (fail closed) rather than letting
+     * queued keystrokes reach a credential prompt unattended.
+     */
+    input(bytes: Buffer): boolean;
+    resize(cols: number, rows: number): void;
+    /** Everything queued before the returned promise settles has reached tmux (tests). */
+    drain(): Promise<void>;
+    private enqueue;
+    cancel(detail?: string): Promise<void>;
+    private onOutput;
+    private schedulePoll;
+    /** Exposed for tests; the timer calls this every second. */
+    poll(): Promise<void>;
+    private observe;
+    private finishFromExit;
+    private finish;
+    private audit;
+}
+/**
+ * Drives a dedicated tmux server (`-L <socket>`, `-f /dev/null` so the user's
+ * tmux.conf cannot alter behaviour). Output: pipe-pane → FIFO held O_RDWR.
+ */
+export declare class TmuxTerminalBackend implements TerminalBackend {
+    private readonly tmuxBin;
+    private readonly streams;
+    /**
+     * Identity of each dedicated server, captured right after new-session: the
+     * PID plus an immutable process-generation fingerprint (Linux /proc start
+     * time). There is no weaker fallback: on platforms without /proc no
+     * identity is recorded and no signal is ever sent. A bare PID may be reused
+     * by the OS once the server dies outside our control; a signal must NEVER
+     * be sent unless the fingerprint still matches — otherwise the "one
+     * command" scope would be violated against an unrelated process.
+     */
+    private readonly servers;
+    private readonly probe;
+    constructor(tmuxBin?: string, opts?: {
+        probeProcess?: (pid: number) => ProcessProbe;
+    });
+    /** Test seam: the recorded server identity, if a signal fallback was registered. */
+    serverRecordForTests(socket: string): {
+        pid: number;
+        identity: string;
+    } | undefined;
+    /**
+     * Run one tmux command. Errors are re-thrown SANITIZED: operation name,
+     * socket and exit code only — never the argv, which for input would be the
+     * user's keystrokes (B2), and never tmux's stderr, which echoes the command.
+     */
+    private tmux;
+    start(opts: {
+        socket: string;
+        command: string;
+        cwd: string;
+        cols: number;
+        rows: number;
+        onOutput: (chunk: Buffer) => void;
+        signal?: AbortSignal;
+    }): Promise<void>;
+    /**
+     * Deliver bytes to the pane WITHOUT putting typed text in any argv (B2).
+     *
+     * Two transports, chosen per run of bytes (see segmentInput):
+     *   - text runs (anything a user could be typing as a secret) go to tmux
+     *     over stdin into a named buffer and are pasted with `paste-buffer -r`
+     *     (raw: bytes unchanged), `-d` deleting the buffer;
+     *   - control runs (0x00–0x1f, 0x7f and complete ESC sequences: arrows,
+     *     Enter, Tab, Ctrl-C…) go through `send-keys -H`. They carry no
+     *     secret, and this is the only path on which the pane's tty performs
+     *     signal handling: a pasted 0x03 is echoed but does NOT raise SIGINT
+     *     (verified live), a sent one does.
+     */
+    sendInput(socket: string, bytes: Buffer): Promise<void>;
+    resize(socket: string, cols: number, rows: number): Promise<void>;
+    capture(socket: string): Promise<string>;
+    paneStatus(socket: string): Promise<{
+        alive: boolean;
+        exitCode?: number;
+    } | null>;
+    /**
+     * Tri-state liveness of the dedicated server. "dead" is asserted only on
+     * POSITIVE evidence of absence (tmux's own no-server answer, and — when a
+     * PID is known — the process gone); a probe that could not execute
+     * (spawn failure, timeout, unexpected exit) is "unknown", never "dead".
+     * stderr is inspected in memory only and never logged.
+     */
+    serverState(socket: string): Promise<"alive" | "dead" | "unknown">;
+    /**
+     * Kill the dedicated server and CONFIRM it is gone (B2). `kill-server` is
+     * tried twice; if the server is not positively dead, the PID captured at
+     * start is sent SIGTERM then SIGKILL. The FINAL probe decides: resolves
+     * only on "dead"; "alive" and "unknown" both reject so the caller reports
+     * a cleanup failure instead of claiming the boundary held. "Already gone"
+     * (positively) is success.
+     */
+    kill(socket: string): Promise<void>;
+    /** Test seam: adopt a server identity as if captured at start. */
+    rememberServerForTests(socket: string, pid: number, identity: string): void;
+}
+export type ProcessProbe = {
+    kind: "identified";
+    identity: string;
+    comm?: string;
+} | {
+    kind: "gone";
+} | {
+    kind: "unknown";
+};
+/**
+ * Tri-state process probe. "gone" requires positive ESRCH evidence. The
+ * identity is the process start time in clock ticks since boot (Linux
+ * /proc/<pid>/stat field 22) and NOTHING else: it is fixed for the life of
+ * the process, so a mismatch is proof of PID reuse. The command name is
+ * returned separately for diagnostics only — a live process can rename
+ * itself (prctl / /proc/self/comm), so it must never take part in equality.
+ * On platforms without /proc there is NO fingerprint: the probe can only say
+ * gone/unknown, and the backend registers no signal fallback.
+ */
+export declare function probeProcess(pid: number): ProcessProbe;
+/**
+ * Split browser input into runs: "control" (C0 bytes, DEL, and complete ESC
+ * sequences — never secrets) vs "text" (everything else — possibly a
+ * password). Control runs may travel in argv; text runs must not.
+ */
+export declare function segmentInput(bytes: Buffer): Array<{
+    kind: "control" | "text";
+    bytes: Buffer;
+}>;
+/** Single-quote for `sh`: the only quoting that survives any content. */
+export declare function shellQuote(s: string): string;