@xingular/harness 1.3.1-unstable.2 → 1.3.1-unstable.4

package/dist/sdk/remote/seal.js

@@ -0,0 +1,84 @@
+// Sealed frames for remote control. A LAN page is served over plain HTTP, where the browser has no
+// WebCrypto and anyone on the Wi-Fi can read traffic, so every body is a NaCl secretbox
+// (XSalsa20-Poly1305) under a key the phone got from the QR code's fragment, which a browser never
+// sends. A random 24-byte nonce per frame; the counter inside the frame stops replays.
+import { timingSafeEqual } from 'node:crypto';
+import nacl from 'tweetnacl';
+import { HarnessError } from "../core/errors.js";
+export const KEY_BYTES = nacl.secretbox.keyLength;
+/** How far behind the highest counter a frame may arrive, for requests a phone sent at once. */
+export const REPLAY_WINDOW = 256;
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+export function newKey() {
+    return nacl.randomBytes(KEY_BYTES);
+}
+/** URL-safe base64 without padding: it travels in fragments, query strings and SSE lines. */
+export function encode(bytes) {
+    return Buffer.from(bytes).toString('base64url');
+}
+export function decode(text) {
+    return new Uint8Array(Buffer.from(text, 'base64url'));
+}
+export function seal(key, n, body) {
+    const nonce = nacl.randomBytes(nacl.secretbox.nonceLength);
+    const box = nacl.secretbox(encoder.encode(JSON.stringify({ n, body })), nonce, key);
+    const frame = new Uint8Array(nonce.length + box.length);
+    frame.set(nonce);
+    frame.set(box, nonce.length);
+    return encode(frame);
+}
+const rejected = () => new HarnessError('unauthorized', 'This remote-control frame could not be opened.');
+/**
+ * Opens a frame and asks `fresh` whether its counter is new. A frame that fails here is a wrong
+ * key, a tampered body, or a replay; callers answer all three the same way.
+ */
+export function open(key, frame, fresh) {
+    if (typeof frame !== 'string' || frame.length > 1_500_000)
+        throw rejected();
+    const bytes = decode(frame);
+    const nonceLength = nacl.secretbox.nonceLength;
+    if (bytes.length <= nonceLength + nacl.secretbox.overheadLength)
+        throw rejected();
+    const plain = nacl.secretbox.open(bytes.subarray(nonceLength), bytes.subarray(0, nonceLength), key);
+    if (!plain)
+        throw rejected();
+    let value;
+    try {
+        value = JSON.parse(decoder.decode(plain));
+    }
+    catch {
+        throw rejected();
+    }
+    if (typeof value.n !== 'number' || !Number.isSafeInteger(value.n) || value.n < 1 || !fresh(value.n))
+        throw rejected();
+    return { n: value.n, body: value.body };
+}
+/**
+ * Remembers the counters a sender used: a counter is fresh when it is above the highest seen, or
+ * within the window below it and not seen before.
+ */
+export class ReplayGuard {
+    highest = 0;
+    recent = new Set();
+    accept(n) {
+        if (n > this.highest) {
+            this.highest = n;
+            this.recent.add(n);
+            for (const seen of this.recent)
+                if (seen <= n - REPLAY_WINDOW)
+                    this.recent.delete(seen);
+            return true;
+        }
+        if (n <= this.highest - REPLAY_WINDOW || this.recent.has(n))
+            return false;
+        this.recent.add(n);
+        return true;
+    }
+}
+/** Compares two identifiers without leaking how much of them matched. */
+export function sameSecret(a, b) {
+    const left = Buffer.from(a);
+    const right = Buffer.from(b);
+    return left.length === right.length && timingSafeEqual(left, right);
+}

package/dist/sdk/remote/server.d.ts

@@ -0,0 +1,28 @@
+export interface RemoteAsset {
+    type: string;
+    body: string;
+}
+export interface RemoteStream {
+    /** Sends one sealed frame as an SSE message. */
+    send(frame: string): void;
+    end(): void;
+}
+export interface RemoteRoutes {
+    /** The page and its scripts, by path. */
+    asset(path: string): RemoteAsset | null;
+    hello(body: Record<string, unknown>): Promise<{
+        f: string;
+    }>;
+    call(body: Record<string, unknown>): Promise<{
+        f: string;
+    }>;
+    /** Opens a stream for a paired device; returns what to run when the phone hangs up. */
+    stream(deviceId: string, frame: string, stream: RemoteStream): () => void;
+}
+export interface RemoteListening {
+    host: string;
+    port: number;
+    close(): Promise<void>;
+}
+/** Starts the server on one address. `port` 0 picks a free one. */
+export declare function listenRemote(host: string, port: number, routes: RemoteRoutes): Promise<RemoteListening>;

package/dist/sdk/remote/server.js

@@ -0,0 +1,158 @@
+// The remote-control HTTP server: the phone page, pairing, sealed calls and a sealed event stream.
+// It listens on exactly one private or Tailscale address (INV-RC-1). Bodies are sealed (seal.ts),
+// so this layer only checks the Host and Origin, caps sizes, and routes.
+import { createServer } from 'node:http';
+import { HarnessError, toErrorShape } from "../core/errors.js";
+const MAX_HELLO = 64_000;
+const MAX_CALL = 1_200_000;
+const PING_MS = 15_000;
+const HEADERS = {
+    'cache-control': 'no-store',
+    'referrer-policy': 'no-referrer',
+    'x-content-type-options': 'nosniff',
+    'x-frame-options': 'DENY',
+    'cross-origin-resource-policy': 'same-origin'
+};
+const CSP = "default-src 'none'; script-src 'self'; style-src 'self'; connect-src 'self'; img-src 'self' data:; manifest-src 'self'; base-uri 'none'; form-action 'none'; frame-ancestors 'none'";
+const STATUS = { unauthorized: 401, remote_denied: 403, rate_limited: 429, remote_busy: 409, remote_full: 409, session_busy: 409, terminal_has_draft: 409, too_large: 413, not_found: 404 };
+function reply(response, status, body) {
+    response.writeHead(status, { ...HEADERS, 'content-type': 'application/json; charset=utf-8' });
+    response.end(JSON.stringify(body));
+}
+function failure(response, error) {
+    const shape = toErrorShape(error);
+    reply(response, STATUS[shape.code] ?? 400, { error: { code: shape.code, message: shape.message } });
+}
+async function readBody(request, limit) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of request) {
+        size += chunk.length;
+        if (size > limit)
+            throw new HarnessError('too_large', 'This message is too large.');
+        chunks.push(chunk);
+    }
+    try {
+        const value = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+        if (value && typeof value === 'object' && !Array.isArray(value))
+            return value;
+    }
+    catch { }
+    throw new HarnessError('invalid_request', 'The request is not JSON.');
+}
+/** Starts the server on one address. `port` 0 picks a free one. */
+export async function listenRemote(host, port, routes) {
+    const sockets = new Set();
+    const streams = new Set();
+    let authority = '';
+    const handle = async (request, response) => {
+        // A page on another site cannot reach this server through DNS it controls (rebinding), and no
+        // other origin may post to it.
+        if (request.headers.host !== authority)
+            return reply(response, 421, { error: { code: 'wrong_host', message: 'Open the link shown in the terminal.' } });
+        const origin = request.headers.origin;
+        if (origin !== undefined && origin !== `http://${authority}`)
+            return reply(response, 403, { error: { code: 'wrong_origin', message: 'Requests from other sites are refused.' } });
+        const url = new URL(request.url ?? '/', `http://${authority}`);
+        if (request.method === 'GET' && url.pathname === '/rc/events') {
+            const deviceId = url.searchParams.get('d') ?? '';
+            const frame = url.searchParams.get('f') ?? '';
+            let ended = false;
+            let opened = false;
+            let ping = null;
+            // The route sends its first frame as the stream opens, so the headers go out with it.
+            const begin = () => {
+                if (opened)
+                    return;
+                opened = true;
+                response.writeHead(200, { ...HEADERS, 'content-type': 'text/event-stream; charset=utf-8', connection: 'keep-alive' });
+                response.write(': open\n\n');
+            };
+            const stream = {
+                send: (data) => {
+                    if (ended)
+                        return;
+                    begin();
+                    response.write(`data: ${data}\n\n`);
+                },
+                end: () => {
+                    if (ended)
+                        return;
+                    ended = true;
+                    streams.delete(stream);
+                    if (ping)
+                        clearInterval(ping);
+                    response.end();
+                }
+            };
+            let release;
+            try {
+                release = routes.stream(deviceId, frame, stream);
+            }
+            catch (error) {
+                return failure(response, error);
+            }
+            begin();
+            if (ended)
+                return release();
+            streams.add(stream);
+            ping = setInterval(() => { if (!ended)
+                response.write(': ping\n\n'); }, PING_MS);
+            ping.unref?.();
+            request.on('close', () => {
+                stream.end();
+                release();
+            });
+            return;
+        }
+        if (request.method === 'POST' && (url.pathname === '/rc/hello' || url.pathname === '/rc/call')) {
+            try {
+                const hello = url.pathname === '/rc/hello';
+                const body = await readBody(request, hello ? MAX_HELLO : MAX_CALL);
+                return reply(response, 200, hello ? await routes.hello(body) : await routes.call(body));
+            }
+            catch (error) {
+                return failure(response, error);
+            }
+        }
+        if (request.method === 'GET') {
+            const asset = routes.asset(url.pathname);
+            if (asset) {
+                response.writeHead(200, { ...HEADERS, 'content-type': asset.type, 'content-security-policy': CSP });
+                response.end(asset.body);
+                return;
+            }
+        }
+        reply(response, 404, { error: { code: 'not_found', message: 'Not found.' } });
+    };
+    const server = createServer((request, response) => {
+        handle(request, response).catch((error) => { if (!response.headersSent)
+            failure(response, error); });
+    });
+    server.on('connection', (socket) => {
+        sockets.add(socket);
+        socket.on('close', () => sockets.delete(socket));
+    });
+    await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen({ host, port, exclusive: true }, () => {
+            server.off('error', reject);
+            resolve();
+        });
+    });
+    const bound = server.address().port;
+    authority = `${host.includes(':') ? `[${host}]` : host}:${bound}`;
+    return {
+        host,
+        port: bound,
+        close: async () => {
+            for (const stream of [...streams])
+                stream.end();
+            await new Promise((resolve) => {
+                server.close(() => resolve());
+                for (const socket of sockets)
+                    socket.destroy();
+            });
+        }
+    };
+}

package/dist/sdk/remote/service.d.ts

@@ -0,0 +1,125 @@
+import type { RunEvent } from "../sessions/contracts.js";
+import { type RemoteAddress, type RemoteAddressKind, type RemoteInterfaceChoice } from "./addresses.js";
+import { type PairRequest } from "./pairing.js";
+/** The session remote control drives. Terminals supplies it; tests supply a fake. */
+export interface RemoteSessionPort {
+    sessionId: string;
+    /** A short title for the phone's header. */
+    title(): string;
+    send(text: string): Promise<{
+        runId: string;
+    }>;
+    /** One of the terminal controller's decision calls. */
+    control(call: 'terminal.interrupt' | 'terminal.approve' | 'terminal.answer' | 'terminal.answers' | 'terminal.pending.wait', params: Record<string, unknown>): Promise<unknown>;
+    /** The conversation so far, as saved run events, oldest first. */
+    history(): RunEvent[];
+    /** Events of this session's own runs, after they are redacted and saved. */
+    listen(listener: (event: RunEvent) => void): () => void;
+    state(): {
+        ready: boolean;
+        active: boolean;
+    };
+}
+/** What the phone is sent for one run event. Everything else in an event stays on the computer. */
+export type PhoneEvent = {
+    kind: 'delta';
+    runId: string;
+    messageId: string;
+    text: string;
+} | {
+    kind: 'message';
+    runId: string;
+    messageId: string;
+    role: 'user' | 'assistant';
+    text: string;
+} | {
+    kind: 'tool';
+    runId: string;
+    id: string;
+    name: string;
+    phase: 'start' | 'end';
+    summary?: string;
+    ok?: boolean;
+} | {
+    kind: 'run';
+    runId: string;
+    status: string;
+} | {
+    kind: 'todo';
+    runId: string;
+    items: Array<{
+        text: string;
+        status: string;
+    }>;
+};
+export declare function projectEvent(event: RunEvent): PhoneEvent | null;
+/** A pending decision as the phone shows it. The approval's full action text is kept whole. */
+export declare function projectRequest(request: Record<string, unknown>): Record<string, unknown>;
+/** What the phone may type. Commands and shell escapes belong to the terminal (INV-RC-6). */
+export declare function checkPrompt(value: unknown): string;
+export interface RemoteStatus {
+    running: boolean;
+    revision: number;
+    url: string | null;
+    kind: RemoteAddressKind | null;
+    /** Which address kinds this computer has, for switching. */
+    kinds: RemoteAddressKind[];
+    devices: Array<{
+        id: string;
+        label: string;
+        connected: boolean;
+    }>;
+    request: PairRequest | null;
+    warning: string | null;
+}
+export interface RemoteControlOptions {
+    /** Addresses to choose from; the computer's own by default. */
+    addresses?: () => RemoteAddress[];
+    /** Listen here instead of the chosen address, for tests. */
+    bindHost?: string;
+    port?: number;
+    /** The host's product name for the phone page (`env.productName`). */
+    productName?: string;
+}
+export declare class RemoteControl {
+    private readonly session;
+    private readonly options;
+    private listening;
+    private address;
+    private pairing;
+    private readonly connections;
+    private revision;
+    private readonly waiters;
+    private unlisten;
+    private pendingLoop;
+    private pendingRequests;
+    private starting;
+    private ended;
+    constructor(session: RemoteSessionPort, options?: RemoteControlOptions);
+    private changed;
+    status(): RemoteStatus;
+    /** Returns at once for a changed revision, otherwise after a change or 20 seconds. */
+    waitStatus(revision: unknown): Promise<RemoteStatus>;
+    private base;
+    /** Starts listening, or switches address kind. Starting again with the same kind changes nothing. */
+    start(choice?: RemoteInterfaceChoice): Promise<RemoteStatus>;
+    private listen;
+    /** A new pairing link; every paired phone is disconnected. */
+    rotate(): RemoteStatus;
+    confirm(requestId: string, allow: boolean): RemoteStatus;
+    /** Stops remote control; phones are told the session is no longer reachable. */
+    stop(): Promise<RemoteStatus>;
+    /** The terminal session ended (INV-RC-5). */
+    dispose(): Promise<void>;
+    private close;
+    private get productName();
+    private asset;
+    private send;
+    private broadcast;
+    private drop;
+    private openStream;
+    /** Follows the controller's decisions while a phone is connected, as the terminal itself does. */
+    private watchPending;
+    private call;
+    private dispatch;
+}