@platless/axom-cli 0.6.36 → 0.6.52

package/dist/workstation/control/runtimeHost.js

@@ -7,6 +7,8 @@ import { pidAlive, processCommand } from '../keepers/kit/lock.js';
 import { processStartTime } from '../keepers/kit/orphanSweep.js';
 import { LocalControlError } from './protocol.js';
 import { withPrivateLock } from './locks.js';
+import { addRegistrationRequestSchema, assertDeviceGuard, deviceInspectionSchema, deviceRuntimeUpdateRequestSchema, removeRegistrationRequestSchema, deviceResultSchema } from './deviceProtocol.js';
+import { deviceHealthExpectationSchema, deviceHealthRequestSchema, deviceHealthWitnessSchema, deviceRollbackReceiptSchema } from '../update/deviceHealthProtocol.js';
 export function runtimePaths(directory) {
     const root = path.join(path.resolve(directory), 'control');
     const key = createHash('sha256').update(`${process.getuid?.() ?? 'user'}:${path.resolve(directory)}`).digest('hex').slice(0, 24);
@@ -35,6 +37,13 @@ export async function runtimeOwnerLive(owner) {
     return true;
 }
 export async function openRuntimeHost(options) {
+    const binding = { ...options.binding };
+    return openControlHost({ ...options, inspect: async (generation) => ({ ...await options.snapshot(), state: 'running', binding, generation, mode: options.mode }), shutdown: () => options.shutdown() });
+}
+export async function openDeviceRuntimeHost(options) {
+    return openControlHost({ ...options, inspect: async (generation) => deviceInspectionSchema.parse({ ...await options.snapshot(), runtime: { state: 'running', generation, mode: options.mode } }), device: true });
+}
+async function openControlHost(options) {
     const paths = runtimePaths(options.directory);
     await privateDirectory(path.dirname(paths.ownerFile));
     await privateDirectory(path.dirname(paths.socket));
@@ -65,7 +74,7 @@ export async function openRuntimeHost(options) {
         await fs.rm(paths.socket, { force: true });
         const generation = randomUUID();
         const token = randomBytes(32).toString('hex');
-        const binding = { ...options.binding };
+        const preparations = new Map();
         let closed = false;
         const clients = new Set();
         const server = net.createServer(socket => {
@@ -93,20 +102,98 @@ export async function openRuntimeHost(options) {
                             throw new LocalControlError('BINDING_CONFLICT', 'Runtime generation changed');
                         let value;
                         if (request.action === 'inspect')
-                            value = { ...await options.snapshot(), state: 'running', binding, generation, mode: options.mode };
-                        else if (request.action === 'stop')
+                            value = await options.inspect(generation);
+                        else if (request.action === 'prepare-update-rollback' && options.device && options.prepareUpdateRollback) {
+                            if (Object.keys(request).some(key => !['token', 'generation', 'action', 'request'].includes(key)))
+                                throw new LocalControlError('UNSUPPORTED_PROTOCOL', 'Invalid private rollback preparation envelope');
+                            const expected = deviceHealthExpectationSchema.parse(request.request);
+                            socket.setTimeout(20_000, () => socket.destroy());
+                            const receipt = deviceRollbackReceiptSchema.parse(await options.prepareUpdateRollback(expected, generation));
+                            if (receipt.daemonGeneration !== generation)
+                                throw new LocalControlError('OUTCOME_UNKNOWN', 'Original rollback cleanup receipt belongs to another daemon');
+                            value = receipt;
+                        }
+                        else if (request.action === 'update-health' && options.device && options.updateHealth) {
+                            if (Object.keys(request).some(key => !['token', 'generation', 'action', 'request'].includes(key)))
+                                throw new LocalControlError('UNSUPPORTED_PROTOCOL', 'Invalid private device health envelope');
+                            const parsed = deviceHealthRequestSchema.safeParse(request.request);
+                            if (!parsed.success)
+                                throw new LocalControlError('UNSUPPORTED_PROTOCOL', 'Invalid private device health request');
+                            const witness = deviceHealthWitnessSchema.parse(await options.updateHealth(parsed.data, generation));
+                            if (witness.daemonGeneration !== generation)
+                                throw new LocalControlError('OUTCOME_UNKNOWN', 'Private health witness is not owned by this daemon');
+                            value = witness;
+                        }
+                        else if (request.action === 'remove-registration' && options.device && options.removeRegistration) {
+                            if (Object.keys(request).some(key => !['token', 'generation', 'action', 'request'].includes(key)))
+                                throw new LocalControlError('UNSUPPORTED_PROTOCOL', 'Invalid local removal envelope');
+                            const parsed = removeRegistrationRequestSchema.safeParse(request.request);
+                            if (!parsed.success)
+                                throw new LocalControlError('UNSUPPORTED_PROTOCOL', 'Invalid local device removal request');
+                            if (parsed.data.guard.runtimeGeneration !== generation)
+                                throw new LocalControlError('BINDING_CONFLICT', 'Original removal runtime generation changed');
+                            socket.setTimeout(20_000, () => socket.destroy());
+                            value = deviceResultSchema.parse(await options.removeRegistration(parsed.data));
+                        }
+                        else if (request.action === 'add-registration' && options.device && options.addRegistration) {
+                            if (Object.keys(request).some(key => !['token', 'generation', 'action', 'request'].includes(key)))
+                                throw new LocalControlError('UNSUPPORTED_PROTOCOL', 'Invalid local enrollment envelope');
+                            const parsed = addRegistrationRequestSchema.safeParse(request.request);
+                            if (!parsed.success)
+                                throw new LocalControlError('UNSUPPORTED_PROTOCOL', 'Invalid local device enrollment request');
+                            if (parsed.data.guard.runtimeGeneration !== generation)
+                                throw new LocalControlError('BINDING_CONFLICT', 'Original enrollment runtime generation changed');
+                            socket.setTimeout(35_000, () => socket.destroy());
+                            value = deviceResultSchema.parse(await options.addRegistration(parsed.data));
+                        }
+                        else if (request.action === 'stop') {
+                            if (options.device && request.stopMode !== 'detach' && request.stopMode !== 'terminate')
+                                throw new LocalControlError('UNSUPPORTED_PROTOCOL', 'Device shutdown requires an explicit stop mode');
                             value = { accepted: true };
+                        }
+                        else if (request.action === 'prepare-stop' && options.device && options.prepareShutdown) {
+                            if (request.stopMode !== 'detach' && request.stopMode !== 'terminate')
+                                throw new LocalControlError('UNSUPPORTED_PROTOCOL', 'Device preparation requires an explicit stop mode');
+                            if (typeof request.operationId !== 'string' || request.operationId.length < 1 || request.operationId.length > 128 || /[\u0000-\u001f\u007f]/.test(request.operationId))
+                                throw new LocalControlError('UNSUPPORTED_PROTOCOL', 'Invalid device preparation operation ID');
+                            let prepared = preparations.get(request.operationId);
+                            if (prepared && prepared.mode !== request.stopMode)
+                                throw new LocalControlError('BINDING_CONFLICT', 'Device preparation mode changed');
+                            if (!prepared) {
+                                if (preparations.size >= 128)
+                                    throw new LocalControlError('BUSY', 'Too many device preparation operations');
+                                const result = options.prepareShutdown(request.stopMode, request.operationId).catch(error => { preparations.delete(request.operationId); throw error; });
+                                prepared = { mode: request.stopMode, result };
+                                preparations.set(request.operationId, prepared);
+                            }
+                            socket.setTimeout(20_000, () => socket.destroy());
+                            await prepared.result;
+                            value = { prepared: true, generation, stopMode: prepared.mode };
+                        }
+                        else if (request.action === 'reconcile' && options.reconcile) {
+                            await options.reconcile();
+                            value = { accepted: true };
+                        }
                         else if (request.action === 'update') {
-                            const r = request.release;
-                            if (typeof request.operationId !== 'string' || request.operationId.length > 128 || !r || typeof r.version !== 'string' || typeof r.url !== 'string' || typeof r.sha512 !== 'string' || !Number.isSafeInteger(r.size))
-                                throw Error('Invalid update request');
-                            value = await options.update(r, request.operationId);
+                            if (options.device) {
+                                if (Object.keys(request).some(key => !['token', 'generation', 'action', 'request'].includes(key)))
+                                    throw new LocalControlError('UNSUPPORTED_PROTOCOL', 'Invalid device update envelope');
+                                const parsed = deviceRuntimeUpdateRequestSchema.parse(request.request);
+                                assertDeviceGuard(parsed.guard, deviceInspectionSchema.parse(await options.inspect(generation)));
+                                value = await options.update(parsed.release, parsed.operationId, parsed.server);
+                            }
+                            else {
+                                const r = request.release;
+                                if (typeof request.operationId !== 'string' || request.operationId.length > 128 || !r || typeof r.version !== 'string' || typeof r.url !== 'string' || typeof r.sha512 !== 'string' || !Number.isSafeInteger(r.size))
+                                    throw Error('Invalid update request');
+                                value = await options.update(r, request.operationId);
+                            }
                         }
                         else
                             throw Error('Invalid action');
                         socket.end(JSON.stringify({ ok: true, value }) + '\n');
                         if (request.action === 'stop')
-                            setImmediate(() => { void options.shutdown().catch(() => { }); });
+                            setImmediate(() => { void options.shutdown(request.stopMode === 'terminate' ? 'terminate' : 'detach').catch(() => { }); });
                     }
                     catch (error) {
                         socket.end(JSON.stringify({ ok: false, code: error instanceof LocalControlError ? error.code : 'SERVICE_FAILED' }) + '\n');
@@ -136,7 +223,7 @@ export async function openRuntimeHost(options) {
             await fs.chmod(paths.socket, 0o600);
             await fs.writeFile(paths.tokenFile, token, { mode: 0o600 });
             await fs.chmod(paths.tokenFile, 0o600);
-            await fs.writeFile(paths.ownerFile, JSON.stringify({ schemaVersion: 1, pid: process.pid, command: await processCommand(process.pid), startTime: await processStartTime(process.pid), generation }), { mode: 0o600 });
+            await fs.writeFile(paths.ownerFile, JSON.stringify({ schemaVersion: options.device ? 2 : 1, pid: process.pid, command: await processCommand(process.pid), startTime: await processStartTime(process.pid), generation }), { mode: 0o600 });
             await fs.chmod(paths.ownerFile, 0o600);
             return { generation, close };
         }

package/dist/workstation/control/serverIdentity.js

@@ -1,4 +1,4 @@
-const ENDPOINTS = new Set(['/workstation/register', '/download/client/manifest.json', '/rest/auth/me', '/rest/auth/scopes/check']);
+const ENDPOINTS = new Set(['/workstation/register', '/workstation/enroll', '/workstation/enroll/identity', '/download/client/manifest.json', '/rest/auth/me', '/rest/auth/scopes/check']);
 export function normalizeWorkstationServer(value) {
     if (/[\u0000-\u0020\\]/.test(value))
         throw new Error('Invalid workstation server URL');
@@ -16,7 +16,7 @@ export function normalizeWorkstationServer(value) {
     return url.origin + url.pathname.replace(/\/+$/, '');
 }
 export function workstationEndpoint(server, apiPath) {
-    if (!ENDPOINTS.has(apiPath))
+    if (!ENDPOINTS.has(apiPath) && !/^\/workstation\/enroll\/[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$/.test(apiPath))
         throw new Error('Unrecognized workstation endpoint');
     return new URL(normalizeWorkstationServer(server) + apiPath);
 }

package/dist/workstation/control/updateTransition.js

@@ -0,0 +1,91 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { LocalControlError } from './protocol.js';
+import { readControlFile } from './runtimeHost.js';
+import { readDeviceBootstrapRecovery, readPrivateUpdateBytes, updateTransactionKey } from '../update/recoveryPlan.js';
+import { readLegacyBridge, assertLegacyBridgeTransferred, assertLegacyBridgeMutationAllowed } from '../update/legacyBridge.js';
+export async function assertDurableDeviceMutationAllowed(directory) {
+    await assertLegacyBridgeMutationAllowed(directory);
+    let bytes;
+    try {
+        bytes = await readPrivateUpdateBytes(path.join(directory, 'update/device-transaction.json'), 33_554_432);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return;
+        throw new LocalControlError('OUTCOME_UNKNOWN', 'Private device update ownership requires compatible recovery');
+    }
+    let transaction;
+    try {
+        const { deviceTransactionSchema } = await import('../update/deviceCoordinator.js');
+        transaction = deviceTransactionSchema.parse(JSON.parse(bytes.toString('utf8')));
+    }
+    catch {
+        throw new LocalControlError('OUTCOME_UNKNOWN', 'Preserve corrupt private device update ownership before changing registrations');
+    }
+    if (transaction.recoveryRequired || !['SUCCEEDED', 'FAILED', 'ROLLED_BACK', 'BUSY'].includes(transaction.phase))
+        throw new LocalControlError('BUSY', 'The original durable device update still owns membership admission');
+    if (['FAILED', 'BUSY'].includes(transaction.phase) && transaction.installation !== 'not-started')
+        throw new LocalControlError('OUTCOME_UNKNOWN', 'Original update mutation cannot be excluded; preserve compatible recovery evidence');
+}
+export async function assertDeviceUpdateTransitionSafe(directory, startup) {
+    const bridge = await readLegacyBridge(directory, startup);
+    if (bridge) {
+        await assertLegacyBridgeTransferred(bridge);
+        return;
+    }
+    const remediation = 'Unresolved legacy update/watchdog evidence: verify the predecessor updater and watchdog have exited, install a compatible CLI, then explicitly retire the verified old update evidence before starting the device daemon';
+    if (startup) {
+        try {
+            const update = path.join(directory, 'update');
+            const stat = await fs.lstat(update);
+            if (!stat.isDirectory() || stat.isSymbolicLink() || stat.mode & 0o077 || process.getuid && stat.uid !== process.getuid())
+                throw Error(remediation);
+            const plans = (await fs.readdir(update)).filter(name => /^watchdog-.*\.json(?:\..*)?$/.test(name));
+            if (plans.length) {
+                const recovery = await readDeviceBootstrapRecovery(directory, startup);
+                if (!recovery)
+                    throw Error(remediation);
+                if (plans.length !== 1 || plans[0] !== `watchdog-${updateTransactionKey(recovery.transaction.transactionId)}.json`)
+                    throw Error(remediation);
+                return;
+            }
+            try {
+                const transaction = JSON.parse((await readPrivateUpdateBytes(path.join(update, 'device-transaction.json'), 33_554_432)).toString('utf8'));
+                if (transaction.lifecycle === 'container' || transaction.lifecycle === 'none') {
+                    await readDeviceBootstrapRecovery(directory, startup);
+                    return;
+                }
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+            }
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw new LocalControlError('OUTCOME_UNKNOWN', remediation);
+        }
+    }
+    try {
+        const state = JSON.parse(await readControlFile(path.join(directory, 'update-state.json')));
+        if (!state || !['SUCCEEDED', 'FAILED', 'ROLLED_BACK', 'BUSY', 'UPDATE_IN_PROGRESS'].includes(state.phase))
+            throw Error(remediation);
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw new LocalControlError('OUTCOME_UNKNOWN', remediation);
+    }
+    try {
+        const update = path.join(directory, 'update');
+        const stat = await fs.lstat(update);
+        if (!stat.isDirectory() || stat.isSymbolicLink() || (stat.mode & 0o077) || (process.getuid && stat.uid !== process.getuid()))
+            throw Error(remediation);
+        if ((await fs.readdir(update)).some(name => /^watchdog-.*\.json(?:\..*)?$/.test(name)))
+            throw Error(remediation);
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw new LocalControlError('OUTCOME_UNKNOWN', remediation);
+    }
+}