@mcpherson-ai/observa-local-node 0.1.3

package/distribution/observa-cli/src/install.mjs

@@ -0,0 +1,443 @@
+// The installation transaction.
+//
+//   verify manifest signature → validate tenant/install identity →
+//   resolve exact artifacts → verify digests → safe staging →
+//   validate contents → preflight → atomic activation
+//
+// Nothing becomes current until everything passed; a failure at any step
+// removes the staging directory and leaves the previous installation —
+// including a completely absent one — byte-for-byte untouched. Activation is
+// one symlink rename. The previous known-good manifest, artifacts and release
+// tree are RETAINED for rollback, and rollback re-verifies them rather than
+// trusting that nothing touched them in the meantime.
+
+import { execFileSync } from "node:child_process";
+import {
+  copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync,
+  renameSync, rmSync, symlinkSync, writeFileSync,
+} from "node:fs";
+import { join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { canonicalDigest } from "../../../sdk/contracts/canonical.mjs";
+import { parseStrictJson } from "../../../runtime-adapters/n8n/src/strict-json.mjs";
+import { refuseCli } from "./errors.mjs";
+import {
+  contentDigestOfEntries, extractEntries, readArtifactEntries,
+  sha256HexOf, wrapperManifestOf,
+} from "./artifact.mjs";
+import { compareExactVersions } from "./manifest-schema.mjs";
+import { findVerifiedRevocation, verifySignedManifestText } from "./manifest-verify.mjs";
+import { acquireLock } from "./lock.mjs";
+import { readState, writeState } from "./state.mjs";
+import { CLI_VERSION, RELEASE_RECORD_SCHEMA_ID } from "./vocabulary.mjs";
+import { serviceIsRunning, stopService } from "./service.mjs";
+
+export function homePaths(home) {
+  const root = resolve(home);
+  return Object.freeze({
+    root,
+    manifestsDir: join(root, "manifests"),
+    revocationsDir: join(root, "manifests", "revocations"),
+    artifactsDir: join(root, "artifacts"),
+    releasesDir: join(root, "releases"),
+    currentLink: join(root, "current"),
+    serviceDir: join(root, "service"),
+  });
+}
+
+export function releaseDirFor(home, manifestId) {
+  return join(homePaths(home).releasesDir, manifestId);
+}
+
+function readSignedManifestFile(path) {
+  let text;
+  try {
+    text = readFileSync(path, "utf8");
+  } catch {
+    refuseCli("MANIFEST_FILE_UNAVAILABLE");
+  }
+  return text;
+}
+
+/**
+ * Load the state AND the stored current signed manifest, re-verify the
+ * signature, and cross-check identity and mode. The manifest, not the state
+ * file, is the authority — divergence refuses.
+ */
+export function loadCurrentInstallation(home, { trustedKeys }) {
+  const state = readState(home);
+  if (state === null) return null;
+  const paths = homePaths(home);
+  const manifestPath = join(paths.manifestsDir, `${state.current_manifest_id}.signed.json`);
+  const text = readSignedManifestFile(manifestPath);
+  if (sha256HexOf(Buffer.from(text, "utf8")) !== state.current_manifest_sha256) {
+    refuseCli("STORED_MANIFEST_DIVERGED_FROM_STATE");
+  }
+  const manifest = verifySignedManifestText(text, { trustedKeys });
+  if (manifest.manifest_id !== state.current_manifest_id
+    || manifest.organization_id !== state.organization_id
+    || manifest.workspace_id !== state.workspace_id
+    || manifest.installation_id !== state.installation_id
+    || manifest.mode !== state.mode) {
+    refuseCli("STATE_DIVERGED_FROM_SIGNED_MANIFEST");
+  }
+  return { state, manifest, manifestText: text };
+}
+
+function assertNotRevoked(home, { trustedKeys, manifest }) {
+  const paths = homePaths(home);
+  const revocation = findVerifiedRevocation({
+    revocationDir: paths.revocationsDir,
+    trustedKeys,
+    organizationId: manifest.organization_id,
+    workspaceId: manifest.workspace_id,
+    installationId: manifest.installation_id,
+  });
+  if (revocation !== null) refuseCli("INSTALLATION_REVOKED", revocation.reason_code);
+}
+
+function resolveArtifacts({ manifest, artifactDir, paths }) {
+  mkdirSync(paths.artifactsDir, { recursive: true });
+  const resolved = [];
+  for (const component of manifest.components) {
+    const cached = join(paths.artifactsDir, `${component.artifact_sha256}.tgz`);
+    let bytes = null;
+    if (existsSync(cached)) {
+      bytes = readFileSync(cached);
+      if (sha256HexOf(bytes) !== component.artifact_sha256) {
+        refuseCli("ARTIFACT_CACHE_TAMPERED", component.component_id);
+      }
+    } else {
+      if (typeof artifactDir !== "string") refuseCli("ARTIFACT_SOURCE_REQUIRED", component.component_id);
+      const source = join(artifactDir, component.artifact_filename);
+      try {
+        bytes = readFileSync(source);
+      } catch {
+        refuseCli("ARTIFACT_UNAVAILABLE", component.component_id);
+      }
+      // The digest, not the filename, is the identity: a swapped file under
+      // the right name fails here before anything is unpacked.
+      if (sha256HexOf(bytes) !== component.artifact_sha256) {
+        refuseCli("ARTIFACT_DIGEST_MISMATCH", component.component_id);
+      }
+      copyFileSync(source, cached);
+    }
+    resolved.push({ component, bytes });
+  }
+  return resolved;
+}
+
+function stageRelease({ manifest, resolved, paths }) {
+  mkdirSync(paths.releasesDir, { recursive: true });
+  const staging = join(paths.releasesDir, `.staging-${manifest.manifest_id}-${process.pid}`);
+  rmSync(staging, { recursive: true, force: true });
+  mkdirSync(staging, { recursive: true });
+  const libRoot = join(staging, "lib");
+  const componentsRecord = [];
+  try {
+    for (const { component, bytes } of resolved) {
+      const entries = readArtifactEntries(bytes);
+      if (contentDigestOfEntries(entries) !== component.content_digest) {
+        refuseCli("ARTIFACT_CONTENT_DIGEST_MISMATCH", component.component_id);
+      }
+      const wrapper = wrapperManifestOf(entries);
+      if (wrapper.name !== component.package_name || wrapper.version !== component.package_version) {
+        refuseCli("ARTIFACT_IDENTITY_MISMATCH", component.component_id);
+      }
+      const entryPath = wrapper.exports?.["."];
+      if (typeof entryPath !== "string" || !entryPath.startsWith("./")) {
+        refuseCli("ARTIFACT_ENTRY_UNDECLARED", component.component_id);
+      }
+      const installed = extractEntries({ entries, destinationRoot: libRoot });
+      componentsRecord.push({
+        component_id: component.component_id,
+        package_name: component.package_name,
+        package_version: component.package_version,
+        artifact_sha256: component.artifact_sha256,
+        content_digest: component.content_digest,
+        entry: entryPath,
+        files: installed,
+      });
+    }
+    const record = {
+      schema: RELEASE_RECORD_SCHEMA_ID,
+      schema_version: 1,
+      manifest_id: manifest.manifest_id,
+      components: componentsRecord,
+    };
+    writeFileSync(join(staging, "release-record.json"), `${JSON.stringify({
+      ...record,
+      record_digest: canonicalDigest(record),
+    }, null, 2)}\n`, { mode: 0o600 });
+    return { staging, libRoot, componentsRecord };
+  } catch (error) {
+    rmSync(staging, { recursive: true, force: true });
+    throw error;
+  }
+}
+
+function preflight({ staging, libRoot, componentsRecord }) {
+  const [major] = process.versions.node.split(".").map(Number);
+  if (!(major >= 22)) refuseCli("PREFLIGHT_NODE_VERSION_UNSUPPORTED");
+  for (const component of componentsRecord) {
+    const entryFile = resolve(join(libRoot, component.entry));
+    if (!entryFile.startsWith(`${resolve(libRoot)}/`)) refuseCli("PREFLIGHT_ENTRY_ESCAPES_RELEASE");
+    if (!existsSync(entryFile)) refuseCli("PREFLIGHT_ENTRY_ABSENT", component.component_id);
+    try {
+      execFileSync(process.execPath, [
+        "--input-type=module", "-e",
+        `await import(${JSON.stringify(pathToFileURL(entryFile).href)});`,
+      ], { stdio: ["ignore", "ignore", "pipe"], timeout: 30000 });
+    } catch (error) {
+      refuseCli("PREFLIGHT_ENTRY_IMPORT_FAILED",
+        `${component.component_id}: ${String(error.stderr ?? "").slice(0, 200)}`);
+    }
+  }
+  const adapterBin = join(libRoot, "runtime-adapters", "n8n", "bin", "observa-n8n.mjs");
+  if (existsSync(adapterBin)) {
+    // The sealed adapter's own self-verification (no-authority scan, source
+    // integrity, provenance self-check) runs over the INSTALLED bytes. A
+    // clean environment is passed so the ledger check reports SKIP instead
+    // of touching any live configuration.
+    try {
+      execFileSync(process.execPath, [adapterBin, "verify"], {
+        cwd: staging,
+        env: { PATH: process.env.PATH },
+        stdio: ["ignore", "pipe", "pipe"],
+        timeout: 60000,
+      });
+    } catch {
+      refuseCli("PREFLIGHT_ADAPTER_VERIFY_FAILED");
+    }
+  }
+}
+
+function activate({ home, manifest, manifestText, staging, previousManifestId, now }) {
+  const paths = homePaths(home);
+  const releaseDir = releaseDirFor(home, manifest.manifest_id);
+  rmSync(releaseDir, { recursive: true, force: true });
+  renameSync(staging, releaseDir);
+  mkdirSync(paths.manifestsDir, { recursive: true });
+  const manifestPath = join(paths.manifestsDir, `${manifest.manifest_id}.signed.json`);
+  writeFileSync(manifestPath, manifestText, { mode: 0o600 });
+  const linkTmp = `${paths.currentLink}.tmp-${process.pid}`;
+  rmSync(linkTmp, { force: true });
+  symlinkSync(join("releases", manifest.manifest_id), linkTmp);
+  renameSync(linkTmp, paths.currentLink);
+  return writeState(home, {
+    cli_version: CLI_VERSION,
+    organization_id: manifest.organization_id,
+    workspace_id: manifest.workspace_id,
+    installation_id: manifest.installation_id,
+    current_manifest_id: manifest.manifest_id,
+    current_manifest_sha256: sha256HexOf(Buffer.from(manifestText, "utf8")),
+    previous_manifest_id: previousManifestId,
+    mode: manifest.mode,
+    installed_at: now().toISOString(),
+  });
+}
+
+function cleanStaleStaging(paths) {
+  let names = [];
+  try {
+    names = readdirSync(paths.releasesDir).filter((n) => n.startsWith(".staging-"));
+  } catch {
+    return;
+  }
+  for (const name of names) rmSync(join(paths.releasesDir, name), { recursive: true, force: true });
+}
+
+/**
+ * Install, reinstall or update from a signed manifest file.
+ * `expectedInstallationId` (optional) binds a FIRST install to a known
+ * identity — founder-assisted pairing writes it ahead of time.
+ */
+export function installFromManifestFile({
+  home, manifestFile, artifactDir, trustedKeys,
+  expectedInstallationId = null, now = () => new Date(),
+}) {
+  const paths = homePaths(home);
+  mkdirSync(paths.root, { recursive: true, mode: 0o700 });
+  const lock = acquireLock(paths.root, { operation: "install" });
+  try {
+    cleanStaleStaging(paths);
+    const manifestText = readSignedManifestFile(manifestFile);
+    const manifest = verifySignedManifestText(manifestText, { trustedKeys });
+    if (compareExactVersions(CLI_VERSION, manifest.min_cli_version) < 0) {
+      refuseCli("CLI_VERSION_BELOW_MANIFEST_MINIMUM");
+    }
+    assertNotRevoked(paths.root, { trustedKeys, manifest });
+    const current = loadCurrentInstallation(paths.root, { trustedKeys });
+    let previousManifestId = null;
+    let transition = "install";
+    if (current !== null) {
+      // Tenant/install binding: a manifest for any other organization,
+      // workspace or installation refuses — the manifest names ITS
+      // installation, it does not get adopted by whoever reads it.
+      if (manifest.organization_id !== current.state.organization_id
+        || manifest.workspace_id !== current.state.workspace_id
+        || manifest.installation_id !== current.state.installation_id) {
+        refuseCli("MANIFEST_TENANT_BINDING_MISMATCH");
+      }
+      if (manifest.manifest_id === current.state.current_manifest_id) {
+        transition = "reinstall";
+        previousManifestId = current.state.previous_manifest_id;
+      } else {
+        transition = "update";
+        // Updates only move FORWARD along signed issuance order. Moving back
+        // is the rollback lane, which targets the retained previous manifest
+        // explicitly — a re-presented older manifest is not an update.
+        if (manifest.issued_seq <= current.manifest.issued_seq) {
+          refuseCli("MANIFEST_NOT_NEWER_THAN_CURRENT");
+        }
+        previousManifestId = current.state.current_manifest_id;
+      }
+    } else if (expectedInstallationId !== null
+      && manifest.installation_id !== expectedInstallationId) {
+      refuseCli("MANIFEST_INSTALLATION_BINDING_MISMATCH");
+    }
+    const resolved = resolveArtifacts({ manifest, artifactDir, paths });
+    const { staging, libRoot, componentsRecord } = stageRelease({ manifest, resolved, paths });
+    try {
+      preflight({ staging, libRoot, componentsRecord });
+    } catch (error) {
+      rmSync(staging, { recursive: true, force: true });
+      throw error;
+    }
+    const state = activate({
+      home: paths.root, manifest, manifestText, staging, previousManifestId, now,
+    });
+    pruneReleases(paths, state);
+    return { transition, state, manifest };
+  } finally {
+    lock.release();
+  }
+}
+
+function pruneReleases(paths, state) {
+  const keep = new Set([state.current_manifest_id]);
+  if (state.previous_manifest_id !== null) keep.add(state.previous_manifest_id);
+  let names = [];
+  try {
+    names = readdirSync(paths.releasesDir);
+  } catch {
+    return;
+  }
+  for (const name of names) {
+    if (name.startsWith(".staging-")) continue;
+    if (!keep.has(name)) rmSync(join(paths.releasesDir, name), { recursive: true, force: true });
+  }
+}
+
+/** Re-verify installed bytes of a retained release against its record. */
+export function verifyReleaseIntegrity(home, manifestId) {
+  const releaseDir = releaseDirFor(home, manifestId);
+  let record;
+  try {
+    record = parseStrictJson(readFileSync(join(releaseDir, "release-record.json"), "utf8"));
+  } catch {
+    return { ok: false, problems: ["release record unavailable"] };
+  }
+  const { record_digest: digest, ...rest } = record;
+  if (canonicalDigest(rest) !== digest) return { ok: false, problems: ["release record tampered"] };
+  if (rest.manifest_id !== manifestId) return { ok: false, problems: ["release record for wrong manifest"] };
+  const problems = [];
+  for (const component of rest.components) {
+    for (const file of component.files) {
+      const path = join(releaseDir, "lib", ...file.path.split("/"));
+      let bytes;
+      try {
+        bytes = readFileSync(path);
+      } catch {
+        problems.push(`${component.component_id}: ${file.path} missing`);
+        continue;
+      }
+      if (sha256HexOf(bytes) !== file.sha256) {
+        problems.push(`${component.component_id}: ${file.path} diverged`);
+      }
+    }
+  }
+  return { ok: problems.length === 0, problems, record: rest };
+}
+
+/**
+ * Rollback: return to the RETAINED previous manifest — no other target
+ * exists. Tampered retained bytes are re-staged from the verified artifact
+ * cache (offline), and if that cannot be proven either, rollback refuses
+ * rather than activating unproven bytes.
+ */
+export function rollbackToPrevious({ home, trustedKeys, now = () => new Date() }) {
+  const paths = homePaths(home);
+  const lock = acquireLock(paths.root, { operation: "rollback" });
+  try {
+    const current = loadCurrentInstallation(paths.root, { trustedKeys });
+    if (current === null) refuseCli("NOT_INSTALLED");
+    const previousId = current.state.previous_manifest_id;
+    if (previousId === null) refuseCli("ROLLBACK_TARGET_ABSENT");
+    const manifestPath = join(paths.manifestsDir, `${previousId}.signed.json`);
+    const manifestText = readSignedManifestFile(manifestPath);
+    const manifest = verifySignedManifestText(manifestText, { trustedKeys });
+    if (manifest.manifest_id !== previousId
+      || manifest.organization_id !== current.state.organization_id
+      || manifest.workspace_id !== current.state.workspace_id
+      || manifest.installation_id !== current.state.installation_id) {
+      refuseCli("ROLLBACK_MANIFEST_BINDING_MISMATCH");
+    }
+    const integrity = verifyReleaseIntegrity(paths.root, previousId);
+    if (!integrity.ok) {
+      // Retained tree cannot be trusted — rebuild it from the verified
+      // artifact cache, fully offline.
+      const resolved = resolveArtifacts({ manifest, artifactDir: null, paths });
+      const { staging, libRoot, componentsRecord } = stageRelease({ manifest, resolved, paths });
+      try {
+        preflight({ staging, libRoot, componentsRecord });
+      } catch (error) {
+        rmSync(staging, { recursive: true, force: true });
+        throw error;
+      }
+      const releaseDir = releaseDirFor(paths.root, previousId);
+      rmSync(releaseDir, { recursive: true, force: true });
+      renameSync(staging, releaseDir);
+    }
+    const linkTmp = `${paths.currentLink}.tmp-${process.pid}`;
+    rmSync(linkTmp, { force: true });
+    symlinkSync(join("releases", previousId), linkTmp);
+    renameSync(linkTmp, paths.currentLink);
+    const state = writeState(paths.root, {
+      cli_version: CLI_VERSION,
+      organization_id: manifest.organization_id,
+      workspace_id: manifest.workspace_id,
+      installation_id: manifest.installation_id,
+      current_manifest_id: previousId,
+      current_manifest_sha256: sha256HexOf(Buffer.from(manifestText, "utf8")),
+      previous_manifest_id: null,
+      mode: manifest.mode,
+      installed_at: now().toISOString(),
+    });
+    return { state, manifest };
+  } finally {
+    lock.release();
+  }
+}
+
+/**
+ * Uninstall Observa-managed state. Never touches n8n, Odoo, or anything
+ * outside the Observa home; customer configuration (their credentials)
+ * survives unless `purgeConfig` is EXPLICITLY requested.
+ */
+export function uninstall({ home, purgeConfig = false }) {
+  const paths = homePaths(home);
+  const lock = acquireLock(paths.root, { operation: "uninstall" });
+  try {
+    if (serviceIsRunning(paths.root)) stopService(paths.root);
+    for (const dir of [paths.releasesDir, paths.artifactsDir, paths.manifestsDir, paths.serviceDir]) {
+      rmSync(dir, { recursive: true, force: true });
+    }
+    rmSync(paths.currentLink, { force: true });
+    rmSync(join(paths.root, "state.json"), { force: true });
+    if (purgeConfig) rmSync(join(paths.root, "config"), { recursive: true, force: true });
+    return { removed: true, configRetained: !purgeConfig };
+  } finally {
+    lock.release();
+  }
+}

package/distribution/observa-cli/src/lock.mjs

@@ -0,0 +1,57 @@
+// Installation lock. One state-changing operation at a time, per home.
+//
+// `mkdir` is the atomic primitive: it either creates the lock directory or
+// fails, with no read-then-write window. A lock whose owning process is gone
+// is stale and may be reclaimed; a lock whose owner is alive means a
+// CONCURRENT operation and refuses — corruption by two installers is a
+// worse outcome than asking one of them to wait.
+
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { refuseCli } from "./errors.mjs";
+
+export function lockDir(home) {
+  return join(home, "lock");
+}
+
+function ownerIsAlive(pid) {
+  if (!Number.isSafeInteger(pid) || pid < 1) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error.code === "EPERM";
+  }
+}
+
+export function acquireLock(home, { operation }) {
+  const dir = lockDir(home);
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    try {
+      mkdirSync(dir, { recursive: false });
+      writeFileSync(join(dir, "owner.json"), `${JSON.stringify({
+        pid: process.pid,
+        operation,
+      })}\n`, { mode: 0o600 });
+      return { release: () => rmSync(dir, { recursive: true, force: true }) };
+    } catch (error) {
+      if (error.code !== "EEXIST") throw error;
+      let owner = null;
+      try {
+        owner = JSON.parse(readFileSync(join(dir, "owner.json"), "utf8"));
+      } catch {
+        // Lock directory without a readable owner: a crash between mkdir and
+        // write. Treat as stale.
+      }
+      // A live owner refuses — INCLUDING this same process: two operations
+      // in one process are still two operations, and a same-pid leak means
+      // a prior operation is genuinely still inside its critical section.
+      if (owner !== null && ownerIsAlive(owner.pid)) {
+        refuseCli("INSTALLATION_LOCKED", "another observa operation is running");
+      }
+      rmSync(dir, { recursive: true, force: true });
+    }
+  }
+  refuseCli("INSTALLATION_LOCK_UNAVAILABLE");
+  return undefined;
+}