@ours.network/fleet 1.2.0-nightly.6 → 1.2.0-nightly.60

package/dist/web/agent-attachments.js

@@ -0,0 +1,162 @@
+import { createHash } from 'node:crypto';
+import { constants, closeSync, existsSync, fstatSync, lstatSync, mkdirSync, openSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { FleetError } from '../application/errors.js';
+export const MAX_ATTACHMENT_BYTES = 20 * 1024 * 1024;
+export const MAX_ATTACHMENT_BODY = Math.ceil(MAX_ATTACHMENT_BYTES / 3) * 4 + 4096;
+function fail(message) { throw new FleetError('invalid_request', message); }
+const digest = (data) => createHash('sha256').update(data).digest('hex');
+function directory(path, create = false, privateStorage = true) {
+    if (create && !existsSync(path))
+        mkdirSync(path, { mode: 0o700 });
+    const stat = lstatSync(path);
+    if (!stat.isDirectory() || stat.isSymbolicLink() || stat.uid !== process.getuid?.() || (stat.mode & (privateStorage ? 0o022 : 0o002)))
+        fail('Attachment directory is not a private owned directory');
+}
+function read(path, max) {
+    const fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        const stat = fstatSync(fd);
+        if (!stat.isFile() || stat.nlink !== 1 || stat.uid !== process.getuid?.() || stat.size > max)
+            fail('Attachment is not a bounded owned regular file');
+        return readFileSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function immutable(path, bytes) {
+    try {
+        writeFileSync(path, bytes, { flag: 'wx', mode: 0o400 });
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST')
+            throw error;
+        if (!read(path, bytes.length).equals(bytes))
+            fail('Attachment content changed');
+    }
+}
+function filename(name) {
+    const chars = Array.from(name.replace(/[^\p{L}\p{N}._-]/gu, '_').replace(/^\.+/, '_'));
+    while (Buffer.byteLength(chars.join('')) > 120)
+        chars.pop();
+    return chars.join('') || 'file';
+}
+export function storeAgentAttachment(stateDir, generation, input) {
+    if (!input || typeof input !== 'object')
+        fail('File data is required');
+    const body = input;
+    if (typeof body.name !== 'string' || !body.name.trim() || body.name.length > 240 || /[\x00-\x1f]/u.test(body.name))
+        fail('A file name of 1–240 characters is required');
+    if (typeof body.mimeType !== 'string' || !/^[a-zA-Z0-9.+-]+\/[a-zA-Z0-9.+-]+$/.test(body.mimeType))
+        fail('A valid media type is required');
+    if (typeof body.data !== 'string' || body.data.length > Math.ceil(MAX_ATTACHMENT_BYTES / 3) * 4 || /[^A-Za-z0-9+/=]/.test(body.data))
+        fail('Invalid base64 file data or file exceeds 20 MiB');
+    const bytes = Buffer.from(body.data, 'base64');
+    if (bytes.length > MAX_ATTACHMENT_BYTES || bytes.toString('base64') !== body.data)
+        fail('Invalid file data or file exceeds 20 MiB');
+    const sha256 = digest(bytes), name = body.name, mimeType = body.mimeType;
+    const id = digest(JSON.stringify({ generation, name, mimeType, sha256 }));
+    const record = { id, name, mimeType, size: bytes.length, sha256, generation };
+    // Fleet runtime state directories may use the account group (0775). Upload storage remains private.
+    directory(stateDir, false, false);
+    const root = join(stateDir, 'web-attachments');
+    directory(root, true);
+    const dir = join(root, id);
+    directory(dir, true);
+    immutable(join(dir, 'content-' + filename(name)), bytes);
+    immutable(join(dir, 'metadata.json'), Buffer.from(JSON.stringify(record)));
+    return record;
+}
+export function attachmentPrompt(stateDir, generation, ids, text) {
+    if (!Array.isArray(ids) || ids.length < 1 || ids.length > 5 || new Set(ids).size !== ids.length)
+        fail('Select between 1 and 5 distinct attachments');
+    // Fleet runtime state directories may use the account group (0775). Upload storage remains private.
+    directory(stateDir, false, false);
+    const root = join(stateDir, 'web-attachments');
+    directory(root);
+    const files = ids.map(id => {
+        if (typeof id !== 'string' || !/^[a-f0-9]{64}$/.test(id))
+            fail('Invalid attachment ID');
+        const dir = join(root, id);
+        directory(dir);
+        const record = JSON.parse(read(join(dir, 'metadata.json'), 4096).toString());
+        if (record.id !== id || record.generation !== generation)
+            throw new FleetError('stale_state', 'Attachment belongs to a different agent session');
+        const file = join(dir, 'content-' + filename(record.name)), bytes = read(file, MAX_ATTACHMENT_BYTES);
+        if (bytes.length !== record.size || digest(bytes) !== record.sha256 || digest(JSON.stringify({ generation, name: record.name, mimeType: record.mimeType, sha256: record.sha256 })) !== id)
+            fail('Attachment content changed');
+        return { name: record.name, mimeType: record.mimeType, size: record.size, sha256: record.sha256, path: file };
+    });
+    return `${text}${text ? '\n\n' : ''}Attached files (available on this host; open the files to inspect their contents, and use the image viewer for images):\n${JSON.stringify(files, null, 2)}`;
+}
+/** Authenticated content access reuses the same ownership and integrity checks as admission. */
+function attachmentMetadata(stateDir, id) {
+    if (!/^[a-f0-9]{64}$/.test(id))
+        fail('Invalid attachment ID');
+    directory(stateDir, false, false);
+    const root = join(stateDir, 'web-attachments');
+    directory(root);
+    const dir = join(root, id);
+    directory(dir);
+    const record = JSON.parse(read(join(dir, 'metadata.json'), 4096).toString());
+    if (record.id !== id || typeof record.name !== 'string' || typeof record.mimeType !== 'string')
+        fail('Invalid attachment metadata');
+    if (digest(JSON.stringify({ generation: record.generation, name: record.name, mimeType: record.mimeType, sha256: record.sha256 })) !== id)
+        fail('Attachment metadata changed');
+    return record;
+}
+export function readAgentAttachment(stateDir, id) {
+    let record;
+    try {
+        record = attachmentMetadata(stateDir, id);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            throw new FleetError('resource_not_found', 'Attachment not found');
+        throw error;
+    }
+    const bytes = read(join(stateDir, 'web-attachments', id, 'content-' + filename(record.name)), MAX_ATTACHMENT_BYTES);
+    if (bytes.length !== record.size || digest(bytes) !== record.sha256)
+        fail('Attachment content changed');
+    return { record, bytes };
+}
+/** Written before admission so a lost HTTP response cannot lose the visible message. */
+export function storeAttachmentPresentation(stateDir, value) {
+    directory(stateDir, false, false);
+    const root = join(stateDir, 'web-attachment-messages');
+    directory(root, true);
+    immutable(join(root, digest(JSON.stringify([value.generation, value.commandId])) + '.json'), Buffer.from(JSON.stringify(value)));
+}
+export function prepareAttachmentPresentation(stateDir, generation, commandId, ids, text, transport) {
+    storeAttachmentPresentation(stateDir, { generation, commandId, ids, text, transportDigest: digest(transport) });
+}
+/** Never infer attachments by stripping user text or interpreting a marker. */
+export function presentAttachmentEvent(stateDir, roleId, event) {
+    const e = event;
+    if (!stateDir || e.kind !== 'prompt.admitted' || e.source !== 'owner_admin_console' || !e.commandId || e.payload?.text?.redacted)
+        return event;
+    const root = join(stateDir, 'web-attachment-messages');
+    if (!existsSync(root))
+        return event;
+    const path = join(root, digest(JSON.stringify([e.sessionGeneration, e.commandId])) + '.json');
+    if (!existsSync(path))
+        return event;
+    try {
+        directory(stateDir, false, false);
+        directory(root);
+        const value = JSON.parse(read(path, 1024 * 1024).toString());
+        if (value.generation !== e.sessionGeneration || value.commandId !== e.commandId || value.transportDigest !== digest(e.payload.text.text))
+            return event;
+        const attachments = value.ids.map(id => {
+            const record = attachmentMetadata(stateDir, id);
+            if (record.generation !== value.generation)
+                fail('Attachment session changed');
+            return { id, name: record.name, mimeType: record.mimeType, size: record.size, url: `/api/v1/roles/${encodeURIComponent(roleId)}/attachments/${id}` };
+        });
+        return { ...e, payload: { ...e.payload, text: { type: 'text', text: value.text, bytes: Buffer.byteLength(value.text) }, displayText: { type: 'text', text: value.text, bytes: Buffer.byteLength(value.text) }, attachments } };
+    }
+    catch {
+        return event;
+    }
+}

package/dist/web/auth.d.ts

@@ -1,3 +1,4 @@
+import { WorkspaceDeviceStore } from './workspace-devices.js';
 import type { FastifyRequest } from 'fastify';
 import type { WebSocket } from 'ws';
 import { TrustedDeviceStore, type TrustedDeviceIssue } from './device-store.js';
@@ -8,6 +9,8 @@ export interface BrowserSession {
     createdAt: number;
     lastSeenAt: number;
     absoluteExpiresAt: number;
+    /** A workspace access credential, which cannot create further device links. */
+    rotating?: boolean;
 }
 export interface AuthResult {
     session: BrowserSession;
@@ -19,6 +22,8 @@ interface Ticket {
     purpose: 'events' | 'conversation';
     roleId?: string;
     expiresAt: number;
+    /** When the credential that minted this ticket stops authorizing; a socket opened with it ends then. */
+    authorizedUntil: number;
 }
 export declare class WebAuth {
     private _origin;
@@ -26,6 +31,8 @@ export declare class WebAuth {
     private readonly now;
     private readonly devices;
     private readonly access;
+    private readonly workspaceDevices?;
+    readonly appOrigin: string;
     private _bootstrapSecret;
     private bootstrapExpiresAt;
     private bootstrapUsed;
@@ -33,8 +40,10 @@ export declare class WebAuth {
     private readonly sessionDevices;
     private readonly tickets;
     private readonly rates;
+    private readonly transports;
+    private readonly renewals;
     private readonly sockets;
-    constructor(_origin: string, _host: string, now?: () => number, devices?: TrustedDeviceStore, access?: WebAccessConfig);
+    constructor(_origin: string, _host: string, now?: () => number, devices?: TrustedDeviceStore, access?: WebAccessConfig, workspaceDevices?: WorkspaceDeviceStore | undefined, appOrigin?: string);
     get bootstrapSecret(): string;
     get origin(): string;
     get host(): string;
@@ -48,6 +57,8 @@ export declare class WebAuth {
     }): void;
     /** Mint a replacement for an operator-triggered reauthentication ceremony. */
     mintBootstrap(): string;
+    /** The configured account origin, when this request comes from it and workspace devices are enabled. */
+    accountOrigin(request: Pick<FastifyRequest, 'headers'>): string | undefined;
     validateBoundary(request: FastifyRequest, requireOrigin: boolean): void;
     exchange(request: FastifyRequest): AuthResult;
     login(request: FastifyRequest, password: string): AuthResult;
@@ -60,9 +71,59 @@ export declare class WebAuth {
         expiresAt: string;
     };
     consumeTicket(request: FastifyRequest, value: string, purpose: Ticket['purpose'], roleId?: string): BrowserSession;
-    bindSocket(sessionId: string, socket: WebSocket): void;
+    /**
+     * `session` is what authenticate() or consumeTicket() returned for this connection. A workspace
+     * device shares one session id across credentials, so the socket ends at that credential's own
+     * deadline; revocation still ends everything the device has open.
+     */
+    bindSocket(session: Pick<BrowserSession, 'id' | 'absoluteExpiresAt'>, socket: WebSocket): void;
+    /** Raw service streams share the same logout/revocation boundary as native sockets. */
+    bindTransport(session: Pick<BrowserSession, 'id' | 'absoluteExpiresAt'>, close: () => void, renewal?: string): () => void;
+    /**
+     * Keep one open transport past the credential that opened it. Only its own reader knows the
+     * name it was given, and it must authenticate with a newer credential of the same device while
+     * the transport is still open: a copied credential cannot renew after it has expired.
+     */
+    renewTransport(request: FastifyRequest, renewal: string): {
+        authorizedUntil: number;
+    };
     clearSessions(): void;
     revokeAllTrustedDevices(): number;
+    workspaceIdentity(): {
+        workspaceId: string;
+    };
+    workspaceEnrollment(issuer?: string | null): {
+        enrollment: string;
+        workspaceId: string;
+        expiresAt: number;
+    };
+    enrollWorkspace(request: FastifyRequest, input: {
+        enrollment: string;
+        workspaceId: string;
+        label: string;
+        credential?: unknown;
+    }): import("./workspace-devices.js").WorkspaceCredentials | {
+        token: string;
+        device: import("./workspace-devices.js").WorkspaceDevice;
+        workspaceId: string;
+    };
+    /**
+     * Refresh credentials are exchanged between the account server and this host only. A browser
+     * always states where a request comes from, so a request that does is refused: no page can be
+     * handed refresh material, whichever origin it runs on.
+     */
+    private machineOnly;
+    refreshWorkspace(request: FastifyRequest, refreshToken: string): import("./workspace-devices.js").WorkspaceCredentials;
+    exchangeWorkspace(request: FastifyRequest): import("./workspace-devices.js").WorkspaceCredentials;
+    revokeWorkspaceRefresh(request: FastifyRequest, refreshHash: string): boolean;
+    /** A link code for another browser, for the issuing link's own current refresh credential, which it rotates. */
+    linkWorkspaceDevice(request: FastifyRequest, refreshToken: string): import("./workspace-devices.js").WorkspaceCredentials & {
+        enrollment: string;
+        enrollmentExpiresAt: number;
+    };
+    listWorkspaceDevices(): import("./workspace-devices.js").WorkspaceDevice[];
+    revokeWorkspaceDevice(id: string): void;
+    private requireWorkspaceDevices;
     shutdown(): void;
     private createSession;
     private removeSession;

package/dist/web/auth.js

@@ -1,3 +1,4 @@
+import { WorkspaceDeviceAuthError, WorkspaceRefreshReuseError } from './workspace-devices.js';
 import { randomBytes, timingSafeEqual } from 'node:crypto';
 import { FleetError } from '../application/errors.js';
 import { TrustedDeviceStore } from './device-store.js';
@@ -14,6 +15,8 @@ export class WebAuth {
     now;
     devices;
     access;
+    workspaceDevices;
+    appOrigin;
     _bootstrapSecret = token(32);
     bootstrapExpiresAt = Date.now() + 5 * 60_000;
     bootstrapUsed = false;
@@ -21,13 +24,17 @@ export class WebAuth {
     sessionDevices = new Map();
     tickets = new Map();
     rates = new Map();
+    transports = new Map();
+    renewals = new Map();
     sockets = new Map();
-    constructor(_origin, _host, now = Date.now, devices = new TrustedDeviceStore(), access = { version: 1, mode: 'pairing' }) {
+    constructor(_origin, _host, now = Date.now, devices = new TrustedDeviceStore(), access = { version: 1, mode: 'pairing' }, workspaceDevices, appOrigin = 'https://app.ours.network') {
         this._origin = _origin;
         this._host = _host;
         this.now = now;
         this.devices = devices;
         this.access = access;
+        this.workspaceDevices = workspaceDevices;
+        this.appOrigin = appOrigin;
     }
     get bootstrapSecret() { return this._bootstrapSecret; }
     get origin() { return this._origin; }
@@ -49,16 +56,24 @@ export class WebAuth {
         this.bootstrapUsed = false;
         return this._bootstrapSecret;
     }
+    /** The configured account origin, when this request comes from it and workspace devices are enabled. */
+    accountOrigin(request) {
+        return this.workspaceDevices && request.headers.origin === this.appOrigin ? this.appOrigin : undefined;
+    }
     validateBoundary(request, requireOrigin) {
         const host = request.headers.host;
         const hosts = this.allowedHosts.size ? this.allowedHosts : new Set([this.host]);
         const origins = this.allowedOrigins.size ? this.allowedOrigins : new Set([this.origin]);
         if (!host || !hosts.has(host))
             throw new FleetError('forbidden', `This address is not configured for the fleet console. Open ${this.origin} or set --public-origin.`);
-        if (requireOrigin && (!request.headers.origin || !origins.has(request.headers.origin)))
+        if (this.workspaceDevices && String(request.headers.authorization ?? '').startsWith('Bearer ') && request.headers.origin && request.headers.origin !== this.appOrigin && !origins.has(request.headers.origin))
+            throw new FleetError('forbidden', 'workspace request Origin does not match configured account origin');
+        const workspaceRequest = Boolean(this.workspaceDevices) && request.headers.origin === this.appOrigin
+            && (String(request.headers.authorization ?? '').startsWith('Bearer ') || (request.url ?? '').split('?')[0] === '/api/v1/devices/enroll' || request.method === 'OPTIONS');
+        if (requireOrigin && !workspaceRequest && (!request.headers.origin || !origins.has(request.headers.origin)))
             throw new FleetError('forbidden', 'request Origin does not match the configured control-panel origin');
         const fetchSite = request.headers['sec-fetch-site'];
-        if (fetchSite && !['same-origin', 'none'].includes(String(fetchSite)))
+        if (!workspaceRequest && fetchSite && !['same-origin', 'none'].includes(String(fetchSite)))
             throw new FleetError('forbidden', 'cross-site request rejected');
     }
     exchange(request) {
@@ -100,7 +115,24 @@ export class WebAuth {
         return { session: this.createSession(device.id), device };
     }
     authenticate(request, mutation = false) {
+        const authorization = String(request.headers.authorization ?? '');
+        if (authorization.startsWith('Bearer ')) {
+            this.validateBoundary(request, mutation);
+            if (!this.workspaceDevices)
+                throw new WorkspaceDeviceAuthError('workspace bearer credential is invalid');
+            const device = this.requireWorkspaceDevices().authenticate(authorization.slice(7));
+            const id = `workspace:${device.id}`;
+            // A transport opened with this credential ends when this credential does, whatever replaces it.
+            const session = { id, csrf: '', createdAt: device.createdAt, lastSeenAt: this.now(), absoluteExpiresAt: device.authorizedUntil, rotating: device.rotating };
+            this.sessions.set(id, session);
+            this.sessionDevices.set(id, id);
+            if (mutation)
+                this.consumeRate(`mutation:${id}`, 120, 60000);
+            return session;
+        }
         this.validateBoundary(request, mutation);
+        if (request.headers.origin === this.appOrigin && !this.allowedOrigins.has(this.appOrigin))
+            throw new FleetError('unauthorized', 'workspace bearer credential required');
         const id = parseCookies(request.headers.cookie ?? '').ofs_session;
         const session = id ? this.sessions.get(id) : undefined;
         const now = this.now();
@@ -121,7 +153,9 @@ export class WebAuth {
     logout(request) {
         const session = this.authenticate(request, true);
         const deviceId = this.sessionDevices.get(session.id);
-        if (deviceId && deviceId !== 'unprotected')
+        if (session.id.startsWith('workspace:'))
+            this.workspaceDevices?.revoke(session.id.slice(10));
+        else if (deviceId && deviceId !== 'unprotected')
             this.devices.revokeId(deviceId);
         this.removeSession(session.id);
     }
@@ -130,7 +164,8 @@ export class WebAuth {
         const value = token();
         const ticket = {
             value, sessionId: session.id, purpose, roleId,
-            expiresAt: this.now() + 30_000,
+            expiresAt: Math.min(this.now() + 30_000, session.absoluteExpiresAt),
+            authorizedUntil: session.absoluteExpiresAt,
         };
         this.tickets.set(value, ticket);
         return { ticket: value, expiresAt: new Date(ticket.expiresAt).toISOString() };
@@ -143,20 +178,82 @@ export class WebAuth {
             || ticket.roleId !== roleId)
             throw new FleetError('unauthorized', 'WebSocket ticket is invalid, expired, or already used');
         const session = this.sessions.get(ticket.sessionId);
-        if (!session)
+        if (!session || (session.id.startsWith('workspace:') && !this.workspaceDevices?.valid(session.id.slice(10))))
             throw new FleetError('unauthorized', 'browser session expired');
-        return session;
+        if (!session.id.startsWith('workspace:'))
+            return session;
+        // A workspace device's session entry is replaced by each newer credential; the ticket carries
+        // the deadline of the credential that minted it, and nothing newer extends it.
+        if (ticket.authorizedUntil <= this.now())
+            throw new FleetError('unauthorized', 'WebSocket ticket is invalid, expired, or already used');
+        return { ...session, absoluteExpiresAt: ticket.authorizedUntil };
     }
-    bindSocket(sessionId, socket) {
+    /**
+     * `session` is what authenticate() or consumeTicket() returned for this connection. A workspace
+     * device shares one session id across credentials, so the socket ends at that credential's own
+     * deadline; revocation still ends everything the device has open.
+     */
+    bindSocket(session, socket) {
+        const sessionId = session.id, deadline = sessionId.startsWith('workspace:') ? session.absoluteExpiresAt : undefined;
         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));
+        const expiry = setInterval(() => { const current = this.sessions.get(sessionId); if (!current || (deadline !== undefined ? !this.workspaceDevices?.valid(sessionId.slice(10)) : current.absoluteExpiresAt <= this.now()))
+            this.removeSession(sessionId);
+        else if (deadline !== undefined && deadline <= this.now()) {
+            clearInterval(expiry);
+            socket.close(4401, 'authentication expired');
+        } }, 1000);
+        expiry.unref();
+        socket.once('close', () => { clearInterval(expiry); sockets?.delete(socket); });
+    }
+    /** Raw service streams share the same logout/revocation boundary as native sockets. */
+    bindTransport(session, close, renewal) {
+        const sessionId = session.id, workspace = sessionId.startsWith('workspace:');
+        let transports = this.transports.get(sessionId);
+        if (!transports) {
+            transports = new Set();
+            this.transports.set(sessionId, transports);
+        }
+        transports.add(close);
+        const lease = { sessionId, deadline: session.absoluteExpiresAt };
+        if (workspace && renewal)
+            this.renewals.set(renewal, lease);
+        const expiry = setInterval(() => { const current = this.sessions.get(sessionId); if (!current || (workspace ? !this.workspaceDevices?.valid(sessionId.slice(10)) : current.absoluteExpiresAt <= this.now()))
+            this.removeSession(sessionId);
+        else if (workspace && lease.deadline <= this.now()) {
+            clearInterval(expiry);
+            transports.delete(close);
+            if (renewal)
+                this.renewals.delete(renewal);
+            close();
+        } }, 1000);
+        expiry.unref();
+        return () => { clearInterval(expiry); transports.delete(close); if (renewal)
+            this.renewals.delete(renewal); if (!transports.size)
+            this.transports.delete(sessionId); };
+    }
+    /**
+     * Keep one open transport past the credential that opened it. Only its own reader knows the
+     * name it was given, and it must authenticate with a newer credential of the same device while
+     * the transport is still open: a copied credential cannot renew after it has expired.
+     */
+    renewTransport(request, renewal) {
+        const session = this.authenticate(request, true), lease = this.renewals.get(renewal);
+        if (!lease || lease.sessionId !== session.id || lease.deadline <= this.now())
+            throw new FleetError('resource_not_found', 'transport is not open');
+        lease.deadline = Math.max(lease.deadline, session.absoluteExpiresAt);
+        return { authorizedUntil: lease.deadline };
     }
     clearSessions() {
+        for (const transports of this.transports.values())
+            for (const close of transports)
+                close();
+        this.transports.clear();
+        this.renewals.clear();
         for (const sockets of this.sockets.values())
             for (const socket of sockets)
                 socket.close(4401, 'authentication revoked');
@@ -167,10 +264,88 @@ export class WebAuth {
     }
     revokeAllTrustedDevices() {
         const count = this.devices.revokeAll();
+        for (const device of this.workspaceDevices?.list() ?? [])
+            this.workspaceDevices?.revoke(device.id);
         this.clearSessions();
         return count;
     }
-    shutdown() { this.clearSessions(); }
+    workspaceIdentity() { return { workspaceId: this.requireWorkspaceDevices().workspaceId }; }
+    workspaceEnrollment(issuer = null) { return this.requireWorkspaceDevices().mint(issuer?.startsWith('workspace:') ? issuer.slice(10) : null); }
+    enrollWorkspace(request, input) {
+        if (input.credential === 2) {
+            this.machineOnly(request);
+            this.consumeRate('workspace-enrollment', 30, 60000);
+            return this.requireWorkspaceDevices().enroll(input.enrollment, input.workspaceId, input.label, true);
+        }
+        this.validateBoundary(request, true);
+        this.consumeRate('workspace-enrollment', 30, 60000);
+        return this.requireWorkspaceDevices().enroll(input.enrollment, input.workspaceId, input.label);
+    }
+    /**
+     * Refresh credentials are exchanged between the account server and this host only. A browser
+     * always states where a request comes from, so a request that does is refused: no page can be
+     * handed refresh material, whichever origin it runs on.
+     */
+    machineOnly(request) {
+        this.validateBoundary(request, false);
+        if (request.headers.origin !== undefined || Object.keys(request.headers).some(name => name.startsWith('sec-fetch-')) || request.headers.cookie !== undefined)
+            throw new FleetError('forbidden', 'this endpoint does not accept browser requests');
+    }
+    refreshWorkspace(request, refreshToken) {
+        this.machineOnly(request);
+        this.consumeRate('workspace-refresh', 240, 60000);
+        try {
+            return this.requireWorkspaceDevices().refresh(refreshToken);
+        }
+        catch (error) {
+            if (error instanceof WorkspaceRefreshReuseError)
+                for (const id of error.revoked)
+                    this.removeSession(`workspace:${id}`);
+            throw error;
+        }
+    }
+    exchangeWorkspace(request) {
+        this.machineOnly(request);
+        this.consumeRate('workspace-enrollment', 30, 60000);
+        const authorization = String(request.headers.authorization ?? '');
+        const issued = this.requireWorkspaceDevices().exchange(authorization.startsWith('Bearer ') ? authorization.slice(7) : '');
+        // Whatever the fixed bearer had open ends with it.
+        this.removeSession(`workspace:${issued.device.id}`);
+        return issued;
+    }
+    revokeWorkspaceRefresh(request, refreshHash) {
+        this.machineOnly(request);
+        this.consumeRate('workspace-revoke', 120, 60000);
+        const id = this.requireWorkspaceDevices().revokeByRefreshHash(refreshHash);
+        if (id)
+            this.removeSession(`workspace:${id}`);
+        return Boolean(id);
+    }
+    /** A link code for another browser, for the issuing link's own current refresh credential, which it rotates. */
+    linkWorkspaceDevice(request, refreshToken) {
+        this.machineOnly(request);
+        this.consumeRate('workspace-link', 10, 60000);
+        try {
+            return this.requireWorkspaceDevices().link(refreshToken);
+        }
+        catch (error) {
+            if (error instanceof WorkspaceRefreshReuseError)
+                for (const id of error.revoked)
+                    this.removeSession(`workspace:${id}`);
+            throw error;
+        }
+    }
+    listWorkspaceDevices() { return this.requireWorkspaceDevices().list(); }
+    revokeWorkspaceDevice(id) {
+        this.requireWorkspaceDevices().revoke(id);
+        this.removeSession(`workspace:${id}`);
+    }
+    requireWorkspaceDevices() {
+        if (!this.workspaceDevices)
+            throw new FleetError('capability_unavailable', 'workspace device access is not configured');
+        return this.workspaceDevices;
+    }
+    shutdown() { this.clearSessions(); this.workspaceDevices?.close(); }
     createSession(deviceId) {
         const now = this.now();
         const session = {
@@ -182,6 +357,12 @@ export class WebAuth {
         return session;
     }
     removeSession(id) {
+        for (const close of this.transports.get(id) ?? [])
+            close();
+        this.transports.delete(id);
+        for (const [renewal, lease] of this.renewals)
+            if (lease.sessionId === id)
+                this.renewals.delete(renewal);
         this.sessions.delete(id);
         this.sessionDevices.delete(id);
         for (const [ticket, value] of this.tickets)

package/dist/web/available-port.d.ts

@@ -0,0 +1,2 @@
+/** Bind the preferred loopback port; only EADDRINUSE permits an OS-selected replacement. */
+export declare function availableWebPort(preferred: number): Promise<number>;

package/dist/web/available-port.js

@@ -0,0 +1,23 @@
+import { createServer } from 'node:net';
+/** Bind the preferred loopback port; only EADDRINUSE permits an OS-selected replacement. */
+export async function availableWebPort(preferred) {
+    const server = createServer();
+    const listen = (port) => new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(port, '127.0.0.1', () => { server.removeListener('error', reject); resolve(); });
+    });
+    try {
+        await listen(preferred);
+    }
+    catch (error) {
+        if (error.code !== 'EADDRINUSE')
+            throw error;
+        await listen(0);
+    }
+    const address = server.address();
+    if (!address || typeof address === 'string')
+        throw Error('No loopback port selected');
+    const port = address.port;
+    await new Promise((resolve, reject) => server.close(error => error ? reject(error) : resolve()));
+    return port;
+}

package/dist/web/control.d.ts

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