@platless/axom-cli 0.5.9 → 0.6.52

package/dist/workstation/control/runtimeHost.js

@@ -0,0 +1,235 @@
+import { createHash, randomBytes, randomUUID, timingSafeEqual } from 'node:crypto';
+import { promises as fs } from 'node:fs';
+import net from 'node:net';
+import path from 'node:path';
+import { privateDirectory, socketLimit } from '../keepers/kit/paths.js';
+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);
+    const local = path.join(root, 'runtime.sock');
+    return { socket: Buffer.byteLength(local) < socketLimit() ? local : `/tmp/axom-control-${process.getuid?.() ?? 'user'}/${key}.sock`, tokenFile: path.join(root, 'runtime.token'), ownerFile: path.join(root, 'runtime.owner.json') };
+}
+export async function readControlFile(file) {
+    const stat = await fs.lstat(file);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 65_536 || (process.getuid && stat.uid !== process.getuid()) || (stat.mode & 0o077))
+        throw Error('Unsafe control file');
+    return fs.readFile(file, 'utf8');
+}
+/** A persisted PID can belong to another process after a container restart or reboot. */
+export async function runtimeOwnerLive(owner) {
+    if (!pidAlive(owner.pid))
+        return false;
+    const command = await processCommand(owner.pid);
+    if (command !== null && command !== owner.command)
+        return false;
+    if (typeof owner.startTime === 'string') {
+        const startTime = await processStartTime(owner.pid);
+        if (startTime !== null && startTime !== owner.startTime)
+            return false;
+    }
+    // Inability to read the process identity is not evidence that it stopped.
+    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));
+    return withPrivateLock(path.join(options.directory, 'control/runtime-start'), async () => {
+        try {
+            const owner = JSON.parse(await readControlFile(paths.ownerFile));
+            if (!Number.isSafeInteger(owner.pid) || owner.pid <= 0 || typeof owner.command !== 'string')
+                throw Error('Unknown runtime owner');
+            if (await runtimeOwnerLive(owner))
+                throw new LocalControlError('INSTANCE_OCCUPIED', 'A workstation daemon already owns this computer');
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT') {
+                if (error instanceof LocalControlError)
+                    throw error;
+                throw new LocalControlError('INSTANCE_OCCUPIED', 'Cannot verify the existing workstation daemon');
+            }
+            // A socket with no owner cannot safely be reclaimed.
+            try {
+                await fs.lstat(paths.socket);
+                throw new LocalControlError('INSTANCE_OCCUPIED', 'Unverified workstation socket');
+            }
+            catch (e) {
+                if (e.code !== 'ENOENT')
+                    throw e;
+            }
+        }
+        await fs.rm(paths.socket, { force: true });
+        const generation = randomUUID();
+        const token = randomBytes(32).toString('hex');
+        const preparations = new Map();
+        let closed = false;
+        const clients = new Set();
+        const server = net.createServer(socket => {
+            clients.add(socket);
+            socket.on('close', () => clients.delete(socket));
+            socket.on('error', () => { });
+            socket.setTimeout(3000, () => socket.destroy());
+            let body = '';
+            let handled = false;
+            socket.on('data', chunk => {
+                body += chunk.toString();
+                if (Buffer.byteLength(body) > 65_536) {
+                    socket.destroy();
+                    return;
+                }
+                if (handled || !body.includes('\n'))
+                    return;
+                handled = true;
+                void (async () => {
+                    try {
+                        const request = JSON.parse(body.split('\n')[0]);
+                        if (typeof request.token !== 'string' || request.token.length !== token.length || !timingSafeEqual(Buffer.from(token), Buffer.from(request.token)))
+                            throw Error('Unauthorized');
+                        if (request.generation !== generation)
+                            throw new LocalControlError('BINDING_CONFLICT', 'Runtime generation changed');
+                        let value;
+                        if (request.action === 'inspect')
+                            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') {
+                            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(request.stopMode === 'terminate' ? 'terminate' : 'detach').catch(() => { }); });
+                    }
+                    catch (error) {
+                        socket.end(JSON.stringify({ ok: false, code: error instanceof LocalControlError ? error.code : 'SERVICE_FAILED' }) + '\n');
+                    }
+                })();
+            });
+        });
+        const close = async () => {
+            if (closed)
+                return;
+            closed = true;
+            for (const socket of clients)
+                socket.destroy();
+            await new Promise(resolve => server.close(() => resolve()));
+            // Only remove our own generation.
+            try {
+                if (JSON.parse(await readControlFile(paths.ownerFile)).generation === generation) {
+                    await fs.rm(paths.ownerFile, { force: true });
+                    await fs.rm(paths.tokenFile, { force: true });
+                    await fs.rm(paths.socket, { force: true });
+                }
+            }
+            catch { /* never remove another owner */ }
+        };
+        try {
+            await new Promise((resolve, reject) => { server.once('error', reject); server.listen(paths.socket, () => { server.removeListener('error', reject); resolve(); }); });
+            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: 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 };
+        }
+        catch (error) {
+            await close();
+            throw error;
+        }
+    });
+}

package/dist/workstation/control/serverIdentity.js

@@ -0,0 +1,35 @@
+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');
+    // Inspect the original path: URL construction silently removes encoded dot segments.
+    const rawPath = /^[A-Za-z][A-Za-z0-9+.-]*:\/\/[^/?#]*(\/[^?#]*)?/.exec(value)?.[1] ?? '';
+    for (const part of rawPath.split('/')) {
+        const decoded = decodeURIComponent(part);
+        if (decoded === '.' || decoded === '..' || /[\/\\\u0000-\u001f\u007f]/.test(decoded))
+            throw new Error('Invalid workstation server path');
+    }
+    const url = new URL(value);
+    if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.search || url.hash) {
+        throw new Error('Workstation server must be an HTTP(S) URL without credentials, query or fragment');
+    }
+    return url.origin + url.pathname.replace(/\/+$/, '');
+}
+export function workstationEndpoint(server, 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);
+}
+/** Catalog URLs are deployment-relative even when a reverse proxy adds a path prefix. */
+export function deploymentDownloadURL(server, value) {
+    const base = normalizeWorkstationServer(server);
+    const configured = new URL(base);
+    const candidate = value.startsWith('/download/client/') ? base + value : new URL(value, base + '/').toString();
+    const normalized = normalizeWorkstationServer(candidate);
+    const url = new URL(normalized);
+    if (url.origin !== configured.origin)
+        throw new Error('Artifact URL must use the configured server origin');
+    if (!url.pathname.startsWith(configured.pathname.replace(/\/$/, '') + '/download/client/'))
+        throw new Error('Artifact URL must stay in the configured deployment');
+    return normalized;
+}

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);
+    }
+}