@ours.network/fleet 0.10.2 → 0.10.4

package/dist/web/runtime.js

@@ -0,0 +1,170 @@
+import { spawn } from 'node:child_process';
+import { existsSync, realpathSync } from 'node:fs';
+import { resolve } from 'node:path';
+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';
+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 query = new FleetQueryService({
+        repository, supervisor: backend, tmux,
+        capabilityContext: { terminalPtyAvailable: terminalAvailable },
+    });
+    const ops = { backend, binPath: options.binPath, log: options.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);
+    let server;
+    try {
+        server = await buildWebServer({
+            query, repository, logs, commands, creation, audit, events,
+            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,35 @@
+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 { 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;
+    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>;

package/dist/web/server.js

@@ -0,0 +1,261 @@
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import Fastify from 'fastify';
+import fastifyStatic from '@fastify/static';
+import fastifyWebsocket from '@fastify/websocket';
+import { createHmac, randomBytes } from 'node:crypto';
+import { FleetError, normalizeError } from '../application/errors.js';
+import { VERSION } from '../version.js';
+import { AuditSink } from './audit.js';
+import { WebAuth } from './auth.js';
+import { FleetEventBus } from './events.js';
+const statusFor = (code) => ({
+    role_not_found: 404, unauthorized: 401, forbidden: 403, conflict: 409,
+    idempotency_conflict: 409, stale_state: 409, rate_limited: 429,
+    invalid_request: 400, capability_unavailable: 409, prerequisite_unavailable: 503,
+}[code] ?? 500);
+export async function buildWebServer(services, boundary, options = {}) {
+    const app = Fastify({
+        trustProxy: false, bodyLimit: 64 * 1024, logger: false,
+        requestIdHeader: false, genReqId: () => cryptoRandomId(),
+    });
+    const auth = options.auth ?? new WebAuth(boundary.origin, boundary.host);
+    const audit = services.audit ?? new AuditSink();
+    const events = services.events ?? new FleetEventBus();
+    const digestKey = randomBytes(32);
+    await app.register(fastifyWebsocket, {
+        options: { maxPayload: 64 * 1024, perMessageDeflate: false },
+    });
+    app.addHook('onRequest', async (request, reply) => {
+        reply.header('X-Content-Type-Options', 'nosniff');
+        reply.header('Referrer-Policy', 'no-referrer');
+        reply.header('Permissions-Policy', 'camera=(), microphone=(), geolocation=(), payment=()');
+        reply.header('X-Frame-Options', 'DENY');
+        reply.header('Content-Security-Policy', `default-src 'self'; script-src 'self'; style-src 'self'; img-src 'self' data:; ` +
+            `connect-src 'self' ws://${auth.host}; object-src 'none'; base-uri 'none'; ` +
+            `frame-ancestors 'none'; form-action 'self'; manifest-src 'self'; worker-src 'self'`);
+        if (request.url.startsWith('/api/'))
+            reply.header('Cache-Control', 'no-store');
+        if (request.headers.host !== auth.host)
+            throw new FleetError('forbidden', 'invalid Host header');
+    });
+    app.setErrorHandler(async (error, request, reply) => {
+        const fleetError = normalizeError(error, request.id);
+        await audit.record({
+            requestId: request.id, action: `${request.method} ${request.routeOptions.url ?? request.url}`,
+            result: 'rejected', errorCode: fleetError.code,
+        });
+        reply.code(statusFor(fleetError.code)).send({ error: fleetError.toJSON() });
+    });
+    app.post('/api/v1/auth/exchange', async (request, reply) => {
+        const { session, device } = auth.exchange(request);
+        setAuthCookies(reply, session.id, device.token);
+        await audit.record({ requestId: request.id, browser: session.id, action: 'auth.exchange', result: 'succeeded' });
+        return { csrfToken: session.csrf, expiresAt: new Date(session.absoluteExpiresAt).toISOString() };
+    });
+    app.post('/api/v1/auth/resume', async (request, reply) => {
+        const { session, device } = auth.resume(request);
+        setAuthCookies(reply, session.id, device.token);
+        await audit.record({ requestId: request.id, browser: session.id, action: 'auth.resume', result: 'succeeded' });
+        return { csrfToken: session.csrf, expiresAt: new Date(session.absoluteExpiresAt).toISOString() };
+    });
+    app.post('/api/v1/auth/logout', async (request, reply) => {
+        auth.logout(request);
+        clearAuthCookies(reply);
+        await audit.record({ requestId: request.id, action: 'auth.logout', result: 'succeeded' });
+        return { ok: true };
+    });
+    app.get('/api/v1/auth/session', async (request) => {
+        const session = auth.authenticate(request);
+        return { csrfToken: session.csrf, expiresAt: new Date(session.absoluteExpiresAt).toISOString() };
+    });
+    app.get('/api/v1/meta', async (request) => {
+        auth.authenticate(request);
+        return {
+            version: VERSION, api: { major: 1, minor: 0 },
+            websocketProtocols: ['ours-fleet-events.v1', 'ours-fleet-terminal.v1'],
+            auditDegraded: audit.degraded,
+        };
+    });
+    app.get('/api/v1/creation-capabilities', async (request) => {
+        auth.authenticate(request);
+        return services.creation.capabilities();
+    });
+    app.post('/api/v1/roles/preview', async (request) => {
+        auth.authenticate(request, true);
+        return services.creation.preview(request.body);
+    });
+    app.post('/api/v1/roles', async (request, reply) => {
+        const session = auth.authenticate(request, true);
+        const body = request.body;
+        const idempotencyKey = String(request.headers['idempotency-key'] ?? '');
+        if (!body?.request || !body.previewHash)
+            throw new FleetError('invalid_request', 'request and previewHash are required');
+        const action = await services.creation.create(body.request, body.previewHash, idempotencyKey, session.id);
+        events.publish('creation.changed', action, action.roleId);
+        reply.header('Location', `/api/v1/creation-actions/${encodeURIComponent(action.actionId)}`);
+        reply.code(202);
+        return action;
+    });
+    app.get('/api/v1/roles', async (request) => {
+        auth.authenticate(request);
+        return { roles: await services.query.list() };
+    });
+    app.get('/api/v1/roles/:id', async (request) => {
+        auth.authenticate(request);
+        return services.query.detail(request.params.id);
+    });
+    app.get('/api/v1/roles/:id/output', async (request) => {
+        auth.authenticate(request);
+        const control = await services.session(request.params.id);
+        return control.recentOutput({
+            since: request.query.since ? Number(request.query.since) : undefined,
+            limit: request.query.limit ? Number(request.query.limit) : undefined,
+        });
+    });
+    app.post('/api/v1/roles/:id/input', async (request) => {
+        const session = auth.authenticate(request, true);
+        const text = String(request.body?.text ?? '');
+        const control = await services.session(request.params.id);
+        const receipt = await control.sendText(text);
+        await audit.record({
+            requestId: request.id, browser: session.id, roleId: request.params.id,
+            action: 'session.send_text', result: receipt.accepted ? 'accepted' : 'failed',
+            bytes: Buffer.byteLength(text),
+            digest: createHmac('sha256', digestKey).update(text).digest('hex').slice(0, 24),
+        });
+        return receipt;
+    });
+    app.post('/api/v1/roles/:id/interrupt', async (request) => {
+        auth.authenticate(request, true);
+        const control = await services.session(request.params.id);
+        if (!control.interrupt)
+            throw new FleetError('capability_unavailable', 'interrupt is unavailable');
+        return control.interrupt();
+    });
+    app.post('/api/v1/roles/:id/permissions/:permissionId', async (request) => {
+        auth.authenticate(request, true);
+        const control = await services.session(request.params.id);
+        if (!control.respondPermission)
+            throw new FleetError('capability_unavailable', 'permission response is unavailable');
+        return control.respondPermission({
+            permissionId: request.params.permissionId,
+            optionId: String(request.body?.optionId ?? ''),
+        });
+    });
+    app.get('/api/v1/roles/:id/logs', async (request) => {
+        auth.authenticate(request);
+        return services.logs.source(request.params.id)
+            .tail(Number(request.query.limit ?? 200), request.query.cursor);
+    });
+    app.post('/api/v1/roles/:id/actions', async (request, reply) => {
+        auth.authenticate(request, true);
+        const body = request.body;
+        if (!body.action || !['start', 'stop', 'restart_resume', 'restart_fresh'].includes(body.action))
+            throw new FleetError('invalid_request', 'invalid lifecycle action');
+        const receipt = await services.commands.execute({
+            roleId: request.params.id, action: body.action,
+            actionId: body.actionId, confirmation: body.confirmation,
+        });
+        events.publish('action.changed', receipt, request.params.id);
+        reply.code(202);
+        return receipt;
+    });
+    app.get('/api/v1/actions/:actionId', async (request) => {
+        auth.authenticate(request);
+        const receipt = services.commands.get(request.params.actionId);
+        if (!receipt)
+            throw new FleetError('role_not_found', 'action not found');
+        return receipt;
+    });
+    app.get('/api/v1/creation-actions/:actionId', async (request) => {
+        auth.authenticate(request);
+        const action = services.creation.get(request.params.actionId);
+        if (!action)
+            throw new FleetError('role_not_found', 'creation action not found');
+        return action;
+    });
+    app.post('/api/v1/ws-tickets', async (request) => {
+        const body = request.body;
+        if (!body?.purpose || !['events', 'terminal'].includes(body.purpose))
+            throw new FleetError('invalid_request', 'ticket purpose is required');
+        return auth.mintTicket(request, body.purpose, body.roleId);
+    });
+    app.get('/api/v1/audit', async (request) => {
+        auth.authenticate(request);
+        return { records: audit.list() };
+    });
+    app.get('/api/v1/events', { websocket: true }, (socket, request) => {
+        requireSubprotocol(request, 'ours-fleet-events.v1');
+        authorizeSocket(socket, request, async (hello) => {
+            const session = auth.consumeTicket(request, String(hello.ticket ?? ''), 'events');
+            auth.bindSocket(session.id, socket);
+            const detach = events.attach(socket, typeof hello.lastEventId === 'string' ? hello.lastEventId : undefined);
+            socket.on('close', detach);
+            socket.send(JSON.stringify({ kind: 'ready', at: new Date().toISOString() }));
+        });
+    });
+    app.get('/api/v1/roles/:id/terminal', { websocket: true }, (socket, request) => {
+        requireSubprotocol(request, 'ours-fleet-terminal.v1');
+        authorizeSocket(socket, request, async (hello) => {
+            const ticket = String(hello.ticket ?? '');
+            const session = auth.consumeTicket(request, ticket, 'terminal', request.params.id);
+            auth.bindSocket(session.id, socket);
+            if (!services.terminalUpgrade)
+                throw new FleetError('capability_unavailable', 'terminal PTY support is unavailable');
+            await services.terminalUpgrade(socket, request, request.params.id, ticket, hello);
+        });
+    });
+    const staticRoot = join(dirname(fileURLToPath(import.meta.url)), '..', 'web-app');
+    if (existsSync(staticRoot)) {
+        await app.register(fastifyStatic, { root: staticRoot, prefix: '/' });
+        app.setNotFoundHandler((request, reply) => {
+            if (request.url.startsWith('/api/'))
+                return reply.code(404).send({ error: 'not found' });
+            return reply.sendFile('index.html');
+        });
+    }
+    return {
+        app, auth, audit, events,
+        async close() {
+            auth.shutdown();
+            events.close();
+            await app.close();
+        },
+    };
+}
+function setAuthCookies(reply, session, device) {
+    reply.header('Set-Cookie', [
+        `ofs_session=${encodeURIComponent(session)}; HttpOnly; SameSite=Strict; Path=/api; Max-Age=28800`,
+        `ofs_device=${encodeURIComponent(device)}; HttpOnly; SameSite=Strict; Path=/api; Max-Age=2592000`,
+    ]);
+}
+function clearAuthCookies(reply) {
+    reply.header('Set-Cookie', [
+        'ofs_session=; HttpOnly; SameSite=Strict; Path=/api; Max-Age=0',
+        'ofs_device=; HttpOnly; SameSite=Strict; Path=/api; Max-Age=0',
+    ]);
+}
+function cryptoRandomId() { return randomBytes(12).toString('hex'); }
+function requireSubprotocol(request, expected) {
+    const protocols = String(request.headers['sec-websocket-protocol'] ?? '')
+        .split(',').map(value => value.trim());
+    if (!protocols.includes(expected))
+        throw new FleetError('forbidden', `required subprotocol ${expected}`);
+}
+function authorizeSocket(socket, request, authorize) {
+    const timer = setTimeout(() => socket.close(4401, 'authorization timeout'), 5_000);
+    socket.once('message', data => {
+        clearTimeout(timer);
+        void (async () => {
+            try {
+                const hello = JSON.parse(data.toString());
+                await authorize(hello);
+            }
+            catch (error) {
+                socket.close(4403, normalizeError(error).message.slice(0, 120));
+            }
+        })();
+    });
+}

package/dist/web/service.d.ts

@@ -0,0 +1,42 @@
+import { type Exec } from '../exec.js';
+export declare const WEB_SYSTEMD_UNIT = "ours-fleet-web.service";
+export declare const WEB_LAUNCHD_LABEL = "network.ours.fleet.web";
+interface ServiceMetadata {
+    version: 2;
+    platform: 'linux' | 'darwin';
+    runtime: string;
+    script: string;
+    port: number;
+    configuration?: string;
+}
+export interface WebServiceOptions {
+    platform?: NodeJS.Platform;
+    exec?: Exec;
+    homeDir?: string;
+    stateDir?: string;
+    uid?: number;
+    runtimeExecutable?: string;
+}
+export declare class WebServiceManager {
+    private readonly platform;
+    private readonly exec;
+    private readonly homeDir;
+    private readonly stateDir;
+    private readonly uid;
+    private readonly runtimeExecutable;
+    constructor(options?: WebServiceOptions);
+    get metadataPath(): string;
+    get definitionPath(): string;
+    install(script: string, port?: number, configuration?: string): Promise<string[]>;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    restart(): Promise<void>;
+    status(): Promise<string>;
+    uninstall(): Promise<string>;
+    readMetadata(): ServiceMetadata | undefined;
+    private requireInstalled;
+    private must;
+}
+export declare function systemdUnit(runtime: string, script: string, port: number, configuration?: string): string;
+export declare function launchdPlist(runtime: string, script: string, port: number, configuration?: string): string;
+export {};