dsh-apk-vm 0.3.13 → 0.4.0

package/lib/flows.js

@@ -0,0 +1,198 @@
+/**
+ * Interaction flow recorder for the APK VM.
+ *
+ * The Host records validated input payloads (tap/swipe/key/text) as they arrive
+ * through the panel or the apk_vm tool, then replays them with the original
+ * relative timing. Flows are plain JSON files under the OS temp dir, so they can
+ * be listed, downloaded, copied to another machine, or replayed later.
+ */
+import { randomUUID } from 'node:crypto';
+import { promises as fsp } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const MAX_EVENTS = 2000;
+const MAX_FLOW_FILES = 100;
+
+function safePart(value, fallback) {
+  const text = String(value == null ? '' : value)
+    .trim()
+    .replace(/[^A-Za-z0-9._-]+/g, '_')
+    .slice(0, 64);
+  return text || fallback;
+}
+
+function normalizePayload(payload) {
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) return null;
+  const type = String(payload.type || payload.action || payload.kind || '').toLowerCase();
+  if (type === 'tap') {
+    const x = Number(payload.x);
+    const y = Number(payload.y);
+    if (!Number.isFinite(x) || !Number.isFinite(y)) return null;
+    return { type: 'tap', x: Math.round(x), y: Math.round(y) };
+  }
+  if (type === 'swipe') {
+    const values = [payload.x1, payload.y1, payload.x2, payload.y2].map(Number);
+    if (!values.every(Number.isFinite)) return null;
+    const durationMs = Math.max(1, Math.min(60000, Math.round(Number(payload.durationMs ?? payload.duration) || 300)));
+    return {
+      type: 'swipe',
+      x1: Math.round(values[0]),
+      y1: Math.round(values[1]),
+      x2: Math.round(values[2]),
+      y2: Math.round(values[3]),
+      durationMs,
+    };
+  }
+  if (type === 'key' || type === 'keyevent') {
+    const key = String(payload.key ?? payload.keycode ?? payload.code ?? '');
+    return key ? { type: 'key', key } : null;
+  }
+  if (type === 'text') {
+    const text = payload.text ?? payload.value;
+    if (typeof text !== 'string' || !text || text.length > 4096) return null;
+    return { type: 'text', text };
+  }
+  return null;
+}
+
+function publicFlow(flow) {
+  if (!flow) return null;
+  return {
+    id: flow.id,
+    name: flow.name,
+    instanceId: flow.instanceId,
+    createdAt: flow.createdAt,
+    updatedAt: flow.updatedAt,
+    durationMs: flow.durationMs || 0,
+    events: Array.isArray(flow.events) ? flow.events.length : 0,
+  };
+}
+
+export class FlowRecorder {
+  constructor(options = {}) {
+    const opts = options && typeof options === 'object' ? options : {};
+    this.dir = opts.dir || path.join(os.tmpdir(), 'dsh-apk-vm-flows');
+    this.active = new Map();
+    this._writeQueue = Promise.resolve();
+  }
+
+  _fileFor(id) {
+    return path.join(this.dir, `${id}.json`);
+  }
+
+  async _ensureDir() {
+    await fsp.mkdir(this.dir, { recursive: true });
+  }
+
+  start(instanceId, name) {
+    const instance = safePart(instanceId, 'default');
+    const id = `${instance}-${Date.now().toString(36)}-${randomUUID().slice(0, 6)}`;
+    const flow = {
+      id,
+      name: safePart(name, 'flow') || 'flow',
+      instanceId: instance,
+      createdAt: new Date().toISOString(),
+      updatedAt: new Date().toISOString(),
+      events: [],
+      startedAtMs: Date.now(),
+    };
+    this.active.set(instance, flow);
+    return publicFlow(flow);
+  }
+
+  isRecording(instanceId) {
+    return this.active.has(safePart(instanceId, 'default'));
+  }
+
+  record(instanceId, payload) {
+    const instance = safePart(instanceId, 'default');
+    const flow = this.active.get(instance);
+    if (!flow) return false;
+    const normalized = normalizePayload(payload);
+    if (!normalized) return false;
+    if (flow.events.length >= MAX_EVENTS) return false;
+    flow.events.push({ at: Date.now() - flow.startedAtMs, payload: normalized });
+    return true;
+  }
+
+  async stop(instanceId) {
+    const instance = safePart(instanceId, 'default');
+    const flow = this.active.get(instance);
+    if (!flow) throw new Error(`no flow recording is active for instance ${instance}`);
+    this.active.delete(instance);
+    flow.updatedAt = new Date().toISOString();
+    flow.durationMs = flow.events.length ? flow.events[flow.events.length - 1].at : 0;
+    delete flow.startedAtMs;
+    await this._ensureDir();
+    await fsp.writeFile(this._fileFor(flow.id), `${JSON.stringify(flow, null, 2)}\n`, 'utf8');
+    return publicFlow(flow);
+  }
+
+  async list(instanceId) {
+    const instance = instanceId ? safePart(instanceId, 'default') : '';
+    await this._ensureDir();
+    let names = [];
+    try {
+      names = await fsp.readdir(this.dir);
+    } catch {
+      return [];
+    }
+    const jsonNames = names.filter((name) => name.endsWith('.json')).sort().reverse().slice(0, MAX_FLOW_FILES);
+    const flows = [];
+    for (const name of jsonNames) {
+      try {
+        const raw = await fsp.readFile(path.join(this.dir, name), 'utf8');
+        const flow = JSON.parse(raw);
+        if (!flow || typeof flow !== 'object') continue;
+        if (instance && flow.instanceId !== instance) continue;
+        flows.push(publicFlow(flow));
+      } catch {
+        /* ignore corrupt flow files */
+      }
+    }
+    return flows;
+  }
+
+  async get(id, instanceId) {
+    if (!/^[A-Za-z0-9._-]{1,160}$/.test(String(id || ''))) throw new Error('invalid flow id');
+    await this._ensureDir();
+    const raw = await fsp.readFile(this._fileFor(id), 'utf8');
+    const flow = JSON.parse(raw);
+    if (instanceId && flow.instanceId !== safePart(instanceId, 'default')) {
+      throw new Error(`flow ${id} belongs to another instance`);
+    }
+    return flow;
+  }
+
+  async remove(id, instanceId) {
+    const flow = await this.get(id, instanceId);
+    await fsp.unlink(this._fileFor(flow.id));
+    return publicFlow(flow);
+  }
+
+  /** Replay a saved flow through the provided async input function. */
+  async replay(id, inputFn, options = {}) {
+    if (typeof inputFn !== 'function') throw new Error('replay requires an input function');
+    const flow = await this.get(id, options.instanceId);
+    const delayCap = Math.max(0, Math.min(30000, Number(options.delayCapMs) || 5000));
+    const events = Array.isArray(flow.events) ? flow.events : [];
+    let previous = 0;
+    let replayed = 0;
+    for (let index = 0; index < events.length; index += 1) {
+      const event = events[index];
+      if (!event || !event.payload) continue;
+      const at = Math.max(0, Number(event.at) || 0);
+      const wait = Math.min(delayCap, Math.max(0, at - previous));
+      if (wait > 0) await new Promise((resolve) => setTimeout(resolve, wait));
+      previous = at;
+      try {
+        await inputFn(event.payload);
+      } catch (error) {
+        throw new Error(`flow replay failed at step ${index + 1}/${events.length}: ${error.message}`);
+      }
+      replayed += 1;
+    }
+    return { id: flow.id, name: flow.name, steps: replayed, durationMs: flow.durationMs || 0 };
+  }
+}

package/lib/ui-inspector.js

@@ -0,0 +1,174 @@
+/**
+ * UIAutomator hierarchy parser + stable selector generation.
+ *
+ * Kept dependency-free (plain XML tokenizer) so the Host half can use it on every
+ * platform and the client receives a ready-to-use `apk_vm` command for each node.
+ */
+
+function decodeEntities(value) {
+  return String(value || '')
+    .replace(/"/g, '"')
+    .replace(/'/g, "'")
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&amp;/g, '&');
+}
+
+function parseBounds(value) {
+  const match = /^\[(-?\d+),(-?\d+)\]\[(-?\d+),(-?\d+)\]$/.exec(String(value || ''));
+  if (!match) return null;
+  const bounds = {
+    x1: Number(match[1]),
+    y1: Number(match[2]),
+    x2: Number(match[3]),
+    y2: Number(match[4]),
+  };
+  return {
+    ...bounds,
+    width: Math.max(0, bounds.x2 - bounds.x1),
+    height: Math.max(0, bounds.y2 - bounds.y1),
+    center: {
+      x: Math.round((bounds.x1 + bounds.x2) / 2),
+      y: Math.round((bounds.y1 + bounds.y2) / 2),
+    },
+  };
+}
+
+/** Parse a UIAutomator XML document into lightweight node objects. */
+export function parseUiHierarchy(xml) {
+  const source = String(xml || '');
+  const rotationMatch = /<hierarchy[^>]*\brotation="(-?\d+)"/i.exec(source);
+  const nodes = [];
+  const nodeRe = /<node\b([^>]*?)\/?>/g;
+  const attrRe = /([A-Za-z_:][-A-Za-z0-9_:.]*)\s*=\s*"([^"]*)"/g;
+  let match;
+  let order = 0;
+  while ((match = nodeRe.exec(source))) {
+    const attrs = {};
+    let attr;
+    while ((attr = attrRe.exec(match[1]))) {
+      attrs[attr[1]] = decodeEntities(attr[2]);
+    }
+    const bounds = parseBounds(attrs.bounds);
+    const text = attrs.text || '';
+    const contentDesc = attrs['content-desc'] || '';
+    const resourceId = attrs['resource-id'] || '';
+    const className = attrs.class || '';
+    if (!text && !contentDesc && !resourceId && !className && !bounds) continue;
+    nodes.push({
+      order: order++,
+      text,
+      resourceId,
+      contentDesc,
+      className,
+      packageName: attrs.package || '',
+      clickable: attrs.clickable === 'true',
+      longClickable: attrs['long-clickable'] === 'true',
+      enabled: attrs.enabled === 'true',
+      focusable: attrs.focusable === 'true',
+      focused: attrs.focused === 'true',
+      scrollable: attrs.scrollable === 'true',
+      selected: attrs.selected === 'true',
+      password: attrs.password === 'true',
+      checkable: attrs.checkable === 'true',
+      checked: attrs.checked === 'true',
+      bounds,
+    });
+  }
+  return {
+    rotation: rotationMatch ? Number(rotationMatch[1]) : null,
+    nodes,
+  };
+}
+
+function shortLabel(node) {
+  const text = String(node.text || '').trim();
+  if (text) return text.length > 60 ? `${text.slice(0, 57)}...` : text;
+  const desc = String(node.contentDesc || '').trim();
+  if (desc) return desc.length > 60 ? `${desc.slice(0, 57)}...` : desc;
+  const id = String(node.resourceId || '').trim();
+  if (id) return id.split('/').pop();
+  const cls = String(node.className || '').split('.').pop();
+  return cls || `node ${node.order}`;
+}
+
+/**
+ * Build the most stable selector for a node, in this order:
+ * resource-id > text > content-desc > class. The returned `args` can be passed
+ * directly to the `apk_vm` find_ui/assert_text/tap_text actions.
+ */
+export function selectorForNode(node) {
+  if (!node || typeof node !== 'object') throw new Error('selectorForNode requires a node');
+  let args = null;
+  let by = '';
+  if (node.resourceId) {
+    args = { resourceId: node.resourceId };
+    by = 'resourceId';
+  } else if (node.text) {
+    args = { text: node.text };
+    by = 'text';
+  } else if (node.contentDesc) {
+    args = { contentDesc: node.contentDesc };
+    by = 'contentDesc';
+  } else if (node.className) {
+    args = { className: node.className };
+    by = 'className';
+  } else if (node.bounds) {
+    args = { x: node.bounds.center.x, y: node.bounds.center.y };
+    by = 'coordinates';
+  }
+  if (!args) return null;
+  const json = JSON.stringify(args);
+  const label = `${by}=${JSON.stringify(args[by] || `${args.x},${args.y}`)}`;
+  return {
+    by,
+    args,
+    label,
+    selector: label,
+    findCommand: `find_ui ${json}`,
+    assertCommand: `assert_text ${json}`,
+    tapCommand: `tap_text ${json}`,
+    tapCoordinates:
+      node.bounds && node.bounds.width > 0 && node.bounds.height > 0
+        ? { x: node.bounds.center.x, y: node.bounds.center.y }
+        : null,
+  };
+}
+
+/** Add stable labels/selectors and keep the result bounded for browser transport. */
+export function decorateUiNodes(nodes, options = {}) {
+  const limit = Math.max(1, Math.min(1000, Number(options.limit) || 400));
+  const all = Array.isArray(nodes) ? nodes : [];
+  const decorated = [];
+  for (const node of all) {
+    if (!node) continue;
+    if (!node.bounds || node.bounds.width <= 0 || node.bounds.height <= 0) continue;
+    const selector = selectorForNode(node);
+    decorated.push({
+      ...node,
+      label: shortLabel(node),
+      selector,
+      // Overlay only needs interactive/meaningful boxes; containers are still
+      // returned to the inspector list so Agents can see hierarchy.
+      interactive: node.clickable || node.focusable || node.scrollable || Boolean(node.text),
+    });
+    if (decorated.length >= limit) break;
+  }
+  return { nodes: decorated, total: all.length, truncated: all.length > decorated.length };
+}
+
+/** Complete payload used by GET /apk-vm/debug/inspect and the apk_vm tool. */
+export function buildInspectorPayload(dump, screen, options = {}) {
+  const parsed = parseUiHierarchy(dump && dump.xml);
+  const decorated = decorateUiNodes(parsed.nodes, options);
+  return {
+    ok: true,
+    rotation: parsed.rotation,
+    screen: screen || null,
+    nodes: decorated.nodes,
+    total: decorated.total,
+    truncated: decorated.truncated,
+    xmlBytes: dump && dump.bytes ? dump.bytes : null,
+    remotePath: dump && dump.remotePath ? dump.remotePath : null,
+  };
+}

package/lib/x509.js

@@ -0,0 +1,107 @@
+/**
+ * Minimal X.509 helpers for installing a local proxy CA certificate in Android.
+ *
+ * Android names user CA files by the OpenSSL "subject hash" (`<hash>.0`). Modern
+ * Node has no OpenSSL CLI, so we parse the DER certificate here and compute the
+ * same legacy hash: MD5 of the DER-encoded subject, first four bytes as a
+ * little-endian 32-bit hex value.
+ */
+import { createHash } from 'node:crypto';
+
+function readTlv(buffer, offset) {
+  if (offset + 2 > buffer.length) throw new Error('truncated DER');
+  const tag = buffer[offset];
+  let length = buffer[offset + 1];
+  let header = 2;
+  if (length & 0x80) {
+    const count = length & 0x7f;
+    if (count === 0 || count > 4 || offset + 2 + count > buffer.length) throw new Error('unsupported DER length');
+    length = 0;
+    for (let i = 0; i < count; i += 1) length = length * 256 + buffer[offset + 2 + i];
+    header += count;
+  }
+  const start = offset + header;
+  const end = start + length;
+  if (end > buffer.length) throw new Error('truncated DER value');
+  return { tag, start, end, der: buffer.subarray(offset, end) };
+}
+
+function children(buffer, tlv) {
+  const result = [];
+  let offset = tlv.start;
+  while (offset < tlv.end) {
+    const child = readTlv(buffer, offset);
+    result.push(child);
+    offset = child.end;
+    if (result.length > 64) throw new Error('unexpected DER structure');
+  }
+  return result;
+}
+
+function pemToDer(input) {
+  const text = String(input || '');
+  if (!/-----BEGIN CERTIFICATE-----/.test(text)) {
+    // Accept raw DER too.
+    if (text.length && text.charCodeAt(0) === 0x30) return Buffer.from(text, 'latin1');
+    throw new Error('certificate is not PEM/DER encoded');
+  }
+  const matches = text.match(/-----BEGIN CERTIFICATE-----([\s\S]*?)-----END CERTIFICATE-----/g) || [];
+  if (!matches.length) throw new Error('no PEM certificate block found');
+  const body = matches[0]
+    .replace(/-----BEGIN CERTIFICATE-----/, '')
+    .replace(/-----END CERTIFICATE-----/, '')
+    .replace(/\s+/g, '');
+  return Buffer.from(body, 'base64');
+}
+
+function printableName(subjectDer) {
+  // Best effort only; this is diagnostic metadata, not used for trust decisions.
+  const parts = [];
+  for (const match of subjectDer.toString('latin1').matchAll(/([\x20-\x7e]{2,80})/g)) {
+    const text = match[1].trim();
+    if (text && /[A-Za-z]/.test(text)) parts.push(text);
+  }
+  return parts.slice(0, 6).join(' ');
+}
+
+/** Extract the DER-encoded subject Name from a certificate. */
+export function extractSubjectDer(der) {
+  const cert = readTlv(der, 0);
+  if (cert.tag !== 0x30) throw new Error('certificate is not a DER SEQUENCE');
+  const certChildren = children(der, cert);
+  if (!certChildren.length) throw new Error('empty certificate');
+  const tbs = certChildren[0];
+  if (tbs.tag !== 0x30) throw new Error('certificate tbsCertificate is not a SEQUENCE');
+  const fields = children(der, tbs);
+  let index = 0;
+  // Optional [0] EXPLICIT version (0xA0).
+  if (fields[index] && fields[index].tag === 0xa0) index += 1;
+  // serialNumber, signatureAlgorithm, issuer, validity, subject
+  const subject = fields[index + 4];
+  if (!subject || subject.tag !== 0x30) throw new Error('certificate subject not found');
+  return subject.der;
+}
+
+/** OpenSSL-compatible subject_hash_old (used by Android's user CA directory). */
+export function subjectHashOld(der) {
+  if (!Buffer.isBuffer(der) || !der.length) throw new Error('subjectHashOld requires DER bytes');
+  const subject = extractSubjectDer(der);
+  const digest = createHash('md5').update(subject).digest();
+  const value = digest.readUInt32LE(0);
+  return value.toString(16).padStart(8, '0');
+}
+
+/** Parse a PEM/DER certificate into the fields needed for CA installation. */
+export function inspectCertificate(input) {
+  const der = pemToDer(input);
+  const subjectDer = extractSubjectDer(der);
+  const hash = subjectHashOld(der);
+  return {
+    der,
+    derBytes: der.length,
+    hash,
+    fileName: `${hash}.0`,
+    subject: printableName(subjectDer),
+    pem: `-----BEGIN CERTIFICATE-----\n${der.toString('base64').match(/.{1,64}/g).join('\n')}\n-----END CERTIFICATE-----\n`,
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-apk-vm",
-  "version": "0.3.13",
+  "version": "0.4.0",
   "type": "module",
   "description": "Local AOSP Android VM for DeepSeek Harness: preview rooted APKs at up to 60 fps, automate UIAutomator flows, and give each Agent an isolated VM.",
   "license": "Apache-2.0",
@@ -25,9 +25,9 @@
     "registry": "https://registry.npmjs.org/"
   },
   "scripts": {
-    "check": "node --check index.js && node --check client.js && node --check lib/android.js && node --check lib/scrcpy.js && node --check lib/ws.js && node --check lib/setup.js && node --check lib/instances.js && node --check lib/video-stream.js",
+    "check": "node --check index.js && node --check client.js && node --check lib/android.js && node --check lib/apk-bundle.js && node --check lib/flows.js && node --check lib/ui-inspector.js && node --check lib/x509.js && node --check lib/scrcpy.js && node --check lib/ws.js && node --check lib/setup.js && node --check lib/instances.js && node --check lib/video-stream.js",
     "privacy": "node scripts/privacy-scan.mjs",
-    "test": "node spike/ui-smoke.cjs && node spike/ui-better-sidebar-smoke.cjs && node spike/setup-smoke.mjs && node spike/android/mock-device.mjs && node spike/android/launch-plan.mjs && node spike/instances-smoke.mjs"
+    "test": "node spike/ui-smoke.cjs && node spike/ui-better-sidebar-smoke.cjs && node spike/setup-smoke.mjs && node spike/android/mock-device.mjs && node spike/android/launch-plan.mjs && node spike/instances-smoke.mjs && node spike/features.mjs"
   },
   "exports": {
     ".": "./index.js",
@@ -41,11 +41,15 @@
     "client.js",
     "cordis.patch.yml",
     "lib/android.js",
+    "lib/apk-bundle.js",
+    "lib/flows.js",
     "lib/scrcpy.js",
+    "lib/ui-inspector.js",
     "lib/ws.js",
     "lib/setup.js",
     "lib/instances.js",
     "lib/video-stream.js",
+    "lib/x509.js",
     "lib/vendor/scrcpy-server-v5.0.1.jar",
     "LICENSE",
     "NOTICE",
@@ -56,6 +60,7 @@
     "docs/RELEASING.md",
     "docs/PRIVACY.md",
     "docs/SUBMISSION.md",
+    "docs/LINUX-E2E.md",
     "docs/*.png",
     "scripts/privacy-scan.mjs",
     "locale/*.json",