@platless/axom-cli 0.5.9 → 0.6.52

package/dist/workstation/oauth/deviceAuthorization.js

@@ -42,8 +42,11 @@ function requireString(value, field, description) {
         throw new DeviceAuthorizationError(`${description} missing ${field}`);
     return value;
 }
-function websocketUrl(server) {
-    const url = new URL('/oauth/device/ws', server);
+function deviceEndpoint(server, endpoint, identity) {
+    return identity ? new URL(server + endpoint) : new URL(endpoint, server);
+}
+function websocketUrl(server, identity) {
+    const url = deviceEndpoint(server, '/oauth/device/ws', identity);
     url.protocol = url.protocol === 'https:' ? 'wss:' : 'ws:';
     return url.toString();
 }
@@ -89,23 +92,33 @@ function waitForNotification(socket, sessionId, notificationTicket, deadline, no
         socket.on('error', () => finish('reconnect'));
     });
 }
-async function exchangeDeviceCode(server, clientId, deviceCode, fetch_, requestedScopes) {
-    const response = await requestJson(fetch_, new URL('/oauth/token', server), {
+async function exchangeDeviceCode(server, clientId, deviceCode, fetch_, requestedScopes, identity) {
+    const response = await requestJson(fetch_, deviceEndpoint(server, '/oauth/token', identity), {
         method: 'POST',
         headers: { 'content-type': 'application/x-www-form-urlencoded' },
         body: new URLSearchParams({
             grant_type: DEVICE_CODE_GRANT_TYPE,
             client_id: clientId,
             device_code: deviceCode,
-            device_id: await loadDeviceId(),
+            device_id: identity?.deviceId ?? await loadDeviceId(),
         }),
     }, 200, 'Device token exchange');
-    return validateTokenResponse(server, response, requestedScopes, fetch_);
+    return validateTokenResponse(server, response, requestedScopes, fetch_, identity);
 }
-async function validateTokenResponse(server, response, requestedScopes, fetch_) {
-    const accessToken = requireString(response.access_token, 'access_token', 'Device token response');
+async function validateTokenResponse(server, response, requestedScopes, fetch_, identity) {
+    let accessToken;
+    try {
+        accessToken = requireString(response.access_token, 'access_token', 'Device token response');
+    }
+    catch (error) {
+        if (identity && typeof response.refresh_token === 'string' && response.refresh_token)
+            await revokeRefreshToken(server, response.refresh_token, fetch_);
+        throw error;
+    }
     const refreshToken = requireString(response.refresh_token, 'refresh_token', 'Device token response');
     if (!Number.isFinite(response.expires_in) || response.expires_in <= 0) {
+        if (identity)
+            await revokeRefreshToken(server, refreshToken, fetch_);
         throw new DeviceAuthorizationError('Device token response has invalid expires_in');
     }
     let scopes;
@@ -118,15 +131,15 @@ async function validateTokenResponse(server, response, requestedScopes, fetch_)
     }
     return { accessToken, refreshToken, expiresInSeconds: response.expires_in, scopes };
 }
-async function pollDeviceCode(server, clientId, deviceCode, fetch_, requestedScopes) {
-    const response = await fetch_(new URL('/oauth/token', server), {
+async function pollDeviceCode(server, clientId, deviceCode, fetch_, requestedScopes, identity) {
+    const response = await fetch_(deviceEndpoint(server, '/oauth/token', identity), {
         method: 'POST',
         headers: { 'content-type': 'application/x-www-form-urlencoded' },
         body: new URLSearchParams({
             grant_type: DEVICE_CODE_GRANT_TYPE,
             client_id: clientId,
             device_code: deviceCode,
-            device_id: await loadDeviceId(),
+            device_id: identity?.deviceId ?? await loadDeviceId(),
         }),
     });
     if (response.status === 400) {
@@ -141,13 +154,13 @@ async function pollDeviceCode(server, clientId, deviceCode, fetch_, requestedSco
     if (response.status !== 200)
         throw new DeviceAuthorizationError(`Device token polling failed: ${response.status}`);
     const token = await response.json();
-    return validateTokenResponse(server, token, requestedScopes, fetch_);
+    return validateTokenResponse(server, token, requestedScopes, fetch_, identity);
 }
 /**
  * Uses OAuth Device Authorization for both desktop and headless clients. The notification socket
  * only carries state; the tokens exist only in this call's return value.
  */
-export async function authorizeDevice(server, clientName, hostname, deps = {}, requestedScopes = DEFAULT_CLI_SCOPES) {
+export async function authorizeDevice(server, clientName, hostname, deps = {}, requestedScopes = DEFAULT_CLI_SCOPES, identity) {
     const baseUrl = normalizedServer(server);
     const fetch_ = deps.fetch ?? globalThis.fetch;
     const print = deps.print ?? console.log;
@@ -155,9 +168,10 @@ export async function authorizeDevice(server, clientName, hostname, deps = {}, r
     const createWebSocket = deps.createWebSocket ?? ((url) => new WebSocket(url));
     const now = deps.now ?? Date.now;
     const wait = deps.sleep ?? sleep;
+    const flowIdentity = identity ? Object.freeze({ deviceId: requireString(identity.deviceId, 'deviceId', 'Device authorization identity') }) : undefined;
     void clientName;
     const clientId = 'axom-cli';
-    const authorization = await requestJson(fetch_, new URL('/oauth/device_authorization', baseUrl), {
+    const authorization = await requestJson(fetch_, deviceEndpoint(baseUrl, '/oauth/device_authorization', flowIdentity), {
         method: 'POST',
         headers: { 'content-type': 'application/x-www-form-urlencoded' },
         body: new URLSearchParams({ client_id: clientId, hostname, scope: requestedScopes.join(' ') }),
@@ -176,7 +190,7 @@ export async function authorizeDevice(server, clientName, hostname, deps = {}, r
     while (now() < deadline) {
         let socket;
         try {
-            socket = createWebSocket(websocketUrl(baseUrl));
+            socket = createWebSocket(websocketUrl(baseUrl, flowIdentity));
         }
         catch {
             const delay = Math.min(retry.recordFailure(), Math.max(0, deadline - now()));
@@ -187,14 +201,14 @@ export async function authorizeDevice(server, clientName, hostname, deps = {}, r
         }
         const status = await waitForNotification(socket, sessionId, notificationTicket, deadline, now, () => retry.recordSuccess());
         if (status === 'approved') {
-            const tokens = await exchangeDeviceCode(baseUrl, clientId, deviceCode, fetch_, requestedScopes);
+            const tokens = await exchangeDeviceCode(baseUrl, clientId, deviceCode, fetch_, requestedScopes, flowIdentity);
             return { clientId, ...tokens };
         }
         if (status === 'denied')
             throw new DeviceAuthorizationError('Device authorization was denied');
         if (status === 'expired')
             break;
-        const polled = await pollDeviceCode(baseUrl, clientId, deviceCode, fetch_, requestedScopes);
+        const polled = await pollDeviceCode(baseUrl, clientId, deviceCode, fetch_, requestedScopes, flowIdentity);
         if (polled)
             return { clientId, ...polled };
         const pollingFloor = Math.max(1, authorization.interval ?? 5) * 1_000;

package/dist/workstation/protocol/agent.js

@@ -1,5 +1,5 @@
 import { accountLimitsSchema } from './accountLimits.js';
-import { isRuntimeDiagnostics } from '../qoderAdapter/profile.js';
+import { isRuntimeDiagnostics } from './runtimeDiagnostics.js';
 import { decodeChannelFrame, hasOptional, hasRequired, isBoolean, isBridgeInfoArray, isNullableAuthMethodInfoArray, isNullableString, isNumber, isObject, isString, isStringArray, isStringRecord, } from './common.js';
 /** Current version and feature floors for the independently negotiated agent protocol. */
 export const AGENT_WIRE_VERSION = 27;
@@ -14,9 +14,7 @@ export const AGENT_WIRE_SWITCH_IDLE_VERSION = 26;
 export const AGENT_WIRE_NATIVE_DELETE_VERSION = 24;
 export const AGENT_WIRE_PROVIDER_TASK_VERSION = 23;
 export const AGENT_WIRE_RUNTIME_PROFILE_VERSION = 22;
-export const AGENT_WIRE_DELEGATION_RENEW_VERSION = 21;
 export const AGENT_WIRE_TURN_IDENTITY_VERSION = 20;
-export const AGENT_WIRE_DELEGATION_MCP_VERSION = 19;
 /** Scoped replay/history is enabled only when both peers preserve native origin. */
 export const AGENT_WIRE_SCOPED_ORIGIN_VERSION = 18;
 /** agent_open.requireSessionLoad: reject unsupported/failed load without session/new fallback. */
@@ -246,9 +244,6 @@ export const AGENT_FRAME_SHAPES = {
             env: isStringRecord, pathPrepend: isStringArray, agentEnv: isStringRecord, command: isNullableString,
             args: isStringArray, nativeSessionId: isNullableString,
             resumeFromSeq: isNumber, backfill: isBoolean, requireSessionLoad: isBoolean,
-            delegationMcp: (value) => isObject(value) &&
-                isString(value.url) && isStringRecord(value.headers) && isNumber(value.expiresAtEpochMs) &&
-                (value.bindingId === undefined || isString(value.bindingId)),
         },
     },
     agent_opened: {
@@ -265,9 +260,6 @@ export const AGENT_FRAME_SHAPES = {
             // `reloaded` is `true`-or-absent for the same reason as `supportsSteering`: a `false` would
             // be a second spelling of what its absence already says.
             reloaded: isVerifiedTrue,
-            delegationExpiresAtEpochMs: isNumber,
-            delegationRefreshPending: isVerifiedTrue,
-            delegationInstanceId: isString, delegationBindingId: isString, delegationRenewalRevision: isNumber,
             agentInfo: isAgentInfo, supportsImageInput: isVerifiedTrue, configOptions: isNullableSessionConfigOptionArray,
             // Same guard as `agent_verified.authMethods`, and the same absent-vs-`[]` reading: a
             // half-decoded method table is worse than none, because the reader would offer a login the
@@ -286,10 +278,6 @@ export const AGENT_FRAME_SHAPES = {
         },
     },
     agent_prompt: { required: { sessionRef: isString, text: isString }, optional: { images: isImageBlockArray, platformTurnId: isString } },
-    agent_delegation_renew: { required: { id: isString, sessionRef: isString, nativeSessionId: isString,
-            instanceId: isString, bindingId: isString, renewalRevision: isNumber, expiresAtEpochMs: isNumber } },
-    agent_delegation_renewed: { required: { id: isString, ok: isBoolean }, optional: { error: isString,
-            nativeSessionId: isString, instanceId: isString, bindingId: isString, renewalRevision: isNumber, expiresAtEpochMs: isNumber } },
     agent_answer: { required: { sessionRef: isString, requestId: isString, outcome: isString } },
     // `content`'s interior is never validated here -- it is ACP's free-form elicitation payload, and
     // this table is transport, not translator. `isRecord` only rejects a non-object.
@@ -773,7 +761,6 @@ export function outboundFailureReply(frame, reason) {
         case 'agent_steered': return { t: 'agent_steered', id, ok: false, error };
         case 'agent_account_read_result': return { t: 'agent_account_read_result', id, ok: false, error };
         case 'agent_config_option_set': return { t: 'agent_config_option_set', id, ok: false, error };
-        case 'agent_delegation_renewed': return { t: 'agent_delegation_renewed', id, ok: false, error };
         case 'agent_switch_idle_result': return { t: 'agent_switch_idle_result', id, ok: false, error };
         case 'agent_provider_task_stopped': return { t: 'agent_provider_task_stopped', id, state: 'unknown', error };
         case 'agent_backfill_done':
@@ -790,7 +777,7 @@ export function decodeAgentFrame(text) {
         if ((frame.state === 'completed' || frame.state === 'failed' || frame.state === 'stopped') && frame.live)
             throw new TypeError('Invalid provider task terminal live state');
         if (frame.status !== undefined &&
-            (frame.status !== frame.state || !['completed', 'failed', 'stopped'].includes(frame.status)))
+            (frame.status !== frame.state || !['completed', 'failed', 'stopped'].some(status => status === frame.status)))
             throw new TypeError('Invalid provider task terminal status');
         if (frame.summary !== undefined && frame.status === undefined)
             throw new TypeError('Provider task summary requires terminal status');

package/dist/workstation/protocol/management.js

@@ -1,3 +1,5 @@
+import { decodeDesktopManagementFrame, parseDesktopJson, DesktopProtocolError } from '../desktopControl/protocol.js';
+import { parseAutomationJson } from '../desktopControl/automationJson.js';
 import { decodeChannelFrame, hasOptional, hasRequired, isBoolean, isBridgeInfoArray, isNullableString, isNumber, isObject, isString, } from './common.js';
 export const MANAGEMENT_WIRE_MIN_VERSION = 1;
 /** Adds the `DRAINING` value to ClientUpdatePhase. */
@@ -12,7 +14,9 @@ export const MANAGEMENT_WIRE_LOAD_AVERAGES_VERSION = 6;
 export const MANAGEMENT_WIRE_GPU_VERSION = 7;
 /** Adds `keepers` to heartbeats and the `keeper_control` / `keeper_control_result` pair (spec §8.1, Task 26). */
 export const MANAGEMENT_WIRE_KEEPERS_VERSION = 8;
-export const MANAGEMENT_WIRE_VERSION = MANAGEMENT_WIRE_KEEPERS_VERSION;
+export const MANAGEMENT_WIRE_DESKTOP_VERSION = 9;
+export const MANAGEMENT_WIRE_DEVICE_OWNERSHIP_VERSION = 10;
+export const MANAGEMENT_WIRE_VERSION = MANAGEMENT_WIRE_DEVICE_OWNERSHIP_VERSION;
 /** Bounds of one heartbeat's `keepers` (spec §8.1). */
 export const KEEPER_STATUS_MAX_ITEMS = 32;
 export const KEEPER_LABEL_MAX_CHARS = 64;
@@ -57,6 +61,7 @@ function isUpdateStatus(value) {
         && hasOptional(value, {
             commandId: isString, version: isString, releaseSha512: isString, force: isBoolean,
             activeShellTasks: isNumber, activeAgentTasks: isNumber, error: isString,
+            remoteForcePolicy: policy => policy === 'drain-only',
         });
 }
 function isOsInfo(value) {
@@ -128,7 +133,7 @@ function isManagementFrame(value) {
         }) && hasOptional(value, { bridges: isBridgeInfoArray });
         case 'management_ready': return hasRequired(value, {
             serverNonce: isString, generation: isString, protocols: isSelectedProtocolMap,
-        }) && hasOptional(value, { release: isNullable(isRelease) });
+        }) && hasOptional(value, { release: isNullable(isRelease), ownerUserId: isString });
         case 'heartbeat': return hasRequired(value, {
             seq: isNumber, sentAtEpochMs: isNumber, clientVersion: isString,
             channels: (channels) => isObject(channels) && Object.entries(channels).every(([kind, state]) => CHANNEL_KINDS.has(kind) && isChannelState(state)),
@@ -137,14 +142,16 @@ function isManagementFrame(value) {
             playgroundCwd: isString,
             protocols: (protocols) => isProtocolRangeMap(protocols, false),
             os: isNullable(isOsInfo),
+            toolchain: (toolchain) => isObject(toolchain) && hasRequired(toolchain, { python: isNullableString, node: isNullableString }),
             update: isNullable(isUpdateStatus),
             metrics: isNullable(isWorkstationMetrics),
             keepers: isNullable((keepers) => Array.isArray(keepers) && keepers.every(isKeeperStatus)),
+            capabilitiesRevision: value => Number.isSafeInteger(value) && value > 0,
         });
         case 'heartbeat_ack': return hasRequired(value, { seq: isNumber });
         case 'channel_ticket_request': return hasRequired(value, { channel: isChannelKind });
         case 'channel_ticket': return hasRequired(value, { channel: isChannelKind, ticket: isString, expiresAtEpochMs: isNumber });
-        case 'client_update': return hasRequired(value, { commandId: isString, release: isRelease, force: isBoolean });
+        case 'client_update': return hasRequired(value, { commandId: isString, release: isRelease, force: isBoolean }) && hasOptional(value, { remoteForcePolicy: value => value === 'drain-only' });
         case 'client_update_status': return hasRequired(value, { status: isUpdateStatus });
         case 'external_agents_scan': return hasRequired(value, { commandId: isString });
         case 'external_agents_scan_result': return hasRequired(value, { commandId: isString, bridges: isBridgeInfoArray });
@@ -157,8 +164,109 @@ function isManagementFrame(value) {
     }
 }
 export function encodeManagementFrame(frame) {
-    return JSON.stringify(frame);
+    const text = JSON.stringify(frame);
+    if (frame.t === 'desktop_automation_prepare')
+        decodeAutomationPrepare(text);
+    if (isDesktopManagementType(frame.t))
+        decodeDesktopManagementFrame(text);
+    return text;
 }
-export function decodeManagementFrame(text) {
+export function decodeManagementFrame(source) {
+    const text = typeof source === 'string' ? source : new TextDecoder('utf-8', { fatal: true }).decode(source);
+    // Desktop extensions get the strict lexical/shape guard before any lossy object parsing.
+    const parsed = JSON.parse(text);
+    if (isObject(parsed) && parsed.t === 'desktop_automation_prepare')
+        return decodeAutomationPrepare(text);
+    if (isObject(parsed) && isDesktopManagementType(parsed.t))
+        return decodeDesktopManagementFrame(text);
+    if (isObject(parsed) && parsed.t === 'heartbeat' && Object.hasOwn(parsed, 'capabilitiesRevision'))
+        validateHeartbeatRevision(text);
     return decodeChannelFrame(text, DISCRIMINATORS, isManagementFrame);
 }
+function decodeAutomationPrepare(text) {
+    const value = parseAutomationJson(text, 49152).value;
+    if (Object.keys(value).sort().join(',') !== 'automationProtocol,binding,deviceGeneration,grant,t' || value.automationProtocol !== 1 ||
+        typeof value.grant !== 'string' || !/^[A-Za-z0-9_-]{43}$/.test(value.grant) ||
+        value.binding?.route?.deviceGeneration !== value.deviceGeneration || !value.binding?.native || !value.binding?.preparation || typeof value.binding.executionId !== 'string')
+        throw new DesktopProtocolError('Invalid automation preparation');
+    return value;
+}
+/** Select only the new root field. JSON.parse already validates syntax; legacy nesting, size,
+ * unknown fields and duplicate legacy keys keep their established decoder behavior. */
+function validateHeartbeatRevision(text) {
+    let depth = 0, count = 0;
+    for (let offset = 0; offset < text.length; offset++) {
+        const char = text[offset];
+        if (char === '"') {
+            const start = offset++;
+            while (offset < text.length) {
+                if (text[offset] === '\\')
+                    offset += 2;
+                else if (text[offset++] === '"')
+                    break;
+            }
+            const end = offset--;
+            if (depth !== 1 || JSON.parse(text.slice(start, end)) !== 'capabilitiesRevision')
+                continue;
+            let tokenStart = end;
+            while (/\s/.test(text[tokenStart] ?? ''))
+                tokenStart++;
+            if (text[tokenStart] !== ':')
+                continue; // This string was a legacy field's value.
+            let tokenEnd = ++tokenStart;
+            while (tokenEnd < text.length && text[tokenEnd] !== ',' && text[tokenEnd] !== '}')
+                tokenEnd++;
+            const token = text.slice(tokenStart, tokenEnd).trim();
+            if (++count !== 1 || !/^[1-9][0-9]*$/.test(token) || !Number.isSafeInteger(Number(token))) {
+                throw new DesktopProtocolError('Invalid capabilities revision');
+            }
+            parseDesktopJson(`{"capabilitiesRevision":${token}}`);
+        }
+        else if (char === '{' || char === '[')
+            depth++;
+        else if (char === '}' || char === ']')
+            depth--;
+    }
+}
+function isDesktopManagementType(type) {
+    return typeof type === 'string' && ['desktop_background', 'desktop_lobby', 'desktop_lobby_result', 'workstation_capabilities', 'workstation_capabilities_request', 'desktop_prepare',
+        'desktop_prepare_result', 'desktop_cancel', 'desktop_isolation_result', 'desktop_session_state', 'desktop_ownership', 'desktop_ownership_result'].includes(type);
+}
+export class ManagementFrameAdmission {
+    isCurrent;
+    ready;
+    disposed = false;
+    constructor(isCurrent = () => true) {
+        this.isCurrent = isCurrent;
+    }
+    admit(frame) {
+        if (this.disposed || !this.isCurrent())
+            return false;
+        if (frame.t === 'management_ready') {
+            if (this.ready || !Number.isInteger(frame.protocols.MANAGEMENT) || frame.protocols.MANAGEMENT < MANAGEMENT_WIRE_MIN_VERSION
+                || frame.protocols.MANAGEMENT > MANAGEMENT_WIRE_VERSION || !frame.generation)
+                return false;
+            this.ready = frame;
+            return true;
+        }
+        if (frame.t === 'heartbeat' && frame.capabilitiesRevision !== undefined)
+            return false;
+        if (frame.t === 'desktop_ownership')
+            return !!this.ready && this.ready.protocols.MANAGEMENT >= 10 && frame.deviceGeneration === this.ready.generation;
+        if (frame.t === 'desktop_automation_prepare')
+            return !!this.ready && this.ready.protocols.MANAGEMENT >= MANAGEMENT_WIRE_DESKTOP_VERSION && frame.deviceGeneration === this.ready.generation;
+        if (!isDesktopManagementType(frame.t))
+            return true;
+        if (!this.ready || this.ready.protocols.MANAGEMENT < MANAGEMENT_WIRE_DESKTOP_VERSION)
+            return false;
+        switch (frame.t) {
+            case 'workstation_capabilities_request': return frame.generation === this.ready.generation;
+            case 'desktop_lobby':
+            case 'desktop_background':
+            case 'desktop_prepare': return frame.deviceGeneration === this.ready.generation;
+            case 'desktop_cancel': return true; // Current socket binding; T10 additionally fences its session/control generation.
+            default: return false; // Device-authored reports/results/states cannot be echoed as server activity.
+        }
+    }
+    dispose() { this.disposed = true; }
+}

package/dist/workstation/protocol/runtimeDiagnostics.js

@@ -0,0 +1,15 @@
+export function isRuntimeDiagnostics(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const input = value;
+    const bounded = (value, max) => typeof value === 'string' &&
+        value.trim().length > 0 && value.length <= max && !/[\x00-\x1f\x7f]/.test(value);
+    if (!bounded(input.generation, 256) || !Number.isSafeInteger(input.revision) ||
+        input.revision < 0 || typeof input.available !== 'boolean' ||
+        !input.launch || typeof input.launch !== 'object')
+        return false;
+    const launch = input.launch;
+    return ['command-override', 'registry', 'registry-fallback', 'direct'].includes(launch.source) &&
+        bounded(launch.executable, 4096) && bounded(launch.platform, 64) && bounded(launch.architecture, 64) &&
+        launch.transport === 'stdio' && (input.profile === undefined || (typeof input.profile === 'object' && input.profile !== null && !Array.isArray(input.profile)));
+}

package/dist/workstation/rd/artifact.js

@@ -0,0 +1,120 @@
+import { promises as fs, constants } from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { gunzipSync } from 'node:zlib';
+import { z } from 'zod';
+import { deploymentDownloadURL } from '../control/serverIdentity.js';
+import { downloadVerified } from '../update/artifact.js';
+import { privateDirectory } from '../keepers/kit/paths.js';
+const legacyRdFiles = ['bin/axom-desktop-keeper', 'bin/axom-input-guardian', 'bin/axom-quic', 'xorg.conf'];
+export const RD_DEVICE_HOST_PLATFORM = 'linux-x64-debian-13-device-host';
+export const rdFiles = [...legacyRdFiles, 'bin/axom-display', 'bin/axom-desktop-session'];
+const sha256 = z.string().regex(/^[a-f0-9]{64}$/);
+export const rdArtifactSchema = z.object({ version: z.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9._+-]{0,127}$/),
+    filename: z.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9._+-]*\.(?:tar\.gz|tgz)$/),
+    url: z.string(), size: z.number().int().min(1).max(134217728), sha512: z.string().regex(/^[a-f0-9]{128}$/),
+    unpackedSize: z.number().int().min(1).max(268435456), ipcVersion: z.union([z.literal(1), z.literal(2)]),
+    files: z.record(z.string(), sha256),
+}).refine(artifact => {
+    const files = artifact.ipcVersion === 1 ? legacyRdFiles : rdFiles;
+    const licenses = artifact.ipcVersion === 2 ? ['opus-LICENSE', 'webp-LICENSE'].filter(file => file in artifact.files) : [];
+    return Object.keys(artifact.files).length === files.length + licenses.length && files.every(file => file in artifact.files);
+}, 'RD artifact files do not match its runtime version');
+export function rdPlatform(osRelease, architecture) {
+    const values = Object.fromEntries(osRelease.split('\n').map(line => /^([A-Z_]+)=["']?([^"']*)["']?$/.exec(line)).filter(Boolean).map(match => [match[1], match[2]]));
+    if (values.ID !== 'debian' || values.VERSION_ID !== '13' || architecture !== 'x64') {
+        throw new Error('Remote desktop currently supports Debian 13 amd64; this distribution/architecture has no qualified RD package');
+    }
+    return RD_DEVICE_HOST_PLATFORM;
+}
+export function unpackRd(bytes, artifact) {
+    const archive = gunzipSync(bytes, { maxOutputLength: artifact.unpackedSize + 65536 });
+    const files = new Map();
+    let unpackedSize = 0;
+    let terminated = false;
+    for (let offset = 0; offset + 512 <= archive.length;) {
+        const header = archive.subarray(offset, offset + 512);
+        if (header.every(byte => byte === 0)) {
+            if (offset + 1024 > archive.length || archive.subarray(offset).some(byte => byte !== 0))
+                throw new Error('RD archive has an invalid terminator or trailing records');
+            terminated = true;
+            break;
+        }
+        const field = (start, length) => header.subarray(start, start + length).toString('utf8').replace(/\0.*$/s, '');
+        const name = field(0, 100), prefix = field(345, 155), sizeText = field(124, 12).trim();
+        const checksum = field(148, 8).trim();
+        const actualChecksum = header.reduce((sum, byte, index) => sum + (index >= 148 && index < 156 ? 32 : byte), 0);
+        if (field(257, 6) !== 'ustar' || field(263, 2) !== '00' || !/^[0-7]+$/.test(checksum) || Number.parseInt(checksum, 8) !== actualChecksum)
+            throw new Error('RD archive has an invalid USTAR header');
+        if (prefix || !/^[0-7]+$/.test(sizeText) || !Object.hasOwn(artifact.files, name) || files.has(name) || ![0, 48].includes(header[156])) {
+            throw new Error('RD archive contains an unexpected file, path, link or duplicate');
+        }
+        const size = Number.parseInt(sizeText, 8);
+        offset += 512;
+        unpackedSize += size;
+        if (!Number.isSafeInteger(size) || offset + size > archive.length || unpackedSize > artifact.unpackedSize)
+            throw new Error('RD archive exceeds its declared size');
+        const contents = archive.subarray(offset, offset + size);
+        if (createHash('sha256').update(contents).digest('hex') !== artifact.files[name])
+            throw new Error(`RD component checksum mismatch: ${name}`);
+        files.set(name, contents);
+        offset += Math.ceil(size / 512) * 512;
+    }
+    if (!terminated || files.size !== Object.keys(artifact.files).length || unpackedSize !== artifact.unpackedSize)
+        throw new Error('RD archive is incomplete');
+    return files;
+}
+export async function verifyRdInstallation(directory, artifact) {
+    for (const name of Object.keys(rdArtifactSchema.parse(artifact).files)) {
+        const file = await fs.open(path.join(directory, name), constants.O_RDONLY | constants.O_NOFOLLOW);
+        try {
+            const info = await file.stat();
+            if (!info.isFile() || info.uid !== process.getuid?.() || info.mode & 0o022 || info.size > artifact.unpackedSize)
+                throw new Error('Unsafe RD installation');
+            if (createHash('sha256').update(await file.readFile()).digest('hex') !== artifact.files[name])
+                throw new Error(`RD component checksum mismatch: ${name}`);
+        }
+        finally {
+            await file.close();
+        }
+    }
+}
+export async function installRd(directory, server, platform, fetchImpl = globalThis.fetch) {
+    const response = await fetchImpl(deploymentDownloadURL(server, '/download/client/desktop/manifest.json'), { redirect: 'error', signal: AbortSignal.timeout(15000) });
+    if (!response.ok)
+        throw new Error(`The server does not publish Linux RD packages (HTTP ${response.status})`);
+    const text = await response.text();
+    if (Buffer.byteLength(text) > 1048576)
+        throw new Error('RD catalog is too large');
+    const catalog = z.object({ schemaVersion: z.literal(1), artifacts: z.record(z.string(), rdArtifactSchema) }).parse(JSON.parse(text));
+    const artifact = catalog.artifacts[platform];
+    if (!artifact)
+        throw new Error(`The server has no RD package for ${platform}`);
+    if (artifact.url !== `/download/client/desktop/${artifact.filename}`)
+        throw new Error('RD artifact URL does not match its filename');
+    const target = path.join(directory, 'rd', 'versions', artifact.sha512.slice(0, 32));
+    try {
+        await verifyRdInstallation(target, artifact);
+        return { directory: target, artifact };
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    const downloaded = await downloadVerified(artifact, { server, fetch: fetchImpl });
+    await privateDirectory(path.dirname(target));
+    const staging = await fs.mkdtemp(path.join(path.dirname(target), '.install-'));
+    try {
+        const files = unpackRd(await fs.readFile(downloaded.path), artifact);
+        await privateDirectory(path.join(staging, 'bin'));
+        for (const [name, contents] of files)
+            await fs.writeFile(path.join(staging, name), contents, { flag: 'wx', mode: name.startsWith('bin/') ? 0o700 : 0o600 });
+        await verifyRdInstallation(staging, artifact);
+        await fs.rename(staging, target);
+        return { directory: target, artifact };
+    }
+    finally {
+        await downloaded.cleanup();
+        await fs.rm(staging, { recursive: true, force: true });
+    }
+}

package/dist/workstation/rd/control.js

@@ -0,0 +1,117 @@
+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 { loadConfig, resolveServer } from '../../config.js';
+import { loadClientConfig } from '../config.js';
+import { normalizeWorkstationServer } from '../control/serverIdentity.js';
+import { withPrivateLock } from '../control/locks.js';
+import { installRd, rdPlatform } from './artifact.js';
+import { readRdState, writeRdState } from './state.js';
+import { chooseSession, discoverSessions } from './sessions.js';
+const execute = promisify(execFile);
+export function rdSessionSelection(previous, options) {
+    const session = z.enum(['auto', 'existing', 'virtual']).parse(options.rdSession ?? previous?.session ?? 'auto');
+    const display = options.rdDisplay ?? (options.rdSession === undefined ? previous?.display : undefined);
+    if (display !== undefined && !/^:\d+(?:\.\d+)?$/.test(display))
+        throw new Error('--rd-display must be a local X11 display such as :10');
+    if (session === 'virtual' && display)
+        throw new Error('--rd-display selects an existing session and cannot be combined with --rd-session virtual');
+    return { session, display };
+}
+export async function configureRd(directory, options) {
+    if (!options.enableRd && !options.disableRd && options.rdSession === undefined && options.rdDisplay === undefined)
+        return;
+    if (process.platform !== 'linux' || process.getuid?.() === 0)
+        throw new Error('Linux RD must be configured and run as the workstation user, not root');
+    if (options.enableRd && options.disableRd)
+        throw new Error('--enable-rd and --disable-rd cannot be combined');
+    if (!options.enableRd && !options.disableRd)
+        throw new Error('--rd-session and --rd-display require --enable-rd');
+    await withPrivateLock(path.join(directory, 'rd', 'install'), async () => {
+        const previous = await readRdState(directory);
+        const registered = await loadClientConfig(directory).catch(error => {
+            if (error.code !== 'ENOENT')
+                throw error;
+            return undefined;
+        });
+        const server = normalizeWorkstationServer(options.server ?? registered?.server ?? resolveServer(await loadConfig()));
+        if (options.disableRd) {
+            await writeRdState(directory, previous ? { ...previous, enabled: false } : { schemaVersion: 2, enabled: false, artifactSource: server, session: 'auto' });
+            return;
+        }
+        const { session, display } = rdSessionSelection(previous, options);
+        const platform = rdPlatform(await fs.readFile('/etc/os-release', 'utf8'), process.arch);
+        const installed = await installRd(directory, server, platform);
+        await ensureDependencies(installed.directory, session, display, installed.artifact);
+        await writeRdState(directory, { schemaVersion: 2, enabled: true, artifactSource: server, session, ...(display ? { display } : {}),
+            installation: installed.directory, artifact: installed.artifact });
+        console.log(`Remote desktop enabled (${session}, ${installed.artifact.version}); capture starts only when an authorized viewer connects`);
+    });
+}
+async function ensureDependencies(installation, session, display, artifact) {
+    let runtimeMissing = false;
+    try {
+        await execute(path.join(installation, 'bin/axom-desktop-keeper'), ['--self-test'], { timeout: 5000, maxBuffer: 8192 });
+    }
+    catch {
+        runtimeMissing = true;
+    }
+    const selected = chooseSession(await discoverSessions(), { session, display });
+    const packages = runtimeMissing ? ['libavcodec61', 'libavutil59', 'libswscale8', 'libgstreamer-plugins-bad1.0-0', 'libx11-6', 'libxext6', 'libxdamage1', 'libxfixes3', 'libxtst6', 'libxrandr2', 'libxcomposite1', 'zlib1g'] : [];
+    if (artifact?.ipcVersion === 2)
+        packages.push('python3', 'x11-xserver-utils', 'x11-utils', 'xauth', 'libpulse0', 'pulseaudio', 'pulseaudio-utils', 'libasound2-plugins');
+    if (!selected)
+        packages.push('xserver-xorg-core', 'xserver-xorg-video-dummy', 'xfce4-session', 'xfwm4', 'xfce4-panel', 'xfdesktop4', 'xfce4-settings', 'thunar', 'xfce4-terminal', 'dbus-x11', 'xauth', 'x11-utils', 'fonts-dejavu-core');
+    if (!packages.length)
+        return;
+    const missing = [];
+    for (const name of packages) {
+        try {
+            const { stdout } = await execute('dpkg-query', ['-W', '-f=${db:Status-Status}', name], { timeout: 2000, maxBuffer: 4096 });
+            if (stdout.trim() !== 'installed')
+                missing.push(name);
+        }
+        catch {
+            missing.push(name);
+        }
+    }
+    if (missing.length) {
+        console.log(`Installing remote desktop dependencies: ${missing.join(', ')}`);
+        try {
+            await execute('sudo', ['-n', 'apt-get', 'install', '-y', '--no-install-recommends', ...missing], { timeout: 180000, maxBuffer: 1048576 });
+        }
+        catch {
+            throw new Error(`Install the required RD packages, then retry: sudo apt-get install --no-install-recommends ${missing.join(' ')}`);
+        }
+    }
+    await execute(path.join(installation, 'bin/axom-desktop-keeper'), ['--self-test'], { timeout: 5000, maxBuffer: 8192 });
+    if (artifact?.ipcVersion === 2) {
+        for (const command of ['axom-display', 'axom-desktop-session'])
+            await execute(path.join(installation, 'bin', command), ['--self-test'], { timeout: 5000, maxBuffer: 8192 });
+    }
+}
+export async function rdStatus(directory) {
+    const state = await readRdState(directory);
+    if (!state)
+        return { enabled: false, installed: false };
+    let observed;
+    let update;
+    try {
+        observed = JSON.parse(await fs.readFile(path.join(directory, 'rd', 'status.json'), 'utf8'));
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    try {
+        update = JSON.parse(await fs.readFile(path.join(directory, 'rd', 'update-status.json'), 'utf8'));
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    return { enabled: state.enabled, installed: state.installation !== undefined, version: state.artifact?.version, selection: state.session, artifactSource: state.artifactSource,
+        ...(state.display ? { requestedDisplay: state.display } : {}), ...(state.enabled ? { observed, update } : {}) };
+}

package/dist/workstation/rd/display.js

@@ -0,0 +1,29 @@
+import { captureSamplingModes } from '../desktopControl/captureModes.js';
+export function parseXrandr(text) {
+    const screen = /current (\d+) x (\d+)/.exec(text);
+    const outputs = [...text.matchAll(/^(\S+) connected(?: primary)? (\d+)x(\d+)\+(\d+)\+(\d+).*$/gm)];
+    if (!screen || outputs.length !== 1 || outputs[0][4] !== '0' || outputs[0][5] !== '0' ||
+        screen[1] !== outputs[0][2] || screen[2] !== outputs[0][3])
+        throw new Error('No consistent single-output X11 desktop is available');
+    const output = outputs[0];
+    const section = text.slice(output.index + output[0].length).split(/^\S/m)[0];
+    const modes = [...section.matchAll(/^\s+(\d+)x(\d+)(?:\S*)\s/gm)]
+        .map(match => ({ width: Number(match[1]), height: Number(match[2]) }))
+        .filter(mode => mode.width >= 2 && mode.height >= 2 && mode.width <= 4096 && mode.height <= 4096 && mode.width % 2 === 0 && mode.height % 2 === 0);
+    return { output: output[1], width: Number(output[2]), height: Number(output[3]),
+        modes: modes.filter((mode, index) => modes.findIndex(other => other.width === mode.width && other.height === mode.height) === index) };
+}
+export function desktopDisplayControl(target, actual, managed) {
+    if (target.kind !== 'window' && target.width === actual.width && target.height === actual.height &&
+        target.width % 2 === 0 && target.height % 2 === 0 && !/^rdp\d+$/i.test(actual.output)) {
+        if (managed && /^DUMMY\d+$/i.test(actual.output))
+            return { ...target, overview: true, resize: 'dynamic',
+                resizeRange: { minWidth: 320, minHeight: 320, maxWidth: 4096, maxHeight: 4096 },
+                modes: [{ width: 1280, height: 720 }, { width: 1920, height: 1080 }, { width: 1024, height: 768 }, { width: 720, height: 1280 }] };
+        if (actual.modes.length > 1)
+            return { ...target, overview: true, resize: 'modes', modes: actual.modes };
+    }
+    return { ...target, overview: true, resize: 'dynamic', captureViewport: true, capturePixelScale: 1,
+        resizeRange: { minWidth: 2, minHeight: 2, maxWidth: target.width & ~1, maxHeight: target.height & ~1 },
+        modes: captureSamplingModes(target.width, target.height) };
+}