@braedonsaunders/appkit-desk 0.4.0

package/plan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan.js","sourceRoot":"","sources":["../src/plan.ts"],"names":[],"mappings":"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","sourcesContent":["import { existsSync } from 'node:fs'\nimport { dirname, isAbsolute, join, resolve } from 'node:path'\n\nexport const DEFAULT_VMM_PATH = '/usr/bin/cloud-hypervisor'\nexport const DEFAULT_KVM_PATH = '/dev/kvm'\nexport const DEFAULT_QEMU_IMG_PATH = '/usr/bin/qemu-img'\nexport const DEFAULT_RUNTIME_DIR = '/run/appkit-desk'\nexport const DEFAULT_MEMORY_MB = 384\nexport const DEFAULT_VCPUS = 2\nexport const DEFAULT_KERNEL_CMDLINE = 'root=/dev/vda rw quiet'\n\nconst DESK_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/\nconst TAP_DEVICE_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_-]{0,14}$/\nconst MAC_ADDRESS_PATTERN = /^[0-9a-f]{2}(?::[0-9a-f]{2}){5}$/i\n/** vsock CIDs 0–2 are reserved (hypervisor, loopback, host). */\nconst MIN_GUEST_CID = 3\nconst MAX_GUEST_CID = 0xffff_fffe\n\n/**\n * Every failure this package raises. The `name` is annotated as `string`\n * rather than left to infer its literal so a subclass can narrow the meaning\n * of a failure — see `DeskRequestFateUnknownError` — without callers losing\n * the one `instanceof DeskError` they already check.\n */\nexport class DeskError extends Error {\n  override readonly name: string = 'DeskError'\n}\n\nexport interface DeskLauncherIdentity {\n  /** Host/container UID used to invoke the VMM and image tooling. */\n  uid: number\n  /** Host/container GID used to invoke the VMM and image tooling. */\n  gid: number\n}\n\nexport interface DeskLaunchPlanOptions {\n  deskId: string\n  vmmPath?: string\n  kvmPath?: string\n  qemuImgPath?: string\n  /** Absolute path of the kernel image the microVM boots. */\n  kernelPath: string\n  /**\n   * Absolute path of an initramfs. Required whenever the kernel loads its\n   * root-filesystem or virtio drivers as modules — a stock distro cloud kernel\n   * panics with \"VFS: Unable to mount root fs\" if it boots without one. Omit\n   * only for a kernel with virtio_blk/ext4 built in.\n   */\n  initramfsPath?: string\n  /** Absolute path of the golden raw base image every desk clones. */\n  baseImagePath: string\n  /** Absolute path of this desk's copy-on-write overlay (a raw reflink clone). */\n  overlayPath: string\n  memoryMb?: number\n  vcpus?: number\n  /** Guest vsock context ID; must be unique among resident desks. */\n  vsockCid: number\n  /** Directory holding the vsock and API control sockets. */\n  runtimeDir?: string\n  /** Host TAP device name; derived from the CID when omitted. */\n  tapDevice?: string\n  /** Guest MAC address; derived from the CID when omitted. */\n  macAddress?: string\n  kernelCmdline?: string\n  launcherIdentity?: DeskLauncherIdentity\n}\n\n/**\n * The complete Cloud Hypervisor invocation as inspectable data. Nothing here\n * has been spawned: tests, audit logs, and readiness screens can assert on the\n * exact argv a desk would boot with.\n */\nexport interface DeskLaunchPlan {\n  deskId: string\n  vmm: { command: string; args: string[] }\n  overlay: {\n    path: string\n    basePath: string\n    /** The overlay-creation step, or `null` when the overlay already exists. */\n    create: { command: string; args: string[] } | null\n  }\n  vsock: { cid: number; socketPath: string }\n  api: { socketPath: string }\n  tap: { device: string; mac: string }\n  memoryMb: number\n  vcpus: number\n  kernelPath: string\n  /** Resolved initramfs path, or `null` when the kernel needs none. */\n  initramfsPath: string | null\n  kernelCmdline: string\n  launcherIdentity?: DeskLauncherIdentity\n}\n\n/**\n * Whether this host can run desks at all: Linux, a usable `/dev/kvm`, and the\n * Cloud Hypervisor binary. All three checks are injectable and the answer is\n * fail-closed — a host missing any of them gets no desk capability rather\n * than a degraded one.\n */\nexport function isDeskSupported(options: {\n  platform?: NodeJS.Platform\n  kvmPath?: string\n  vmmPath?: string\n  pathExists?: (path: string) => boolean\n} = {}): boolean {\n  const platform = options.platform ?? process.platform\n  const pathExists = options.pathExists ?? existsSync\n  return (\n    platform === 'linux'\n    && pathExists(options.kvmPath ?? DEFAULT_KVM_PATH)\n    && pathExists(options.vmmPath ?? DEFAULT_VMM_PATH)\n  )\n}\n\n/** Validate a desk identifier, which is used in socket paths and device names. */\nexport function cleanDeskId(value: string): string {\n  if (!DESK_ID_PATTERN.test(value)) {\n    throw new DeskError(\n      'deskId must be 1–64 letters, numbers, dots, underscores, or hyphens.',\n    )\n  }\n  return value\n}\n\n/**\n * Build the deterministic Cloud Hypervisor launch plan without spawning\n * anything. Fail closed: a missing `/dev/kvm`, VMM binary, kernel, base image,\n * or overlay directory throws instead of producing a plan that cannot boot.\n */\nexport function buildDeskLaunchPlan(\n  options: DeskLaunchPlanOptions,\n  dependencies: {\n    pathExists?: (path: string) => boolean\n    deviceExists?: (path: string) => boolean\n  } = {},\n): DeskLaunchPlan {\n  const pathExists = dependencies.pathExists ?? existsSync\n  const deviceExists = dependencies.deviceExists ?? existsSync\n  const deskId = cleanDeskId(options.deskId)\n  const kvmPath = absolutePath(options.kvmPath ?? DEFAULT_KVM_PATH, 'kvmPath')\n  if (!deviceExists(kvmPath)) {\n    throw new DeskError(\n      `KVM is not available at ${kvmPath}. Desks require hardware virtualization; `\n        + 'there is no software-emulation fallback.',\n    )\n  }\n  const vmmPath = absolutePath(options.vmmPath ?? DEFAULT_VMM_PATH, 'vmmPath')\n  if (!pathExists(vmmPath)) {\n    throw new DeskError(\n      `Cloud Hypervisor was not found at ${vmmPath}. Install cloud-hypervisor or configure vmmPath.`,\n    )\n  }\n  const kernelPath = absolutePath(options.kernelPath, 'kernelPath')\n  if (!pathExists(kernelPath)) {\n    throw new DeskError(`Guest kernel does not exist: ${kernelPath}`)\n  }\n  const initramfsPath =\n    options.initramfsPath === undefined\n      ? null\n      : absolutePath(options.initramfsPath, 'initramfsPath')\n  if (initramfsPath !== null && !pathExists(initramfsPath)) {\n    throw new DeskError(`Initramfs does not exist: ${initramfsPath}`)\n  }\n  const baseImagePath = absolutePath(options.baseImagePath, 'baseImagePath')\n  if (!pathExists(baseImagePath)) {\n    throw new DeskError(`Base image does not exist: ${baseImagePath}`)\n  }\n  const overlayPath = absolutePath(options.overlayPath, 'overlayPath')\n  const overlayDirectory = dirname(overlayPath)\n  if (!pathExists(overlayDirectory)) {\n    throw new DeskError(`Overlay directory does not exist: ${overlayDirectory}`)\n  }\n  const memoryMb = positiveInteger(options.memoryMb ?? DEFAULT_MEMORY_MB, 'memoryMb')\n  const vcpus = positiveInteger(options.vcpus ?? DEFAULT_VCPUS, 'vcpus')\n  const vsockCid = cleanCid(options.vsockCid)\n  const runtimeDir = absolutePath(options.runtimeDir ?? DEFAULT_RUNTIME_DIR, 'runtimeDir')\n  const tapDevice = cleanTapDevice(options.tapDevice ?? defaultTapDevice(vsockCid))\n  const macAddress = cleanMacAddress(options.macAddress ?? defaultMacAddress(vsockCid))\n  const kernelCmdline = options.kernelCmdline ?? DEFAULT_KERNEL_CMDLINE\n  const launcherIdentity = cleanLauncherIdentity(options.launcherIdentity)\n  const vsockSocketPath = join(runtimeDir, `desk-${deskId}.vsock`)\n  const apiSocketPath = join(runtimeDir, `desk-${deskId}.api.sock`)\n\n  const create = pathExists(overlayPath)\n    ? null\n    : {\n        // Cloud Hypervisor cannot follow disk backing chains: a qcow2 overlay\n        // over a qcow2/raw base is rejected with UnsupportedFeature /\n        // MaxNestingDepthExceeded. So the overlay is a plain raw file, cloned\n        // from the raw base with `cp --reflink=auto` — an instant, block-sharing\n        // copy-on-write clone on XFS/Btrfs and a graceful full-copy fallback on\n        // ext4. Either way CH boots the resulting raw file with no backing chain.\n        command: 'cp',\n        args: ['--reflink=auto', baseImagePath, overlayPath],\n      }\n\n  const args = [\n    '--api-socket', apiSocketPath,\n    '--kernel', kernelPath,\n    // A modular distro kernel needs its initramfs to bring up virtio_blk and\n    // mount root; omitted only for a kernel with those drivers built in.\n    ...(initramfsPath === null ? [] : ['--initramfs', initramfsPath]),\n    '--cmdline', kernelCmdline,\n    // Be explicit that the disk is raw: CH deprecated image-format auto-detection\n    // and warns without image_type; there is never a qcow2 overlay here.\n    '--disk', `path=${overlayPath},image_type=raw`,\n    '--memory', `size=${memoryMb}M`,\n    '--cpus', `boot=${vcpus}`,\n    '--vsock', `cid=${vsockCid},socket=${vsockSocketPath}`,\n    '--net', `tap=${tapDevice},mac=${macAddress}`,\n    '--serial', 'off',\n    '--console', 'off',\n  ]\n\n  return {\n    deskId,\n    vmm: { command: vmmPath, args },\n    overlay: { path: overlayPath, basePath: baseImagePath, create },\n    vsock: { cid: vsockCid, socketPath: vsockSocketPath },\n    api: { socketPath: apiSocketPath },\n    tap: { device: tapDevice, mac: macAddress },\n    memoryMb,\n    vcpus,\n    kernelPath,\n    initramfsPath,\n    kernelCmdline,\n    launcherIdentity,\n  }\n}\n\nfunction defaultTapDevice(cid: number): string {\n  return `dsk${cid}`\n}\n\nfunction defaultMacAddress(cid: number): string {\n  // Locally administered, unicast prefix; the low four octets carry the CID so\n  // the address is stable per desk and never collides across resident desks.\n  const octets = [0x06, 0x00, (cid >>> 24) & 0xff, (cid >>> 16) & 0xff, (cid >>> 8) & 0xff, cid & 0xff]\n  return octets.map((octet) => octet.toString(16).padStart(2, '0')).join(':')\n}\n\nfunction cleanCid(value: number): number {\n  if (!Number.isInteger(value) || value < MIN_GUEST_CID || value > MAX_GUEST_CID) {\n    throw new DeskError(\n      `vsockCid must be an integer between ${MIN_GUEST_CID} and ${MAX_GUEST_CID}.`,\n    )\n  }\n  return value\n}\n\nfunction cleanTapDevice(value: string): string {\n  if (!TAP_DEVICE_PATTERN.test(value)) {\n    throw new DeskError('tapDevice must be 1–15 characters of letters, numbers, underscores, or hyphens.')\n  }\n  return value\n}\n\nfunction cleanMacAddress(value: string): string {\n  if (!MAC_ADDRESS_PATTERN.test(value)) {\n    throw new DeskError(`macAddress is not a valid MAC address: ${value}`)\n  }\n  return value.toLowerCase()\n}\n\nexport function cleanLauncherIdentity(\n  identity: DeskLauncherIdentity | undefined,\n): DeskLauncherIdentity | undefined {\n  if (!identity) return undefined\n  const max = 2_147_483_647\n  if (!Number.isInteger(identity.uid) || identity.uid < 1 || identity.uid > max) {\n    throw new DeskError(`launcherIdentity.uid must be an integer between 1 and ${max}.`)\n  }\n  if (!Number.isInteger(identity.gid) || identity.gid < 0 || identity.gid > max) {\n    throw new DeskError(`launcherIdentity.gid must be an integer between 0 and ${max}.`)\n  }\n  return { uid: identity.uid, gid: identity.gid }\n}\n\nfunction absolutePath(value: string, field: string): string {\n  if (!value || !isAbsolute(value)) {\n    throw new DeskError(`${field} must be an absolute path.`)\n  }\n  return resolve(value)\n}\n\nfunction positiveInteger(value: number, field: string): number {\n  if (!Number.isInteger(value) || value < 1) {\n    throw new DeskError(`${field} must be a positive integer.`)\n  }\n  return value\n}\n"]}

package/portable-home.d.ts

@@ -0,0 +1,79 @@
+export declare const PORTABLE_DESK_HOME_VERSION: 1;
+export type PortableDeskHomeEntry = {
+    path: string;
+    kind: 'directory';
+    mode: number;
+    modifiedAt: string | null;
+} | {
+    path: string;
+    kind: 'file';
+    mode: number;
+    modifiedAt: string | null;
+    size: number;
+    digest: string;
+} | {
+    path: string;
+    kind: 'symlink';
+    mode: number;
+    modifiedAt: string | null;
+    target: string;
+};
+export type PortableDeskHomeManifest = {
+    version: typeof PORTABLE_DESK_HOME_VERSION;
+    createdAt: string;
+    entries: readonly PortableDeskHomeEntry[];
+    totalBytes: number;
+};
+export type PortableDeskHomeArchive = {
+    manifest: PortableDeskHomeManifest;
+    /** Content-addressed file bodies. Identical files occupy one blob. */
+    blobs: ReadonlyMap<string, Uint8Array>;
+};
+export type DeskHomeSourceEntry = Omit<Extract<PortableDeskHomeEntry, {
+    kind: 'directory';
+}>, 'path'> & {
+    path: string;
+} | Omit<Extract<PortableDeskHomeEntry, {
+    kind: 'file';
+}>, 'path' | 'size' | 'digest'> & {
+    path: string;
+} | Omit<Extract<PortableDeskHomeEntry, {
+    kind: 'symlink';
+}>, 'path'> & {
+    path: string;
+};
+export interface PortableDeskHomeSource {
+    entries(signal: AbortSignal): AsyncIterable<DeskHomeSourceEntry>;
+    readFile(path: string, signal: AbortSignal): Promise<Uint8Array>;
+}
+export interface PortableDeskHomeImport {
+    writeDirectory(entry: Extract<PortableDeskHomeEntry, {
+        kind: 'directory';
+    }>, signal: AbortSignal): Promise<void>;
+    writeFile(entry: Extract<PortableDeskHomeEntry, {
+        kind: 'file';
+    }>, bytes: Uint8Array, signal: AbortSignal): Promise<void>;
+    writeSymlink(entry: Extract<PortableDeskHomeEntry, {
+        kind: 'symlink';
+    }>, signal: AbortSignal): Promise<void>;
+    /** Atomically make the staged home authoritative. */
+    commit(signal: AbortSignal): Promise<void>;
+    /** Best-effort cleanup of an uncommitted staging area. */
+    rollback(): Promise<void>;
+}
+export interface PortableDeskHomeSink {
+    begin(manifest: PortableDeskHomeManifest, signal: AbortSignal): Promise<PortableDeskHomeImport>;
+}
+export type PortableDeskHomeLimits = {
+    maxEntries?: number;
+    maxFileBytes?: number;
+    maxTotalBytes?: number;
+};
+export declare function exportPortableDeskHome(source: PortableDeskHomeSource, options?: PortableDeskHomeLimits & {
+    signal?: AbortSignal;
+    now?: () => Date;
+}): Promise<PortableDeskHomeArchive>;
+export declare function importPortableDeskHome(archive: PortableDeskHomeArchive, sink: PortableDeskHomeSink, options?: PortableDeskHomeLimits & {
+    signal?: AbortSignal;
+}): Promise<void>;
+//# sourceMappingURL=portable-home.d.ts.map

package/portable-home.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"portable-home.d.ts","sourceRoot":"","sources":["../src/portable-home.ts"],"names":[],"mappings":"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"}

package/portable-home.js

@@ -0,0 +1,193 @@
+import { createHash } from 'node:crypto';
+import { posix } from 'node:path';
+export const PORTABLE_DESK_HOME_VERSION = 1;
+const DEFAULT_LIMITS = {
+    maxEntries: 20_000,
+    maxFileBytes: 64 * 1024 * 1024,
+    maxTotalBytes: 512 * 1024 * 1024,
+};
+export async function exportPortableDeskHome(source, options = {}) {
+    const limits = resolveLimits(options);
+    const controller = linkedController(options.signal);
+    const entries = [];
+    const blobs = new Map();
+    let totalBytes = 0;
+    for await (const raw of source.entries(controller.signal)) {
+        throwIfAborted(controller.signal);
+        if (entries.length >= limits.maxEntries)
+            throw new Error(`Desk home exceeds ${limits.maxEntries} entries.`);
+        const path = portablePath(raw.path);
+        const base = { path, mode: portableMode(raw.mode), modifiedAt: portableDate(raw.modifiedAt) };
+        if (raw.kind === 'directory') {
+            entries.push({ ...base, kind: 'directory' });
+            continue;
+        }
+        if (raw.kind === 'symlink') {
+            entries.push({ ...base, kind: 'symlink', target: portableSymlinkTarget(path, raw.target) });
+            continue;
+        }
+        const bytes = await source.readFile(path, controller.signal);
+        if (!(bytes instanceof Uint8Array))
+            throw new Error(`Desk home source returned invalid bytes for ${path}.`);
+        if (bytes.byteLength > limits.maxFileBytes)
+            throw new Error(`Desk home file ${path} exceeds ${limits.maxFileBytes} bytes.`);
+        totalBytes += bytes.byteLength;
+        if (totalBytes > limits.maxTotalBytes)
+            throw new Error(`Desk home exceeds ${limits.maxTotalBytes} total bytes.`);
+        const digest = digestBytes(bytes);
+        if (!blobs.has(digest))
+            blobs.set(digest, Uint8Array.from(bytes));
+        entries.push({ ...base, kind: 'file', size: bytes.byteLength, digest });
+    }
+    entries.sort(compareEntries);
+    assertUniquePaths(entries);
+    return {
+        manifest: {
+            version: PORTABLE_DESK_HOME_VERSION,
+            createdAt: (options.now?.() ?? new Date()).toISOString(),
+            entries,
+            totalBytes,
+        },
+        blobs,
+    };
+}
+export async function importPortableDeskHome(archive, sink, options = {}) {
+    const limits = resolveLimits(options);
+    const controller = linkedController(options.signal);
+    const manifest = validateArchive(archive, limits);
+    const writer = await sink.begin(manifest, controller.signal);
+    let committed = false;
+    try {
+        for (const entry of manifest.entries.filter((candidate) => candidate.kind === 'directory')) {
+            throwIfAborted(controller.signal);
+            await writer.writeDirectory(entry, controller.signal);
+        }
+        for (const entry of manifest.entries.filter((candidate) => candidate.kind !== 'directory')) {
+            throwIfAborted(controller.signal);
+            if (entry.kind === 'symlink')
+                await writer.writeSymlink(entry, controller.signal);
+            else {
+                const bytes = archive.blobs.get(entry.digest);
+                if (!bytes)
+                    throw new Error(`Desk home blob ${entry.digest} is missing.`);
+                await writer.writeFile(entry, Uint8Array.from(bytes), controller.signal);
+            }
+        }
+        await writer.commit(controller.signal);
+        committed = true;
+    }
+    finally {
+        if (!committed)
+            await writer.rollback().catch(() => undefined);
+    }
+}
+function validateArchive(archive, limits) {
+    const manifest = archive.manifest;
+    if (manifest.version !== PORTABLE_DESK_HOME_VERSION)
+        throw new Error(`Unsupported desk home version ${String(manifest.version)}.`);
+    if (!Number.isFinite(Date.parse(manifest.createdAt)))
+        throw new Error('Desk home createdAt is invalid.');
+    if (manifest.entries.length > limits.maxEntries)
+        throw new Error(`Desk home exceeds ${limits.maxEntries} entries.`);
+    let totalBytes = 0;
+    const entries = manifest.entries.map((entry) => {
+        const path = portablePath(entry.path);
+        const base = { path, mode: portableMode(entry.mode), modifiedAt: portableDate(entry.modifiedAt) };
+        if (entry.kind === 'directory')
+            return { ...base, kind: 'directory' };
+        if (entry.kind === 'symlink')
+            return { ...base, kind: 'symlink', target: portableSymlinkTarget(path, entry.target) };
+        if (!Number.isInteger(entry.size) || entry.size < 0 || entry.size > limits.maxFileBytes) {
+            throw new Error(`Desk home file ${path} has an invalid size.`);
+        }
+        const bytes = archive.blobs.get(entry.digest);
+        if (!bytes || bytes.byteLength !== entry.size || digestBytes(bytes) !== entry.digest) {
+            throw new Error(`Desk home file ${path} failed content verification.`);
+        }
+        totalBytes += entry.size;
+        if (totalBytes > limits.maxTotalBytes)
+            throw new Error(`Desk home exceeds ${limits.maxTotalBytes} total bytes.`);
+        return { ...base, kind: 'file', size: entry.size, digest: entry.digest };
+    });
+    assertUniquePaths(entries);
+    if (totalBytes !== manifest.totalBytes)
+        throw new Error('Desk home total byte count does not match its manifest.');
+    return { ...manifest, entries: [...entries].sort(compareEntries), totalBytes };
+}
+function portablePath(value) {
+    if (typeof value !== 'string' || value.length === 0 || value.includes('\0') || value.includes('\\')) {
+        throw new Error('Desk home paths must be non-empty portable paths.');
+    }
+    const normalized = posix.normalize(value);
+    if (normalized !== value || posix.isAbsolute(value) || value === '..' || value.startsWith('../')) {
+        throw new Error(`Desk home path escapes its root: ${value}`);
+    }
+    return value;
+}
+function portableSymlinkTarget(path, target) {
+    if (typeof target !== 'string' || target.length === 0 || target.includes('\0') || target.includes('\\') || posix.isAbsolute(target)) {
+        throw new Error(`Desk home symlink ${path} has an unsafe target.`);
+    }
+    const resolved = posix.normalize(posix.join(posix.dirname(path), target));
+    if (resolved === '..' || resolved.startsWith('../'))
+        throw new Error(`Desk home symlink ${path} escapes its root.`);
+    return target;
+}
+function portableMode(mode) {
+    if (!Number.isInteger(mode) || mode < 0 || mode > 0o7777)
+        throw new Error('Desk home mode must be between 0000 and 7777.');
+    return mode;
+}
+function portableDate(value) {
+    if (value === null)
+        return null;
+    if (!Number.isFinite(Date.parse(value)))
+        throw new Error('Desk home modifiedAt is invalid.');
+    return value;
+}
+function digestBytes(bytes) {
+    return `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
+}
+function compareEntries(left, right) {
+    const leftDepth = left.path.split('/').length;
+    const rightDepth = right.path.split('/').length;
+    return leftDepth - rightDepth || left.path.localeCompare(right.path);
+}
+function assertUniquePaths(entries) {
+    const paths = new Set();
+    for (const entry of entries) {
+        if (paths.has(entry.path))
+            throw new Error(`Desk home contains duplicate path ${entry.path}.`);
+        paths.add(entry.path);
+    }
+}
+function resolveLimits(options) {
+    return {
+        maxEntries: positiveLimit(options.maxEntries ?? DEFAULT_LIMITS.maxEntries, 'maxEntries'),
+        maxFileBytes: positiveLimit(options.maxFileBytes ?? DEFAULT_LIMITS.maxFileBytes, 'maxFileBytes'),
+        maxTotalBytes: positiveLimit(options.maxTotalBytes ?? DEFAULT_LIMITS.maxTotalBytes, 'maxTotalBytes'),
+    };
+}
+function positiveLimit(value, name) {
+    if (!Number.isSafeInteger(value) || value <= 0)
+        throw new Error(`${name} must be a positive safe integer.`);
+    return value;
+}
+function linkedController(signal) {
+    const controller = new AbortController();
+    if (!signal)
+        return controller;
+    if (signal.aborted)
+        controller.abort(signal.reason);
+    else
+        signal.addEventListener('abort', () => controller.abort(signal.reason), { once: true });
+    return controller;
+}
+function throwIfAborted(signal) {
+    if (!signal.aborted)
+        return;
+    if (signal.reason instanceof Error)
+        throw signal.reason;
+    throw new DOMException('The operation was aborted.', 'AbortError');
+}
+//# sourceMappingURL=portable-home.js.map

package/portable-home.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"portable-home.js","sourceRoot":"","sources":["../src/portable-home.ts"],"names":[],"mappings":"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","sourcesContent":["import { createHash } from 'node:crypto'\nimport { posix } from 'node:path'\n\nexport const PORTABLE_DESK_HOME_VERSION = 1 as const\n\nexport type PortableDeskHomeEntry =\n  | { path: string; kind: 'directory'; mode: number; modifiedAt: string | null }\n  | { path: string; kind: 'file'; mode: number; modifiedAt: string | null; size: number; digest: string }\n  | { path: string; kind: 'symlink'; mode: number; modifiedAt: string | null; target: string }\n\nexport type PortableDeskHomeManifest = {\n  version: typeof PORTABLE_DESK_HOME_VERSION\n  createdAt: string\n  entries: readonly PortableDeskHomeEntry[]\n  totalBytes: number\n}\n\nexport type PortableDeskHomeArchive = {\n  manifest: PortableDeskHomeManifest\n  /** Content-addressed file bodies. Identical files occupy one blob. */\n  blobs: ReadonlyMap<string, Uint8Array>\n}\n\nexport type DeskHomeSourceEntry =\n  | Omit<Extract<PortableDeskHomeEntry, { kind: 'directory' }>, 'path'> & { path: string }\n  | Omit<Extract<PortableDeskHomeEntry, { kind: 'file' }>, 'path' | 'size' | 'digest'> & { path: string }\n  | Omit<Extract<PortableDeskHomeEntry, { kind: 'symlink' }>, 'path'> & { path: string }\n\nexport interface PortableDeskHomeSource {\n  entries(signal: AbortSignal): AsyncIterable<DeskHomeSourceEntry>\n  readFile(path: string, signal: AbortSignal): Promise<Uint8Array>\n}\n\nexport interface PortableDeskHomeImport {\n  writeDirectory(entry: Extract<PortableDeskHomeEntry, { kind: 'directory' }>, signal: AbortSignal): Promise<void>\n  writeFile(\n    entry: Extract<PortableDeskHomeEntry, { kind: 'file' }>,\n    bytes: Uint8Array,\n    signal: AbortSignal,\n  ): Promise<void>\n  writeSymlink(entry: Extract<PortableDeskHomeEntry, { kind: 'symlink' }>, signal: AbortSignal): Promise<void>\n  /** Atomically make the staged home authoritative. */\n  commit(signal: AbortSignal): Promise<void>\n  /** Best-effort cleanup of an uncommitted staging area. */\n  rollback(): Promise<void>\n}\n\nexport interface PortableDeskHomeSink {\n  begin(manifest: PortableDeskHomeManifest, signal: AbortSignal): Promise<PortableDeskHomeImport>\n}\n\nexport type PortableDeskHomeLimits = {\n  maxEntries?: number\n  maxFileBytes?: number\n  maxTotalBytes?: number\n}\n\nconst DEFAULT_LIMITS = {\n  maxEntries: 20_000,\n  maxFileBytes: 64 * 1024 * 1024,\n  maxTotalBytes: 512 * 1024 * 1024,\n} as const\n\nexport async function exportPortableDeskHome(\n  source: PortableDeskHomeSource,\n  options: PortableDeskHomeLimits & { signal?: AbortSignal; now?: () => Date } = {},\n): Promise<PortableDeskHomeArchive> {\n  const limits = resolveLimits(options)\n  const controller = linkedController(options.signal)\n  const entries: PortableDeskHomeEntry[] = []\n  const blobs = new Map<string, Uint8Array>()\n  let totalBytes = 0\n\n  for await (const raw of source.entries(controller.signal)) {\n    throwIfAborted(controller.signal)\n    if (entries.length >= limits.maxEntries) throw new Error(`Desk home exceeds ${limits.maxEntries} entries.`)\n    const path = portablePath(raw.path)\n    const base = { path, mode: portableMode(raw.mode), modifiedAt: portableDate(raw.modifiedAt) }\n    if (raw.kind === 'directory') {\n      entries.push({ ...base, kind: 'directory' })\n      continue\n    }\n    if (raw.kind === 'symlink') {\n      entries.push({ ...base, kind: 'symlink', target: portableSymlinkTarget(path, raw.target) })\n      continue\n    }\n    const bytes = await source.readFile(path, controller.signal)\n    if (!(bytes instanceof Uint8Array)) throw new Error(`Desk home source returned invalid bytes for ${path}.`)\n    if (bytes.byteLength > limits.maxFileBytes) throw new Error(`Desk home file ${path} exceeds ${limits.maxFileBytes} bytes.`)\n    totalBytes += bytes.byteLength\n    if (totalBytes > limits.maxTotalBytes) throw new Error(`Desk home exceeds ${limits.maxTotalBytes} total bytes.`)\n    const digest = digestBytes(bytes)\n    if (!blobs.has(digest)) blobs.set(digest, Uint8Array.from(bytes))\n    entries.push({ ...base, kind: 'file', size: bytes.byteLength, digest })\n  }\n\n  entries.sort(compareEntries)\n  assertUniquePaths(entries)\n  return {\n    manifest: {\n      version: PORTABLE_DESK_HOME_VERSION,\n      createdAt: (options.now?.() ?? new Date()).toISOString(),\n      entries,\n      totalBytes,\n    },\n    blobs,\n  }\n}\n\nexport async function importPortableDeskHome(\n  archive: PortableDeskHomeArchive,\n  sink: PortableDeskHomeSink,\n  options: PortableDeskHomeLimits & { signal?: AbortSignal } = {},\n): Promise<void> {\n  const limits = resolveLimits(options)\n  const controller = linkedController(options.signal)\n  const manifest = validateArchive(archive, limits)\n  const writer = await sink.begin(manifest, controller.signal)\n  let committed = false\n  try {\n    for (const entry of manifest.entries.filter((candidate) => candidate.kind === 'directory')) {\n      throwIfAborted(controller.signal)\n      await writer.writeDirectory(entry, controller.signal)\n    }\n    for (const entry of manifest.entries.filter((candidate) => candidate.kind !== 'directory')) {\n      throwIfAborted(controller.signal)\n      if (entry.kind === 'symlink') await writer.writeSymlink(entry, controller.signal)\n      else {\n        const bytes = archive.blobs.get(entry.digest)\n        if (!bytes) throw new Error(`Desk home blob ${entry.digest} is missing.`)\n        await writer.writeFile(entry, Uint8Array.from(bytes), controller.signal)\n      }\n    }\n    await writer.commit(controller.signal)\n    committed = true\n  } finally {\n    if (!committed) await writer.rollback().catch(() => undefined)\n  }\n}\n\nfunction validateArchive(archive: PortableDeskHomeArchive, limits: Required<PortableDeskHomeLimits>): PortableDeskHomeManifest {\n  const manifest = archive.manifest\n  if (manifest.version !== PORTABLE_DESK_HOME_VERSION) throw new Error(`Unsupported desk home version ${String(manifest.version)}.`)\n  if (!Number.isFinite(Date.parse(manifest.createdAt))) throw new Error('Desk home createdAt is invalid.')\n  if (manifest.entries.length > limits.maxEntries) throw new Error(`Desk home exceeds ${limits.maxEntries} entries.`)\n  let totalBytes = 0\n  const entries = manifest.entries.map((entry): PortableDeskHomeEntry => {\n    const path = portablePath(entry.path)\n    const base = { path, mode: portableMode(entry.mode), modifiedAt: portableDate(entry.modifiedAt) }\n    if (entry.kind === 'directory') return { ...base, kind: 'directory' }\n    if (entry.kind === 'symlink') return { ...base, kind: 'symlink', target: portableSymlinkTarget(path, entry.target) }\n    if (!Number.isInteger(entry.size) || entry.size < 0 || entry.size > limits.maxFileBytes) {\n      throw new Error(`Desk home file ${path} has an invalid size.`)\n    }\n    const bytes = archive.blobs.get(entry.digest)\n    if (!bytes || bytes.byteLength !== entry.size || digestBytes(bytes) !== entry.digest) {\n      throw new Error(`Desk home file ${path} failed content verification.`)\n    }\n    totalBytes += entry.size\n    if (totalBytes > limits.maxTotalBytes) throw new Error(`Desk home exceeds ${limits.maxTotalBytes} total bytes.`)\n    return { ...base, kind: 'file', size: entry.size, digest: entry.digest }\n  })\n  assertUniquePaths(entries)\n  if (totalBytes !== manifest.totalBytes) throw new Error('Desk home total byte count does not match its manifest.')\n  return { ...manifest, entries: [...entries].sort(compareEntries), totalBytes }\n}\n\nfunction portablePath(value: string): string {\n  if (typeof value !== 'string' || value.length === 0 || value.includes('\\0') || value.includes('\\\\')) {\n    throw new Error('Desk home paths must be non-empty portable paths.')\n  }\n  const normalized = posix.normalize(value)\n  if (normalized !== value || posix.isAbsolute(value) || value === '..' || value.startsWith('../')) {\n    throw new Error(`Desk home path escapes its root: ${value}`)\n  }\n  return value\n}\n\nfunction portableSymlinkTarget(path: string, target: string): string {\n  if (typeof target !== 'string' || target.length === 0 || target.includes('\\0') || target.includes('\\\\') || posix.isAbsolute(target)) {\n    throw new Error(`Desk home symlink ${path} has an unsafe target.`)\n  }\n  const resolved = posix.normalize(posix.join(posix.dirname(path), target))\n  if (resolved === '..' || resolved.startsWith('../')) throw new Error(`Desk home symlink ${path} escapes its root.`)\n  return target\n}\n\nfunction portableMode(mode: number): number {\n  if (!Number.isInteger(mode) || mode < 0 || mode > 0o7777) throw new Error('Desk home mode must be between 0000 and 7777.')\n  return mode\n}\n\nfunction portableDate(value: string | null): string | null {\n  if (value === null) return null\n  if (!Number.isFinite(Date.parse(value))) throw new Error('Desk home modifiedAt is invalid.')\n  return value\n}\n\nfunction digestBytes(bytes: Uint8Array): string {\n  return `sha256:${createHash('sha256').update(bytes).digest('hex')}`\n}\n\nfunction compareEntries(left: PortableDeskHomeEntry, right: PortableDeskHomeEntry): number {\n  const leftDepth = left.path.split('/').length\n  const rightDepth = right.path.split('/').length\n  return leftDepth - rightDepth || left.path.localeCompare(right.path)\n}\n\nfunction assertUniquePaths(entries: readonly PortableDeskHomeEntry[]): void {\n  const paths = new Set<string>()\n  for (const entry of entries) {\n    if (paths.has(entry.path)) throw new Error(`Desk home contains duplicate path ${entry.path}.`)\n    paths.add(entry.path)\n  }\n}\n\nfunction resolveLimits(options: PortableDeskHomeLimits): Required<PortableDeskHomeLimits> {\n  return {\n    maxEntries: positiveLimit(options.maxEntries ?? DEFAULT_LIMITS.maxEntries, 'maxEntries'),\n    maxFileBytes: positiveLimit(options.maxFileBytes ?? DEFAULT_LIMITS.maxFileBytes, 'maxFileBytes'),\n    maxTotalBytes: positiveLimit(options.maxTotalBytes ?? DEFAULT_LIMITS.maxTotalBytes, 'maxTotalBytes'),\n  }\n}\n\nfunction positiveLimit(value: number, name: string): number {\n  if (!Number.isSafeInteger(value) || value <= 0) throw new Error(`${name} must be a positive safe integer.`)\n  return value\n}\n\nfunction linkedController(signal?: AbortSignal): AbortController {\n  const controller = new AbortController()\n  if (!signal) return controller\n  if (signal.aborted) controller.abort(signal.reason)\n  else signal.addEventListener('abort', () => controller.abort(signal.reason), { once: true })\n  return controller\n}\n\nfunction throwIfAborted(signal: AbortSignal): void {\n  if (!signal.aborted) return\n  if (signal.reason instanceof Error) throw signal.reason\n  throw new DOMException('The operation was aborted.', 'AbortError')\n}\n"]}

package/protocol.d.ts

@@ -0,0 +1,224 @@
+/**
+ * The framed JSON protocol spoken between the host and the in-guest agent
+ * over vsock. Everything here is pure encode/decode/validate — no sockets, no
+ * processes — so the security-critical parsing is unit-testable on any
+ * platform, and both the host backend and the guest agent share one message
+ * vocabulary.
+ *
+ * Wire format: a 4-byte big-endian length prefix followed by that many bytes
+ * of UTF-8 JSON. Frame sizes are bounded; a peer declaring an oversized frame
+ * is a protocol violation and the connection must be dropped, not resynced.
+ */
+import { Buffer } from 'node:buffer';
+import type { A11yNode, DeskFrameFormat, DeskHandoverScope, DeskPoint, DeskPointerButton, DeskVideoChunkKind, WindowInfo } from './events.js';
+export declare const FRAME_HEADER_BYTES = 4;
+export declare const DEFAULT_MAX_FRAME_BYTES: number;
+/** The vsock port the in-guest agent listens on. */
+export declare const GUEST_AGENT_VSOCK_PORT = 5252;
+export declare class DeskProtocolError extends Error {
+    readonly name = "DeskProtocolError";
+}
+export type GuestInput = {
+    type: 'move';
+    x: number;
+    y: number;
+} | {
+    type: 'click';
+    x: number;
+    y: number;
+    button: DeskPointerButton;
+} | {
+    type: 'type';
+    text: string;
+} | {
+    type: 'key';
+    combo: string;
+} | {
+    type: 'scroll';
+    x: number;
+    y: number;
+    dx: number;
+    dy: number;
+} | {
+    type: 'drag';
+    from: DeskPoint;
+    to: DeskPoint;
+};
+/** A request body, before the transport assigns its correlation id. */
+export type GuestCommand = {
+    op: 'ping';
+} | {
+    op: 'capabilities';
+} | {
+    op: 'exec';
+    command: string;
+    args?: readonly string[];
+    cwd?: string;
+    env?: Readonly<Record<string, string>>;
+    timeoutMs?: number;
+} | {
+    op: 'job-start';
+    command: string;
+    args?: readonly string[];
+    cwd?: string;
+    env?: Readonly<Record<string, string>>;
+} | {
+    op: 'job-signal';
+    jobId: string;
+    signal: 'SIGTERM' | 'SIGKILL';
+} | {
+    op: 'screen-start';
+    width: number;
+    height: number;
+} | {
+    op: 'screen-stop';
+} | {
+    op: 'observe';
+} | {
+    op: 'input';
+    input: GuestInput;
+} | {
+    op: 'a11y-invoke';
+    nodeId: string;
+    action: string;
+} | {
+    op: 'launch';
+    appId: string;
+    args?: readonly string[];
+} | {
+    op: 'clipboard-read';
+} | {
+    op: 'clipboard-write';
+    text: string;
+} | {
+    op: 'frames-start';
+    fps: number;
+    width: number;
+    height: number;
+    /** Omitted lets the guest choose; a guest that predates this ignores it. */
+    format?: DeskFrameFormat;
+} | {
+    op: 'frames-stop';
+} | {
+    op: 'video-start';
+    fps: number;
+    width: number;
+    height: number;
+} | {
+    op: 'video-stop';
+} | {
+    op: 'handover-begin';
+    ttlMs: number;
+    scope: DeskHandoverScope;
+} | {
+    op: 'handover-end';
+};
+export type GuestOp = GuestCommand['op'];
+export type GuestRequest = GuestCommand & {
+    id: string;
+};
+export type GuestResponse = {
+    id: string;
+    ok: true;
+    result: unknown;
+} | {
+    id: string;
+    ok: false;
+    error: string;
+};
+/** Unsolicited guest-to-host messages: job exits, frames, focus changes. */
+export type GuestEventMessage = {
+    event: 'job-exit';
+    jobId: string;
+    exitCode: number | null;
+    signal: string | null;
+} | {
+    event: 'frame';
+    seq: number;
+    width: number;
+    height: number;
+    data: string;
+    /**
+     * How `data` is encoded. Absent on the wire means `png`: frames were
+     * PNG-only before this field existed, so an older guest paired with a
+     * newer host keeps working rather than having its every frame rejected.
+     */
+    format: DeskFrameFormat;
+} | {
+    event: 'video-chunk';
+    seq: number;
+    kind: DeskVideoChunkKind;
+    /** RFC 6381, e.g. `avc1.42C020`, read out of the bytes by the guest. */
+    codec: string;
+    width: number;
+    height: number;
+    /**
+     * Whether a `media` chunk begins at a sync sample. Only a chunk that does
+     * can start or resume a decoder; `init` chunks report false because the
+     * question does not apply to them.
+     */
+    keyframe: boolean;
+    data: string;
+} | {
+    event: 'window-focus';
+    window: WindowInfo;
+};
+export type HostBoundMessage = GuestResponse | GuestEventMessage;
+/** The wire shape of an exec result, before the host turns it into a snapshot. */
+export interface GuestExecResult {
+    exitCode: number | null;
+    signal: string | null;
+    stdout: string;
+    stderr: string;
+    truncated: boolean;
+}
+/** The wire shape of an observation; `png` is base64. */
+export interface GuestObservation {
+    png: string;
+    width: number;
+    height: number;
+    a11y: A11yNode | null;
+    windows: WindowInfo[];
+    focused: WindowInfo | null;
+}
+/** Encode one message as a length-prefixed JSON frame. */
+export declare function encodeFrame(message: unknown, maxFrameBytes?: number): Buffer;
+/**
+ * Incremental frame decoder. Feed it arbitrary chunk boundaries; it returns
+ * every complete parsed JSON value. A declared frame length beyond the bound
+ * or a body that is not valid JSON throws — framing violations are fatal to
+ * the connection because there is no way to resynchronize a byte stream whose
+ * lengths cannot be trusted.
+ */
+export declare class FrameDecoder {
+    #private;
+    constructor(options?: {
+        maxFrameBytes?: number;
+    });
+    push(chunk: Buffer): unknown[];
+}
+/** Validate a host-to-guest request. Unknown ops and malformed fields throw. */
+export declare function parseGuestRequest(value: unknown): GuestRequest;
+export declare function parseGuestInput(value: unknown): GuestInput;
+/** Validate a guest-to-host message: a correlated response or an event. */
+export declare function parseHostBoundMessage(value: unknown): HostBoundMessage;
+/** Validate the result payload of an `exec` response. */
+export declare function parseExecResult(value: unknown): GuestExecResult;
+/** Validate the result payload of a `job-start` response. */
+export declare function parseJobStarted(value: unknown): {
+    jobId: string;
+};
+/** Validate the result payload of an `observe` response. */
+export declare function parseObservation(value: unknown): GuestObservation;
+/** Validate the result payload of a `handover-begin` response. */
+export declare function parseHandoverBegun(value: unknown): {
+    url: string;
+};
+/** Validate the result payload of a `clipboard-read` response. */
+export declare function parseClipboardText(value: unknown): string;
+/** Validate the result payload of a `capabilities` response. */
+export declare function parseCapabilities(value: unknown): {
+    virtioGpu: boolean;
+};
+export declare function parseWindowInfo(value: unknown): WindowInfo;
+//# sourceMappingURL=protocol.d.ts.map

package/protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"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"}