@ours.network/fleet 0.10.3 → 0.11.0

package/dist/web/device-store.d.ts

@@ -0,0 +1,27 @@
+export interface TrustedDeviceIssue {
+    token: string;
+    id: string;
+    expiresAt: number;
+}
+/** Persistent trusted-device registry. Raw device secrets never enter this store. */
+export declare class TrustedDeviceStore {
+    private readonly now;
+    private readonly ttlMs;
+    private readonly maxDevices;
+    readonly dir: string;
+    readonly path: string;
+    private devices;
+    constructor(dir?: string, now?: () => number, ttlMs?: number, maxDevices?: number);
+    issue(): TrustedDeviceIssue;
+    /** Validate and rotate on use. The old token is invalid as soon as this returns. */
+    rotate(token: string): TrustedDeviceIssue | undefined;
+    revoke(token: string): boolean;
+    /** Revoke an already-authenticated device without retaining its raw secret in a session. */
+    revokeId(id: string): boolean;
+    revokeAll(): number;
+    count(): number;
+    private read;
+    private prune;
+    private write;
+}
+export declare const TRUSTED_DEVICE_MAX_AGE_SECONDS: number;

package/dist/web/device-store.js

@@ -0,0 +1,155 @@
+import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
+import { chmodSync, lstatSync, mkdirSync, readFileSync, } from 'node:fs';
+import { join } from 'node:path';
+import { replaceFileAtomically } from '../atomic-file.js';
+import { FleetError } from '../application/errors.js';
+import { stateRoot } from '../paths.js';
+const VERSION = 1;
+const DEFAULT_TTL_MS = 30 * 24 * 60 * 60_000;
+const DEFAULT_MAX_DEVICES = 32;
+const MAX_STORE_BYTES = 128 * 1024;
+const opaque = (bytes) => randomBytes(bytes).toString('base64url');
+const digest = (id, secret) => createHash('sha256').update('ours-fleet-device-v1\0').update(id).update('\0').update(secret).digest('base64url');
+const safeEqual = (left, right) => {
+    const a = Buffer.from(left);
+    const b = Buffer.from(right);
+    return a.length === b.length && timingSafeEqual(a, b);
+};
+function parseToken(token) {
+    const split = token.indexOf('.');
+    if (split < 1)
+        return undefined;
+    const id = token.slice(0, split);
+    const secret = token.slice(split + 1);
+    if (!/^[A-Za-z0-9_-]{16,64}$/.test(id) || !/^[A-Za-z0-9_-]{32,128}$/.test(secret))
+        return undefined;
+    return { id, secret };
+}
+/** Persistent trusted-device registry. Raw device secrets never enter this store. */
+export class TrustedDeviceStore {
+    now;
+    ttlMs;
+    maxDevices;
+    dir;
+    path;
+    devices;
+    constructor(dir = join(stateRoot(), 'web'), now = Date.now, ttlMs = DEFAULT_TTL_MS, maxDevices = DEFAULT_MAX_DEVICES) {
+        this.now = now;
+        this.ttlMs = ttlMs;
+        this.maxDevices = maxDevices;
+        this.dir = dir;
+        this.path = join(dir, 'trusted-devices.json');
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+        chmodSync(dir, 0o700);
+        this.devices = this.read();
+        this.prune(true);
+    }
+    issue() {
+        this.prune(false);
+        const now = this.now();
+        const id = opaque(16);
+        const secret = opaque(32);
+        const device = {
+            id, secretHash: digest(id, secret), pairedAt: now,
+            lastUsedAt: now, expiresAt: now + this.ttlMs,
+        };
+        this.devices.push(device);
+        this.devices.sort((a, b) => b.lastUsedAt - a.lastUsedAt);
+        this.devices = this.devices.slice(0, Math.max(1, Math.min(this.maxDevices, 128)));
+        this.write();
+        return { token: `${id}.${secret}`, id, expiresAt: device.expiresAt };
+    }
+    /** Validate and rotate on use. The old token is invalid as soon as this returns. */
+    rotate(token) {
+        const parsed = parseToken(token);
+        if (!parsed)
+            return undefined;
+        this.prune(false);
+        const index = this.devices.findIndex(device => device.id === parsed.id);
+        const existing = index >= 0 ? this.devices[index] : undefined;
+        if (!existing || !safeEqual(existing.secretHash, digest(parsed.id, parsed.secret)))
+            return undefined;
+        const now = this.now();
+        if (existing.expiresAt <= now) {
+            this.devices.splice(index, 1);
+            this.write();
+            return undefined;
+        }
+        const secret = opaque(32);
+        const replacement = {
+            ...existing, secretHash: digest(existing.id, secret),
+            lastUsedAt: now, expiresAt: now + this.ttlMs,
+        };
+        this.devices[index] = replacement;
+        this.write();
+        return { token: `${existing.id}.${secret}`, id: existing.id, expiresAt: replacement.expiresAt };
+    }
+    revoke(token) {
+        const parsed = parseToken(token);
+        if (!parsed)
+            return false;
+        const index = this.devices.findIndex(device => device.id === parsed.id
+            && safeEqual(device.secretHash, digest(parsed.id, parsed.secret)));
+        if (index < 0)
+            return false;
+        this.devices.splice(index, 1);
+        this.write();
+        return true;
+    }
+    /** Revoke an already-authenticated device without retaining its raw secret in a session. */
+    revokeId(id) {
+        const index = this.devices.findIndex(device => device.id === id);
+        if (index < 0)
+            return false;
+        this.devices.splice(index, 1);
+        this.write();
+        return true;
+    }
+    revokeAll() {
+        const count = this.devices.length;
+        this.devices = [];
+        this.write();
+        return count;
+    }
+    count() { this.prune(true); return this.devices.length; }
+    read() {
+        try {
+            const stat = lstatSync(this.path);
+            if (!stat.isFile() || stat.isSymbolicLink())
+                throw new FleetError('forbidden', 'trusted-device store is not a regular private file');
+            if (stat.size > MAX_STORE_BYTES)
+                throw new FleetError('forbidden', 'trusted-device store is oversized');
+            chmodSync(this.path, 0o600);
+            const parsed = JSON.parse(readFileSync(this.path, 'utf8'));
+            if (parsed.version !== VERSION || !Array.isArray(parsed.devices))
+                return [];
+            return parsed.devices.slice(0, 128).filter((device) => Boolean(device && typeof device.id === 'string' && /^[A-Za-z0-9_-]{16,64}$/.test(device.id)
+                && typeof device.secretHash === 'string' && /^[A-Za-z0-9_-]{32,128}$/.test(device.secretHash)
+                && Number.isFinite(device.pairedAt) && Number.isFinite(device.lastUsedAt)
+                && Number.isFinite(device.expiresAt)));
+        }
+        catch (error) {
+            if (error instanceof FleetError)
+                throw error;
+            if (error.code === 'ENOENT')
+                return [];
+            // Corrupt content fails closed. A later explicit pairing atomically
+            // replaces it; no credential is recovered or guessed.
+            return [];
+        }
+    }
+    prune(persist) {
+        const now = this.now();
+        const before = this.devices.length;
+        this.devices = this.devices.filter(device => device.expiresAt > now)
+            .sort((a, b) => b.lastUsedAt - a.lastUsedAt)
+            .slice(0, Math.max(1, Math.min(this.maxDevices, 128)));
+        if (persist && before !== this.devices.length)
+            this.write();
+    }
+    write() {
+        replaceFileAtomically(this.path, JSON.stringify({ version: VERSION, devices: this.devices }, null, 2) + '\n', 0o600);
+        chmodSync(this.path, 0o600);
+    }
+}
+export const TRUSTED_DEVICE_MAX_AGE_SECONDS = DEFAULT_TTL_MS / 1000;

package/dist/web/events.d.ts

@@ -0,0 +1,15 @@
+import type { WebSocket } from 'ws';
+export interface FleetEvent {
+    eventId: string;
+    at: string;
+    roleId?: string;
+    kind: string;
+    payload: unknown;
+}
+export declare class FleetEventBus {
+    private readonly events;
+    private readonly clients;
+    publish(kind: string, payload: unknown, roleId?: string): FleetEvent;
+    attach(socket: WebSocket, lastEventId?: string): () => void;
+    close(): void;
+}

package/dist/web/events.js

@@ -0,0 +1,34 @@
+import { randomUUID } from 'node:crypto';
+export class FleetEventBus {
+    events = [];
+    clients = new Set();
+    publish(kind, payload, roleId) {
+        const event = { eventId: randomUUID(), at: new Date().toISOString(), roleId, kind, payload };
+        this.events.push(event);
+        if (this.events.length > 5_000)
+            this.events.shift();
+        const frame = JSON.stringify(event);
+        for (const socket of this.clients) {
+            if (socket.readyState === socket.OPEN && socket.bufferedAmount < 1024 * 1024)
+                socket.send(frame);
+        }
+        return event;
+    }
+    attach(socket, lastEventId) {
+        this.clients.add(socket);
+        if (lastEventId) {
+            const index = this.events.findIndex(event => event.eventId === lastEventId);
+            if (index < 0)
+                socket.send(JSON.stringify({ kind: 'resync.required', at: new Date().toISOString() }));
+            else
+                for (const event of this.events.slice(index + 1))
+                    socket.send(JSON.stringify(event));
+        }
+        return () => this.clients.delete(socket);
+    }
+    close() {
+        for (const socket of this.clients)
+            socket.close(1001, 'server shutdown');
+        this.clients.clear();
+    }
+}

package/dist/web/lock.d.ts

@@ -0,0 +1,5 @@
+export interface WebServerLock {
+    path: string;
+    release(): void;
+}
+export declare function acquireWebServerLock(dir?: string): WebServerLock;

package/dist/web/lock.js

@@ -0,0 +1,69 @@
+import { closeSync, mkdirSync, openSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { stateRoot } from '../paths.js';
+import { FleetError } from '../application/errors.js';
+const processMarker = (pid) => {
+    try {
+        const stat = readFileSync(`/proc/${pid}/stat`, 'utf8');
+        const end = stat.lastIndexOf(')');
+        return stat.slice(end + 2).split(/\s+/)[19];
+    }
+    catch {
+        return undefined;
+    }
+};
+const alive = (pid) => {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+export function acquireWebServerLock(dir = join(stateRoot(), 'web')) {
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const path = join(dir, 'server.lock');
+    const ours = { pid: process.pid, marker: processMarker(process.pid), createdAt: new Date().toISOString() };
+    for (let attempt = 0; attempt < 2; attempt++) {
+        try {
+            const fd = openSync(path, 'wx', 0o600);
+            writeFileSync(fd, JSON.stringify(ours) + '\n');
+            closeSync(fd);
+            let released = false;
+            return {
+                path,
+                release() {
+                    if (released)
+                        return;
+                    released = true;
+                    try {
+                        const current = JSON.parse(readFileSync(path, 'utf8'));
+                        if (current.pid === ours.pid && current.marker === ours.marker)
+                            rmSync(path, { force: true });
+                    }
+                    catch { /* do not remove a lock we cannot prove is ours */ }
+                },
+            };
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+            try {
+                const current = JSON.parse(readFileSync(path, 'utf8'));
+                if (typeof current.pid === 'number' && alive(current.pid)) {
+                    const marker = processMarker(current.pid);
+                    if (!marker || !current.marker || marker === current.marker)
+                        throw new FleetError('conflict', `another ours-fleet web server is running (pid ${current.pid})`);
+                }
+                rmSync(path, { force: true });
+            }
+            catch (readError) {
+                if (readError instanceof FleetError)
+                    throw readError;
+                throw new FleetError('conflict', 'web server lock exists but cannot be verified safely');
+            }
+        }
+    }
+    throw new FleetError('conflict', 'could not acquire web server lock');
+}

package/dist/web/runtime.d.ts

@@ -0,0 +1,12 @@
+import { type WebServer } from './server.js';
+export interface StartWebOptions {
+    configPath?: string;
+    port?: number;
+    open?: boolean;
+    binPath: string;
+    log?(line: string): void;
+}
+export interface RunningWebConsole extends WebServer {
+    address: string;
+}
+export declare function startWebConsole(options: StartWebOptions): Promise<RunningWebConsole>;

package/dist/web/runtime.js

@@ -0,0 +1,214 @@
+import { spawn } from 'node:child_process';
+import { existsSync, realpathSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { loadConfig } from '../config.js';
+import { RoleRepository } from '../application/role-repository.js';
+import { FleetQueryService } from '../application/fleet-query-service.js';
+import { AcpRoleSessionAdapter, TmuxRoleSessionAdapter } from '../application/session-control.js';
+import { StructuredLogService } from '../application/log-service.js';
+import { RoleCommandService } from '../application/role-command-service.js';
+import { RoleCreationService } from '../application/role-creation-service.js';
+import { FleetError } from '../application/errors.js';
+import { controlRequest, controlSocketPath } from '../session/control.js';
+import { Tmux } from '../tmux.js';
+import { pickBackend } from '../supervisor/index.js';
+import { realExec } from '../exec.js';
+import { home, stateRoot } from '../paths.js';
+import { AuditSink } from './audit.js';
+import { FleetEventBus } from './events.js';
+import { buildWebServer } from './server.js';
+import { TerminalBridgeManager } from './terminal/bridge.js';
+import { acquireWebServerLock } from './lock.js';
+import { TrustedDeviceStore } from './device-store.js';
+import { WebAuth } from './auth.js';
+import { startWebControlServer } from './control.js';
+import { buildWatchdogFindings, cachedWatchdogFindingsProvider, WatchdogQueryService } from '../watchdog/query.js';
+import { latestReport } from '../watchdog/store.js';
+const CONFIG_CACHE_TTL_MS = 5_000;
+/**
+ * loadConfig re-parses YAML from disk on every call; the watchdog list/reports
+ * routes get polled by the console UI, so cache the resolved config for a
+ * short TTL rather than re-parsing per request. Runtime-only concern (not the
+ * scheduler's), so a plain Date.now() clock is fine.
+ */
+function cachedConfigProvider(configPath) {
+    let cached;
+    return () => {
+        const now = Date.now();
+        if (!cached || now - cached.at >= CONFIG_CACHE_TTL_MS)
+            cached = { at: now, cfg: loadConfig(configPath) };
+        return cached.cfg;
+    };
+}
+export async function startWebConsole(options) {
+    const requestedPort = options.port ?? 49_271;
+    if (!Number.isInteger(requestedPort) || requestedPort < 0 || requestedPort > 65_535)
+        throw new FleetError('invalid_request', 'port must be between 0 and 65535');
+    const lock = acquireWebServerLock();
+    const webDir = resolve(stateRoot(), 'web');
+    const auth = new WebAuth(`http://127.0.0.1:${requestedPort}`, `127.0.0.1:${requestedPort}`, Date.now, new TrustedDeviceStore(webDir));
+    const tmux = new Tmux();
+    const backend = pickBackend();
+    const repository = new RoleRepository({
+        configPath: options.configPath,
+        probeBackend: async (name) => {
+            let acp = false;
+            const permanent = resolve(home(), '.ours-fleet', 'agents', name);
+            const temporary = resolve(home(), '.ours-fleet', 'tmp', name);
+            for (const dir of [permanent, temporary]) {
+                if (!existsSync(controlSocketPath(dir)))
+                    continue;
+                try {
+                    acp = (await controlRequest(dir, { command: 'snapshot' }, 500)).ok;
+                }
+                catch { /* stale socket is evidence, not reachability */ }
+            }
+            return { acp, tmux: await tmux.has(name).catch(() => false) };
+        },
+    });
+    const events = new FleetEventBus();
+    const audit = new AuditSink();
+    const terminals = new TerminalBridgeManager({ repository, audit, tmux });
+    const terminalAvailable = await terminals.available();
+    const watchdogConfigProvider = cachedConfigProvider(options.configPath);
+    const log = options.log ?? (() => { });
+    let loggedWatchdogFindingsError = false;
+    // Needs-attention integration (Task 19): worst per-role watchdog finding,
+    // rebuilt from stored reports. A store hiccup (corrupt state, unreadable
+    // report) must never break the fleet list, so it degrades to an empty map
+    // and logs once rather than repeating on every poll. status() calls this
+    // once per role, so list()'s O(roles) sweep would otherwise cost
+    // O(roles x watchdogs) disk reads every 1-3s of console polling —
+    // cachedWatchdogFindingsProvider memoizes the whole build behind the same
+    // TTL as the config cache above.
+    const watchdogFindings = cachedWatchdogFindingsProvider(() => {
+        try {
+            return buildWatchdogFindings(watchdogConfigProvider(), latestReport);
+        }
+        catch (error) {
+            if (!loggedWatchdogFindingsError) {
+                loggedWatchdogFindingsError = true;
+                log(`watchdog findings unavailable: ${error.message}`);
+            }
+            return new Map();
+        }
+    }, CONFIG_CACHE_TTL_MS);
+    const query = new FleetQueryService({
+        repository, supervisor: backend, tmux,
+        capabilityContext: { terminalPtyAvailable: terminalAvailable },
+        watchdogFindings,
+    });
+    const ops = { backend, binPath: options.binPath, log };
+    const creation = new RoleCreationService({
+        configPath: options.configPath, ops, binPath: options.binPath,
+        allowedCwdRoots: [realpathSync(home()), realpathSync(process.cwd())],
+        probeReady: async (name) => {
+            const detail = await query.detail(name).catch(() => undefined);
+            return detail?.status.overall === 'ready' || detail?.status.overall === 'busy'
+                ? 'ready' : detail?.status.overall === 'attention' ? 'attention' : 'unknown';
+        },
+        onProgress: action => {
+            events.publish('creation.changed', action, action.roleId);
+            void audit.record({
+                roleId: action.roleId, action: `creation.${action.state}`,
+                result: action.error?.code ?? action.state,
+            });
+        },
+    });
+    const commands = new RoleCommandService({
+        repository, ops, configPath: options.configPath,
+        status: async (roleId) => (await query.detail(roleId)).status,
+        onProgress: receipt => {
+            events.publish('action.changed', receipt, receipt.roleId);
+            void audit.record({
+                roleId: receipt.roleId, action: `lifecycle.${receipt.action}`,
+                result: receipt.state, errorCode: receipt.error?.code,
+            });
+        },
+    });
+    const logs = new StructuredLogService(backend, realExec);
+    const watchdogs = new WatchdogQueryService(watchdogConfigProvider);
+    let server;
+    try {
+        server = await buildWebServer({
+            query, repository, logs, commands, creation, audit, events, watchdogs,
+            terminalUpgrade: terminalAvailable
+                ? async (socket, _request, roleId, _ticket, hello) => terminals.connect(socket, roleId, hello)
+                : undefined,
+            async session(roleId) {
+                const role = await repository.get(roleId);
+                if (!role)
+                    throw new FleetError('role_not_found', `no such role '${roleId}'`);
+                if (role.configuredBackend === 'acp') {
+                    const dir = repository.stateDir(role);
+                    if (!dir)
+                        throw new FleetError('control_unavailable', 'role state directory is unavailable');
+                    return new AcpRoleSessionAdapter(dir);
+                }
+                if (role.configuredBackend === 'tmux' || role.detectedBackend === 'tmux')
+                    return new TmuxRoleSessionAdapter(roleId, tmux);
+                throw new FleetError('capability_unavailable', 'role session backend is unavailable');
+            },
+        }, { origin: `http://127.0.0.1:${requestedPort}`, host: `127.0.0.1:${requestedPort}` }, { auth });
+    }
+    catch (error) {
+        lock.release();
+        throw error;
+    }
+    let address;
+    try {
+        address = await server.app.listen({ host: '127.0.0.1', port: requestedPort });
+    }
+    catch (error) {
+        await server.close();
+        lock.release();
+        throw error;
+    }
+    const actual = new URL(address);
+    if (actual.hostname !== '127.0.0.1') {
+        await server.close();
+        lock.release();
+        throw new FleetError('forbidden', 'web console refused a non-loopback bind');
+    }
+    const host = `127.0.0.1:${actual.port}`;
+    server.auth.setBoundary(`http://${host}`, host);
+    let control;
+    try {
+        control = await startWebControlServer({
+            dir: webDir,
+            onOpen() {
+                const url = `http://${host}/#bootstrap=${server.auth.mintBootstrap()}`;
+                openBrowser(url);
+            },
+            onRevokeAll() { server.auth.revokeAllTrustedDevices(); },
+        });
+    }
+    catch (error) {
+        await server.close();
+        lock.release();
+        throw error;
+    }
+    if (options.open !== false)
+        openBrowser(`http://${host}/#bootstrap=${server.auth.bootstrapSecret}`);
+    return {
+        ...server, address: `http://${host}`,
+        async close() {
+            try {
+                await control.close();
+                await terminals.close();
+                await server.close();
+            }
+            finally {
+                lock.release();
+            }
+        },
+    };
+}
+function openBrowser(url) {
+    const command = process.platform === 'darwin' ? 'open'
+        : process.platform === 'win32' ? 'cmd' : 'xdg-open';
+    const args = process.platform === 'win32' ? ['/c', 'start', '', url] : [url];
+    const child = spawn(command, args, { stdio: 'ignore', detached: true, shell: false });
+    child.on('error', () => undefined);
+    child.unref();
+}

package/dist/web/server.d.ts

@@ -0,0 +1,37 @@
+import { type FastifyInstance, type FastifyRequest } from 'fastify';
+import type { WebSocket } from 'ws';
+import type { FleetQueryService } from '../application/fleet-query-service.js';
+import type { RoleRepository } from '../application/role-repository.js';
+import type { RoleSessionControl } from '../application/session-control.js';
+import type { StructuredLogService } from '../application/log-service.js';
+import type { RoleCommandService } from '../application/role-command-service.js';
+import type { RoleCreationService } from '../application/role-creation-service.js';
+import type { WatchdogQueryService } from '../watchdog/query.js';
+import { AuditSink } from './audit.js';
+import { WebAuth } from './auth.js';
+import { FleetEventBus } from './events.js';
+export interface WebServices {
+    query: FleetQueryService;
+    repository: RoleRepository;
+    session(roleId: string): Promise<RoleSessionControl>;
+    logs: StructuredLogService;
+    commands: RoleCommandService;
+    creation: RoleCreationService;
+    audit?: AuditSink;
+    events?: FleetEventBus;
+    watchdogs?: WatchdogQueryService;
+    terminalUpgrade?: (socket: WebSocket, request: FastifyRequest, roleId: string, ticket: string, hello: Record<string, unknown>) => Promise<void>;
+}
+export interface WebServer {
+    app: FastifyInstance;
+    auth: WebAuth;
+    audit: AuditSink;
+    events: FleetEventBus;
+    close(): Promise<void>;
+}
+export declare function buildWebServer(services: WebServices, boundary: {
+    origin: string;
+    host: string;
+}, options?: {
+    auth?: WebAuth;
+}): Promise<WebServer>;