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

package/README.md

@@ -175,7 +175,9 @@ never enables it or requests root privileges.
 Use `ours-fleet web revoke-all` to revoke every linked device and active
 session. Only a domain-separated SHA-256 device-secret hash and bounded
 timestamps are stored in the owner-private fleet state directory (`0700`
-directory, `0600` atomic file). The link and revoke controls use an
+directory, `0600` atomic file). App browser links use 5-minute access
+credentials and rotating refresh credentials; see
+[workspace onboarding](docs/workspace-onboarding.md#browser-link-credentials). The link and revoke controls use an
 owner-private Unix socket; local processes running as the same OS user are
 therefore inside the trust boundary.
 

package/dist/build-info.json

@@ -1,9 +1,9 @@
 {
-  "version": "1.2.0-nightly.59",
-  "buildId": "ec27a9a1f17b",
-  "commit": "92cc074f0a71a287f27f89787c4eefdbac9207e8",
+  "version": "1.2.0-nightly.60",
+  "buildId": "79a456ff560c",
+  "commit": "869d23c6d674d33b832c2b8ae97daaea2d5048b3",
   "dirty": true,
-  "builtAt": "2026-10-13T11:05:39.720Z",
+  "builtAt": "2026-10-13T12:13:09.187Z",
   "capabilities": [
     "managed-cli.codex-reasoning-effort-v1",
     "managed-cli.setup-v1",

package/dist/web/auth.d.ts

@@ -9,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;
@@ -20,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;
@@ -37,6 +41,7 @@ export declare class WebAuth {
     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, workspaceDevices?: WorkspaceDeviceStore | undefined, appOrigin?: string);
     get bootstrapSecret(): string;
@@ -66,9 +71,22 @@ 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(sessionId: string, close: () => void): () => void;
+    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(): {
@@ -83,11 +101,26 @@ export declare class WebAuth {
         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;

package/dist/web/auth.js

@@ -1,4 +1,4 @@
-import { WorkspaceDeviceAuthError } from './workspace-devices.js';
+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';
@@ -25,6 +25,7 @@ export class WebAuth {
     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' }, workspaceDevices, appOrigin = 'https://app.ours.network') {
         this._origin = _origin;
@@ -121,7 +122,8 @@ export class WebAuth {
                 throw new WorkspaceDeviceAuthError('workspace bearer credential is invalid');
             const device = this.requireWorkspaceDevices().authenticate(authorization.slice(7));
             const id = `workspace:${device.id}`;
-            const session = { id, csrf: '', createdAt: device.createdAt, lastSeenAt: this.now(), absoluteExpiresAt: device.expiresAt };
+            // 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)
@@ -162,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() };
@@ -177,39 +180,80 @@ export class WebAuth {
         const session = this.sessions.get(ticket.sessionId);
         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);
-        const expiry = setInterval(() => { const session = this.sessions.get(sessionId); if (!session || session.absoluteExpiresAt <= this.now() || (sessionId.startsWith('workspace:') && !this.workspaceDevices?.valid(sessionId.slice(10))))
-            this.removeSession(sessionId); }, 1000);
+        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(sessionId, close) {
+    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 expiry = setInterval(() => { const session = this.sessions.get(sessionId); if (!session || session.absoluteExpiresAt <= this.now() || (sessionId.startsWith('workspace:') && !this.workspaceDevices?.valid(sessionId.slice(10))))
-            this.removeSession(sessionId); }, 1000);
+        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 (!transports.size)
+        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');
@@ -228,10 +272,69 @@ export class WebAuth {
     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);
@@ -257,6 +360,9 @@ export class WebAuth {
         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/prefix-gateway.js

@@ -106,7 +106,8 @@ export function createPrefixGateway(options) {
     const track = (authHeaders, session, close) => {
         if (!session)
             return () => { };
-        const unbind = auth.bindTransport(session.id, close);
+        // The session authenticated for this request, with its own deadline, not whatever is current later.
+        const unbind = auth.bindTransport(session, close);
         const timer = setInterval(() => { try {
             auth.authenticate({ headers: authHeaders });
         }

package/dist/web/server.js

@@ -134,10 +134,41 @@ export async function buildWebServer(services, boundary, options = {}) {
             throw new FleetError('invalid_request', 'device enrollment body required');
         return auth.enrollWorkspace(request, input);
     });
-    app.post('/api/v1/devices/link', async (request) => {
+    // Refresh credentials travel between the account server and this host; these routes refuse browsers.
+    const refreshInput = (request, name) => {
+        const value = request.body?.[name];
+        if (typeof value !== 'string')
+            throw new FleetError('invalid_request', `${name} is required`);
+        return value;
+    };
+    app.post('/api/v1/devices/refresh', async (request, reply) => {
+        reply.header('Cache-Control', 'no-store');
+        return auth.refreshWorkspace(request, refreshInput(request, 'refreshToken'));
+    });
+    app.post('/api/v1/devices/exchange', async (request, reply) => {
+        reply.header('Cache-Control', 'no-store');
+        return auth.exchangeWorkspace(request);
+    });
+    app.post('/api/v1/devices/revoke', async (request) => ({ revoked: auth.revokeWorkspaceRefresh(request, refreshInput(request, 'refreshHash')) }));
+    app.post('/api/v1/devices/link', async (request, reply) => {
+        const proof = request.body?.refreshToken;
+        if (proof !== undefined) {
+            reply.header('Cache-Control', 'no-store');
+            const { enrollment, enrollmentExpiresAt, ...credentials } = auth.linkWorkspaceDevice(request, refreshInput(request, 'refreshToken'));
+            return { ...credentials, code: { version: 1, origin: auth.origin, enrollment, workspaceId: credentials.workspaceId, expiresAt: enrollmentExpiresAt } };
+        }
         const session = auth.authenticate(request, true);
+        // A short-lived access credential must not be able to create a lasting one.
+        if (session.rotating)
+            throw new FleetError('forbidden', 'linking another device requires this link\'s refresh credential');
         return { version: 1, origin: auth.origin, ...auth.workspaceEnrollment(session.id) };
     });
+    app.get('/api/v1/devices/current', async (request) => {
+        const session = auth.authenticate(request);
+        if (!session.id.startsWith('workspace:'))
+            throw new FleetError('resource_not_found', 'no workspace device');
+        return { deviceId: session.id.slice(10), authorizedUntil: session.absoluteExpiresAt };
+    });
     app.get('/api/v1/devices', async (request) => { auth.authenticate(request); return { devices: auth.listWorkspaceDevices() }; });
     app.delete('/api/v1/devices/:id', async (request) => { auth.authenticate(request, true); auth.revokeWorkspaceDevice(request.params.id); return { revoked: true }; });
     app.get('/api/v1/meta', async (request) => {
@@ -1003,7 +1034,9 @@ export async function buildWebServer(services, boundary, options = {}) {
         const write = (value) => { if (!ended && !reply.raw.write(JSON.stringify(value) + '\n'))
             close(); };
         reply.raw.once('close', close);
-        unbind = auth.bindTransport(browser.id, close);
+        // A voice session outlives one access credential; its page renews this stream by name.
+        const renewal = browser.rotating ? randomBytes(32).toString('base64url') : undefined;
+        unbind = auth.bindTransport(browser, close, renewal);
         try {
             follow = await control.followConversation({
                 after: page.nextCursor,
@@ -1012,7 +1045,7 @@ export async function buildWebServer(services, boundary, options = {}) {
                     close();
                 }
                 else
-                    write({ ready: true }); },
+                    write({ ready: true, ...(renewal ? { renewal } : {}) }); },
                 onEvent: event => { if (event.sessionGeneration !== generation) {
                     write({ error: 'Agent session changed. Start live voice again.' });
                     close();
@@ -1021,9 +1054,11 @@ export async function buildWebServer(services, boundary, options = {}) {
             });
             if (ended)
                 follow.close();
+            // A renewable stream is ended by its own deadline and by revocation, not by the first credential's expiry.
             else
                 heartbeat = setInterval(() => { try {
-                    auth.authenticate(request);
+                    if (!renewal)
+                        auth.authenticate(request);
                     write({ heartbeat: true });
                 }
                 catch {
@@ -1035,6 +1070,7 @@ export async function buildWebServer(services, boundary, options = {}) {
             close();
         }
     });
+    app.post('/api/v1/transports/:id/renew', async (request) => auth.renewTransport(request, request.params.id));
     app.post('/api/v1/ws-tickets', async (request) => {
         const body = request.body;
         if (!body?.purpose || !['events', 'conversation'].includes(body.purpose))
@@ -1069,7 +1105,7 @@ export async function buildWebServer(services, boundary, options = {}) {
         requireSubprotocol(request, 'ours-fleet-events.v1');
         authorizeSocket(socket, request, async (hello) => {
             const session = auth.consumeTicket(request, String(hello.ticket ?? ''), 'events');
-            auth.bindSocket(session.id, socket);
+            auth.bindSocket(session, socket);
             const detach = events.attach(socket, typeof hello.lastEventId === 'string' ? hello.lastEventId : undefined);
             socket.on('close', detach);
             socket.send(JSON.stringify({ kind: 'ready', at: new Date().toISOString() }));
@@ -1079,7 +1115,7 @@ export async function buildWebServer(services, boundary, options = {}) {
         requireSubprotocol(request, 'ours-fleet-conversation.v1');
         authorizeSocket(socket, request, async (hello) => {
             const session = auth.consumeTicket(request, String(hello.ticket ?? ''), 'conversation', request.params.id);
-            auth.bindSocket(session.id, socket);
+            auth.bindSocket(session, socket);
             const control = await services.session(request.params.id);
             if (!control.followConversation)
                 throw new FleetError('capability_unavailable', 'this role has no conversation ledger');

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

@@ -3,6 +3,21 @@ import { FleetError } from '../application/errors.js';
 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;
@@ -11,22 +26,78 @@ export interface WorkspaceDevice {
     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;
     };
-    enroll(enrollment: string, workspaceId: string, label: string): {
+    /** 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;
     };
-    authenticate(token: string): WorkspaceDevice;
+    /** 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;

package/dist/web/workspace-devices.js

@@ -1,5 +1,5 @@
 import { createRequire } from 'node:module';
-import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
+import { createHash, createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
 import { mkdirSync, chmodSync } from 'node:fs';
 import { join } from 'node:path';
 import { stateRoot } from '../paths.js';
@@ -10,10 +10,33 @@ const hash = (value) => createHash('sha256').update(value).digest('hex');
 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');
@@ -26,76 +49,229 @@ export class WorkspaceDeviceStore {
       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);`);
-        this.db.prepare('INSERT OR IGNORE INTO metadata VALUES(?,?)').run('workspaceId', opaque());
-        this.workspaceId = String(this.db.prepare('SELECT value FROM metadata WHERE key=?').get('workspaceId').value);
+        // 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());
     }
-    mint(issuer = null) {
-        const now = this.now(), enrollment = opaque(), expiresAt = now + 5 * 60000;
+    transaction(run) {
         this.db.exec('BEGIN IMMEDIATE');
         try {
-            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);
+            const result = run();
             this.db.exec('COMMIT');
-            return { enrollment, workspaceId: this.workspaceId, expiresAt };
+            return result;
         }
         catch (error) {
             this.db.exec('ROLLBACK');
             throw error;
         }
     }
-    enroll(enrollment, workspaceId, label) {
+    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()}`;
-        this.db.exec('BEGIN IMMEDIATE');
-        try {
+        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.db.prepare('SELECT id FROM devices WHERE id=? AND revokedAt IS NULL AND expiresAt>?').get(code.issuer, now))
+            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 device = { id, label: label.trim(), createdAt: now, lastUsedAt: now, expiresAt: now + 90 * 86400000, revokedAt: null };
-            this.db.prepare('INSERT INTO devices VALUES(?,?,?,?,?,?,NULL)').run(id, hash(token), device.label, now, now, device.expiresAt);
-            this.db.exec('COMMIT');
-            return { token, device, workspaceId };
-        }
-        catch (error) {
-            this.db.exec('ROLLBACK');
-            throw error;
-        }
+            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);
+        });
     }
-    authenticate(token) {
-        const id = typeof token === 'string' ? token.split('.')[0] : '', now = this.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);
-        const supplied = Buffer.from(hash(token || '')), expected = Buffer.from(String(row?.hash || '0'.repeat(64)));
-        if (!row || !timingSafeEqual(supplied, expected))
+        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();
-        this.db.prepare('UPDATE devices SET lastUsedAt=? WHERE id=?').run(now, id);
-        return { id, label: String(row.label), createdAt: Number(row.createdAt), lastUsedAt: now, expiresAt: Number(row.expiresAt), revokedAt: null };
+        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);
+        });
     }
-    valid(id) { return Boolean(this.db.prepare('SELECT id FROM devices WHERE id=? AND revokedAt IS NULL AND expiresAt>?').get(id, this.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.db.prepare('UPDATE devices SET revokedAt=? WHERE id=? AND revokedAt IS NULL').run(this.now(), id); this.db.prepare('DELETE FROM enrollments WHERE issuer=?').run(id); }
+    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.db.exec('BEGIN IMMEDIATE');
-        try {
-            this.db.prepare('UPDATE devices SET revokedAt=? WHERE revokedAt IS NULL').run(this.now());
-            this.db.exec('DELETE FROM enrollments');
-            this.db.exec('COMMIT');
-        }
-        catch (error) {
-            this.db.exec('ROLLBACK');
-            throw error;
-        }
+        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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ours.network/fleet",
-  "version": "1.2.0-nightly.59",
+  "version": "1.2.0-nightly.60",
   "description": "Harness-agnostic fleet of persistent, identity-bound AI agents. Declarative fleet.yaml, managed native/ACP sessions, supervision, and ours.network messaging.",
   "type": "module",
   "license": "FSL-1.1-Apache-2.0",