@mobileaidev/ai-app-bridge 0.2.15 → 0.3.0-rc.2

package/bin/shared-kernel/evidence-recording.js

@@ -0,0 +1,131 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { sanitizePersistentValue } = require('../fact-codec');
+
+const PAYLOAD_SCHEMA = 'aab.recorded-payload/v1';
+const MAX_FILE_BYTES = 16 * 1024 * 1024;
+const MAX_RECORDING_BYTES = 256 * 1024 * 1024;
+const MAX_ATTACHMENTS = 10_000;
+const sha256 = bytes => crypto.createHash('sha256').update(bytes).digest('hex');
+const jsonHash = value => sha256(JSON.stringify(value ?? null));
+
+function requireValue(condition, code, detail) {
+  if (!condition) throw Object.assign(new Error(code), { code, detail });
+}
+
+function readRegularFile(directory, name, maxBytes = MAX_FILE_BYTES) {
+  const root = fs.lstatSync(directory);
+  requireValue(root.isDirectory() && !root.isSymbolicLink(), 'invalid_archive_directory');
+  requireValue(path.basename(name) === name && name !== '.' && name !== '..', 'invalid_archive_path');
+  const file = path.join(directory, name);
+  const stat = fs.lstatSync(file);
+  requireValue(stat.isFile() && !stat.isSymbolicLink(), 'invalid_archive_file', name);
+  requireValue(stat.size <= maxBytes, 'archive_limit_exceeded');
+  const descriptor = fs.openSync(file, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+  try {
+    const opened = fs.fstatSync(descriptor);
+    requireValue(opened.isFile() && opened.size <= maxBytes, 'invalid_archive_file', name);
+    const bytes = fs.readFileSync(descriptor);
+    requireValue(bytes.length <= maxBytes, 'archive_limit_exceeded');
+    return bytes;
+  } finally { fs.closeSync(descriptor); }
+}
+
+function checkPng(bytes) {
+  requireValue(bytes.length >= 24 && bytes.subarray(0, 8).equals(Buffer.from('89504e470d0a1a0a', 'hex'))
+    && bytes.toString('ascii', 12, 16) === 'IHDR'
+    && bytes.readUInt32BE(16) > 0 && bytes.readUInt32BE(20) > 0, 'invalid_screenshot');
+}
+
+// An explicitly requested, single-execution file output. No reader in the live
+// capture path uses this directory, and it is never reopened for automatic replay.
+function createEvidenceRecording({ directory, namespace, operationId, store, now = Date.now }) {
+  requireValue(typeof directory === 'string' && directory.trim().length > 0, 'invalid_recording_directory');
+  requireValue(store && typeof store.persist === 'function', 'recording_store_required');
+  const root = path.resolve(directory);
+  try { fs.mkdirSync(root); }
+  catch (error) { if (error.code === 'EEXIST') error.code = 'output_exists'; throw error; }
+  const recordingId = crypto.randomUUID();
+  let sequence = 0;
+  let bytesWritten = 0;
+  let failure = null;
+  let tail = Promise.resolve();
+
+  function write(name, bytes) {
+    requireValue(bytes.length <= MAX_FILE_BYTES && bytesWritten + bytes.length <= MAX_RECORDING_BYTES,
+      'recording_limit_exceeded');
+    const descriptor = fs.openSync(path.join(root, name), 'wx', 0o600);
+    try { fs.writeFileSync(descriptor, bytes); fs.fsyncSync(descriptor); }
+    finally { fs.closeSync(descriptor); }
+    bytesWritten += bytes.length;
+    return { name, bytes: bytes.length, sha256: sha256(bytes) };
+  }
+
+  function record({ kind, revision, target, data, parentFactId }) {
+    if (failure) return Promise.resolve({ ok: false, error: failure });
+    let metadata;
+    try {
+      // Detach and copy screenshots before any await, including a previous
+      // persistence receipt. Another call may reuse the original screenshot path.
+      const serialized = JSON.stringify(data);
+      requireValue(Buffer.byteLength(serialized) <= MAX_FILE_BYTES, 'recording_limit_exceeded');
+      const original = JSON.parse(serialized);
+      const detached = sanitizePersistentValue(original);
+      const originalSha256 = jsonHash(original);
+      const dataSha256 = jsonHash(detached);
+      const sourcePayload = kind === 'script-call' && original.envelope.evidence?.source
+        ? { originalSha256: jsonHash(original.envelope.result), archivedSha256: jsonHash(detached.envelope.result) }
+        : null;
+      requireValue(sequence < MAX_ATTACHMENTS, 'recording_limit_exceeded');
+      sequence += 1;
+      const screenshots = [];
+      if (kind === 'script-call') {
+        for (const ref of original.envelope.evidence?.refs || []) {
+          if (ref.stream !== 'screenshot') continue;
+          requireValue(typeof ref.screenshotId === 'string' && /^[a-f0-9]{64}$/.test(ref.sha256),
+            'invalid_screenshot_reference');
+          const file = path.resolve(ref.screenshotId);
+          const bytes = readRegularFile(path.dirname(file), path.basename(file));
+          requireValue(sha256(bytes) === ref.sha256, 'screenshot_checksum_mismatch');
+          checkPng(bytes);
+          screenshots.push({ ...write(`${sequence}-${screenshots.length + 1}.png`, bytes), ref });
+        }
+      }
+      const document = { schemaVersion: PAYLOAD_SCHEMA, namespace, operationId, recordingId,
+        sequence, kind, target, data: detached, screenshots };
+      const file = write(`${sequence}.json`, Buffer.from(JSON.stringify(document) + '\n'));
+      metadata = {
+        operationId, revision, target, recordingId, sequence, payloadKind: kind,
+        timestampMs: now(), ...(parentFactId ? { parentFactId } : {}),
+        evidenceId: `${namespace}:attachment:${operationId}:${recordingId}:${sequence}`,
+        directory: root, file, screenshots: screenshots.map(({ ref, ...entry }) => entry),
+        representation: originalSha256 === dataSha256 ? 'original-json' : 'redacted-json',
+        originalSha256, dataSha256, sourcePayload,
+      };
+    } catch (error) {
+      failure = error.code || 'recording_failed';
+      return Promise.resolve({ ok: false, error: failure, detail: error.detail });
+    }
+    const pending = tail.then(async () => {
+      if (failure) return { ok: false, error: failure };
+      try {
+        const receipt = await store.persist('attachment', metadata);
+        requireValue(receipt?.ok === true && receipt.persisted === true, 'recording_not_persisted', receipt?.error);
+        return receipt;
+      } catch (error) {
+        failure = error.code || 'recording_failed';
+        return { ok: false, error: failure, detail: error.detail };
+      }
+    });
+    tail = pending;
+    return pending;
+  }
+
+  return { record, info: () => ({ recordingId, directory: root, attachments: sequence, bytes: bytesWritten, error: failure }) };
+}
+
+module.exports = { createEvidenceRecording, readRegularFile, checkPng, requireValue, sha256, jsonHash,
+  PAYLOAD_SCHEMA, MAX_FILE_BYTES, MAX_RECORDING_BYTES, MAX_ATTACHMENTS };

package/bin/shared-kernel/evidence-schema.js

@@ -0,0 +1,194 @@
+'use strict';
+
+const crypto = require('node:crypto');
+const { sanitizePersistentValue } = require('../fact-codec');
+
+const NAMESPACES = Object.freeze(['script', 'intent']);
+const PROVIDERS = Object.freeze(['native', 'uia', 'flutter', 'h5']);
+const RECORD_SCHEMA = 'aab.execution-evidence/v1';
+const AGENT_DECISIONS = Object.freeze(['act', 'complete', 'fail', 'inconclusive']);
+const KINDS = Object.freeze([
+  'observation',
+  'summary',
+  'plan',
+  'decision',
+  'dispatch-marker',
+  'action-receipt',
+  'checkpoint',
+  'result',
+  'attachment',
+]);
+
+function checksumOf(value) {
+  return crypto.createHash('sha256').update(canonicalJson(value), 'utf8').digest('hex');
+}
+
+function canonicalJson(value) {
+  return JSON.stringify(canonicalize(value));
+}
+
+function canonicalize(value) {
+  if (value === null || typeof value !== 'object') return value;
+  if (Array.isArray(value)) return value.map(canonicalize);
+  return Object.fromEntries(
+    Object.keys(value).sort().map((key) => [key, canonicalize(value[key])]),
+  );
+}
+
+function serializeRecord(value) {
+  try {
+    const json = canonicalJson(value);
+    JSON.parse(json);
+    return { ok: true, json, bytes: Buffer.byteLength(json) };
+  } catch (error) {
+    return { ok: false, error: 'serialize_failed', detail: error.message || String(error) };
+  }
+}
+
+function verifyChecksum(record) {
+  if (!record || typeof record !== 'object') {
+    return { ok: false, error: 'checksum_mismatch' };
+  }
+  const { checksum, persisted, ...body } = record;
+  if (checksumOf(body) !== checksum) {
+    return { ok: false, error: 'checksum_mismatch' };
+  }
+  return { ok: true, record };
+}
+
+function requiredFields(kind) {
+  if (kind === 'observation') {
+    return ['operationId', 'revision', 'target', 'provider', 'capturedAtMs'];
+  }
+  if (kind === 'summary') {
+    return ['operationId', 'revision', 'rawTreeId'];
+  }
+  if (kind === 'plan') {
+    return ['operationId', 'revision', 'planStepId', 'actionSpecHash'];
+  }
+  if (kind === 'decision') {
+    return ['decisionId', 'operationId', 'revision', 'basedOnEvidenceIds', 'actionSpecHash', 'agentDecision'];
+  }
+  if (kind === 'dispatch-marker') {
+    return ['actionId', 'operationId', 'target', 'actionSpecHash'];
+  }
+  if (kind === 'action-receipt') {
+    return ['actionId', 'startedAtMs', 'completedAtMs', 'mechanicalStatus'];
+  }
+  if (kind === 'checkpoint') {
+    return ['operationId', 'revision', 'stepId'];
+  }
+  if (kind === 'result') {
+    return ['operationId', 'revision', 'bytes', 'sha256', 'originalSha256', 'representation'];
+  }
+  if (kind === 'attachment') {
+    return ['operationId', 'revision', 'recordingId', 'sequence', 'payloadKind', 'directory', 'file'];
+  }
+  return null;
+}
+
+function validateRecord(namespace, kind, record, { archivedUnversioned = false } = {}) {
+  if (!NAMESPACES.includes(namespace)) {
+    return { ok: false, error: 'invalid_namespace' };
+  }
+  if (!KINDS.includes(kind)) {
+    return { ok: false, error: 'invalid_kind' };
+  }
+  if (!record || typeof record !== 'object') {
+    return { ok: false, error: 'invalid_record' };
+  }
+  if (!archivedUnversioned && record.schemaVersion !== undefined && record.schemaVersion !== RECORD_SCHEMA) {
+    return { ok: false, error: 'unsupported_record_schema', field: 'schemaVersion' };
+  }
+  const fields = archivedUnversioned && kind === 'observation'
+    ? ['operationId', 'revision', 'serial', 'packageName', 'provider', 'capturedAtMs'] : requiredFields(kind);
+  for (const field of fields) {
+    if (record[field] === undefined || record[field] === null || record[field] === '') {
+      return { ok: false, error: 'invalid_record', field };
+    }
+  }
+  if (kind === 'result' && (namespace !== 'script' || !Object.hasOwn(record, 'result')
+    || !Number.isSafeInteger(record.bytes) || record.bytes < 1
+    || !/^[a-f0-9]{64}$/.test(record.sha256) || !/^[a-f0-9]{64}$/.test(record.originalSha256)
+    || !['original-json', 'redacted-json'].includes(record.representation))) {
+    return { ok: false, error: 'invalid_record', field: 'result' };
+  }
+  for (const field of ['target', 'observedTarget']) {
+    if (archivedUnversioned || record[field] === undefined) continue;
+    try {
+      require('./execution-target').normalizeExecutionTarget(record[field], { intent: namespace === 'intent', nullable: true });
+    } catch (error) {
+      return { ok: false, error: 'invalid_record', field: error.field?.replace(/^target/, field), detail: error.message };
+    }
+  }
+  if (kind === 'observation' && !PROVIDERS.includes(record.provider)) {
+    return { ok: false, error: 'invalid_provider' };
+  }
+  if (kind === 'decision' && !AGENT_DECISIONS.includes(record.agentDecision)) {
+    return { ok: false, error: 'invalid_agent_decision' };
+  }
+  if (kind === 'decision' && !Array.isArray(record.basedOnEvidenceIds)) {
+    return { ok: false, error: 'invalid_record', field: 'basedOnEvidenceIds' };
+  }
+  if (kind === 'dispatch-marker' && !record.decisionId && !record.planStepId) {
+    return { ok: false, error: 'invalid_record', field: 'decisionId' };
+  }
+  return { ok: true };
+}
+
+// Immutable archive v1/v2 files predate platform targets. Verify their declared
+// original fields and checksum without converting them into current targets.
+// New execution writes always use validateRecord's current contract.
+function validateArchivedRecord(namespace, kind, record) {
+  if (record?.schemaVersion === RECORD_SCHEMA) return validateRecord(namespace, kind, record);
+  if (record?.schemaVersion !== undefined) return { ok: false, error: 'unsupported_record_schema' };
+  return validateRecord(namespace, kind, record, { archivedUnversioned: true });
+}
+
+function buildEnvelope(namespace, kind, record, { now, sequence } = {}) {
+  const validation = validateRecord(namespace, kind, record);
+  if (!validation.ok) return validation;
+  const committedAtMs = typeof now === 'function' ? now() : Date.now();
+  const revision = record.revision;
+  const evidenceId = record.evidenceId || `${namespace}:${kind}:${record.operationId}:${revision}:${sequence}`;
+  const body = {
+    ...record,
+    schemaVersion: RECORD_SCHEMA,
+    namespace,
+    kind,
+    evidenceId,
+    revision,
+    committedAtMs,
+  };
+  const serialized = serializeRecord(body);
+  if (!serialized.ok) return serialized;
+  // Hash the detached JSON representation that the FactStore will persist.
+  // Otherwise absent values or write-side redaction change the body after hashing.
+  const durableBody = sanitizePersistentValue(JSON.parse(serialized.json));
+  const durableSerialized = serializeRecord(durableBody);
+  if (!durableSerialized.ok) return durableSerialized;
+  return {
+    ok: true,
+    envelope: {
+      ...durableBody,
+      checksum: checksumOf(durableBody),
+      persisted: true,
+    },
+    bytes: durableSerialized.bytes,
+  };
+}
+
+module.exports = {
+  AGENT_DECISIONS,
+  KINDS,
+  NAMESPACES,
+  PROVIDERS,
+  RECORD_SCHEMA,
+  buildEnvelope,
+  canonicalJson,
+  checksumOf,
+  serializeRecord,
+  validateRecord,
+  validateArchivedRecord,
+  verifyChecksum,
+};

package/bin/shared-kernel/evidence-store.js

@@ -0,0 +1,190 @@
+'use strict';
+
+const { buildEnvelope, verifyChecksum } = require('./evidence-schema');
+
+function createEvidenceStore({ namespace, adapter, now = Date.now, maxBytes = 8 * 1024 * 1024 } = {}) {
+  if (namespace !== 'script' && namespace !== 'intent') {
+    throw new TypeError('namespace must be script or intent');
+  }
+  if (!adapter || typeof adapter.record !== 'function' || typeof adapter.readById !== 'function') {
+    throw new TypeError('adapter with record/readById is required');
+  }
+  let sequence = 0;
+
+  function prepare(kind, record) {
+    sequence += 1;
+    const built = buildEnvelope(namespace, kind, record, { now, sequence });
+    if (!built.ok) {
+      return { ok: false, error: built.error, field: built.field, detail: built.detail };
+    }
+    if (built.bytes > maxBytes) {
+      return { ok: false, error: 'payload_too_large', bytes: built.bytes, maxBytes };
+    }
+    return built;
+  }
+
+  async function persist(kind, record) {
+    const built = prepare(kind, record);
+    if (!built.ok) return { ...built, persisted: false };
+    let receipt;
+    try {
+      receipt = await adapter.record(built.envelope);
+    } catch (error) {
+      return {
+        ok: false,
+        persisted: false,
+        error: error.code || 'persist_failed',
+        detail: error.message || String(error),
+      };
+    }
+    if (!receipt || receipt.ok === false) {
+      return {
+        ok: false,
+        persisted: false,
+        error: receipt?.error || 'persist_failed',
+        detail: receipt?.detail,
+      };
+    }
+    return {
+      ok: true,
+      persisted: true,
+      evidenceId: built.envelope.evidenceId,
+      checksum: built.envelope.checksum,
+      revision: built.envelope.revision,
+      kind,
+      namespace,
+    };
+  }
+
+  function offer(kind, record) {
+    const built = prepare(kind, record);
+    if (!built.ok) return { ...built, accepted: false };
+    if (typeof adapter.offer !== 'function') {
+      return { ok: false, accepted: false, reason: 'async_offer_unsupported' };
+    }
+    let offered;
+    try {
+      offered = adapter.offer(built.envelope);
+    } catch (error) {
+      return {
+        ok: false,
+        accepted: false,
+        reason: error.code || 'offer_failed',
+        detail: error.message || String(error),
+      };
+    }
+    if (!offered?.accepted) return { ok: false, ...offered };
+    return {
+      ok: true,
+      accepted: true,
+      evidenceId: built.envelope.evidenceId,
+      checksum: built.envelope.checksum,
+      revision: built.envelope.revision,
+      kind,
+      namespace,
+      completion: Promise.resolve(offered.completion).then(
+        (receipt) => {
+          if (!receipt || receipt.ok === false) {
+            return {
+              ok: false,
+              persisted: false,
+              error: receipt?.error || 'persist_failed',
+              detail: receipt?.detail,
+            };
+          }
+          return {
+            ok: true,
+            persisted: true,
+            evidenceId: built.envelope.evidenceId,
+            checksum: built.envelope.checksum,
+            revision: built.envelope.revision,
+            kind,
+            namespace,
+          };
+        },
+        (error) => ({
+          ok: false,
+          persisted: false,
+          error: error.code || 'persist_failed',
+          detail: error.message || String(error),
+        }),
+      ),
+    };
+  }
+
+  function read(evidenceId) {
+    const record = adapter.readById(evidenceId);
+    if (!record) {
+      return { ok: false, error: 'not_found' };
+    }
+    if (record.namespace !== namespace) {
+      return { ok: false, error: 'namespace_mismatch' };
+    }
+    const verified = verifyChecksum(record);
+    if (!verified.ok) return verified;
+    return { ok: true, record: verified.record };
+  }
+
+  function list(operationId) {
+    return (adapter.list?.({ namespace, operationId }) || []).filter((item) => item.namespace === namespace);
+  }
+
+  function latest(operationId, kind) {
+    const matches = list(operationId).filter((item) => item.kind === kind);
+    return matches.length === 0 ? null : matches[matches.length - 1];
+  }
+
+  function canExposeRevision(operationId) {
+    const observation = latest(operationId, 'observation');
+    if (!observation || observation.persisted !== true) {
+      return { ok: false, error: 'evidence_not_persisted' };
+    }
+    const verified = verifyChecksum(observation);
+    if (!verified.ok) return verified;
+    return { ok: true, revision: observation.revision, evidenceId: observation.evidenceId };
+  }
+
+  function canPrepareAction(operationId) {
+    const exposed = canExposeRevision(operationId);
+    if (!exposed.ok) return exposed;
+    const plan = latest(operationId, 'plan');
+    const decision = latest(operationId, 'decision');
+    if (!plan && !decision) {
+      return { ok: false, error: 'plan_or_decision_not_persisted' };
+    }
+    return { ok: true, revision: exposed.revision, plan, decision };
+  }
+
+  function canDispatch(operationId) {
+    const prepared = canPrepareAction(operationId);
+    if (!prepared.ok) return prepared;
+    const marker = latest(operationId, 'dispatch-marker');
+    if (!marker || marker.persisted !== true) {
+      return { ok: false, error: 'dispatch_marker_not_persisted' };
+    }
+    const verified = verifyChecksum(marker);
+    if (!verified.ok) return { ok: false, error: 'checksum_mismatch' };
+    return { ok: true, marker, revision: prepared.revision };
+  }
+
+  function status() {
+    return adapter.status?.() || { ok: true };
+  }
+
+  return {
+    namespace,
+    commit: persist,
+    persist,
+    offer,
+    read,
+    list,
+    latest,
+    canExposeRevision,
+    canPrepareAction,
+    canDispatch,
+    status,
+    close: () => adapter.close?.(),
+  };
+}
+
+module.exports = { createEvidenceStore };

package/bin/shared-kernel/execution-admission.js

@@ -0,0 +1,22 @@
+'use strict';
+
+const { CommandError } = require('../command-errors');
+
+// iOS providers resolve devicectl identity and own the canonical physical UDID
+// lease. An outer operation must not acquire a second lock using its connection
+// identifier, which can differ from that UDID. Android providers inherit the
+// operation's serial lease. The serving Web provider owns its session lease.
+async function admitExecutionMutation(target, lease, action) {
+  if (target.platform === 'ios' || target.platform === 'web') return action();
+  if (target.platform !== 'android') {
+    throw new CommandError('unsupported_execution_platform', 'No mutation admission is implemented for this platform.',
+      { dispatched: false, ambiguous: false });
+  }
+  const held = lease.acquire(target.serial);
+  if (!held.ok) throw new CommandError(held.error, 'The target device cannot admit this operation.',
+    { dispatched: false, ambiguous: false, details: held });
+  try { return await held.run(action); }
+  finally { held.release(); }
+}
+
+module.exports = { admitExecutionMutation };