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

package/dist/web/service.d.ts

@@ -1,6 +1,7 @@
 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";
+type ServiceEnvironment = Partial<Record<'OURS_CONFIG' | 'OURS_FLEET_HOME' | 'PATH', string>>;
 interface ServiceMetadata {
     version: 3;
     platform: 'linux' | 'darwin';
@@ -10,6 +11,7 @@ interface ServiceMetadata {
     configuration?: string;
     bind?: string;
     publicOrigin?: string;
+    environment?: ServiceEnvironment;
 }
 export interface WebServiceOptions {
     platform?: NodeJS.Platform;
@@ -18,6 +20,7 @@ export interface WebServiceOptions {
     stateDir?: string;
     uid?: number;
     runtimeExecutable?: string;
+    environment?: NodeJS.ProcessEnv;
 }
 export declare class WebServiceManager {
     private readonly platform;
@@ -26,6 +29,7 @@ export declare class WebServiceManager {
     private readonly stateDir;
     private readonly uid;
     private readonly runtimeExecutable;
+    private readonly environment;
     constructor(options?: WebServiceOptions);
     get metadataPath(): string;
     get definitionPath(): string;
@@ -33,6 +37,11 @@ export declare class WebServiceManager {
         bind?: string;
         publicOrigin?: string;
     }): Promise<string[]>;
+    /** Persist an enrollment bind fallback, reloading launchd's cached definition. */
+    retainBoundPort(script: string, port: number, configuration?: string, web?: {
+        bind?: string;
+        publicOrigin?: string;
+    }): Promise<void>;
     start(): Promise<void>;
     stop(): Promise<void>;
     restart(): Promise<void>;
@@ -45,9 +54,9 @@ export declare class WebServiceManager {
 export declare function systemdUnit(runtime: string, script: string, port: number, configuration?: string, web?: {
     bind?: string;
     publicOrigin?: string;
-}): string;
+}, environment?: ServiceEnvironment): string;
 export declare function launchdPlist(runtime: string, script: string, port: number, configuration?: string, web?: {
     bind?: string;
     publicOrigin?: string;
-}): string;
+}, environment?: ServiceEnvironment): string;
 export {};

package/dist/web/service.js

@@ -15,6 +15,7 @@ export class WebServiceManager {
     stateDir;
     uid;
     runtimeExecutable;
+    environment;
     constructor(options = {}) {
         const platform = options.platform ?? process.platform;
         if (platform !== 'linux' && platform !== 'darwin')
@@ -25,6 +26,7 @@ export class WebServiceManager {
         this.stateDir = options.stateDir ?? join(stateRoot(), 'web');
         this.uid = options.uid ?? process.getuid?.() ?? 501;
         this.runtimeExecutable = options.runtimeExecutable ?? process.execPath;
+        this.environment = serviceEnvironment(options.environment ?? process.env);
     }
     get metadataPath() { return join(this.stateDir, 'service.json'); }
     get definitionPath() {
@@ -42,13 +44,14 @@ export class WebServiceManager {
         const config = configuration ? resolve(configuration) : undefined;
         const metadata = {
             version: VERSION, platform: this.platform, runtime, script: resolvedScript, port,
+            environment: this.environment,
             ...(config ? { configuration: config } : {}),
             ...(web.bind ? { bind: web.bind } : {}),
             ...(web.publicOrigin ? { publicOrigin: web.publicOrigin } : {}),
         };
         replaceFileAtomically(this.definitionPath, this.platform === 'linux'
-            ? systemdUnit(runtime, resolvedScript, port, config, web)
-            : launchdPlist(runtime, resolvedScript, port, config, web), 0o600);
+            ? systemdUnit(runtime, resolvedScript, port, config, web, this.environment)
+            : launchdPlist(runtime, resolvedScript, port, config, web, this.environment), 0o600);
         replaceFileAtomically(this.metadataPath, JSON.stringify(metadata, null, 2) + '\n', 0o600);
         if (this.platform === 'linux') {
             await this.must('systemctl', ['--user', 'daemon-reload']);
@@ -63,6 +66,14 @@ export class WebServiceManager {
         }
         return [`installed ${this.definitionPath}`, 'launchd service starts at login'];
     }
+    /** Persist an enrollment bind fallback, reloading launchd's cached definition. */
+    async retainBoundPort(script, port, configuration, web = {}) {
+        await this.install(script, port, configuration, web);
+        if (this.platform === 'darwin') {
+            await this.stop();
+            await this.start();
+        }
+    }
     async start() {
         this.requireInstalled();
         if (this.platform === 'linux') {
@@ -159,19 +170,20 @@ function validatePort(port) {
 function systemdQuote(value) {
     return `"${value.replace(/[%\\"]/g, char => char === '%' ? '%%' : `\\${char}`)}"`;
 }
-export function systemdUnit(runtime, script, port, configuration, web = {}) {
+export function systemdUnit(runtime, script, port, configuration, web = {}, environment = {}) {
     const config = configuration ? ` --configuration ${systemdQuote(configuration)}` : '';
     const access = `${web.bind ? ` --bind ${systemdQuote(web.bind)}` : ''}`
         + `${web.publicOrigin ? ` --public-origin ${systemdQuote(web.publicOrigin)}` : ''}`;
     return `[Unit]\nDescription=ours-fleet localhost web console\nAfter=default.target\n\n`
         + `[Service]\nType=simple\nExecStart=${systemdQuote(runtime)} ${systemdQuote(script)} web serve --port ${port} --no-open${config}${access}\n`
+        + Object.entries(serviceEnvironment(environment)).map(([key, value]) => `Environment=${systemdQuote(`${key}=${value}`)}\n`).join('')
         + `Restart=on-failure\nRestartSec=5\nTimeoutStopSec=15\n\n`
         + `[Install]\nWantedBy=default.target\n`;
 }
 const xml = (value) => value.replace(/[&<>"']/g, char => ({
     '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&apos;',
 }[char]));
-export function launchdPlist(runtime, script, port, configuration, web = {}) {
+export function launchdPlist(runtime, script, port, configuration, web = {}, environment = {}) {
     const config = configuration
         ? `<string>--configuration</string><string>${xml(configuration)}</string>` : '';
     const access = `${web.bind ? `<string>--bind</string><string>${xml(web.bind)}</string>` : ''}`
@@ -181,6 +193,20 @@ export function launchdPlist(runtime, script, port, configuration, web = {}) {
         + `<plist version="1.0"><dict>\n<key>Label</key><string>${WEB_LAUNCHD_LABEL}</string>\n`
         + `<key>ProgramArguments</key><array><string>${xml(runtime)}</string><string>${xml(script)}</string><string>web</string>`
         + `<string>serve</string><string>--port</string><string>${port}</string><string>--no-open</string>${config}${access}</array>\n`
+        + `<key>EnvironmentVariables</key><dict>${Object.entries(serviceEnvironment(environment)).map(([key, value]) => `<key>${key}</key><string>${xml(value)}</string>`).join('')}</dict>\n`
         + `<key>RunAtLoad</key><true/><key>KeepAlive</key><dict><key>SuccessfulExit</key><false/></dict>\n`
         + `<key>ProcessType</key><string>Background</string>\n</dict></plist>\n`;
 }
+// Retain only profile/tool paths, never inherited credentials or arbitrary environment.
+function serviceEnvironment(source) {
+    const result = {};
+    for (const key of ['OURS_CONFIG', 'OURS_FLEET_HOME', 'PATH']) {
+        const value = source[key];
+        if (!value)
+            continue;
+        if (/[\r\n\0]/.test(value))
+            throw new FleetError('invalid_request', `invalid service path setting: ${key}`);
+        result[key] = key === 'PATH' ? value : resolve(value);
+    }
+    return result;
+}

package/dist/web/workspace-devices.d.ts

@@ -0,0 +1,107 @@
+import { FleetError } from '../application/errors.js';
+/** Only failure of the enrolled device check may invalidate the App's saved credential. */
+export declare class WorkspaceDeviceAuthError extends FleetError {
+    constructor(message?: string);
+}
+/** A spent refresh credential came back after its replacement was in use: the link is revoked, whoever presented it. */
+export declare class WorkspaceRefreshReuseError extends WorkspaceDeviceAuthError {
+    readonly revoked: string[];
+    constructor(revoked: string[]);
+}
+/**
+ * Credential lifetimes of an App browser link. Rotation is not expiry: every refresh replaces the
+ * refresh credential, each one lapses when unused for REFRESH_IDLE_TTL, and no rotation moves a
+ * link past the FAMILY_TTL fixed when it was created.
+ */
+export declare const ACCESS_TTL: number;
+export declare const REFRESH_IDLE_TTL: number;
+export declare const FAMILY_TTL: number;
+/** How long after this store first runs rotating credentials the earlier fixed bearer is still accepted. */
+export declare const LEGACY_BEARER_WINDOW: number;
+export interface WorkspaceDevice {
+    id: string;
+    label: string;
+    createdAt: number;
+    lastUsedAt: number;
+    expiresAt: number;
+    revokedAt: number | null;
+}
+export interface WorkspaceCredentials {
+    device: WorkspaceDevice;
+    workspaceId: string;
+    accessToken: string;
+    accessExpiresAt: number;
+    refreshToken: string;
+    refreshExpiresAt: number;
+    familyExpiresAt: number;
+}
+/** An authenticated device and the moment the presented credential stops authorizing anything. */
+export type AuthenticatedWorkspaceDevice = WorkspaceDevice & {
+    authorizedUntil: number;
+    rotating: boolean;
+};
+export declare class WorkspaceDeviceStore {
+    private readonly now;
+    private readonly db;
+    readonly workspaceId: string;
+    /** After this moment a fixed bearer no longer authenticates and no new one is issued. */
+    readonly legacySunsetAt: number;
+    private readonly rotationKey;
+    constructor(dir?: string, now?: () => number);
+    private transaction;
+    mint(issuer?: string | null): {
+        enrollment: string;
+        workspaceId: string;
+        expiresAt: number;
+    };
+    /** Link a browser with rotating credentials. */
+    enroll(enrollment: string, workspaceId: string, label: string, rotating: true): WorkspaceCredentials;
+    /** The fixed bearer of earlier App versions; refused once the legacy window has closed. */
+    enroll(enrollment: string, workspaceId: string, label: string, rotating?: false): {
+        token: string;
+        device: WorkspaceDevice;
+        workspaceId: string;
+    };
+    /** Inside a transaction: an access credential beside the given current refresh credential. */
+    private grant;
+    private live;
+    private device;
+    /**
+     * Replace a refresh credential. It has exactly one successor, derived on this host. Until that
+     * successor is seen in use (presented itself, or an access credential issued with it
+     * authenticates), the spent credential is answered again with the same successor: a lost
+     * answer, a closed tab or a restart converge on one value and extend nothing. Once the successor
+     * is in use, the spent credential is a replay and ends the link and the links it issued.
+     */
+    refresh(refreshToken: string): WorkspaceCredentials;
+    /**
+     * A link code for another browser, issued by this link. It is a lasting grant, so it takes the
+     * link's current, unspent refresh credential and rotates it in the same step, with the successor
+     * counted as in use at once: whoever else holds the spent credential is a replay on their next
+     * refresh, which also ends the link made from this code. An answer lost here is not retried.
+     */
+    link(refreshToken: string): WorkspaceCredentials & {
+        enrollment: string;
+        enrollmentExpiresAt: number;
+    };
+    /** Inside a transaction. Returns new credentials, or the devices ended by a replay. `strict` allows no repeat and confirms the successor. */
+    private rotate;
+    /**
+     * One-time move of a fixed bearer to rotating credentials. The device keeps its identity, the
+     * bearer stops working in the same transaction, and the link ends no later than it would have.
+     */
+    exchange(token: string): WorkspaceCredentials;
+    private legacy;
+    /** The device behind an access credential, or behind a fixed bearer while those are still accepted. */
+    authenticate(token: string): AuthenticatedWorkspaceDevice;
+    /** End the link a refresh credential belongs to, named by its SHA-256: a hash can end a link, never use it. */
+    revokeByRefreshHash(refreshHash: string): string | undefined;
+    /** Inside a transaction. With cascade, links issued from this one end too. Returns every device ended. */
+    private revokeRows;
+    valid(id: string): boolean;
+    list(): WorkspaceDevice[];
+    revoke(id: string): void;
+    /** Retire account links without changing the installation's stable host ID or other data. */
+    revokeAll(): void;
+    close(): void;
+}

package/dist/web/workspace-devices.js

@@ -0,0 +1,277 @@
+import { createRequire } from 'node:module';
+import { createHash, createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
+import { mkdirSync, chmodSync } from 'node:fs';
+import { join } from 'node:path';
+import { stateRoot } from '../paths.js';
+import { FleetError } from '../application/errors.js';
+const opaque = () => randomBytes(32).toString('base64url');
+const hash = (value) => createHash('sha256').update(value).digest('hex');
+/** Only failure of the enrolled device check may invalidate the App's saved credential. */
+export class WorkspaceDeviceAuthError extends FleetError {
+    constructor(message = 'workspace device is missing, expired, or revoked') { super('unauthorized', message); }
+}
+/** A spent refresh credential came back after its replacement was in use: the link is revoked, whoever presented it. */
+export class WorkspaceRefreshReuseError extends WorkspaceDeviceAuthError {
+    revoked;
+    constructor(revoked) {
+        super('workspace refresh credential was already replaced; this device link is revoked');
+        this.revoked = revoked;
+    }
+}
+/**
+ * Credential lifetimes of an App browser link. Rotation is not expiry: every refresh replaces the
+ * refresh credential, each one lapses when unused for REFRESH_IDLE_TTL, and no rotation moves a
+ * link past the FAMILY_TTL fixed when it was created.
+ */
+export const ACCESS_TTL = 5 * 60_000;
+export const REFRESH_IDLE_TTL = 7 * 86_400_000;
+export const FAMILY_TTL = 30 * 86_400_000;
+/** How long after this store first runs rotating credentials the earlier fixed bearer is still accepted. */
+export const LEGACY_BEARER_WINDOW = 30 * 86_400_000;
+const ACCESS_PREFIX = 'owa.', REFRESH_PREFIX = 'owr.';
+const refreshShaped = (value) => typeof value === 'string' && value.startsWith(REFRESH_PREFIX) && value.length <= 128;
+export class WorkspaceDeviceStore {
+    now;
+    db;
+    workspaceId;
+    /** After this moment a fixed bearer no longer authenticates and no new one is issued. */
+    legacySunsetAt;
+    rotationKey;
+    constructor(dir = join(stateRoot(), 'web'), now = Date.now) {
+        this.now = now;
+        const { DatabaseSync } = createRequire(import.meta.url)('node:sqlite');
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+        chmodSync(dir, 0o700);
+        const path = join(dir, 'workspace-devices.db');
+        this.db = new DatabaseSync(path);
+        chmodSync(path, 0o600);
+        this.db.exec(`PRAGMA journal_mode=WAL; PRAGMA busy_timeout=5000;
+      CREATE TABLE IF NOT EXISTS metadata(key TEXT PRIMARY KEY,value TEXT NOT NULL);
+      CREATE TABLE IF NOT EXISTS devices(id TEXT PRIMARY KEY,hash TEXT NOT NULL,label TEXT NOT NULL,createdAt INTEGER NOT NULL,lastUsedAt INTEGER NOT NULL,expiresAt INTEGER NOT NULL,revokedAt INTEGER);
+      CREATE TABLE IF NOT EXISTS enrollments(hash TEXT PRIMARY KEY,expiresAt INTEGER NOT NULL,issuer TEXT);`);
+        // A device row is one browser link. A rotating link keeps no bearer hash: its credentials are the rows below.
+        const columns = this.db.prepare('PRAGMA table_info(devices)').all().map(column => column.name);
+        if (!columns.includes('familyExpiresAt'))
+            this.db.exec('ALTER TABLE devices ADD COLUMN familyExpiresAt INTEGER');
+        if (!columns.includes('issuer'))
+            this.db.exec('ALTER TABLE devices ADD COLUMN issuer TEXT');
+        this.db.exec(`CREATE TABLE IF NOT EXISTS refresh_tokens(hash TEXT PRIMARY KEY,deviceId TEXT NOT NULL,issuedAt INTEGER NOT NULL,expiresAt INTEGER NOT NULL,consumedAt INTEGER,confirmedAt INTEGER,parent TEXT);
+      CREATE INDEX IF NOT EXISTS refresh_tokens_device ON refresh_tokens(deviceId);
+      CREATE UNIQUE INDEX IF NOT EXISTS refresh_tokens_parent ON refresh_tokens(parent) WHERE parent IS NOT NULL;
+      CREATE TABLE IF NOT EXISTS access_tokens(hash TEXT PRIMARY KEY,deviceId TEXT NOT NULL,expiresAt INTEGER NOT NULL,refresh TEXT NOT NULL);
+      CREATE INDEX IF NOT EXISTS access_tokens_device ON access_tokens(deviceId);`);
+        const metadata = (key, initial) => { this.db.prepare('INSERT OR IGNORE INTO metadata VALUES(?,?)').run(key, initial); return String(this.db.prepare('SELECT value FROM metadata WHERE key=?').get(key).value); };
+        this.legacySunsetAt = Number(metadata('legacySunsetAt', String(this.now() + LEGACY_BEARER_WINDOW)));
+        // Derives each refresh credential's one successor from the credential itself; it never leaves
+        // this host and is useless without a current credential. It lives and dies with this
+        // database: a lost or replaced file ends every link, which then needs a new link code.
+        this.rotationKey = Buffer.from(metadata('rotationKey', opaque()), 'base64url');
+        this.workspaceId = metadata('workspaceId', opaque());
+    }
+    transaction(run) {
+        this.db.exec('BEGIN IMMEDIATE');
+        try {
+            const result = run();
+            this.db.exec('COMMIT');
+            return result;
+        }
+        catch (error) {
+            this.db.exec('ROLLBACK');
+            throw error;
+        }
+    }
+    mint(issuer = null) {
+        const now = this.now(), enrollment = opaque(), expiresAt = now + 5 * 60000;
+        return this.transaction(() => {
+            this.db.prepare('DELETE FROM enrollments WHERE expiresAt<=?').run(now);
+            const count = Number(this.db.prepare('SELECT count(*) AS n FROM enrollments').get().n);
+            if (count >= 32)
+                throw new FleetError('rate_limited', 'too many pending device links');
+            this.db.prepare('INSERT INTO enrollments VALUES(?,?,?)').run(hash(enrollment), expiresAt, issuer);
+            return { enrollment, workspaceId: this.workspaceId, expiresAt };
+        });
+    }
+    enroll(enrollment, workspaceId, label, rotating = false) {
+        if (workspaceId !== this.workspaceId || typeof enrollment !== 'string' || !/^[\w-]{43}$/.test(enrollment))
+            throw new FleetError('unauthorized', 'invalid device enrollment');
+        if (typeof label !== 'string' || !label.trim() || label.length > 100 || /[\x00-\x1f\x7f]/.test(label))
+            throw new FleetError('invalid_request', 'device name must contain 1–100 printable characters');
+        const now = this.now(), id = opaque(), token = `${id}.${opaque()}`;
+        if (!rotating && now >= this.legacySunsetAt)
+            throw new FleetError('invalid_request', 'this workspace no longer issues fixed device credentials; update the App');
+        return this.transaction(() => {
+            const code = this.db.prepare('DELETE FROM enrollments WHERE hash=? AND expiresAt>? RETURNING issuer').get(hash(enrollment), now);
+            if (!code)
+                throw new FleetError('unauthorized', 'device enrollment is expired or already used');
+            if (code.issuer && !this.live(String(code.issuer), now))
+                throw new FleetError('unauthorized', 'issuing device has been revoked');
+            const count = Number(this.db.prepare('SELECT count(*) AS n FROM devices WHERE revokedAt IS NULL AND expiresAt>?').get(now).n);
+            if (count >= 128)
+                throw new FleetError('rate_limited', 'authorized device limit reached');
+            const issuer = code.issuer === null ? null : String(code.issuer);
+            if (!rotating) {
+                const device = { id, label: label.trim(), createdAt: now, lastUsedAt: now, expiresAt: now + 90 * 86400000, revokedAt: null };
+                this.db.prepare('INSERT INTO devices(id,hash,label,createdAt,lastUsedAt,expiresAt,revokedAt,issuer) VALUES(?,?,?,?,?,?,NULL,?)').run(id, hash(token), device.label, now, now, device.expiresAt, issuer);
+                return { token, device, workspaceId };
+            }
+            const familyExpiresAt = now + FAMILY_TTL, refreshToken = REFRESH_PREFIX + opaque(), refreshExpiresAt = Math.min(now + REFRESH_IDLE_TTL, familyExpiresAt);
+            const device = { id, label: label.trim(), createdAt: now, lastUsedAt: now, expiresAt: refreshExpiresAt, revokedAt: null };
+            this.db.prepare('INSERT INTO devices(id,hash,label,createdAt,lastUsedAt,expiresAt,revokedAt,familyExpiresAt,issuer) VALUES(?,?,?,?,?,?,NULL,?,?)').run(id, '', device.label, now, now, refreshExpiresAt, familyExpiresAt, issuer);
+            this.db.prepare('INSERT INTO refresh_tokens VALUES(?,?,?,?,NULL,NULL,NULL)').run(hash(refreshToken), id, now, refreshExpiresAt);
+            return this.grant(device, familyExpiresAt, refreshToken, refreshExpiresAt, now);
+        });
+    }
+    /** Inside a transaction: an access credential beside the given current refresh credential. */
+    grant(device, familyExpiresAt, refreshToken, refreshExpiresAt, now) {
+        const accessToken = ACCESS_PREFIX + opaque(), accessExpiresAt = Math.min(now + ACCESS_TTL, familyExpiresAt);
+        this.db.prepare('DELETE FROM access_tokens WHERE expiresAt<=?').run(now);
+        this.db.prepare('DELETE FROM refresh_tokens WHERE deviceId IN (SELECT id FROM devices WHERE revokedAt IS NOT NULL OR expiresAt<=?)').run(now);
+        this.db.prepare('INSERT INTO access_tokens VALUES(?,?,?,?)').run(hash(accessToken), device.id, accessExpiresAt, hash(refreshToken));
+        return { device, workspaceId: this.workspaceId, accessToken, accessExpiresAt, refreshToken, refreshExpiresAt, familyExpiresAt };
+    }
+    live(id, now) {
+        const row = this.db.prepare('SELECT * FROM devices WHERE id=? AND revokedAt IS NULL AND expiresAt>?').get(id, now);
+        if (!row || (row.familyExpiresAt === null && now >= this.legacySunsetAt))
+            return undefined;
+        return { id: String(row.id), hash: String(row.hash), label: String(row.label), createdAt: Number(row.createdAt), lastUsedAt: Number(row.lastUsedAt), expiresAt: Number(row.expiresAt), revokedAt: null, familyExpiresAt: row.familyExpiresAt === null ? null : Number(row.familyExpiresAt) };
+    }
+    device(row, changes = {}) {
+        return { id: row.id, label: row.label, createdAt: row.createdAt, lastUsedAt: row.lastUsedAt, expiresAt: row.expiresAt, revokedAt: null, ...changes };
+    }
+    /**
+     * Replace a refresh credential. It has exactly one successor, derived on this host. Until that
+     * successor is seen in use (presented itself, or an access credential issued with it
+     * authenticates), the spent credential is answered again with the same successor: a lost
+     * answer, a closed tab or a restart converge on one value and extend nothing. Once the successor
+     * is in use, the spent credential is a replay and ends the link and the links it issued.
+     */
+    refresh(refreshToken) {
+        const outcome = this.transaction(() => this.rotate(refreshToken, false));
+        if (Array.isArray(outcome))
+            throw new WorkspaceRefreshReuseError(outcome);
+        return outcome;
+    }
+    /**
+     * A link code for another browser, issued by this link. It is a lasting grant, so it takes the
+     * link's current, unspent refresh credential and rotates it in the same step, with the successor
+     * counted as in use at once: whoever else holds the spent credential is a replay on their next
+     * refresh, which also ends the link made from this code. An answer lost here is not retried.
+     */
+    link(refreshToken) {
+        const now = this.now(), enrollment = opaque(), enrollmentExpiresAt = now + 5 * 60000;
+        const outcome = this.transaction(() => {
+            const rotated = this.rotate(refreshToken, true);
+            if (Array.isArray(rotated))
+                return rotated;
+            this.db.prepare('DELETE FROM enrollments WHERE expiresAt<=?').run(now);
+            if (Number(this.db.prepare('SELECT count(*) AS n FROM enrollments').get().n) >= 32)
+                throw new FleetError('rate_limited', 'too many pending device links');
+            this.db.prepare('INSERT INTO enrollments VALUES(?,?,?)').run(hash(enrollment), enrollmentExpiresAt, rotated.device.id);
+            return { ...rotated, enrollment, enrollmentExpiresAt };
+        });
+        if (Array.isArray(outcome))
+            throw new WorkspaceRefreshReuseError(outcome);
+        return outcome;
+    }
+    /** Inside a transaction. Returns new credentials, or the devices ended by a replay. `strict` allows no repeat and confirms the successor. */
+    rotate(refreshToken, strict) {
+        if (!refreshShaped(refreshToken))
+            throw new WorkspaceDeviceAuthError();
+        const now = this.now(), key = hash(refreshToken);
+        const row = this.db.prepare('SELECT * FROM refresh_tokens WHERE hash=?').get(key);
+        const device = row && this.live(String(row.deviceId), now);
+        if (!row || !device || device.familyExpiresAt === null)
+            throw new WorkspaceDeviceAuthError();
+        const next = REFRESH_PREFIX + createHmac('sha256', this.rotationKey).update(`ours.fleet.workspace-refresh.v1\0${device.id}\0${refreshToken}`).digest('base64url');
+        if (row.consumedAt === null) {
+            if (Number(row.expiresAt) <= now)
+                throw new WorkspaceDeviceAuthError();
+            const expiresAt = Math.min(now + REFRESH_IDLE_TTL, device.familyExpiresAt);
+            this.db.prepare('UPDATE refresh_tokens SET consumedAt=?,confirmedAt=coalesce(confirmedAt,?) WHERE hash=?').run(now, now, key);
+            this.db.prepare('INSERT INTO refresh_tokens VALUES(?,?,?,?,NULL,?,?)').run(hash(next), device.id, now, expiresAt, strict ? now : null, key);
+            // The link itself lapses with its newest refresh credential.
+            this.db.prepare('UPDATE devices SET expiresAt=?,lastUsedAt=? WHERE id=?').run(expiresAt, now, device.id);
+            return this.grant(this.device(device, { expiresAt, lastUsedAt: now }), device.familyExpiresAt, next, expiresAt, now);
+        }
+        const successor = this.db.prepare('SELECT * FROM refresh_tokens WHERE parent=?').get(key);
+        if (strict || !successor || successor.confirmedAt !== null || successor.consumedAt !== null)
+            return this.revokeRows(device.id, now, true);
+        if (Number(successor.expiresAt) <= now)
+            throw new WorkspaceDeviceAuthError();
+        return this.grant(this.device(device), device.familyExpiresAt, next, Number(successor.expiresAt), now);
+    }
+    /**
+     * One-time move of a fixed bearer to rotating credentials. The device keeps its identity, the
+     * bearer stops working in the same transaction, and the link ends no later than it would have.
+     */
+    exchange(token) {
+        const now = this.now();
+        return this.transaction(() => {
+            const legacy = this.legacy(token, now);
+            const familyExpiresAt = Math.min(legacy.expiresAt, now + FAMILY_TTL), refreshToken = REFRESH_PREFIX + opaque(), refreshExpiresAt = Math.min(now + REFRESH_IDLE_TTL, familyExpiresAt);
+            this.db.prepare('UPDATE devices SET hash=?,familyExpiresAt=?,expiresAt=?,lastUsedAt=? WHERE id=?').run('', familyExpiresAt, refreshExpiresAt, now, legacy.id);
+            this.db.prepare('INSERT INTO refresh_tokens VALUES(?,?,?,?,NULL,NULL,NULL)').run(hash(refreshToken), legacy.id, now, refreshExpiresAt);
+            return this.grant({ ...legacy, expiresAt: refreshExpiresAt, lastUsedAt: now }, familyExpiresAt, refreshToken, refreshExpiresAt, now);
+        });
+    }
+    legacy(token, now) {
+        const row = this.live(typeof token === 'string' ? token.split('.')[0] : '', now);
+        const supplied = Buffer.from(hash(typeof token === 'string' ? token : '')), expected = Buffer.from(row?.hash || '0'.repeat(64));
+        if (!row || row.familyExpiresAt !== null || !timingSafeEqual(supplied, expected))
+            throw new WorkspaceDeviceAuthError();
+        return this.device(row);
+    }
+    /** The device behind an access credential, or behind a fixed bearer while those are still accepted. */
+    authenticate(token) {
+        const now = this.now();
+        if (typeof token === 'string' && token.startsWith(ACCESS_PREFIX)) {
+            const access = token.length <= 128 ? this.db.prepare('SELECT * FROM access_tokens WHERE hash=? AND expiresAt>?').get(hash(token), now) : undefined;
+            const device = access && this.live(String(access.deviceId), now);
+            if (!access || !device || device.familyExpiresAt === null)
+                throw new WorkspaceDeviceAuthError();
+            this.db.prepare('UPDATE devices SET lastUsedAt=? WHERE id=?').run(now, device.id);
+            // Use of this credential shows its refresh credential reached the browser.
+            this.db.prepare('UPDATE refresh_tokens SET confirmedAt=? WHERE hash=? AND confirmedAt IS NULL').run(now, String(access.refresh));
+            return { ...this.device(device, { lastUsedAt: now }), authorizedUntil: Number(access.expiresAt), rotating: true };
+        }
+        const device = this.legacy(token, now);
+        this.db.prepare('UPDATE devices SET lastUsedAt=? WHERE id=?').run(now, device.id);
+        return { ...device, lastUsedAt: now, authorizedUntil: Math.min(device.expiresAt, this.legacySunsetAt), rotating: false };
+    }
+    /** End the link a refresh credential belongs to, named by its SHA-256: a hash can end a link, never use it. */
+    revokeByRefreshHash(refreshHash) {
+        if (typeof refreshHash !== 'string' || !/^[a-f0-9]{64}$/.test(refreshHash))
+            return undefined;
+        const row = this.db.prepare('SELECT deviceId FROM refresh_tokens WHERE hash=?').get(refreshHash);
+        if (!row)
+            return undefined;
+        this.revoke(String(row.deviceId));
+        return String(row.deviceId);
+    }
+    /** Inside a transaction. With cascade, links issued from this one end too. Returns every device ended. */
+    revokeRows(id, now, cascade = false) {
+        const ended = [], pending = [id];
+        while (pending.length) {
+            const current = pending.pop();
+            if (ended.includes(current))
+                continue;
+            ended.push(current);
+            this.db.prepare('UPDATE devices SET revokedAt=? WHERE id=? AND revokedAt IS NULL').run(now, current);
+            this.db.prepare('DELETE FROM enrollments WHERE issuer=?').run(current);
+            this.db.prepare('DELETE FROM access_tokens WHERE deviceId=?').run(current);
+            this.db.prepare('DELETE FROM refresh_tokens WHERE deviceId=?').run(current);
+            if (cascade)
+                for (const child of this.db.prepare('SELECT id FROM devices WHERE issuer=? AND revokedAt IS NULL').all(current))
+                    pending.push(String(child.id));
+        }
+        return ended;
+    }
+    valid(id) { return Boolean(this.live(id, this.now())); }
+    list() { return this.db.prepare('SELECT id,label,createdAt,lastUsedAt,expiresAt,revokedAt FROM devices ORDER BY createdAt DESC LIMIT 256').all().map(row => ({ id: String(row.id), label: String(row.label), createdAt: Number(row.createdAt), lastUsedAt: Number(row.lastUsedAt), expiresAt: Number(row.expiresAt), revokedAt: row.revokedAt === null ? null : Number(row.revokedAt) })); }
+    revoke(id) { this.transaction(() => this.revokeRows(id, this.now())); }
+    /** Retire account links without changing the installation's stable host ID or other data. */
+    revokeAll() {
+        this.transaction(() => { this.db.prepare('UPDATE devices SET revokedAt=? WHERE revokedAt IS NULL').run(this.now()); this.db.exec('DELETE FROM enrollments; DELETE FROM access_tokens; DELETE FROM refresh_tokens'); });
+    }
+    close() { this.db.close(); }
+}

package/dist/web/workspace-tunnel.d.ts

@@ -0,0 +1 @@
+export declare function startWorkspaceTunnel(origin: string): () => Promise<void>;

package/dist/web/workspace-tunnel.js

@@ -0,0 +1,34 @@
+import { spawn } from 'node:child_process';
+import { existsSync, lstatSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { stateRoot } from '../paths.js';
+export function startWorkspaceTunnel(origin) {
+    const dir = join(stateRoot(), 'workspace'), file = join(dir, 'tunnel.json');
+    if (!existsSync(file))
+        return async () => { };
+    const config = JSON.parse(readFileSync(file, 'utf8'));
+    if (config.origin !== origin)
+        throw Error('Workspace tunnel requires its configured public origin');
+    const tokenFile = join(dir, 'connector');
+    if (config.tokenFile !== tokenFile)
+        throw Error('Unexpected connector credential path');
+    const stat = lstatSync(tokenFile);
+    if (!stat.isFile() || stat.isSymbolicLink() || (stat.mode & 0o077) !== 0 || stat.uid !== process.getuid?.())
+        throw Error('Connector credential must be an owned private file');
+    let stopped = false, child, timer, backoff = 1000;
+    const launch = () => {
+        if (stopped)
+            return;
+        child = spawn('cloudflared', ['tunnel', '--no-autoupdate', 'run', '--token-file', tokenFile], { stdio: 'ignore' });
+        let scheduled = false;
+        // Keep an error listener for the child's whole lifetime, including shutdown.
+        const retry = () => { if (scheduled || stopped)
+            return; scheduled = true; timer = setTimeout(launch, backoff); backoff = Math.min(30000, backoff * 2); };
+        child.on('error', retry);
+        child.once('exit', retry);
+    };
+    launch();
+    // A failed spawn has no pid and reports error/close rather than exit.
+    return async () => { stopped = true; clearTimeout(timer); const current = child; if (!current?.pid || current.exitCode !== null || current.signalCode !== null)
+        return; await new Promise(resolve => { const timeout = setTimeout(() => { current.kill('SIGKILL'); resolve(); }, 5000); current.once('close', () => { clearTimeout(timeout); resolve(); }); current.kill('SIGTERM'); }); };
+}

package/dist/workspace-enrollment.d.ts

@@ -0,0 +1,82 @@
+import { type AttachOursClientOptions, type OursClient } from '@ours.network/sdk/client';
+export interface WorkspacePayload {
+    version: 1;
+    appOrigin: string;
+    hostname: string;
+    rootName: string;
+    name: string;
+    surname: string;
+    connectorToken?: string;
+    invitation: string;
+    serverCid: string;
+    challenge: {
+        nonce: string;
+        workspaceId: string;
+        accountId: string;
+        expiresAt: number;
+    };
+}
+export declare function readWorkspacePayload(file: string): WorkspacePayload;
+export declare function decodeWorkspacePayload(input: string, options?: {
+    allowExpired?: boolean;
+}): WorkspacePayload;
+/** Credential-free renewal is allowed only on the host already holding this private connector. */
+export declare function checkWorkspaceConnector(payload: WorkspacePayload): void;
+type DaemonClient = Pick<OursClient, 'listIdentities' | 'chooseIdentity' | 'addContact' | 'listContacts' | 'sendCommand' | 'removeContact' | 'releaseLease' | 'close'>;
+/** How tunnel setup reaches this host's daemon; replaced only by tests. */
+export type AttachDaemonClient = (options: AttachOursClientOptions) => Promise<DaemonClient>;
+/**
+ * Check the Fleet configuration tunnel setup will use, before the one-time command is used.
+ * Reads only; an existing Owner is compared with this host's own Messenger identity.
+ */
+export declare function checkWorkspaceConfiguration(configuration?: string, attach?: AttachDaemonClient): Promise<void>;
+export declare function enrollWorkspace(payload: WorkspacePayload, configuration?: string, options?: {
+    migrateAppOrigin?: boolean;
+    preserveProfile?: boolean;
+    replacingWorkspace?: string;
+    attach?: AttachDaemonClient;
+    contactWaitMs?: number;
+    afterInvitation?: () => void;
+}): Promise<{
+    origin: string;
+    hostWorkspaceId: string;
+    rootCid: string;
+}>;
+/** Only the existing signed-root receipt authorizes the scoped tunnel target. */
+/**
+ * The enrollment server contact exists only to carry the signed binding. Once the account has confirmed
+ * that binding, remove exactly that contact from this host's Messenger, so it does not stay in the
+ * person's chats. The server identity is the one recorded with the binding; nothing else is touched.
+ */
+export declare function removeEnrollmentContact(attach?: AttachDaemonClient): Promise<boolean>;
+export declare function configureWorkspacePort(payload: Pick<WorkspacePayload, 'appOrigin' | 'challenge'>, hostWorkspaceId: string, rootCid: string, port: number): Promise<void>;
+/**
+ * Point the tunnel at this host's port. The account answers only for a confirmed signed binding, and
+ * only after that answer is the enrollment contact removed; a refused or unconfirmed target leaves it,
+ * so the setup can be finished later. A removal that fails is reported and does not undo the setup.
+ */
+export declare function confirmWorkspaceTarget(payload: Pick<WorkspacePayload, 'appOrigin' | 'challenge'>, hostWorkspaceId: string, rootCid: string, port: number, cleanupFailed?: (error: unknown) => void): Promise<void>;
+/** Retire exactly the original registration using the same signed Human root that bound it. */
+export declare function unregisterWorkspace(previous: {
+    workspaceId: string;
+    hostWorkspaceId: string;
+    appOrigin: string;
+    serverCid: string;
+    proofRootCid?: string;
+}, payload: WorkspacePayload, operationNonce: string, attach?: AttachDaemonClient, options?: {
+    request?: typeof fetch;
+    waitMs?: number;
+    checkOnly?: boolean;
+    beforeSend?: () => void;
+    operationExpiresAt?: number;
+    onReceipt?: (status: {
+        deleted?: boolean;
+        retired?: boolean;
+        absent?: boolean;
+        rejected?: boolean;
+        expired?: boolean;
+        deadlineEnforced?: boolean;
+        oldBindingPresent?: boolean;
+    }) => void;
+}): Promise<string>;
+export {};