@ours.network/fleet 0.10.2 → 0.10.4

package/dist/web/auth.js

@@ -0,0 +1,186 @@
+import { randomBytes, timingSafeEqual } from 'node:crypto';
+import { FleetError } from '../application/errors.js';
+import { TrustedDeviceStore } from './device-store.js';
+const token = (bytes = 32) => randomBytes(bytes).toString('base64url');
+const same = (a, b) => {
+    const left = Buffer.from(a);
+    const right = Buffer.from(b);
+    return left.length === right.length && timingSafeEqual(left, right);
+};
+export class WebAuth {
+    _origin;
+    _host;
+    now;
+    devices;
+    _bootstrapSecret = token(32);
+    bootstrapExpiresAt = Date.now() + 5 * 60_000;
+    bootstrapUsed = false;
+    sessions = new Map();
+    sessionDevices = new Map();
+    tickets = new Map();
+    rates = new Map();
+    sockets = new Map();
+    constructor(_origin, _host, now = Date.now, devices = new TrustedDeviceStore()) {
+        this._origin = _origin;
+        this._host = _host;
+        this.now = now;
+        this.devices = devices;
+    }
+    get bootstrapSecret() { return this._bootstrapSecret; }
+    get origin() { return this._origin; }
+    get host() { return this._host; }
+    setBoundary(origin, host) {
+        this._origin = origin;
+        this._host = host;
+    }
+    /** Mint a replacement for an operator-triggered reauthentication ceremony. */
+    mintBootstrap() {
+        this._bootstrapSecret = token(32);
+        this.bootstrapExpiresAt = this.now() + 5 * 60_000;
+        this.bootstrapUsed = false;
+        return this._bootstrapSecret;
+    }
+    validateBoundary(request, requireOrigin) {
+        const host = request.headers.host;
+        if (host !== this.host)
+            throw new FleetError('forbidden', 'invalid Host header');
+        if (requireOrigin && request.headers.origin !== this.origin)
+            throw new FleetError('forbidden', 'invalid Origin header');
+        const fetchSite = request.headers['sec-fetch-site'];
+        if (fetchSite && !['same-origin', 'none'].includes(String(fetchSite)))
+            throw new FleetError('forbidden', 'cross-site request rejected');
+    }
+    exchange(request) {
+        this.validateBoundary(request, true);
+        this.consumeRate('bootstrap', 10, 60_000);
+        const authorization = request.headers.authorization ?? '';
+        const supplied = authorization.startsWith('Bootstrap ') ? authorization.slice(10) : '';
+        if (this.bootstrapUsed || this.now() > this.bootstrapExpiresAt || !same(this._bootstrapSecret, supplied))
+            throw new FleetError('unauthorized', 'bootstrap credential is invalid or expired');
+        this.bootstrapUsed = true;
+        const device = this.devices.issue();
+        return { session: this.createSession(device.id), device };
+    }
+    resume(request) {
+        this.validateBoundary(request, true);
+        this.consumeRate('device-resume', 30, 60_000);
+        const current = parseCookies(request.headers.cookie ?? '').ofs_device;
+        const device = current ? this.devices.rotate(current) : undefined;
+        if (!device)
+            throw new FleetError('unauthorized', 'trusted device is missing, expired, or revoked');
+        return { session: this.createSession(device.id), device };
+    }
+    authenticate(request, mutation = false) {
+        this.validateBoundary(request, mutation);
+        const id = parseCookies(request.headers.cookie ?? '').ofs_session;
+        const session = id ? this.sessions.get(id) : undefined;
+        const now = this.now();
+        if (!session || now > session.absoluteExpiresAt || now - session.lastSeenAt > 30 * 60_000) {
+            if (id)
+                this.removeSession(id);
+            throw new FleetError('unauthorized', 'browser session is missing or expired');
+        }
+        if (mutation) {
+            const supplied = String(request.headers['x-csrf-token'] ?? '');
+            if (!same(session.csrf, supplied))
+                throw new FleetError('forbidden', 'invalid CSRF token');
+            this.consumeRate(`mutation:${session.id}`, 120, 60_000);
+        }
+        session.lastSeenAt = now;
+        return session;
+    }
+    logout(request) {
+        const session = this.authenticate(request, true);
+        const deviceId = this.sessionDevices.get(session.id);
+        if (deviceId)
+            this.devices.revokeId(deviceId);
+        this.removeSession(session.id);
+    }
+    mintTicket(request, purpose, roleId) {
+        const session = this.authenticate(request, true);
+        const value = token();
+        const ticket = {
+            value, sessionId: session.id, purpose, roleId,
+            expiresAt: this.now() + 30_000,
+        };
+        this.tickets.set(value, ticket);
+        return { ticket: value, expiresAt: new Date(ticket.expiresAt).toISOString() };
+    }
+    consumeTicket(request, value, purpose, roleId) {
+        this.validateBoundary(request, true);
+        const ticket = this.tickets.get(value);
+        this.tickets.delete(value);
+        if (!ticket || ticket.expiresAt < this.now() || ticket.purpose !== purpose
+            || ticket.roleId !== roleId)
+            throw new FleetError('unauthorized', 'WebSocket ticket is invalid, expired, or already used');
+        const session = this.sessions.get(ticket.sessionId);
+        if (!session)
+            throw new FleetError('unauthorized', 'browser session expired');
+        return session;
+    }
+    bindSocket(sessionId, socket) {
+        let sockets = this.sockets.get(sessionId);
+        if (!sockets) {
+            sockets = new Set();
+            this.sockets.set(sessionId, sockets);
+        }
+        sockets.add(socket);
+        socket.once('close', () => sockets?.delete(socket));
+    }
+    clearSessions() {
+        for (const sockets of this.sockets.values())
+            for (const socket of sockets)
+                socket.close(4401, 'authentication revoked');
+        this.sockets.clear();
+        this.sessions.clear();
+        this.sessionDevices.clear();
+        this.tickets.clear();
+    }
+    revokeAllTrustedDevices() {
+        const count = this.devices.revokeAll();
+        this.clearSessions();
+        return count;
+    }
+    shutdown() { this.clearSessions(); }
+    createSession(deviceId) {
+        const now = this.now();
+        const session = {
+            id: token(), csrf: token(), createdAt: now, lastSeenAt: now,
+            absoluteExpiresAt: now + 8 * 60 * 60_000,
+        };
+        this.sessions.set(session.id, session);
+        this.sessionDevices.set(session.id, deviceId);
+        return session;
+    }
+    removeSession(id) {
+        this.sessions.delete(id);
+        this.sessionDevices.delete(id);
+        for (const [ticket, value] of this.tickets)
+            if (value.sessionId === id)
+                this.tickets.delete(ticket);
+        for (const socket of this.sockets.get(id) ?? [])
+            socket.close(4401, 'authentication revoked');
+        this.sockets.delete(id);
+    }
+    consumeRate(key, limit, windowMs) {
+        const now = this.now();
+        let rate = this.rates.get(key);
+        if (!rate || rate.resetAt <= now) {
+            rate = { count: 0, resetAt: now + windowMs };
+            this.rates.set(key, rate);
+        }
+        rate.count++;
+        if (rate.count > limit)
+            throw new FleetError('rate_limited', 'request rate limit exceeded', {
+                retryable: true, details: { retryAfterMs: rate.resetAt - now },
+            });
+    }
+}
+export function parseCookies(cookie) {
+    return Object.fromEntries(cookie.split(';').flatMap(part => {
+        const index = part.indexOf('=');
+        if (index < 0)
+            return [];
+        return [[part.slice(0, index).trim(), decodeURIComponent(part.slice(index + 1).trim())]];
+    }));
+}

package/dist/web/control.d.ts

@@ -0,0 +1,14 @@
+export type WebControlCommand = 'open' | 'revoke-all';
+export declare const webControlPath: (dir?: string) => string;
+export interface WebControlServer {
+    path: string;
+    close(): Promise<void>;
+}
+export declare function startWebControlServer(options: {
+    dir?: string;
+    onOpen(): void | Promise<void>;
+    onRevokeAll(): void | Promise<void>;
+    now?: () => number;
+    rateLimit?: number;
+}): Promise<WebControlServer>;
+export declare function requestWebControl(command: WebControlCommand, path?: string, timeoutMs?: number): Promise<void>;

package/dist/web/control.js

@@ -0,0 +1,110 @@
+import { chmodSync, mkdirSync, rmSync } from 'node:fs';
+import { createConnection, createServer } from 'node:net';
+import { join } from 'node:path';
+import { FleetError, safeLine } from '../application/errors.js';
+import { stateRoot } from '../paths.js';
+export const webControlPath = (dir = join(stateRoot(), 'web')) => join(dir, 'control.sock');
+export async function startWebControlServer(options) {
+    const dir = options.dir ?? join(stateRoot(), 'web');
+    const path = webControlPath(dir);
+    const now = options.now ?? Date.now;
+    const rateLimit = options.rateLimit ?? 10;
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    chmodSync(dir, 0o700);
+    rmSync(path, { force: true });
+    let windowStart = now();
+    let used = 0;
+    const server = createServer(socket => {
+        let body = '';
+        socket.setTimeout(5_000, () => socket.destroy());
+        socket.on('data', chunk => {
+            body += chunk.toString('utf8');
+            if (body.length > 4_096)
+                return socket.destroy();
+            if (!body.includes('\n'))
+                return;
+            socket.pause();
+            void (async () => {
+                try {
+                    if (now() - windowStart >= 60_000) {
+                        windowStart = now();
+                        used = 0;
+                    }
+                    used++;
+                    if (used > rateLimit)
+                        throw new FleetError('rate_limited', 'local web control rate limit exceeded');
+                    const parsed = JSON.parse(body.slice(0, body.indexOf('\n')));
+                    if (parsed.command === 'open')
+                        await options.onOpen();
+                    else if (parsed.command === 'revoke-all')
+                        await options.onRevokeAll();
+                    else
+                        throw new FleetError('invalid_request', 'unknown local web control command');
+                    socket.end(JSON.stringify({ ok: true }) + '\n');
+                }
+                catch (error) {
+                    const code = error instanceof FleetError ? error.code : 'internal';
+                    const message = safeLine(error instanceof Error ? error.message : String(error));
+                    socket.end(JSON.stringify({ ok: false, error: { code, message } }) + '\n');
+                }
+            })();
+        });
+    });
+    await listen(server, path);
+    chmodSync(path, 0o600);
+    let closed = false;
+    return {
+        path,
+        async close() {
+            if (closed)
+                return;
+            closed = true;
+            await new Promise(resolve => server.close(() => resolve()));
+            rmSync(path, { force: true });
+        },
+    };
+}
+export async function requestWebControl(command, path = webControlPath(), timeoutMs = 5_000) {
+    await new Promise((resolve, reject) => {
+        const socket = createConnection(path);
+        let response = '';
+        let settled = false;
+        const timer = setTimeout(() => {
+            socket.destroy();
+            reject(new FleetError('timeout', 'local web control request timed out'));
+        }, timeoutMs);
+        const finish = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            if (error)
+                reject(error);
+            else
+                resolve();
+        };
+        socket.once('connect', () => socket.write(JSON.stringify({ command }) + '\n'));
+        socket.on('data', chunk => { response += chunk.toString('utf8'); });
+        socket.once('error', error => finish(new FleetError('control_unavailable', `running web console control is unavailable: ${safeLine(error.message)}`)));
+        socket.once('end', () => {
+            try {
+                const parsed = JSON.parse(response);
+                if (!parsed.ok)
+                    throw new FleetError(parsed.error?.code === 'rate_limited' ? 'rate_limited' : 'rejected', parsed.error?.message ?? 'local web control request was rejected');
+                finish();
+            }
+            catch (error) {
+                finish(error);
+            }
+        });
+    });
+}
+function listen(server, path) {
+    return new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(path, () => {
+            server.off('error', reject);
+            resolve();
+        });
+    });
+}

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>;