@platless/axom-cli 0.5.9 → 0.6.52

package/dist/workstation/channels/computer.js

@@ -11,7 +11,8 @@ import { TaskRegistry } from '../update/taskRegistry.js';
 import { toFileError } from '../files/errors.js';
 import { object } from '../tools/validation.js';
 import { isUnaccountedTool } from '../tools/router.js';
-import { requestRootFileExecutors } from '../files/adapters/computerFileFrames.js';
+import { requestRootFileExecutors, fileErrorFrame } from '../files/adapters/computerFileFrames.js';
+import { DeviceEventRouter } from '../runtime/events.js';
 /**
  * Consumes computer frames without serializing long-running commands behind one another.
  * All command failures and post-close sends are contained here because this is called detached
@@ -211,6 +212,20 @@ export async function dispatchComputerFrames(messages, send, execute, tasks = ne
     };
     try {
         for await (const frame of messages) {
+            if (durable.admission?.() === false) {
+                if (frame.t === 'exec_request') {
+                    safeSend({ t: 'exec_exit', id: frame.id, exitCode: null, stdout: '', stderr: 'Registration admission is paused', timedOut: false, truncated: false });
+                    continue;
+                }
+                if (frame.t === 'tool_request' && frame.method !== 'tools.info') {
+                    safeSend({ t: 'tool_result', id: frame.id, ok: false, result: {}, error: 'Registration admission is paused' });
+                    continue;
+                }
+                if (frame.t === 'file_write_request' || frame.t === 'file_mkdir_request') {
+                    safeSend(fileErrorFrame(frame, { code: 'workstation_offline', message: 'Registration admission is paused' }));
+                    continue;
+                }
+            }
             if (frame.t.startsWith('desktop_'))
                 desktop?.onFrame(frame);
             else if (frame.t === 'tool_request')
@@ -279,9 +294,17 @@ export class ComputerChannel {
         return { closed: channel.closed, close: () => channel.close() };
     }
     async dispatch(channel) {
-        const desktop = new DesktopBridge(resolveBrowserBinding(this.options.browserBinding), frame => channel.send(frame), () => channel.bufferedAmount);
-        await dispatchComputerFrames(channel.messages, (frame) => channel.send(frame), this.options.runExec ?? ((request, onOutput, signal) => runExec(request, onOutput, signal)), this.tasks, this.options, this.tools, desktop, {
-            host: this.execs, bufferedAmount: () => channel.bufferedAmount, log: this.options.log,
+        const registrationId = this.options.registrationId;
+        const events = registrationId ? new DeviceEventRouter((_recipient, event) => channel.send(event.payload), new Set([registrationId])) : undefined;
+        const send = (frame) => {
+            if (events && registrationId)
+                events.publish({ scope: 'registration', registrationId, payload: frame });
+            else
+                channel.send(frame);
+        };
+        const desktop = new DesktopBridge(this.options.desktopEnabled === false ? undefined : resolveBrowserBinding(this.options.browserBinding), frame => channel.send(frame), () => channel.bufferedAmount);
+        await dispatchComputerFrames(channel.messages, send, this.options.runExec ?? ((request, onOutput, signal) => runExec(request, onOutput, signal)), this.tasks, this.options, this.tools, desktop, {
+            host: this.execs, bufferedAmount: () => channel.bufferedAmount, log: this.options.log, admission: this.options.admission,
         });
     }
 }

package/dist/workstation/channels/management.js

@@ -1,16 +1,22 @@
 import { deriveSessionKey, randomBytes } from '../crypto.js';
 import { connectEncryptedChannel } from '../connection/encryptedChannel.js';
 import { CLIENT_PACKAGE_NAME, CLIENT_VERSION } from '../version.js';
-import { decodeManagementFrame, encodeManagementFrame, MANAGEMENT_WIRE_DRAINING_VERSION, MANAGEMENT_WIRE_GPU_VERSION, MANAGEMENT_WIRE_KEEPERS_VERSION, MANAGEMENT_WIRE_LOAD_AVERAGES_VERSION, MANAGEMENT_WIRE_METRICS_VERSION, MANAGEMENT_WIRE_MIN_VERSION, MANAGEMENT_WIRE_PRESSURE_VERSION, MANAGEMENT_WIRE_VERSION, } from '../protocol/management.js';
+import { decodeManagementFrame, encodeManagementFrame, MANAGEMENT_WIRE_DRAINING_VERSION, MANAGEMENT_WIRE_GPU_VERSION, MANAGEMENT_WIRE_KEEPERS_VERSION, MANAGEMENT_WIRE_LOAD_AVERAGES_VERSION, MANAGEMENT_WIRE_METRICS_VERSION, MANAGEMENT_WIRE_MIN_VERSION, MANAGEMENT_WIRE_PRESSURE_VERSION, MANAGEMENT_WIRE_VERSION, ManagementFrameAdmission, } from '../protocol/management.js';
 import { bridgesForWire, helloRoster } from '../protocol/common.js';
 import { AGENT_WIRE_MIN_VERSION, AGENT_WIRE_VERSION } from '../protocol/agent.js';
 import { osInfo } from '../osinfo.js';
 import { workstationChannelUrl } from './url.js';
+import { DesktopCapabilityReporter } from '../desktopControl/capabilities.js';
 const protocols = {
     MANAGEMENT: { min: MANAGEMENT_WIRE_MIN_VERSION, max: MANAGEMENT_WIRE_VERSION },
     // COMPUTER v5: durable exec frames (exec_started/attach/status/ack, offsets on exec_output; spec §4.3).
-    COMPUTER: { min: 1, max: 5 }, AGENT: { min: AGENT_WIRE_MIN_VERSION, max: AGENT_WIRE_VERSION },
+    // COMPUTER v6: this client refuses credential storage to the agent file tools (files/credentials.ts); the server sends
+    // file frames only to v6 clients.
+    COMPUTER: { min: 1, max: 6 }, AGENT: { min: AGENT_WIRE_MIN_VERSION, max: AGENT_WIRE_VERSION },
 };
+function toolchainField(toolchain) {
+    return toolchain ? { toolchain: { python: toolchain.python, node: toolchain.node } } : {};
+}
 /** Exported so tests can assert the wire frame's `clientPackage` without opening a socket. */
 export function buildHelloFrame(options, clientNonce) {
     return {
@@ -91,7 +97,16 @@ export function metricsForManagementWire(metrics, serverManagementWire) {
  *
  * Exported for tests; production's only caller is `routeMessages`.
  */
-export function dispatchUpdateCommand(channel, command, onUpdate, serverManagementWire) {
+export function dispatchUpdateCommand(channel, command, onUpdate, serverManagementWire, requiredRemoteUpdatePolicy) {
+    if (requiredRemoteUpdatePolicy && command.remoteForcePolicy !== requiredRemoteUpdatePolicy) {
+        if (channel.state === 'OPEN') {
+            try {
+                channel.send(toClientUpdateStatusFrame(command, { phase: 'FAILED', remoteForcePolicy: 'drain-only', error: 'upgrade_required: the server must support authenticated device update readiness' }, serverManagementWire));
+            }
+            catch { }
+        }
+        return Promise.resolve();
+    }
     return onUpdate(command)
         .then((status) => {
         if (channel.state !== 'OPEN')
@@ -177,9 +192,43 @@ export class ManagementChannel {
     serverManagementWire;
     /** The open channel of the current connection, for frames this client sends unprompted ({@link pushRoster}). */
     channel;
+    desktopReporter;
+    connectionAttempt = 0;
+    generation;
     constructor(options) {
         this.options = options;
     }
+    async receiveDeviceFact(event) {
+        const generation = this.generation;
+        const channel = this.channel;
+        if (event.scope !== 'device' || !generation || channel?.state !== 'OPEN')
+            return;
+        if (event.kind === 'tool-state' && this.options.onExternalAgentsScan) {
+            const bridges = await this.options.onExternalAgentsScan();
+            if (this.generation === generation && this.channel === channel)
+                this.pushRoster(bridges);
+        }
+        else if (event.kind === 'desktop-capability')
+            this.refreshDesktopCapabilities(generation);
+    }
+    refreshDesktopCapabilities(generation) {
+        if (generation === undefined || generation === this.generation)
+            this.desktopReporter?.refresh();
+    }
+    /** T10 reports only on its authenticated current management socket. */
+    sendDesktopState(generation, frame) {
+        if (frame.t === 'desktop_ownership_result' && (this.serverManagementWire ?? 0) < 10)
+            return false;
+        if (generation !== this.generation || (this.serverManagementWire ?? 0) < 9 || this.channel?.state !== 'OPEN')
+            return false;
+        try {
+            this.channel.send(frame);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
     /**
      * Tell the server about a roster that changed without a scan asking (adapter builds moved by Axom,
      * spec §6.1): the same `external_agents_scan_result` frame a scan answers with, under a client-made
@@ -199,14 +248,22 @@ export class ManagementChannel {
         }
     }
     async connect(signal) {
+        const attempt = ++this.connectionAttempt;
+        this.desktopReporter?.dispose();
+        this.desktopReporter = undefined;
+        this.generation = undefined;
+        this.channel = undefined;
         this.serverManagementWire = undefined;
         const nonce = randomBytes(16);
         let initialHeartbeat = true;
+        const admission = new ManagementFrameAdmission(() => attempt === this.connectionAttempt && !signal?.aborted);
         const channel = await connectEncryptedChannel({
             url: workstationChannelUrl(this.options.server, 'management', this.options.allowInsecureWs),
             signal,
             encode: encodeManagementFrame,
             decode: decodeManagementFrame,
+            decodeBytes: decodeManagementFrame,
+            admitFrame: frame => admission.admit(frame),
             heartbeat: (seq, sentAtEpochMs) => this.heartbeat(seq, sentAtEpochMs),
             initialFrame: () => {
                 initialHeartbeat = false;
@@ -226,16 +283,41 @@ export class ManagementChannel {
         if (initialHeartbeat)
             throw new Error('Management proof heartbeat was not sent');
         const ready = await this.nextReady(channel);
+        if (attempt !== this.connectionAttempt || channel.state !== 'OPEN') {
+            channel.close();
+            throw new Error('Management connection superseded');
+        }
         this.serverManagementWire = ready.protocols.MANAGEMENT;
+        this.generation = ready.generation;
+        this.channel = channel;
+        const reporter = new DesktopCapabilityReporter({ selectedWire: this.serverManagementWire, generation: ready.generation,
+            provider: this.options.desktopProvider, send: report => {
+                if (attempt === this.connectionAttempt && this.channel === channel && channel.state === 'OPEN')
+                    channel.send({ t: 'workstation_capabilities', ...report });
+            } });
+        this.desktopReporter = reporter;
+        // Starts before the existing awaited update hook; heartbeat and reporting never await discovery.
+        reporter.refresh();
+        const retire = () => {
+            admission.dispose();
+            reporter.dispose();
+            try {
+                this.options.onClosed?.(ready.generation);
+            }
+            catch { /* transport retirement must complete */ }
+            if (this.channel === channel) {
+                this.channel = undefined;
+                this.generation = undefined;
+                this.desktopReporter = undefined;
+                this.serverManagementWire = undefined;
+            }
+        };
+        void channel.closed.then(retire, retire);
         // A readiness record is evidence from this encrypted, proof-of-key management generation — it
         // is never driven by the local browser/device-authorization flow.
-        await this.options.onReady?.({ generation: ready.generation, release: ready.release });
+        await this.options.onReady?.({ generation: ready.generation, selectedWire: ready.protocols.MANAGEMENT, release: ready.release });
         const pending = new Map();
-        this.channel = channel;
-        void channel.closed.then(() => { if (this.channel === channel)
-            this.channel = undefined; }, () => { if (this.channel === channel)
-            this.channel = undefined; });
-        void this.routeMessages(channel, pending);
+        void this.routeMessages(channel, pending, ready.generation);
         return {
             generation: ready.generation,
             closed: channel.closed,
@@ -255,6 +337,11 @@ export class ManagementChannel {
         };
     }
     async heartbeat(seq, sentAtEpochMs) {
+        const selectedWire = this.serverManagementWire;
+        // Availability may change without restarting the CLI (Desktop sharing is process-owned).
+        // Discovery stays bounded and never delays the heartbeat or creates a capture session.
+        this.desktopReporter?.refresh();
+        const revision = this.desktopReporter?.revision;
         const snapshot = await this.options.snapshot();
         return {
             t: 'heartbeat', seq, sentAtEpochMs, clientVersion: CLIENT_VERSION,
@@ -266,11 +353,13 @@ export class ManagementChannel {
             },
             activeShellTasks: snapshot.activeShellTasks, activeAgentTasks: snapshot.activeAgentTasks,
             protocols, os: osInfo(),
-            ...(this.options.metrics && (this.serverManagementWire ?? 0) >= MANAGEMENT_WIRE_METRICS_VERSION
-                ? { metrics: metricsForManagementWire(this.options.metrics(), this.serverManagementWire) }
+            ...toolchainField(this.options.toolchain?.() ?? null),
+            ...(this.options.metrics && (selectedWire ?? 0) >= MANAGEMENT_WIRE_METRICS_VERSION
+                ? { metrics: metricsForManagementWire(this.options.metrics(), selectedWire) }
                 : {}),
-            ...(snapshot.update ? { update: statusForManagementWire(snapshot.update, this.serverManagementWire) } : {}),
-            ...await keepersForManagementWire(this.options.keepers, this.serverManagementWire, this.options.keepersCapMs),
+            ...(snapshot.update ? { update: statusForManagementWire(snapshot.update, selectedWire) } : {}),
+            ...await keepersForManagementWire(this.options.keepers, selectedWire, this.options.keepersCapMs),
+            ...((selectedWire ?? 0) >= 9 && revision !== undefined ? { capabilitiesRevision: revision } : {}),
         };
     }
     async nextReady(channel) {
@@ -279,9 +368,35 @@ export class ManagementChannel {
                 return frame;
         throw new Error('Management channel closed before ready');
     }
-    async routeMessages(channel, pending) {
+    async routeMessages(channel, pending, generation) {
         try {
             for await (const frame of channel.messages) {
+                if (channel !== this.channel)
+                    break;
+                if (frame.t === 'desktop_automation_prepare') {
+                    if (frame.deviceGeneration === this.generation && this.generation && this.options.onAutomationPrepare)
+                        void this.options.onAutomationPrepare(frame, this.generation).catch(() => { });
+                    continue;
+                }
+                if (frame.t === 'workstation_capabilities_request') {
+                    if ((this.serverManagementWire ?? 0) >= 9 && frame.generation === this.generation)
+                        this.desktopReporter?.refresh();
+                    continue;
+                }
+                if ((frame.t === 'desktop_background' || frame.t === 'desktop_lobby' || frame.t === 'desktop_prepare' || frame.t === 'desktop_cancel' || frame.t === 'desktop_ownership') && (this.serverManagementWire ?? 0) >= 9) {
+                    if (frame.t === 'desktop_ownership' && (this.serverManagementWire ?? 0) < 10)
+                        continue;
+                    if (frame.t !== 'desktop_cancel' && frame.deviceGeneration !== this.generation)
+                        continue;
+                    if (this.options.onDesktopCommand && this.generation) {
+                        // Capture the authenticated generation now: later callbacks cannot borrow a reconnect.
+                        try {
+                            void this.options.onDesktopCommand(frame, this.generation).catch(() => undefined);
+                        }
+                        catch { /* bounded desktop admission failure */ }
+                    }
+                    continue;
+                }
                 if (frame.t === 'channel_ticket') {
                     const queue = pending.get(frame.channel);
                     queue?.shift()?.resolve(frame.ticket);
@@ -290,7 +405,7 @@ export class ManagementChannel {
                 if (frame.t === 'client_update' && this.options.onUpdate) {
                     // Deliberately not awaited — see dispatchUpdateCommand for why inline handling both
                     // stalled this loop for the whole update and threw the final status away.
-                    void dispatchUpdateCommand(channel, frame, this.options.onUpdate, this.serverManagementWire);
+                    void dispatchUpdateCommand(channel, frame, command => this.options.onUpdate(command, generation), this.serverManagementWire, this.options.requiredRemoteUpdatePolicy);
                     continue;
                 }
                 if (frame.t === 'keeper_control' && this.options.onKeeperControl) {

package/dist/workstation/channels/url.js

@@ -11,7 +11,7 @@ function ipv4Octets(hostname) {
     return octets.every((octet) => octet <= 255) ? octets : null;
 }
 /** Deliberately classifies literal names/IPs only: DNS answers must never downgrade transport security. */
-function isTrustedPlaintextHost(rawHostname) {
+export function isTrustedPlaintextHost(rawHostname) {
     const hostname = rawHostname.toLowerCase().replace(/^\[|\]$/g, '');
     if (TRUSTED_PLAINTEXT_NAMES.has(hostname) || hostname.endsWith('.localhost'))
         return true;

package/dist/workstation/config.js

@@ -1,20 +1,34 @@
+import { loadManagedCliInstallSync, npmExecutionContext } from './managedInstall.js';
 import { resolveBrowserBinding } from './desktop/binding.js';
 import { promises as fs } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import yaml from 'js-yaml';
+import { z } from 'zod';
+import { withWorkstationLock } from './control/locks.js';
+import { assertLegacyRoot } from './control/rootFormat.js';
+const localPath = z.string().refine(p => path.isAbsolute(p) && !p.includes('\0'));
+const nativeConfig = z.strictObject({ kind: z.literal('linux-native'), helperPath: localPath, runtimeDir: localPath });
 export function updateServiceContext(configDir = clientDir(), overrides = {}) {
     // config.ts lives in dist/workstation/ after packaging, so two levels up is the installed package root.
     const packageRoot = overrides.packageRoot ?? path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
-    const nodePath = overrides.nodePath ?? process.execPath;
+    const managed = loadManagedCliInstallSync(packageRoot);
+    const nodePath = managed?.nodePath ?? overrides.nodePath ?? process.execPath;
+    const npmPrefix = managed?.prefix ?? overrides.npmPrefix ?? process.env.AXOM_WORKSTATION_NPM_PREFIX ?? path.resolve(packageRoot, '../../../..');
+    // A previous sudo npm command can leave the interactive user's cache root-owned. Updates and
+    // their detached rollback watchdog share a cache owned by this workstation service instead.
+    const env = { ...npmExecutionContext({ prefix: npmPrefix, nodePath }, process.env), NPM_CONFIG_CACHE: path.join(configDir, 'update/npm-cache') };
+    delete env.npm_config_cache;
     return {
         configDir,
+        ...(managed ? { managed } : {}),
+        env,
         platform: overrides.platform ?? (process.platform === 'darwin' ? 'darwin' : 'linux'),
         nodePath,
-        npmPath: overrides.npmPath ?? process.env.AXOM_WORKSTATION_NPM_PATH ?? path.join(path.dirname(nodePath), 'npm'),
+        npmPath: managed?.npmPath ?? overrides.npmPath ?? process.env.AXOM_WORKSTATION_NPM_PATH ?? path.join(path.dirname(nodePath), 'npm'),
         // packageRoot is under lib/node_modules/@platless; climb to npm's global prefix.
-        npmPrefix: overrides.npmPrefix ?? process.env.AXOM_WORKSTATION_NPM_PREFIX ?? path.resolve(packageRoot, '../../../..'),
+        npmPrefix,
         packageRoot,
     };
 }
@@ -25,8 +39,11 @@ export function clientDir() {
     return process.env.AXOM_WORKSTATION_CONFIG_DIR ?? path.join(os.homedir(), '.axom', 'workstation');
 }
 export async function saveClientConfig(dir, cfg) {
-    await fs.mkdir(dir, { recursive: true });
-    await fs.writeFile(path.join(dir, 'config.yml'), yaml.dump(cfg), { mode: 0o600 });
+    await withWorkstationLock(dir, 'operation', async () => {
+        await assertLegacyRoot(dir);
+        await fs.mkdir(dir, { recursive: true });
+        await fs.writeFile(path.join(dir, 'config.yml'), yaml.dump(cfg), { mode: 0o600 });
+    });
 }
 export async function loadClientConfig(dir) {
     const raw = await fs.readFile(path.join(dir, 'config.yml'), 'utf8');
@@ -35,12 +52,19 @@ export async function loadClientConfig(dir) {
         throw new Error('Invalid workstation config: server and workstationId are required; run axom auth again');
     }
     const browserBinding = parsed.browserBinding ? resolveBrowserBinding(parsed.browserBinding, {}) : undefined;
-    return { ...(browserBinding ? { browserBinding } : {}), server: parsed.server, workstationId: parsed.workstationId, ...(Array.isArray(parsed.workspaces) ? { workspaces: parsed.workspaces } : {}) };
+    const desktopProvider = parsed.desktopProvider ? nativeConfig.parse({ ...parsed.desktopProvider,
+        helperPath: parsed.desktopProvider.helperPath === '/usr/local/bin/axom-desktop-helper' ? '/usr/local/bin/axom-desktop-keeper' : parsed.desktopProvider.helperPath,
+    }) : process.env.AXOM_DESKTOP_NATIVE_PROVIDER === '1' ?
+        nativeConfig.parse({ kind: 'linux-native', helperPath: '/usr/local/bin/axom-desktop-keeper', runtimeDir: '/run/axom-desktop' }) : undefined;
+    return { ...(browserBinding ? { browserBinding } : {}), ...(desktopProvider ? { desktopProvider } : {}), server: parsed.server, workstationId: parsed.workstationId, ...(typeof parsed.ownerUserId === 'string' && parsed.ownerUserId ? { ownerUserId: parsed.ownerUserId } : {}), ...(Array.isArray(parsed.workspaces) ? { workspaces: parsed.workspaces } : {}) };
 }
 export async function writeKeys(dir, clientKeyB64, serverPubB64) {
-    await fs.mkdir(dir, { recursive: true });
-    await fs.writeFile(path.join(dir, 'client.key'), clientKeyB64, { mode: 0o600 });
-    await fs.writeFile(path.join(dir, 'server.pub'), serverPubB64);
+    await withWorkstationLock(dir, 'operation', async () => {
+        await assertLegacyRoot(dir);
+        await fs.mkdir(dir, { recursive: true });
+        await fs.writeFile(path.join(dir, 'client.key'), clientKeyB64, { mode: 0o600 });
+        await fs.writeFile(path.join(dir, 'server.pub'), serverPubB64);
+    });
 }
 export async function readKeys(dir) {
     const clientKey = Buffer.from((await fs.readFile(path.join(dir, 'client.key'), 'utf8')).trim(), 'base64');

package/dist/workstation/connection/encryptedChannel.js

@@ -279,7 +279,10 @@ export function connectEncryptedChannel(options) {
             if (!isBinary)
                 return;
             try {
-                const frame = options.decode(crypto.open(sessionKey, bytes).toString());
+                const plaintext = crypto.open(sessionKey, bytes);
+                const frame = options.decodeBytes ? options.decodeBytes(plaintext) : options.decode(plaintext.toString());
+                if (options.admitFrame && !options.admitFrame(frame))
+                    return;
                 const acknowledged = [...outstandingAcks].some((sequence) => options.isHeartbeatAck(frame, sequence));
                 // A correctly encrypted and decoded frame proves the peer is still reachable. Heartbeat
                 // acknowledgements are one such frame, but computer streaming/agent events may legitimately

package/dist/workstation/control/bindingStore.js

@@ -0,0 +1,204 @@
+import { assertLockOwnership } from './locks.js';
+import { createHash, randomUUID } from 'node:crypto';
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import yaml from 'js-yaml';
+import { loadClientConfig } from '../config.js';
+import { privateDirectory } from '../keepers/kit/paths.js';
+import { bindingSchema, operationRecordSchema, LocalControlError } from './protocol.js';
+import { normalizeWorkstationServer } from './serverIdentity.js';
+import { assertLegacyRoot } from './rootFormat.js';
+const IDENTITY_FILES = ['client.key', 'server.pub', 'config.yml'];
+const missing = (error) => error.code === 'ENOENT';
+async function readPrivateFile(file) {
+    const stat = await fs.lstat(file);
+    if (!stat.isFile() || stat.isSymbolicLink() || (process.getuid && stat.uid !== process.getuid()) || stat.size > 1_048_576)
+        throw new Error('Unsafe workstation identity file');
+    return fs.readFile(file, 'utf8');
+}
+async function exists(file) {
+    try {
+        await fs.lstat(file);
+        return true;
+    }
+    catch (error) {
+        if (missing(error))
+            return false;
+        throw error;
+    }
+}
+async function atomicWrite(file, value) {
+    assertLockOwnership();
+    const temporary = `${file}.${randomUUID()}.tmp`;
+    try {
+        const handle = await fs.open(temporary, 'wx', 0o600);
+        try {
+            await handle.writeFile(value);
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        await fs.rename(temporary, file);
+    }
+    finally {
+        await fs.rm(temporary, { force: true });
+    }
+}
+async function syncDirectory(directory) {
+    const handle = await fs.open(directory, 'r');
+    try {
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+}
+function validateKeys(keys) {
+    for (const value of [keys.clientKey, keys.serverPub]) {
+        if (!/^[A-Za-z0-9+/]{43}=$/.test(value) || Buffer.from(value, 'base64').length !== 32 || Buffer.from(value, 'base64').toString('base64') !== value) {
+            throw new LocalControlError('CORRUPT_IDENTITY', 'Workstation connection keys are invalid');
+        }
+    }
+}
+function bindingOf(config) {
+    return bindingSchema.parse({ server: normalizeWorkstationServer(config.server), workstationId: config.workstationId, ...(config.ownerUserId ? { ownerUserId: config.ownerUserId } : {}) });
+}
+/** Caller holds the shared operation lock for every mutating method. */
+export class BindingStore {
+    directory;
+    pending;
+    constructor(directory) {
+        this.directory = directory;
+        this.pending = path.join(directory, 'identity.pending');
+    }
+    async inspect() {
+        const pending = await exists(this.pending);
+        const present = await Promise.all(IDENTITY_FILES.map(file => exists(path.join(this.directory, file))));
+        if (!present.some(Boolean))
+            return { binding: null, revision: 'unregistered', identityState: pending ? 'incomplete' : 'absent' };
+        let readableBinding = null;
+        let configDigest = 'corrupt';
+        try {
+            configDigest = createHash('sha256').update(await readPrivateFile(path.join(this.directory, 'config.yml'))).digest('hex');
+            await readPrivateFile(path.join(this.directory, 'config.yml'));
+            const binding = bindingOf(await loadClientConfig(this.directory));
+            readableBinding = binding;
+            const keys = { clientKey: (await readPrivateFile(path.join(this.directory, 'client.key'))).trim(), serverPub: (await readPrivateFile(path.join(this.directory, 'server.pub'))).trim() };
+            validateKeys(keys);
+            const revision = createHash('sha256').update(JSON.stringify(binding)).update('\0').update(keys.clientKey).update('\0').update(keys.serverPub).digest('hex');
+            return { binding, revision, identityState: pending ? 'incomplete' : 'ready' };
+        }
+        catch {
+            return { binding: readableBinding, revision: configDigest, identityState: pending ? 'incomplete' : 'corrupt' };
+        }
+    }
+    async history() {
+        try {
+            const data = JSON.parse(await readPrivateFile(path.join(this.directory, 'binding-history.json')));
+            if (!Array.isArray(data))
+                throw new Error('Invalid binding history');
+            return data.map(value => bindingSchema.parse(value));
+        }
+        catch (error) {
+            if (missing(error))
+                return [];
+            throw new LocalControlError('CORRUPT_IDENTITY', 'Workstation binding history is unreadable');
+        }
+    }
+    async recover() {
+        await assertLegacyRoot(this.directory);
+        if (!await exists(this.pending))
+            return;
+        const stat = await fs.lstat(this.pending);
+        if (!stat.isDirectory() || stat.isSymbolicLink() || (process.getuid && stat.uid !== process.getuid()))
+            throw new LocalControlError('CORRUPT_IDENTITY', 'Unsafe pending workstation identity');
+        let marker;
+        try {
+            marker = await readPrivateFile(path.join(this.pending, 'ready'));
+        }
+        catch {
+            throw new LocalControlError('OUTCOME_UNKNOWN', 'Registration needs verification: incomplete local transaction');
+        }
+        if (marker === 'clear') {
+            await this.finishClear();
+            return;
+        }
+        if (marker !== '1')
+            throw new LocalControlError('CORRUPT_IDENTITY', 'Unknown workstation identity transaction');
+        const configText = await readPrivateFile(path.join(this.pending, 'config.yml'));
+        const config = await loadClientConfig(this.pending);
+        bindingOf(config);
+        const keys = { clientKey: (await readPrivateFile(path.join(this.pending, 'client.key'))).trim(), serverPub: (await readPrivateFile(path.join(this.pending, 'server.pub'))).trim() };
+        validateKeys(keys);
+        const operation = operationRecordSchema.parse(JSON.parse(await readPrivateFile(path.join(this.pending, 'operation.json'))));
+        let history;
+        if (await exists(path.join(this.pending, 'binding-history.json'))) {
+            const staged = JSON.parse(await readPrivateFile(path.join(this.pending, 'binding-history.json')));
+            if (!Array.isArray(staged))
+                throw new LocalControlError('CORRUPT_IDENTITY', 'Invalid staged binding history');
+            history = staged.map(value => bindingSchema.parse(value));
+        }
+        // All staging is validated before any existing identity file changes.
+        for (const [name, value] of [['client.key', keys.clientKey], ['server.pub', keys.serverPub], ['config.yml', configText]])
+            await atomicWrite(path.join(this.directory, name), value);
+        if (history)
+            await atomicWrite(path.join(this.directory, 'binding-history.json'), JSON.stringify(history));
+        await atomicWrite(path.join(this.directory, 'operation.json'), JSON.stringify(operation));
+        await syncDirectory(this.directory);
+        await fs.rm(this.pending, { recursive: true });
+        await syncDirectory(this.directory);
+    }
+    async commit(config, keys, operation, repair = false) {
+        await assertLegacyRoot(this.directory);
+        const binding = bindingOf(config);
+        validateKeys(keys);
+        const safeOperation = operationRecordSchema.parse(operation);
+        await privateDirectory(this.directory);
+        await this.recover();
+        const current = await this.inspect();
+        if (current.identityState === 'corrupt' && !(repair && current.binding && (!current.binding.ownerUserId || current.binding.ownerUserId === binding.ownerUserId) && current.binding.server === binding.server && current.binding.workstationId === binding.workstationId))
+            throw new LocalControlError('CORRUPT_IDENTITY', 'Existing workstation identity needs repair');
+        const history = await this.history();
+        for (const previous of [current.binding, binding])
+            if (previous) {
+                const i = history.findIndex(item => item.server === previous.server && item.ownerUserId === previous.ownerUserId);
+                if (i >= 0)
+                    history.splice(i, 1);
+                history.push(previous);
+            }
+        await fs.mkdir(this.pending, { mode: 0o700 });
+        for (const [name, value] of Object.entries({
+            'config.yml': yaml.dump({ ...config, server: binding.server }), 'client.key': keys.clientKey, 'server.pub': keys.serverPub,
+            'operation.json': JSON.stringify(safeOperation), 'binding-history.json': JSON.stringify(history),
+        }))
+            await atomicWrite(path.join(this.pending, name), value);
+        await atomicWrite(path.join(this.pending, 'ready'), '1');
+        await syncDirectory(this.pending);
+        await syncDirectory(this.directory);
+        await this.recover();
+    }
+    async clear(expectedRevision) {
+        await assertLegacyRoot(this.directory);
+        await this.recover();
+        const current = await this.inspect();
+        if (current.revision !== expectedRevision || current.identityState !== 'ready')
+            throw new LocalControlError('BINDING_CONFLICT', 'Workstation identity changed; check it again');
+        await fs.mkdir(this.pending, { mode: 0o700 });
+        await atomicWrite(path.join(this.pending, 'clear.json'), JSON.stringify(current.binding));
+        await atomicWrite(path.join(this.pending, 'ready'), 'clear');
+        await syncDirectory(this.pending);
+        await syncDirectory(this.directory);
+        await this.finishClear();
+    }
+    async finishClear() {
+        const removed = bindingSchema.parse(JSON.parse(await readPrivateFile(path.join(this.pending, 'clear.json'))));
+        const history = (await this.history()).filter(item => item.server !== removed.server || item.workstationId !== removed.workstationId);
+        await atomicWrite(path.join(this.directory, 'binding-history.json'), JSON.stringify(history));
+        for (const name of [...IDENTITY_FILES, 'operation.json'])
+            await fs.rm(path.join(this.directory, name), { force: true });
+        await syncDirectory(this.directory);
+        await fs.rm(this.pending, { recursive: true });
+        await syncDirectory(this.directory);
+    }
+}