@andorra-labs/code 0.0.0-stage → 0.1.5

package/dist/src/remote/command.js

@@ -0,0 +1,211 @@
+import { realpath, stat } from 'node:fs/promises';
+import { basename, resolve } from 'node:path';
+import { configDirectory, loadConfig } from '../config.js';
+import { decodePairingCode } from './pairing.js';
+import { addRemoteShare, addRemoteWorkspace, clearRemoteInvitation, newWorkspaceId, removeRemoteShare, removeRemoteWorkspace, revokeRemoteDevice } from './pairing.js';
+import { ensureRemoteServe, remoteFingerprint, remoteHostingStatus, probeServeStatus } from './serve.js';
+import { ensureRemoteTlsIdentity } from './cert.js';
+import { redeemPairingPlan } from './client.js';
+import { RemoteOwnershipError } from './errors.js';
+export const REMOTE_USAGE = `Usage: andorra remote serve [--port N] [--insecure-http] [--rotate-cert]
+       andorra remote status
+       andorra remote code
+       andorra remote devices | andorra remote revoke <device-id>
+       andorra remote share <path> [--label name] | andorra remote unshare <share-id>
+       andorra remote pair <pairing-code> [--name nickname]
+       andorra remote workspaces | andorra remote unpair <workspace-id>
+       andorra remote rotate-cert`;
+function message(error) { return error instanceof Error ? error.message : String(error); }
+/** Keep the process alive until a stop signal, then run the cleanup exactly once. */
+async function waitForStop() {
+    await new Promise(resolve => {
+        const stop = () => { process.removeListener('SIGINT', stop); process.removeListener('SIGTERM', stop); resolve(); };
+        process.once('SIGINT', stop);
+        process.once('SIGTERM', stop);
+    });
+}
+async function sharePath(value) {
+    const candidate = resolve(value);
+    const realPath = await realpath(candidate).catch(() => undefined);
+    if (!realPath)
+        throw new Error(`That folder does not exist: ${value}`);
+    if (!(await stat(realPath)).isDirectory())
+        throw new Error(`That path is not a folder: ${value}`);
+    return realPath;
+}
+export async function runRemoteCommand(args, print, dependencies = {}) {
+    const [command, ...rest] = args;
+    const flag = (name) => {
+        const index = rest.indexOf(name);
+        return index >= 0 ? rest[index + 1] : undefined;
+    };
+    switch (command) {
+        case 'serve': {
+            const port = flag('--port');
+            const handle = await ensureRemoteServe({
+                owner: 'standalone',
+                ...(port !== undefined ? { port: Number(port) } : {}),
+                insecureHttp: rest.includes('--insecure-http'),
+                rotateCert: rest.includes('--rotate-cert'),
+                version: dependencies.version,
+            });
+            if (!handle.serving)
+                throw new RemoteOwnershipError('The remote listener could not start.');
+            // Everything after the acquisition runs inside the try: a failing status read (the HTTP path
+            // materializes its otherwise-unused TLS identity, and the invitation write can be refused)
+            // must not leave the bound listener and its serve lock alive in a process that reports an
+            // error — later serves would collide with the port, and the lock would look owned forever.
+            try {
+                const status = await remoteHostingStatus({ ensureServing: false });
+                print(`Remote listener: ${handle.transport}://${status.hostname}:${handle.port} (${handle.owned ? 'this process' : 'adopted existing listener'})`);
+                print(`Fingerprint: ${status.fingerprint}`);
+                for (const line of status.code ? [`Pairing code: ${status.code}`] : [])
+                    print(line);
+                if (handle.transport === 'http')
+                    print('WARNING: transport is http — folder names and contents travel unencrypted on the network.');
+                print('Press Ctrl+C to stop serving.');
+                await waitForStop();
+            }
+            finally {
+                await handle.release().catch(() => undefined);
+            }
+            print('Stopped serving.');
+            return 0;
+        }
+        case 'status': {
+            const probed = await probeServeStatus();
+            const config = await loadConfig();
+            print(`Listener: ${probed ? `serving on ${probed.transport} port ${probed.port}` : 'not serving'}`);
+            print(`Transport: ${config.remote?.hosting?.transport ?? 'https'}`);
+            print(`Devices: ${(config.remote?.hosting?.devices ?? []).length}`);
+            print(`Shares: ${(config.remote?.hosting?.shares ?? []).map(share => share.label ?? share.path).join(', ') || 'none'}`);
+            print(`Paired workspaces: ${(config.remote?.workspaces ?? []).length}`);
+            return 0;
+        }
+        case 'code': {
+            const status = await remoteHostingStatus({ ensureServing: true, owner: 'standalone', version: dependencies.version });
+            try {
+                if (!status.code)
+                    throw new Error('No pairing code is available yet — the listener is still starting.');
+                print(status.code);
+                // A code only redeems while a listener answers. When nothing was serving, this call started
+                // the listener, so staying alive is what keeps the printed code usable; when an engine or
+                // another serve already owned it, this process held nothing and exiting changes nothing.
+                if (status.serve?.owned) {
+                    print('Keep this window open while pairing (Ctrl+C stops) — or leave serving to `andorra remote serve`.');
+                    await waitForStop();
+                }
+            }
+            finally {
+                await status.serve?.release().catch(() => undefined);
+            }
+            return 0;
+        }
+        case 'devices': {
+            const config = await loadConfig();
+            const devices = config.remote?.hosting?.devices ?? [];
+            if (!devices.length)
+                print('No paired devices.');
+            for (const device of devices)
+                print(`${device.id}  ${device.label ?? 'unlabeled'}  grant ${device.grant === 'full' ? 'full' : 'browse'}  added ${device.addedAt}${device.lastSeenAt ? `  last seen ${device.lastSeenAt}` : ''}`);
+            return 0;
+        }
+        case 'revoke': {
+            const deviceId = rest[0];
+            if (!deviceId)
+                throw new Error('Usage: andorra remote revoke <device-id>');
+            print(await revokeRemoteDevice(deviceId) ? `Revoked device ${deviceId}.` : `No device with id ${deviceId}.`);
+            return 0;
+        }
+        case 'share': {
+            const path = rest.find(entry => !entry.startsWith('--'));
+            if (!path)
+                throw new Error('Usage: andorra remote share <path> [--label name]');
+            const share = await addRemoteShare(await sharePath(path), { label: flag('--label') });
+            print(`Shared ${share.path} as ${share.label ?? basename(share.path)} (id ${share.id}).`);
+            return 0;
+        }
+        case 'unshare': {
+            const shareId = rest[0];
+            if (!shareId)
+                throw new Error('Usage: andorra remote unshare <share-id>');
+            print(await removeRemoteShare(shareId) ? `Removed share ${shareId}.` : `No share with id ${shareId}.`);
+            return 0;
+        }
+        case 'pair': {
+            const code = rest.find(entry => !entry.startsWith('--'));
+            if (!code)
+                throw new Error('Usage: andorra remote pair <pairing-code> [--name nickname]');
+            // The capacity refusal is deterministic and local, so it is checked BEFORE redemption: the
+            // invitation is single-use and redeeming creates a device credential on the host, so failing
+            // afterwards would consume the code and leave an orphan device to revoke by hand.
+            const local = await loadConfig();
+            if ((local.remote?.workspaces ?? []).length >= 32) {
+                throw new Error('This machine already pairs with the maximum number of workspaces. Unpair one, then pair again — the code has not been used.');
+            }
+            const decoded = decodePairingCode(code);
+            const redeemed = await redeemPairingPlan({
+                hosts: decoded.hosts,
+                port: decoded.port,
+                transport: decoded.transport,
+                fingerprint: decoded.fp,
+                invite: decoded.invite,
+                name: decoded.n,
+            }, { label: flag('--name') });
+            const workspace = {
+                id: newWorkspaceId(),
+                nickname: (flag('--name') ?? redeemed.hostname ?? decoded.n).slice(0, 64),
+                hosts: decoded.hosts,
+                host: redeemed.host,
+                port: decoded.port,
+                transport: decoded.transport,
+                fingerprint: decoded.fp,
+                certPem: redeemed.certPem,
+                token: redeemed.credential,
+                hostname: redeemed.hostname,
+                platform: redeemed.platform,
+                version: redeemed.version,
+                addedAt: new Date().toISOString(),
+            };
+            await addRemoteWorkspace(workspace).catch((error) => {
+                // The redemption already happened, so the host now holds a device for this machine that no
+                // local workspace points at; say so instead of reporting a plain write failure.
+                throw new Error(`Paired with ${workspace.nickname}, but the workspace could not be saved locally (${error instanceof Error ? error.message : String(error)}). That machine now lists a device for this machine — revoke it there before pairing again.`);
+            });
+            print(`Paired with ${workspace.nickname} (id ${workspace.id}). Switch to it from the Workspace selector in the desktop.`);
+            return 0;
+        }
+        case 'workspaces': {
+            const config = await loadConfig();
+            const workspaces = config.remote?.workspaces ?? [];
+            if (!workspaces.length)
+                print('No paired workspaces.');
+            for (const workspace of workspaces)
+                print(`${workspace.id}  ${workspace.nickname}  ${workspace.host ?? workspace.hosts[0]}:${workspace.port} (${workspace.transport})`);
+            return 0;
+        }
+        case 'unpair': {
+            const workspaceId = rest[0];
+            if (!workspaceId)
+                throw new Error('Usage: andorra remote unpair <workspace-id>');
+            print(await removeRemoteWorkspace(workspaceId) ? `Unpaired workspace ${workspaceId}.` : `No workspace with id ${workspaceId}.`);
+            return 0;
+        }
+        case 'rotate-cert': {
+            await ensureRemoteTlsIdentity(`${configDirectory()}/remote-live/tls`, { rotate: true });
+            // A live invitation token authorizes redemption on its own — certificate verification is the
+            // viewer's, and a holder of the old code could redeem it against a restarted listener. The
+            // rotation therefore invalidates outstanding codes (as the serve --rotate-cert path does)
+            // before claiming that they no longer work.
+            await clearRemoteInvitation();
+            const fingerprint = await remoteFingerprint();
+            print(`Rotated the TLS identity. New fingerprint: ${fingerprint}`);
+            print('Existing pairing codes and every peer\'s saved pairing are now invalid: generate new codes and re-pair each machine.');
+            print('Restart any running listener (`andorra remote serve`) so it serves the new certificate.');
+            return 0;
+        }
+        default:
+            print(REMOTE_USAGE);
+            return command === undefined ? 0 : 1;
+    }
+}

package/dist/src/remote/engine-pool.d.ts

@@ -0,0 +1,230 @@
+/**
+ * The engine relay: the host side of full-owner remote access.
+ *
+ * A paired window is a full client of this machine's engine surface, so someone has to stand between
+ * the pairing listener and the engine pool the product describes (ADR 0017): a browsing engine that
+ * answers sessions, run records, workspace reads and terminals, plus one child engine per concurrent
+ * task. That coordinator is this module, and it lives in the process that owns the listener — the
+ * desktop's primary engine, or a standalone `andorra remote serve`. It spawns its own children with
+ * the same `app-server --stdio` wire every other client speaks, so a headless host and a desktop host
+ * serve the identical surface.
+ *
+ * Nothing here decides authority: the endpoints in `server.ts` admit a request only for a full-grant
+ * device over TLS, and this module assumes that check has run. Revocation is still enforced live — a
+ * poller re-reads the device table and cuts a revoked device's event stream and terminals, because a
+ * long-lived stream is exactly the resource a per-request authentication check cannot see.
+ *
+ * Client-lifetime resources are namespaced per connection: terminal ids are prefixed with the
+ * connection that opened them, their output is delivered only to that connection, and a closeAll from
+ * one connection sweeps only its own shells. Run ownership is host-wide (the runs belong to this
+ * machine), so run and prompt routing is by runId and engine id across all children.
+ */
+/** The engine a paired client addresses for everything that is not one task's run. */
+export declare const REMOTE_PRIMARY_ENGINE = "remote-primary";
+/**
+ * The capability that says this relay understands a capability requirement.
+ *
+ * It lives here, with the implementation that honours it, and not in the app-server's shared
+ * capability list: the server loads that list lazily, so a build whose files were replaced under
+ * a running relay would advertise a capability the relay in memory does not have — and a client
+ * that trusted it would send a requirement the old relay forwards to a child that ignores it.
+ */
+export declare const RELAY_CAPABILITY_REQUIREMENT = "remote.engine.relay.capability";
+/** The error shape a relayed engine failure comes back as, mirroring the app-server wire. */
+export interface RelayError {
+    code: string;
+    message: string;
+}
+export interface RelayRequestBody {
+    connectionId: string;
+    /** The viewer's own workspace id, so `rw:` project spellings can be translated to and from it. */
+    viewerWorkspaceId?: string;
+    engine: string;
+    method: string;
+    params?: Record<string, unknown>;
+    /** The viewer's deadline for this call, from its own per-method table. */
+    deadlineMs?: number;
+}
+export interface RelayAnswer {
+    result?: unknown;
+    error?: RelayError;
+}
+/** One event stream subscriber: the SSE response writer for one connection. */
+type EventSink = (payload: {
+    engine: string;
+    event: string;
+    data: Record<string, unknown>;
+}) => void;
+/** How this process spawns another engine of its own CLI. */
+export declare function relayEngineCommand(): string[];
+/**
+ * The viewer's `rw:` project spellings and this machine's folders, as one translation.
+ *
+ * A registered root's id is this machine's own root id, so the host side of a project id is
+ * reversible for roots and only roots: a folder picked INSIDE a root was hashed with a relative path
+ * only the viewer ever knew, and execution through such a pick is refused with the instruction that
+ * makes it executable (register the folder) rather than a silent not-found.
+ */
+export interface PathTranslation {
+    /** `rw:<viewer ws>:<rootId>` → the host path, for requests. */
+    toHost(value: string): string;
+    /** Host path → the viewer's `rw:` spelling, for responses and events. */
+    toViewer(value: string): string;
+    /** Rewrite every known host path inside an arbitrary payload. */
+    rewrite(value: unknown): unknown;
+}
+declare const REMOTE_PROJECT_PREFIX = "rw:";
+declare function isRemoteProjectSpelling(value: string): boolean;
+/** The root id part of an `rw:` spelling: everything after the viewer workspace segment. */
+declare function rootPartOf(value: string): string | undefined;
+/**
+ * The coordinator. One instance per listener, created by the server alongside it.
+ */
+export declare class RemoteEngineRelay {
+    private readonly directory;
+    private readonly children;
+    /**
+     * The children this relay is stopping, so no start takes one that is on its way out.
+     *
+     * It belongs to the relay: two relays in one process allocate the same child ids, and one
+     * relay's reservation would hide another's idle child.
+     */
+    private readonly retiringChildren;
+    private taskSeq;
+    private readonly connections;
+    /** Real (child-side) terminal id → the connection that opened it. */
+    private readonly terminalOwner;
+    /** Session id → the connections whose panels are watching it (a stream they share). */
+    private readonly browserViewers;
+    /** runId / sessionId → the child that owns it, learned from run lifecycle events. */
+    private readonly runEngine;
+    private readonly sessionEngine;
+    /** The `run.started` payload of each live run, keyed by its child — replayed to new connections. */
+    private readonly activeRuns;
+    /** The completions that landed with no stream attached, kept briefly for the reconnect replay. */
+    private readonly finishedRuns;
+    /** Translations by viewer workspace id, each cached briefly (a rebuild realpath-walks the roots). */
+    private readonly translations;
+    private revocationTimer;
+    /** Event delivery is queued: a stream's frames must land in the order the children emitted them. */
+    private delivery;
+    private closed;
+    constructor(directory: string);
+    /**
+     * One relayed request. Throws nothing: every failure is the answer's `error`, because the caller is
+     * an HTTP handler whose status code cannot say what went wrong inside the engine pool.
+     */
+    request(deviceId: string, body: RelayRequestBody): Promise<RelayAnswer>;
+    private validate;
+    private childDeadline;
+    private dispatch;
+    /**
+     * run.start / run.resume: pick a free task engine, spawning one when every child is busy.
+     *
+     * The browsing engine never takes a run (ADR 0017), the busy refusal is the engine's own, and the
+     * answer names the engine that took the run so the viewer can address its prompts directly.
+     */
+    private startRequest;
+    /**
+     * run.cancel / run.approve / run.answer: a prompt belongs to the child that raised it.
+     *
+     * The viewer addresses these by the engine id it learned from `run.started`, which is authoritative
+     * here as well; a cancel names its run id, and the ownership map answers that on its own.
+     */
+    private runTargetRequest;
+    /**
+     * Terminal calls: ids are prefixed with the connection, output goes only to that connection, and a
+     * closeAll sweeps only the shells that connection opened. The browsing engine hosts the PTYs — a
+     * shell outlives any one task and belongs to no run.
+     */
+    private terminalRequest;
+    /**
+     * Translate the viewer's project spellings inside request params. Only the fields that NAME a
+     * workspace folder carry one, so the walk is over those fields, not the whole payload — a task
+     * prompt may legitimately contain the literal text "rw:".
+     */
+    private translateParams;
+    /** Put each listing group back under the spelling the viewer asked with. */
+    private restoreRequestedEcho;
+    /** The connection record, created on first sight. */
+    private connection;
+    /**
+     * End one connection outright: its streams are closed (not merely starved), its terminals swept.
+     *
+     * Revocation and shutdown both go through here, so a connection never survives either — the
+     * viewer observes the stream end and the host keeps no orphaned shells or half-dead sockets.
+     */
+    private sever;
+    /**
+     * Register one connection's event stream. The returned stop function ends delivery; the server
+     * calls it when the HTTP response closes, and it sweeps that connection's terminals with it — a
+     * window that is gone cannot name its shells any more, and the host's slots are not a graveyard.
+     */
+    events(deviceId: string, connectionId: string, viewerWorkspaceId: string | undefined, sink: EventSink, cut: () => void): () => void;
+    /**
+     * Deliver the reconnect snapshot to one stream, in emission order with everything else.
+     *
+     * Active runs first (the replacement client must register them), then the completions that landed
+     * while no stream was attached (so a run that finished in a reconnect gap is not shown as working
+     * forever), then each idle engine's outstanding timers (so a scheduled wake is adopted by the new
+     * client rather than firing unseen).
+     */
+    private replayTo;
+    /** One queued frame for one sink: the reconnect replay shares the queue, not the broadcast. */
+    private enqueueTo;
+    /**
+     * One child event, in emission order.
+     *
+     * The queue is the ordering guarantee a stream needs — `run.started` must reach the viewer before
+     * the run's first events whatever the translation cache is doing between them.
+     */
+    private enqueue;
+    private deliverEvent;
+    /**
+     * One event's data for one viewer, with its project paths translated.
+     *
+     * A panel operation's arguments are the browser's own input, not paths: a `fill` value that
+     * happens to equal a shared root is a form value the page must receive verbatim, and rewriting it
+     * into the viewer's project id would type that id into the page instead. Only the routing fields
+     * around them are translated.
+     */
+    private rewriteEventData;
+    private onChildExit;
+    private engineOwnsRun;
+    private engine;
+    private spawnChild;
+    /**
+     * Whether a child still owns a scheduled wake.
+     *
+     * A child that cannot answer is treated as holding one: stopping it could destroy a wake that
+     * is still owed, and a refused start is a visible failure while a lost wake is not.
+     */
+    /**
+     * Whether a child is free of a run.
+     *
+     * A child that cannot answer is not known to be free, and stopping one that is preparing a run
+     * would abort the task it accepted.
+     */
+    private childIsIdle;
+    private childHoldsWake;
+    private retireChild;
+    /**
+     * The bidirectional project-spelling translation for one viewer.
+     *
+     * Cached briefly per viewer workspace id: building it realpath-walks every authorized root, and a
+     * sessions listing or an event burst would otherwise pay that per call. The cache never outlives a
+     * pairing change by long — five seconds — so a newly registered project is executable almost
+     * immediately.
+     */
+    private translation;
+    /**
+     * Cut every live stream and terminal of devices that no longer hold full authority.
+     *
+     * Per-request authentication already refuses a revoked device's next call; this poller is for the
+     * resource a request never re-checks — the open event stream, and the shells its connection owns.
+     */
+    private startRevocationPoll;
+    /** Stop the pool: every child gets the graceful close, and no stream outlives the listener. */
+    close(): Promise<void>;
+}
+export { REMOTE_PROJECT_PREFIX, isRemoteProjectSpelling, rootPartOf };