@platless/axom-cli 0.6.36 → 0.6.52

package/dist/workstation/daemonctl.js

@@ -1,10 +1,11 @@
 import os from 'node:os';
 import { BindingStore } from './control/bindingStore.js';
-import { stopRuntime } from './control/runtimeClient.js';
+import { inspectRuntime, stopRuntime } from './control/runtimeClient.js';
 import { LocalControlError } from './control/protocol.js';
 import { normalizeWorkstationServer } from './control/serverIdentity.js';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { randomUUID } from 'node:crypto';
 import { clientDir, loadClientConfig, updateServiceContext } from './config.js';
 import { createServiceManager } from './service/installer.js';
 import { buildServicePath } from './service/types.js';
@@ -12,6 +13,16 @@ import { loginShellPath } from './service/loginShell.js';
 import { KeeperLauncher } from './keepers/kit/launcher.js';
 import { stopKeepers } from './keepers/stop.js';
 import { assertRuntimeRestartSafe } from './control/restartGuard.js';
+import { promises as fs } from 'node:fs';
+import { inspectDeviceRuntime, prepareDeviceRuntimeStop, stopDeviceRuntime } from './control/runtimeClient.js';
+import { assertDeviceUpdateTransitionSafe } from './control/daemonIdentity.js';
+import { RegistrationStore } from './registrations/store.js';
+import { readLegacyRegistrationSources, assertRegistrationEnrollmentAdmission } from './registrations/migration.js';
+import { assertDeviceGuard } from './control/deviceProtocol.js';
+import { resolveRegistrationOwnership } from './runtime/ownership.js';
+import { captureStartupPackageEvidence } from './update/deviceHealth.js';
+import { CLIENT_VERSION } from './version.js';
+import { readDeviceBootstrapRecovery } from './update/recoveryPlan.js';
 const __filename = fileURLToPath(import.meta.url);
 /**
  * The package's real npm bin entry (`package.json`'s `bin.axom`), given the directory a compiled
@@ -58,6 +69,10 @@ export function serviceContext() {
         ...(managed.managed ? { npmConfigPrefix: managed.managed.prefix } : {}),
     };
 }
+async function installationServiceContext(base, shellPath = loginShellPath) {
+    const loginPath = await shellPath();
+    return loginPath ? { ...base, pathEnv: buildServicePath(`${loginPath}:${process.env.PATH ?? ''}`, path.dirname(base.nodePath)) } : base;
+}
 /** The workstation's keepers stopped (see {@link DaemonControllerDeps.stopKeepers}); an unregistered client has none. */
 async function stopRegisteredKeepers() {
     const configDir = clientDir();
@@ -106,11 +121,7 @@ export function createDaemonController(overrides = {}) {
             // itself after an update they are not, and only the login shell knows where the user's CLIs
             // are — see loginShellPath for why reusing the service's own PATH would make a machine
             // reinstall its own blind spot.
-            const shellPath = await loginShellPath();
-            const base = serviceContext();
-            const context = shellPath
-                ? { ...base, pathEnv: buildServicePath(`${shellPath}:${process.env.PATH ?? ''}`, path.dirname(base.nodePath)) }
-                : base;
+            const context = await installationServiceContext(serviceContext());
             await deps.service(context).install({ interactive: true });
         },
         // The workstation is stopped by the user: what its keepers host ends too (the daemon first, so nothing relaunches them).
@@ -175,10 +186,137 @@ export function createDaemonController(overrides = {}) {
         },
     };
 }
+export function createDeviceDaemonController(directory, overrides = {}) {
+    const context = overrides.context ?? (() => ({ ...serviceContext(), configDir: directory }));
+    const service = overrides.service ?? ((input) => createServiceManager(input ?? context()));
+    const store = new RegistrationStore(directory);
+    const runtime = async () => {
+        try {
+            return (await inspectDeviceRuntime(directory)).runtime;
+        }
+        catch {
+            const legacy = await inspectRuntime(directory);
+            if (legacy.state !== 'stopped')
+                throw new LocalControlError('OUTCOME_UNKNOWN', 'The existing owner is not a verified device daemon');
+            return { state: 'stopped', generation: null, mode: 'unknown' };
+        }
+    };
+    const checked = async (options) => {
+        if (options) {
+            const inspection = await inspectDeviceRuntime(directory);
+            assertDeviceGuard(options.guard, inspection);
+            return inspection.runtime;
+        }
+        return runtime();
+    };
+    const terminateKeepers = async () => {
+        const inspection = await store.inspect();
+        if (!inspection.known || inspection.entries.some(entry => entry.state !== 'ready'))
+            throw new LocalControlError('OUTCOME_UNKNOWN', 'Cannot verify every owned keeper namespace');
+        for (const registration of await store.list()) {
+            const sources = await readLegacyRegistrationSources(directory, registration.id);
+            const ownership = await resolveRegistrationOwnership(registration, sources);
+            const launcher = new KeeperLauncher({ configDir: registration.keeperConfigDirectory, workstationId: registration.workstationId, server: sources?.keeperServer ?? registration.server, ownership });
+            const reports = await stopKeepers(launcher);
+            if (reports.some(report => !report.result.stopped))
+                throw new LocalControlError('OUTCOME_UNKNOWN', 'A workstation keeper has not stopped');
+        }
+    };
+    const finishPrepared = async (generation, mode) => {
+        const current = await runtime();
+        if (current.state === 'stopped')
+            return;
+        if (current.generation !== generation)
+            throw new LocalControlError('BINDING_CONFLICT', 'A successor device daemon replaced the prepared owner');
+        await stopDeviceRuntime(directory, generation, mode);
+    };
+    return {
+        async install(options) {
+            const installation = await installationServiceContext(context(), overrides.loginShellPath);
+            if (!path.isAbsolute(installation.cliPath) || path.resolve(installation.cliPath) !== installation.cliPath || path.basename(installation.cliPath) !== 'cli.js' || path.basename(path.dirname(installation.cliPath)) !== 'dist')
+                throw new LocalControlError('OUTCOME_UNKNOWN', 'Installed service entrypoint must identify its exact dist/cli.js package');
+            const startup = await captureStartupPackageEvidence(path.dirname(path.dirname(installation.cliPath)), CLIENT_VERSION);
+            await assertDeviceUpdateTransitionSafe(directory, startup);
+            if (options) {
+                const recovery = await readDeviceBootstrapRecovery(directory, startup);
+                const transaction = recovery?.transaction;
+                if (!transaction || transaction.lifecycle !== 'provision-and-arm' || transaction.phase !== 'RESTARTING' || transaction.installation !== 'started' || transaction.installedRollback || transaction.recoveryRequired || transaction.initiatingDaemonGeneration !== options.updateGeneration)
+                    throw new LocalControlError('OUTCOME_UNKNOWN', 'Service replacement requires the original active device update handoff');
+                const current = await inspectDeviceRuntime(directory);
+                if (current.runtime.state !== 'running' || current.runtime.generation !== options.updateGeneration)
+                    throw new LocalControlError('BINDING_CONFLICT', 'The original device update owner changed before service replacement');
+            }
+            await service(installation).install({ interactive: true });
+        },
+        async start(options) { if ((await checked(options)).state === 'running')
+            return; await assertDeviceUpdateTransitionSafe(directory); await assertRegistrationEnrollmentAdmission(directory); await service().start(); },
+        async stop(options) {
+            const current = await checked(options);
+            const manager = service();
+            if (current.generation && current.mode === 'launchd') {
+                await prepareDeviceRuntimeStop(directory, current.generation, 'terminate', options?.operationId ?? randomUUID());
+                await manager.stop();
+                await finishPrepared(current.generation, 'terminate');
+            }
+            else {
+                if (current.generation)
+                    await stopDeviceRuntime(directory, current.generation, 'terminate');
+                await manager.stop();
+            }
+            if (!current.generation)
+                await terminateKeepers();
+        },
+        async uninstall(options) {
+            const current = await checked(options);
+            const manager = service();
+            if (current.generation && current.mode === 'launchd') {
+                await prepareDeviceRuntimeStop(directory, current.generation, 'terminate', options?.operationId ?? randomUUID());
+                await manager.uninstall();
+                await finishPrepared(current.generation, 'terminate');
+            }
+            else {
+                if (current.generation)
+                    await stopDeviceRuntime(directory, current.generation, 'terminate');
+                await manager.uninstall();
+            }
+            if (!current.generation)
+                await terminateKeepers();
+        },
+        async restart(options) {
+            const current = await checked(options);
+            const manager = service();
+            if (current.generation) {
+                await (overrides.restartSafe ?? (generation => assertRuntimeRestartSafe(directory, generation)))(current.generation);
+                if (current.mode === 'launchd') {
+                    await prepareDeviceRuntimeStop(directory, current.generation, 'detach', options?.operationId ?? randomUUID());
+                    await manager.stop();
+                    await finishPrepared(current.generation, 'detach');
+                    await manager.restart();
+                    return;
+                }
+                await stopDeviceRuntime(directory, current.generation, 'detach');
+            }
+            await manager.restart();
+        },
+        async status() { const current = await runtime(); return { running: current.state === 'running' }; },
+    };
+}
+async function deviceControllerSelected() {
+    for (const name of ['device.json', 'legacy-migration.json'])
+        try {
+            await fs.lstat(path.join(clientDir(), name));
+            return true;
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+    return false;
+}
 const controller = createDaemonController();
-export const install = () => controller.install();
-export const uninstall = () => controller.uninstall();
-export const start = () => controller.start();
-export const stop = () => controller.stop();
-export const restart = () => controller.restart();
-export const status = () => controller.status();
+export const install = async () => (await deviceControllerSelected() ? createDeviceDaemonController(clientDir()) : controller).install();
+export const uninstall = async () => (await deviceControllerSelected() ? createDeviceDaemonController(clientDir()) : controller).uninstall();
+export const start = async () => (await deviceControllerSelected() ? createDeviceDaemonController(clientDir()) : controller).start();
+export const stop = async () => (await deviceControllerSelected() ? createDeviceDaemonController(clientDir()) : controller).stop();
+export const restart = async () => (await deviceControllerSelected() ? createDeviceDaemonController(clientDir()) : controller).restart();
+export const status = async () => (await deviceControllerSelected() ? createDeviceDaemonController(clientDir()) : controller).status();

package/dist/workstation/desktopControl/automationDevice.js

@@ -0,0 +1,219 @@
+import WebSocket from 'ws';
+import { automationSchema, decodeAutomationRequest, decodeAutomationResponse, encodeAutomationBinary } from './automationProtocol.js';
+import { parseAutomationJson } from './automationJson.js';
+import { desktopSocketUrl } from './deviceSockets.js';
+import { bounded, NativeCommandError } from './helperProcess.js';
+import { managedAutomationBinding } from './automationLocalState.js';
+export class AutomationDeviceConnections {
+    server;
+    provider;
+    allowPrivateWs;
+    localStateDirectory;
+    admission;
+    get activeCount() { return this.active.size; }
+    active = new Map();
+    generation;
+    constructor(server, provider, allowPrivateWs = false, localStateDirectory, admission) {
+        this.server = server;
+        this.provider = provider;
+        this.allowPrivateWs = allowPrivateWs;
+        this.localStateDirectory = localStateDirectory;
+        this.admission = admission;
+    }
+    ready(generation) { this.close(); this.generation = generation; }
+    retired(generation) { if (generation === this.generation) {
+        this.close();
+        this.generation = undefined;
+    } }
+    close() { for (const entry of this.active.values())
+        entry.close(); this.active.clear(); }
+    async prepare(grant, binding, generation) {
+        if (generation !== this.generation || binding.route.deviceGeneration !== generation || this.active.size >= 8 || this.active.has(grant))
+            throw new Error('stale_generation');
+        if (!this.localStateDirectory)
+            throw new Error('trusted_storage_unavailable');
+        const localBinding = await managedAutomationBinding(this.localStateDirectory, { ...binding, registrationId: this.admission?.registrationId ?? binding.registrationId });
+        if (generation !== this.generation || this.active.size >= 8 || this.active.has(grant))
+            throw new Error('stale_generation');
+        const socket = new WebSocket(desktopSocketUrl(this.server, 'automation', this.allowPrivateWs), {
+            headers: { 'X-Axom-Automation-Grant': grant, 'X-Axom-Automation-Features': 'capture_wait_v1' }, followRedirects: false, perMessageDeflate: false, maxPayload: 49152
+        });
+        let selectedWait = false;
+        socket.once('upgrade', response => {
+            const selected = response.headers['x-axom-automation-features'];
+            if (selected !== undefined && selected !== 'capture_wait_v1') {
+                socket.terminate();
+                return;
+            }
+            selectedWait = selected === 'capture_wait_v1';
+        });
+        let session, retired = false, leaseBusy = false;
+        let mode = 'live';
+        let statusRequest;
+        const pending = new Map();
+        let lease;
+        const close = () => {
+            if (retired)
+                return;
+            retired = true;
+            clearInterval(lease);
+            pending.forEach(controller => controller.abort());
+            pending.clear();
+            this.active.delete(grant);
+            socket.terminate();
+            void session?.dispose().catch(() => { });
+        };
+        const current = () => !retired && this.generation === generation;
+        this.active.set(grant, { generation, close });
+        socket.on('error', close);
+        socket.on('close', close);
+        const send = async (bytes) => {
+            if (!current() || socket.readyState !== WebSocket.OPEN || socket.bufferedAmount > 8388608)
+                throw new Error('transport_failed');
+            await bounded(new Promise((resolve, reject) => socket.send(bytes, error => error ? reject(error) : resolve())), 5000);
+        };
+        try {
+            await bounded(new Promise((resolve, reject) => { socket.once('open', resolve); socket.once('error', reject); socket.once('close', () => reject(new Error('closed'))); }), 3000);
+            if (!this.provider?.prepareAutomation) {
+                await send(JSON.stringify({ automationProtocol: 1, operations: [] }));
+                return;
+            }
+            try {
+                session = await this.provider.prepareAutomation(localBinding);
+            }
+            catch {
+                await send(JSON.stringify({ automationProtocol: 1, operations: [] }));
+                return;
+            }
+            if (!current()) {
+                await session.dispose();
+                return;
+            }
+            await send(JSON.stringify({ automationProtocol: 1, operations: session.operations.filter(method => Object.hasOwn(automationSchema.requests, method) && (method !== 'capture_wait_v1' || selectedWait)) }));
+            const backend = session;
+            lease = setInterval(() => {
+                if (leaseBusy || !current() || mode !== 'live')
+                    return;
+                leaseBusy = true;
+                if (this.admission && !this.admission.current(localBinding)) {
+                    close();
+                    return;
+                }
+                void backend.renewAuthenticatedLease(3000).catch(() => { if (mode === 'live')
+                    close(); }).finally(() => { leaseBusy = false; });
+            }, 1000);
+            socket.on('message', (bytes, binary) => {
+                if (!current() || binary) {
+                    close();
+                    return;
+                }
+                try {
+                    const text = bytes.toString(), raw = parseAutomationJson(text, 49152).value;
+                    if (raw.command === 'cancel' && Object.keys(raw).length === 2) {
+                        pending.get(raw.requestId)?.abort();
+                        return;
+                    }
+                    if (raw.command === 'status_only' || raw.command === 'isolate') {
+                        if (pending.size >= 64 || pending.has(raw.requestId)) {
+                            close();
+                            return;
+                        }
+                        mode = 'detaching';
+                        clearInterval(lease);
+                        const controller = new AbortController();
+                        pending.set(raw.requestId, controller);
+                        const operation = raw.command === 'status_only' ? backend.detachApplicationStatus?.(raw.launchRequestId, raw.canonicalArgsDigest) : backend.isolate?.();
+                        void (operation ?? Promise.reject(new Error('unsupported'))).then(async (result) => {
+                            if (raw.command === 'status_only') {
+                                mode = 'status_only';
+                                statusRequest = raw.launchRequestId;
+                            }
+                            if (current() && !controller.signal.aborted)
+                                await send(JSON.stringify({ control: raw.command, id: raw.requestId, result }));
+                        }, async (error) => {
+                            if (current() && !controller.signal.aborted)
+                                await send(JSON.stringify({ control: 'prepare_failed', id: raw.requestId, code: error instanceof Error ? error.message : 'service_unavailable', detail: null }));
+                        }).catch(close).finally(() => pending.delete(raw.requestId));
+                        return;
+                    }
+                    if (raw.command === 'prepare' && Object.keys(raw).length === 3) {
+                        if (this.admission && !this.admission.current(localBinding))
+                            throw new Error('control_lost');
+                        if (mode !== 'live') {
+                            void send(JSON.stringify({ control: 'prepare_failed', id: raw.requestId, code: 'control_lost', detail: null })).catch(close);
+                            return;
+                        }
+                        if (pending.size >= 64 || pending.has(raw.requestId)) {
+                            close();
+                            return;
+                        }
+                        const controller = new AbortController();
+                        pending.set(raw.requestId, controller);
+                        void backend.prepareAttachment(raw.preparation, { signal: controller.signal }).then(attachment => { if (current() && !controller.signal.aborted)
+                            return send(JSON.stringify({ control: 'prepared', id: raw.requestId, attachment })); }, error => { if (current() && !controller.signal.aborted)
+                            return send(JSON.stringify({ control: 'prepare_failed', id: raw.requestId, code: error instanceof Error ? error.message : 'service_unavailable', detail: error instanceof NativeCommandError ? error.detail : null })); }).catch(close).finally(() => pending.delete(raw.requestId));
+                        return;
+                    }
+                    const request = decodeAutomationRequest(text);
+                    if (this.admission && !this.admission.current(localBinding) && request.method !== 'close')
+                        throw new Error('control_lost');
+                    if (mode !== 'live' && (mode !== 'status_only' || request.method !== 'application_status' || request.payload.requestId !== statusRequest)) {
+                        void send(JSON.stringify({ ...request, payload: { type: 'failure', code: 'control_lost', message: 'Input authority was retired', detail: null } })).catch(close);
+                        return;
+                    }
+                    if (pending.size >= 64 || pending.has(request.requestId)) {
+                        close();
+                        return;
+                    }
+                    if (request.method === 'capture_wait_v1' && (!selectedWait || !backend.operations.includes(request.method))) {
+                        void send(JSON.stringify({ ...request, payload: { type: 'failure', code: 'unsupported', message: 'Conditional observation was not negotiated', detail: null } })).catch(close);
+                        return;
+                    }
+                    const controller = new AbortController();
+                    pending.set(request.requestId, controller);
+                    void (async () => {
+                        const reply = await backend.execute(request, { signal: controller.signal });
+                        if (!current() || controller.signal.aborted)
+                            return;
+                        let response = decodeAutomationResponse(JSON.stringify(reply.response), request);
+                        let binary;
+                        if (reply.image) {
+                            const data = response.payload.data, transfer = request.method === 'capture' ? data : request.method === 'capture_wait_v1' ? data.image : data.postImage;
+                            binary = encodeAutomationBinary(transfer.header, reply.image);
+                            const captureAgeMs = Date.now() - transfer.metadata.capturedAtEpochMs;
+                            if (!Number.isSafeInteger(captureAgeMs) || captureAgeMs < 0 || captureAgeMs > 30000) {
+                                if (request.method !== 'act' && request.method !== 'status')
+                                    throw new Error('stale_observation');
+                                response = { ...response, payload: { type: 'success', data: { ...data, postImage: null, captureError: 'capture_failed' } } };
+                                binary = undefined;
+                            }
+                            else
+                                response = { ...response, captureAgeMs };
+                        }
+                        await send(JSON.stringify(response));
+                        if (binary)
+                            await send(binary);
+                    })().catch(async (error) => {
+                        if (!current() || controller.signal.aborted)
+                            return;
+                        const code = error instanceof Error && error.message === 'stale_observation' ? 'stale_observation'
+                            : error instanceof Error && error.message === 'unsupported' ? 'unsupported' : 'service_unavailable';
+                        try {
+                            await send(JSON.stringify({ ...request, payload: { type: 'failure', code, message: error instanceof Error ? error.message : code, detail: null } }));
+                        }
+                        catch {
+                            close();
+                        }
+                    }).finally(() => pending.delete(request.requestId));
+                }
+                catch {
+                    close();
+                }
+            });
+        }
+        catch (error) {
+            close();
+            throw error;
+        }
+    }
+}

package/dist/workstation/desktopControl/automationJson.js

@@ -0,0 +1,74 @@
+import { parseDesktopJson } from './protocol.js';
+export function parseAutomationJson(source, limit) {
+    if (typeof source !== 'string' && source.byteLength > limit)
+        throw new Error('invalid_automation_protocol');
+    const text = typeof source === 'string' ? source : new TextDecoder('utf-8', { fatal: true }).decode(source);
+    const value = parseDesktopJson(text, limit, new Set());
+    const numbers = new Map();
+    let offset = 0;
+    const space = () => { while (/[ \t\r\n]/.test(text[offset] ?? '\0'))
+        offset++; };
+    const string = () => {
+        const start = offset++;
+        while (offset < text.length) {
+            const character = text[offset++];
+            if (character === '\\')
+                offset++;
+            else if (character === '"')
+                return JSON.parse(text.slice(start, offset));
+        }
+        throw new Error('invalid_automation_protocol');
+    };
+    const visit = (path) => {
+        space();
+        if (text[offset] === '{') {
+            offset++;
+            space();
+            if (text[offset] === '}') {
+                offset++;
+                return;
+            }
+            do {
+                space();
+                const key = string();
+                space();
+                offset++;
+                visit([...path, key]);
+                space();
+                if (text[offset] !== ',')
+                    break;
+                offset++;
+            } while (true);
+            offset++;
+        }
+        else if (text[offset] === '[') {
+            offset++;
+            space();
+            if (text[offset] === ']') {
+                offset++;
+                return;
+            }
+            let index = 0;
+            do {
+                visit([...path, index++]);
+                space();
+                if (text[offset] !== ',')
+                    break;
+                offset++;
+            } while (true);
+            offset++;
+        }
+        else if (text[offset] === '"')
+            string();
+        else {
+            const start = offset;
+            while (offset < text.length && !/[,\]} \t\r\n]/.test(text[offset]))
+                offset++;
+            const token = text.slice(start, offset);
+            if (/^-?[0-9]/.test(token))
+                numbers.set(JSON.stringify(path), token);
+        }
+    };
+    visit([]);
+    return { value, numbers };
+}

package/dist/workstation/desktopControl/automationLocalState.js

@@ -0,0 +1,23 @@
+import { createHash } from 'node:crypto';
+import { lstat, mkdir } from 'node:fs/promises';
+import { isAbsolute, join } from 'node:path';
+export async function managedAutomationBinding(configDirectory, binding) {
+    const leaseMs = binding.native?.leaseMs;
+    if (!Number.isInteger(leaseMs) || leaseMs < 1 || leaseMs > 30000 || !binding.executionId)
+        throw new Error('trusted_preparation_unavailable');
+    if (!isAbsolute(configDirectory))
+        throw new Error('trusted_storage_unavailable');
+    const directory = join(configDirectory, 'desktop-automation');
+    await mkdir(directory, { mode: 0o700 }).catch(error => { if (error?.code !== 'EEXIST')
+        throw error; });
+    const status = await lstat(directory);
+    if (!status.isDirectory() || status.isSymbolicLink() || status.uid !== process.getuid?.() || (status.mode & 0o077) !== 0)
+        throw new Error('trusted_storage_unavailable');
+    const route = binding.route;
+    const identity = [binding.registrationId ?? 'legacy-single-registration', route.workstation, route.desktopId, route.inputDomainId, route.consumerId, route.deviceGeneration, route.controlGeneration, binding.executionId];
+    if (identity.some(value => value === undefined || value === null))
+        throw new Error('trusted_preparation_unavailable');
+    const key = createHash('sha256').update(JSON.stringify(identity)).digest('hex');
+    const domainKey = createHash('sha256').update(JSON.stringify([route.workstation, route.desktopId, route.inputDomainId])).digest('hex');
+    return { ...binding, native: { waitLockPath: join(directory, `${domainKey}.wait`), ledgerPath: join(directory, `${key}.jsonl`), leaseMs } };
+}

package/dist/workstation/desktopControl/automationPreparation.js

@@ -0,0 +1 @@
+export {};