@platless/axom-cli 0.5.9 → 0.6.52

package/dist/workstation/rd/host.js

@@ -0,0 +1,213 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { randomBytes, createHash, randomUUID } from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { createConnection } from 'node:net';
+import { NativeDeviceAdmission } from '../desktopControl/nativeDeviceAdmission.js';
+import { bounded } from '../desktopControl/helperProcess.js';
+import { privateDirectory } from '../keepers/kit/paths.js';
+import { readDeviceHostDescriptor, deviceHostGrantSchema } from '../desktopControl/hostGrant.js';
+export class LinuxDeviceHost {
+    directory;
+    cleanupDescriptor;
+    static pending = new Map();
+    child;
+    owner;
+    exit;
+    stopCommandId = randomUUID();
+    admission;
+    grant;
+    bootstrapGrant;
+    enableAttempted = false;
+    published = false;
+    failed = false;
+    exitObserved = false;
+    constructor(directory, cleanupDescriptor) {
+        this.directory = directory;
+        this.cleanupDescriptor = cleanupDescriptor;
+    }
+    static async recoverPending(root) {
+        const host = this.pending.get(root);
+        if (!host)
+            return;
+        if (host.failed && !host.enableAttempted && !host.published && host.exitObserved) {
+            host.owner?.destroy();
+            await fs.rm(path.join(host.directory, 'launch.json'), { force: true });
+            await fs.rm(path.join(host.directory, 'host.sock'), { force: true });
+            await fs.rmdir(host.directory).catch(error => { if (error.code !== 'ENOENT')
+                throw error; });
+            this.pending.delete(root);
+            return;
+        }
+        if (!host.admission) {
+            const original = host.bootstrapGrant;
+            if (!original)
+                throw Error('native_host_launch_unconfirmed');
+            host.admission = await NativeDeviceAdmission.connect(original);
+            host.grant = { ...original, hostGeneration: host.admission.hostLifetimeId };
+        }
+        return host;
+    }
+    static async launch(root, executable, environment) {
+        if (this.pending.has(root))
+            throw Error('original_native_host_unconfirmed');
+        const cleanup = path.join(root, 'desktop-cleanup');
+        await privateDirectory(cleanup);
+        const directory = await fs.mkdtemp('/tmp/axom-device-host-');
+        await fs.chmod(directory, 0o700);
+        const host = new LinuxDeviceHost(directory, path.join(cleanup, randomBytes(16).toString('hex') + '.json'));
+        const binary = await fs.realpath(executable), sha256 = createHash('sha256').update(await fs.readFile(binary)).digest('hex');
+        const endpoint = { socket: path.join(directory, 'host.sock'), token: randomBytes(32).toString('hex') };
+        host.bootstrapGrant = { schemaVersion: 2, executable: binary, sha256, ...endpoint };
+        const bootstrap = path.join(directory, 'launch.json');
+        await fs.writeFile(bootstrap, JSON.stringify({ ...endpoint, parentPid: process.pid, cleanupDescriptor: host.cleanupDescriptor, executable: binary, sha256 }), { flag: 'wx', mode: 0o600 });
+        this.pending.set(root, host);
+        const child = spawn(binary, ['--device-host', bootstrap], { env: { ...environment, AXOM_ACCESS_TOKEN: undefined }, stdio: 'ignore' });
+        host.child = child;
+        host.exit = new Promise((resolve, reject) => { child.once('exit', () => { host.exitObserved = true; resolve(); }); child.once('error', reject); });
+        void host.exit.catch(() => { });
+        try {
+            const deadline = Date.now() + 5000;
+            while (Date.now() < deadline) {
+                if (child.exitCode !== null)
+                    throw new Error('native_host_launch_failed');
+                try {
+                    await fs.lstat(endpoint.socket);
+                    break;
+                }
+                catch (error) {
+                    if (error.code !== 'ENOENT')
+                        throw error;
+                }
+                await new Promise(resolve => setTimeout(resolve, 10));
+            }
+            const owner = createConnection(endpoint.socket);
+            host.owner = owner;
+            await bounded(new Promise((resolve, reject) => {
+                owner.once('error', reject);
+                owner.once('connect', () => owner.write(endpoint.token));
+                owner.once('data', bytes => { if (bytes.length !== 1 || bytes[0] !== 1) {
+                    reject(new Error('native_host_authentication_failed'));
+                    return;
+                } owner.write('owner\n'); resolve(); });
+                owner.once('end', () => reject(new Error('native_host_owner_closed')));
+            }), 5000);
+            host.admission = await NativeDeviceAdmission.connect(endpoint);
+            host.grant = { schemaVersion: 2, hostGeneration: host.admission.hostLifetimeId, executable: binary, sha256, ...endpoint };
+            host.published = true;
+            await host.persistOriginal();
+            await new Promise((resolve, reject) => {
+                const peer = createConnection(endpoint.socket);
+                const timer = setTimeout(() => { peer.destroy(); reject(new Error('native_host_enable_unconfirmed')); }, 5000);
+                let authenticated = false, bytes = Buffer.alloc(0);
+                peer.once('connect', () => peer.write(endpoint.token));
+                peer.once('error', error => { clearTimeout(timer); reject(error); });
+                peer.on('data', chunk => { bytes = Buffer.concat([bytes, chunk]); if (!authenticated) {
+                    if (bytes[0] !== 1) {
+                        clearTimeout(timer);
+                        peer.destroy();
+                        reject(new Error('native_host_authentication_failed'));
+                        return;
+                    }
+                    authenticated = true;
+                    bytes = bytes.subarray(1);
+                    host.enableAttempted = true;
+                    peer.write('enable\n');
+                } if (bytes.includes(10)) {
+                    clearTimeout(timer);
+                    peer.destroy();
+                    try {
+                        if (JSON.stringify(JSON.parse(bytes.subarray(0, bytes.indexOf(10)).toString())) !== '{}')
+                            throw Error();
+                        resolve();
+                    }
+                    catch {
+                        reject(new Error('native_host_enable_unconfirmed'));
+                    }
+                } });
+            });
+            this.pending.delete(root);
+            return host;
+        }
+        catch (error) {
+            host.failed = true;
+            host.owner?.destroy();
+            throw error;
+        }
+    }
+    async persistOriginal() {
+        const expected = deviceHostGrantSchema.parse(this.grant);
+        try {
+            if (JSON.stringify(await readDeviceHostDescriptor(this.cleanupDescriptor)) !== JSON.stringify(expected))
+                throw Error('original_native_host_unconfirmed');
+            return;
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        const staging = this.cleanupDescriptor + '.writing-' + randomUUID();
+        const file = await fs.open(staging, 'wx', 0o600);
+        try {
+            await file.writeFile(JSON.stringify(expected));
+            await file.sync();
+            await file.close();
+            try {
+                await fs.link(staging, this.cleanupDescriptor);
+            }
+            catch (error) {
+                if (error.code !== 'EEXIST')
+                    throw error;
+            }
+            if (JSON.stringify(await readDeviceHostDescriptor(this.cleanupDescriptor)) !== JSON.stringify(expected))
+                throw Error('original_native_host_unconfirmed');
+        }
+        finally {
+            await file.close();
+            await fs.unlink(staging);
+        }
+    }
+    async stopOriginal() {
+        let failure;
+        try {
+            await this.persistOriginal();
+        }
+        catch (error) {
+            failure = error;
+        }
+        try {
+            await this.admission.stopHost(this.stopCommandId);
+        }
+        catch (error) {
+            failure ??= error;
+        }
+        if (failure)
+            throw failure;
+    }
+    async finalizeOriginal() {
+        this.owner?.destroy();
+        if (this.exit)
+            try {
+                await bounded(this.exit, 5000);
+            }
+            catch (error) {
+                this.child?.kill('SIGTERM');
+                await bounded(this.exit, 5000);
+            }
+        try {
+            const descriptor = await readDeviceHostDescriptor(this.cleanupDescriptor);
+            if (descriptor.hostGeneration === this.grant.hostGeneration && descriptor.token === this.grant.token && descriptor.socket === this.grant.socket)
+                await fs.unlink(this.cleanupDescriptor);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        await fs.rm(path.join(this.directory, 'launch.json'), { force: true });
+        await fs.rmdir(this.directory).catch(error => { if (error.code !== 'ENOENT')
+            throw error; });
+        for (const [root, original] of LinuxDeviceHost.pending)
+            if (original === this)
+                LinuxDeviceHost.pending.delete(root);
+    }
+}

package/dist/workstation/rd/migrationReadiness.js

@@ -0,0 +1,46 @@
+import path from 'node:path';
+import { promises as fs } from 'node:fs';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { z } from 'zod';
+import { installRd, rdPlatform, verifyRdInstallation } from './artifact.js';
+import { readRdState } from './state.js';
+import { withPrivateLock } from '../control/locks.js';
+const execute = promisify(execFile);
+const capabilities = z.strictObject({ deviceAdmissionProtocol: z.literal(1), deviceHost: z.literal(true) });
+/** Stage only. The caller must retain the legacy physical fence: qualification is not retirement
+ * of predecessor capture/input authority, and must never activate this state on its own. */
+export async function prepareLegacyRdReadiness(directory, options = {}) {
+    return withPrivateLock(path.join(directory, 'rd', 'install'), async () => {
+        const previous = await readRdState(directory);
+        if (!previous?.enabled)
+            return { kind: 'not-enabled' };
+        const qualify = async (installation) => {
+            await verifyRdInstallation(installation.directory, installation.artifact);
+            const result = await (options.execute ?? execute)(path.join(installation.directory, 'bin/axom-desktop-keeper'), ['--device-capabilities'], {
+                timeout: 5000, maxBuffer: 8192,
+                env: { ...process.env, AXOM_ACCESS_TOKEN: undefined, AXOM_DEVICE_SCOPE: undefined, AXOM_DEVICE_CONTEXT: undefined,
+                    AXOM_KEEPER_SOCKET: undefined, AXOM_KEEPER_TOKEN: undefined },
+            });
+            capabilities.parse(JSON.parse(result.stdout));
+        };
+        try {
+            await qualify({ directory: previous.installation, artifact: previous.artifact });
+            return { kind: 'ready', state: previous };
+        }
+        catch {
+            // A legacy --self-test or IPC version says nothing about device admission support.
+        }
+        try {
+            const platform = options.platform ?? rdPlatform(await fs.readFile('/etc/os-release', 'utf8'), process.arch);
+            const candidate = await (options.install ?? installRd)(directory, previous.artifactSource, platform);
+            await qualify(candidate);
+            if (JSON.stringify(await readRdState(directory)) !== JSON.stringify(previous))
+                throw Error('Remote desktop selection changed during migration staging');
+            return { kind: 'staged', state: { ...previous, installation: candidate.directory, artifact: candidate.artifact } };
+        }
+        catch (error) {
+            return { kind: 'unavailable', reason: `Remote desktop requires a qualified device host: ${error instanceof Error ? error.message : String(error)}` };
+        }
+    });
+}

package/dist/workstation/rd/provider.js

@@ -0,0 +1,256 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { z } from 'zod';
+import { NativeProvider } from '../desktopControl/nativeProvider.js';
+import { HelperProcess, NativeCommandError } from '../desktopControl/helperProcess.js';
+import { desktopCapabilitiesSchema } from '../desktopControl/protocol.js';
+import { captureTargetLabel } from '../desktopControl/captureTargetLabel.js';
+import { privateDirectory } from '../keepers/kit/paths.js';
+import { verifyRdInstallation } from './artifact.js';
+import { readRdState } from './state.js';
+import { chooseSession, discoverSessions, ensureManagedSession, sessionAlive } from './sessions.js';
+import { desktopDisplayControl, parseXrandr } from './display.js';
+import { LinuxDeviceHost } from './host.js';
+const execute = promisify(execFile);
+const sourceAxis = z.number().int().min(2).max(4096);
+const geometrySchema = z.object({ width: sourceAxis, height: sourceAxis, audio: z.boolean().optional() });
+const windowSchema = z.array(z.object({ id: z.string().regex(/^[a-f0-9]{32}$/), kind: z.literal('window'), label: z.string().max(4096), width: sourceAxis, height: sourceAxis })).max(127);
+export class LinuxDesktopProvider {
+    directory;
+    server;
+    legacy;
+    host;
+    get deviceAdmission() { return this.host?.admission; }
+    static async connect(directory) {
+        if (!(await readRdState(directory))?.enabled)
+            return;
+        const provider = new LinuxDesktopProvider(directory, '');
+        await provider.initialize();
+        if (!provider.host)
+            throw new NativeCommandError('unavailable');
+        return provider;
+    }
+    async stopOriginal() { if (this.host)
+        await this.host.stopOriginal(); }
+    async finalizeOriginal() { if (this.host)
+        await this.host.finalizeOriginal(); }
+    async retirementRequired() {
+        const current = await readRdState(this.directory);
+        return !current?.enabled || !this.state || current.artifact.sha512 !== this.state.artifact.sha512 || current.session !== this.state.session || current.display !== this.state.display || !this.session || !await sessionAlive(this.session);
+    }
+    async prepareAutomation(binding) {
+        await this.initialize();
+        if (!this.usingLegacy)
+            await this.validate();
+        if (!this.provider?.prepareAutomation)
+            throw new NativeCommandError('unsupported_automation_protocol');
+        return this.provider.prepareAutomation(binding);
+    }
+    session;
+    provider;
+    state;
+    runtime = '';
+    revision = 0;
+    geometryIdentity = '';
+    initialization;
+    usingLegacy = false;
+    targetRevisions = new Map();
+    constructor(directory, server, legacy) {
+        this.directory = directory;
+        this.server = server;
+        this.legacy = legacy;
+    }
+    get automaticDpi() {
+        if (this.usingLegacy)
+            return true;
+        const setting = this.session?.environment.AXOM_DESKTOP_AUTO_DPI;
+        if (setting !== undefined)
+            return setting === '1';
+        return this.legacy !== undefined && this.session?.managed === true && this.session.environment.AXOM_DESKTOP_OWNED_DUMMY === '1';
+    }
+    async validate(session = this.session) {
+        const current = await readRdState(this.directory);
+        if (!current?.enabled || !this.state || current.artifact.sha512 !== this.state.artifact.sha512 ||
+            current.session !== this.state.session || current.display !== this.state.display ||
+            !session || this.session !== session || !await sessionAlive(session)) {
+            throw new NativeCommandError('unavailable');
+        }
+    }
+    async initialize() {
+        if (this.initialization)
+            return this.initialization;
+        this.initialization = this.initializeCurrent();
+        try {
+            await this.initialization;
+        }
+        finally {
+            this.initialization = undefined;
+        }
+    }
+    async initializeCurrent() {
+        const state = await readRdState(this.directory);
+        this.usingLegacy = state === undefined && this.legacy !== undefined;
+        if (this.usingLegacy) {
+            this.provider = this.legacy;
+            this.state = undefined;
+            return;
+        }
+        if (!state?.enabled) {
+            this.provider = undefined;
+            this.state = undefined;
+            return;
+        }
+        if (this.host) {
+            if (await this.retirementRequired())
+                throw new NativeCommandError('unavailable');
+            return;
+        }
+        if (this.provider && this.state?.artifact.sha512 === state.artifact.sha512 && this.state.session === state.session && this.state.display === state.display && this.session && await sessionAlive(this.session))
+            return;
+        this.provider = undefined;
+        this.session = undefined;
+        await verifyRdInstallation(state.installation, state.artifact);
+        const session = chooseSession(await discoverSessions(), state) ?? await ensureManagedSession(this.directory);
+        this.session = session;
+        this.state = state;
+        const runtimeRoot = path.join(session.environment.XDG_RUNTIME_DIR ?? `/run/user/${process.getuid?.()}`, 'axom-rd');
+        await privateDirectory(runtimeRoot);
+        this.runtime = session.managed && session.environment.AXOM_DESKTOP_RUNTIME_DIR && path.isAbsolute(session.environment.AXOM_DESKTOP_RUNTIME_DIR) ?
+            session.environment.AXOM_DESKTOP_RUNTIME_DIR : path.join(runtimeRoot, session.identity);
+        await privateDirectory(this.runtime);
+        const executable = path.join(state.installation, 'bin/axom-desktop-keeper');
+        const originalHost = await LinuxDeviceHost.launch(this.directory, executable, this.environment());
+        this.host = originalHost;
+        const originalEnvironment = { ...this.environment(), AXOM_KEEPER_SOCKET: originalHost.grant.socket, AXOM_KEEPER_TOKEN: originalHost.grant.token };
+        this.provider = new NativeProvider({ helperPath: executable, runtimeDir: this.runtime,
+            deviceAdmission: originalHost.admission, environment: originalEnvironment, enumerate: () => this.capabilities(), validateSession: () => this.validate(session),
+            sessionHelperFactory: async (binding) => {
+                await this.validate(session);
+                const helper = await HelperProcess.launch(executable, { ...originalEnvironment, AXOM_KEEPER_TARGET: binding.displayId,
+                    AXOM_DEVICE_CONTEXT: originalHost.admission.context(binding.deviceGrant?.registrationId ?? '', binding.deviceGeneration, binding.sessionId, binding.deviceGrant) });
+                return helper;
+            } });
+        process.env.AXOM_QUIC_BINARY = path.join(state.installation, 'bin/axom-quic');
+    }
+    environment() {
+        return { ...process.env, ...this.session.environment, AXOM_DESKTOP_RUNTIME_DIR: this.runtime, AXOM_ACCESS_TOKEN: undefined,
+            ...(this.state.artifact.ipcVersion === 1 ? { XDG_RUNTIME_DIR: this.runtime } : {}),
+            AXOM_DESKTOP_DISPLAY_CONTROL: path.join(this.state.installation, 'bin/axom-display'),
+            AXOM_DESKTOP_PROVIDER_FILE: path.join(this.runtime, 'provider.json'),
+            AXOM_DESKTOP_OWNED_DUMMY: this.session.managed && this.state.artifact.ipcVersion === 2 ? '1' : undefined };
+    }
+    async capabilities() {
+        await this.validate();
+        const executable = path.join(this.state.installation, 'bin/axom-desktop-keeper');
+        const options = { env: this.environment(), timeout: 2000, maxBuffer: 49152 };
+        const { stdout } = await execute(executable, ['--probe'], options);
+        const probe = geometrySchema.parse(JSON.parse(stdout));
+        const geometry = { width: probe.width, height: probe.height };
+        const sharedRuntime = this.state.artifact.ipcVersion === 2;
+        let actual = { output: '', ...geometry, modes: [] };
+        if (sharedRuntime) {
+            try {
+                actual = parseXrandr((await execute('xrandr', ['--current'], options)).stdout);
+            }
+            catch (error) {
+                if (this.session.managed)
+                    throw error;
+            }
+        }
+        let dpi;
+        if (sharedRuntime && this.session.managed) {
+            const resources = (await execute('xrdb', ['-query'], options)).stdout;
+            const value = Number(/^Xft\.dpi:\s*(\d+)\s*$/m.exec(resources)?.[1] ?? 96);
+            dpi = z.number().int().min(64).max(384).parse(value);
+        }
+        const geometryIdentity = `${this.session.identity}:${geometry.width}:${geometry.height}:${dpi ?? ''}`;
+        if (geometryIdentity !== this.geometryIdentity) {
+            this.revision++;
+            this.geometryIdentity = geometryIdentity;
+        }
+        const staging = path.join(this.runtime, '.geometry.json');
+        await fs.writeFile(staging, JSON.stringify({ ...geometry, ...(dpi === undefined ? {} : { dpi }) }), { mode: 0o600 });
+        await fs.rename(staging, path.join(this.runtime, 'geometry.json'));
+        const targets = windowSchema.parse(JSON.parse((await execute(executable, ['--capture-targets'], options)).stdout));
+        const root = { id: '00000000000000000000000000000001', kind: 'display', label: this.session.managed ? 'Virtual desktop' : 'Desktop', ...geometry };
+        const displays = [root, ...targets].map(target => {
+            const identity = `${this.session.identity}:${target.width}:${target.height}`;
+            const previous = this.targetRevisions.get(target.id);
+            const revision = target.id === root.id ? this.revision : previous ? previous.revision + Number(previous.geometry !== identity) : 1;
+            this.targetRevisions.set(target.id, { geometry: identity, revision });
+            const display = desktopDisplayControl({ ...target, label: captureTargetLabel(target.label), revision }, actual, sharedRuntime && this.session.managed);
+            return { ...display, ...(target.id === root.id && dpi !== undefined && display.captureViewport !== true ? {
+                    dpi, maxDpi: 384, appearanceSync: true,
+                } : {}) };
+        });
+        const live = new Set(displays.map(display => display.id));
+        for (const id of this.targetRevisions.keys())
+            if (!live.has(id))
+                this.targetRevisions.delete(id);
+        const failed = await Promise.all(['display-failed', 'input-failed'].map(async (name) => {
+            try {
+                await fs.lstat(path.join(this.runtime, name));
+                return true;
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+                return false;
+            }
+        }));
+        const capabilities = desktopCapabilitiesSchema.parse({ protocols: { min: 2, max: probe.audio ? 3 : 2 }, providerId: 'linux-x11-v1', providerVersion: 'axom-linux-2',
+            configured: true, permission: 'granted', health: failed.some(Boolean) ? 'unavailable' : 'ready', reason: failed.some(Boolean) ? 'recovery_unverified' : null,
+            cursorEmbedded: false, formats: ['h264-420-v1'], encoderBackends: [{ id: 'libx264', kind: 'software', formats: [{ format: 'h264-420-v1',
+                            maxWidth: 4096, maxHeight: 4096, maxPixels: 4000000, maxFps: 30, cappedRate: true }] }],
+            input: { pointer: true, physicalKeyboard: true, unicodeText: true, clipboard: true, textPaste: true }, displays });
+        const manifest = path.join(this.runtime, '.provider.json');
+        await fs.writeFile(manifest, JSON.stringify(capabilities), { mode: 0o600 });
+        await fs.rename(manifest, path.join(this.runtime, 'provider.json'));
+        return capabilities;
+    }
+    async probe() {
+        try {
+            await this.initialize();
+            if (!this.provider)
+                return null;
+            if (this.usingLegacy)
+                return this.provider.probe();
+            const capabilities = await this.provider.probe();
+            if (!capabilities)
+                return null;
+            await fs.writeFile(path.join(this.directory, 'rd', 'status.json'), JSON.stringify({ updatedAt: new Date().toISOString(), state: capabilities.health,
+                session: this.session.managed ? 'virtual' : 'existing', display: this.session.display, width: capabilities.displays[0].width, height: capabilities.displays[0].height,
+                resolution: capabilities.displays[0].captureViewport === true ? 'sampling' : capabilities.displays[0].resize,
+                modes: capabilities.displays[0].captureViewport === true ? [] : capabilities.displays[0].modes }), { mode: 0o600 });
+            return capabilities;
+        }
+        catch (error) {
+            await fs.writeFile(path.join(this.directory, 'rd', 'status.json'), JSON.stringify({ updatedAt: new Date().toISOString(), state: 'unavailable', reason: String(error) }), { mode: 0o600 }).catch(() => undefined);
+            throw error;
+        }
+    }
+    async prepare(selection, binding, current) {
+        await this.initialize();
+        if (!this.provider)
+            throw new NativeCommandError('unavailable');
+        return this.provider.prepare(selection, binding, current);
+    }
+    async wallpaper(targetId, pixels = { width: 1920, height: 1080 }) {
+        await this.initialize();
+        if (!this.usingLegacy)
+            await this.validate();
+        if (!this.provider)
+            throw new NativeCommandError('unavailable');
+        return this.provider.wallpaper(targetId, pixels);
+    }
+    async recoverDisplay(binding, reservation) {
+        await this.initialize();
+        if (!this.usingLegacy)
+            await this.validate();
+        if (!this.provider)
+            throw new NativeCommandError('unavailable');
+        return this.provider.recoverDisplay(binding, reservation);
+    }
+}