@mcpherson-ai/observa-local-node 0.1.3

package/distribution/observa-cli/src/re-pair.mjs

@@ -0,0 +1,171 @@
+// Post-install unpair/re-pair over the EXISTING installation credential.
+//
+// Unpair revokes only the Hosted mgd1 wrapper. The signed installation and
+// its control-plane identity remain intact. Re-pair self-authenticates that
+// same installed identity and asks Hosted to mint a replacement wrapper for
+// the same deployment. No pairing code is redeemed and no installation is
+// created on this path.
+//
+// AUTHORITY: NONE. These routes manage transport credentials only.
+import { createHash } from "node:crypto";
+import { parseStrictJson } from "../../../runtime-adapters/n8n/src/strict-json.mjs";
+import { refuseCli } from "./errors.mjs";
+import {
+  readLocalConfig, replaceLocalConfigValues,
+} from "./config.mjs";
+import { readState } from "./state.mjs";
+import { HOSTED_BASE_URL_PATTERN } from "./pair.mjs";
+
+export const UNPAIR_ROUTE = "/observa/hosted-service/v1/unpair";
+export const REPAIR_ROUTE = "/observa/hosted-service/v1/re-pair";
+
+const INSTALLATION_SECRET_PATTERN = /^[A-Za-z0-9_-]{43}$/;
+const MGD1_TOKEN_PATTERN = /^mgd1_([a-f0-9]{32})\.([A-Za-z0-9_-]{43})$/;
+const WIRE_SAFE_ID_PATTERN = /^[A-Za-z0-9._:-]{1,96}$/;
+const MAX_RESPONSE_BYTES = 32 * 1024;
+const DEFAULT_TIMEOUT_MS = 10_000;
+
+async function postLifecycle({ baseUrl, route, installationId, installationSecret,
+  fetchImpl, timeoutMs }) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  let response;
+  try {
+    response = await fetchImpl(`${baseUrl}${route}`, {
+      method: "POST",
+      headers: {
+        authorization: `Bearer ${installationSecret}`,
+        "content-type": "application/json",
+      },
+      body: JSON.stringify({ installation_id: installationId }),
+      signal: controller.signal,
+    });
+  } catch (error) {
+    refuseCli("PAIR_HOSTED_UNREACHABLE",
+      error?.name === "AbortError" ? "timed out" : "connection failed");
+  } finally {
+    clearTimeout(timer);
+  }
+  let parsed;
+  try {
+    const text = await response.text();
+    if (text.length > MAX_RESPONSE_BYTES) refuseCli("PAIR_RESPONSE_MALFORMED", "oversized");
+    parsed = parseStrictJson(text);
+  } catch (error) {
+    if (error?.code?.startsWith?.("PAIR_")) throw error;
+    refuseCli("PAIR_RESPONSE_MALFORMED");
+  }
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    refuseCli("PAIR_RESPONSE_MALFORMED");
+  }
+  if (!response.ok || parsed.ok !== true) {
+    const reason = typeof parsed.reason === "string" && /^[a-z_]{1,64}$/.test(parsed.reason)
+      ? parsed.reason : "pairing_refused";
+    refuseCli("PAIR_REFUSED", reason);
+  }
+  return parsed;
+}
+
+function activeIdentity(home) {
+  const state = readState(home);
+  if (state === null) refuseCli("NOT_INSTALLED");
+  const config = readLocalConfig(home);
+  if (!HOSTED_BASE_URL_PATTERN.test(config.hosted_base_url ?? "")
+    || !MGD1_TOKEN_PATTERN.test(config.hosted_connector_token ?? "")
+    || config.hosted_installation_id !== state.installation_id) {
+    refuseCli("UNPAIR_ACTIVE_BINDING_REQUIRED");
+  }
+  const token = MGD1_TOKEN_PATTERN.exec(config.hosted_connector_token);
+  return Object.freeze({
+    state,
+    baseUrl: config.hosted_base_url,
+    installationSecret: token[2],
+  });
+}
+
+export function pairingRecoveryAvailable(home) {
+  const config = readLocalConfig(home);
+  return HOSTED_BASE_URL_PATTERN.test(config.hosted_recovery_base_url ?? "")
+    && INSTALLATION_SECRET_PATTERN.test(config.hosted_installation_secret ?? "");
+}
+
+export async function unpairHosted({ home, fetchImpl = globalThis.fetch,
+  timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  const active = activeIdentity(home);
+  const parsed = await postLifecycle({
+    baseUrl: active.baseUrl,
+    route: UNPAIR_ROUTE,
+    installationId: active.state.installation_id,
+    installationSecret: active.installationSecret,
+    fetchImpl,
+    timeoutMs,
+  });
+  if (parsed.installation_id !== active.state.installation_id
+    || !Number.isSafeInteger(parsed.revoked_credentials)
+    || parsed.revoked_credentials < 0) {
+    refuseCli("PAIR_RESPONSE_MALFORMED");
+  }
+  replaceLocalConfigValues(home, {
+    set: {
+      hosted_recovery_base_url: active.baseUrl,
+      hosted_installation_secret: active.installationSecret,
+    },
+    remove: ["hosted_base_url", "hosted_connector_token", "hosted_installation_id"],
+  });
+  return Object.freeze({
+    unpaired: true,
+    installation_id: active.state.installation_id,
+    revoked_credentials: parsed.revoked_credentials,
+  });
+}
+
+export async function rePairHosted({ home, fetchImpl = globalThis.fetch,
+  timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  const state = readState(home);
+  if (state === null) refuseCli("NOT_INSTALLED");
+  const config = readLocalConfig(home);
+  const baseUrl = config.hosted_recovery_base_url;
+  const installationSecret = config.hosted_installation_secret;
+  if (!HOSTED_BASE_URL_PATTERN.test(baseUrl ?? "")
+    || !INSTALLATION_SECRET_PATTERN.test(installationSecret ?? "")) {
+    refuseCli("PAIR_RECOVERY_BINDING_REQUIRED");
+  }
+  const parsed = await postLifecycle({
+    baseUrl,
+    route: REPAIR_ROUTE,
+    installationId: state.installation_id,
+    installationSecret,
+    fetchImpl,
+    timeoutMs,
+  });
+  const match = typeof parsed.credential === "string"
+    ? MGD1_TOKEN_PATTERN.exec(parsed.credential) : null;
+  if (parsed.installation_id !== state.installation_id
+    || match === null || match[2] !== installationSecret
+    || parsed.credential_id !== match[1]
+    || !WIRE_SAFE_ID_PATTERN.test(parsed.deployment_id ?? "")) {
+    refuseCli("PAIR_RESPONSE_MALFORMED");
+  }
+  const fingerprint = `sha256:${createHash("sha256")
+    .update(parsed.credential).digest("hex").slice(0, 16)}`;
+  if (parsed.fingerprint !== fingerprint) refuseCli("PAIR_CREDENTIAL_METADATA_DIVERGED");
+  replaceLocalConfigValues(home, {
+    set: {
+      n8n_deployment_ref: parsed.deployment_id,
+      hosted_base_url: baseUrl,
+      hosted_connector_token: parsed.credential,
+      hosted_installation_id: state.installation_id,
+    },
+    remove: ["hosted_recovery_base_url", "hosted_installation_secret"],
+  });
+  return Object.freeze({
+    paired: true,
+    repaired: true,
+    installation_id: state.installation_id,
+    deployment_id: parsed.deployment_id,
+    credential_id: parsed.credential_id,
+    fingerprint,
+    hosted_base_url: baseUrl,
+    credential_stored: true,
+  });
+}

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

@@ -0,0 +1,218 @@
+// Observa service lifecycle: the sealed n8n adapter's own `serve` verb,
+// supervised by pidfile. The boundary is structural — the ONLY process this
+// module will ever signal is one whose pid came from Observa's own pidfile
+// AND whose command line still names the Observa release path. The
+// customer's n8n, Odoo, and everything else on the machine are outside the
+// vocabulary of this module: there is no "find process by name", no pkill,
+// no port scan.
+
+import { createHash } from "node:crypto";
+import { execFileSync, spawn } from "node:child_process";
+import { existsSync, mkdirSync, openSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } 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 { readLocalConfig } from "./config.mjs";
+import { readState } from "./state.mjs";
+
+const ADAPTER_BIN_RELATIVE = "lib/runtime-adapters/n8n/bin/observa-n8n.mjs";
+// The v0.1.1 hosted-delivery composition entry ships INSIDE this CLI's own
+// package, beside this module — the runtime components it composes are the
+// installed ones, resolved from the release lib root it is handed.
+const HOSTED_BIN = fileURLToPath(new URL("../bin/observa-n8n-hosted.mjs", import.meta.url));
+// The installed module the hosted composition cannot run without. Presence
+// is necessary but never sufficient: the active release record must select
+// the component and authenticate all of its installed bytes below.
+const HOSTED_TRANSPORT_CLIENT_RELATIVE = "lib/transport/hosted/src/client.mjs";
+const HOSTED_TRANSPORT_COMPONENT_ID = "observa-hosted-transport-client";
+const HOSTED_BASE_URL_RE =
+  /^(https:\/\/[A-Za-z0-9.-]+(:\d{1,5})?|http:\/\/(127\.0\.0\.1|\[::1\])(:\d{1,5})?)$/;
+const MGD1_TOKEN_RE = /^mgd1_[a-f0-9]{32}\.[A-Za-z0-9_-]{43}$/;
+
+export function pidFilePath(home) {
+  return join(home, "service", "observa-n8n.pid.json");
+}
+
+function readPidFile(home) {
+  try {
+    return JSON.parse(readFileSync(pidFilePath(home), "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function processCommand(pid) {
+  try {
+    return execFileSync("ps", ["-p", String(pid), "-o", "command="], { encoding: "utf8" }).trim();
+  } catch {
+    return null;
+  }
+}
+
+function sha256File(path) {
+  return createHash("sha256").update(readFileSync(path)).digest("hex");
+}
+
+/**
+ * Prove the active, verified release selected the hosted transport and that
+ * every byte recorded for that component still matches disk. A planted
+ * client module is not authority to activate an unselected component.
+ */
+function assertHostedTransportAuthorized(home, state) {
+  let record;
+  try {
+    record = parseStrictJson(readFileSync(join(home, "current", "release-record.json"), "utf8"));
+  } catch {
+    refuseCli("HOSTED_RELEASE_RECORD_UNAVAILABLE");
+  }
+  if (record === null || typeof record !== "object" || Array.isArray(record)) {
+    refuseCli("HOSTED_RELEASE_RECORD_INVALID");
+  }
+  const { record_digest: digest, ...rest } = record;
+  if (typeof digest !== "string" || canonicalDigest(rest) !== digest) {
+    refuseCli("HOSTED_RELEASE_RECORD_TAMPERED");
+  }
+  if (record.manifest_id !== state.current_manifest_id) {
+    refuseCli("HOSTED_RELEASE_RECORD_MANIFEST_MISMATCH");
+  }
+  const component = Array.isArray(record.components)
+    ? record.components.find((entry) => entry?.component_id === HOSTED_TRANSPORT_COMPONENT_ID)
+    : null;
+  if (component === null || component === undefined || !Array.isArray(component.files)) {
+    refuseCli("HOSTED_TRANSPORT_COMPONENT_ABSENT");
+  }
+  const requiredPath = HOSTED_TRANSPORT_CLIENT_RELATIVE.slice("lib/".length);
+  if (!component.files.some((file) => file?.path === requiredPath)) {
+    refuseCli("HOSTED_TRANSPORT_COMPONENT_INVALID");
+  }
+  for (const file of component.files) {
+    if (file === null || typeof file !== "object" || typeof file.path !== "string"
+      || typeof file.sha256 !== "string" || file.path.startsWith("/")
+      || file.path.split("/").includes("..")) {
+      refuseCli("HOSTED_TRANSPORT_COMPONENT_INVALID");
+    }
+    const installed = join(home, "current", "lib", ...file.path.split("/"));
+    try {
+      if (sha256File(installed) !== file.sha256) refuseCli("HOSTED_TRANSPORT_COMPONENT_TAMPERED");
+    } catch (error) {
+      if (error?.code?.startsWith?.("HOSTED_")) throw error;
+      refuseCli("HOSTED_TRANSPORT_COMPONENT_TAMPERED");
+    }
+  }
+}
+
+/** True only for a live process that is provably OUR spawned service. */
+function pidIsOurService(record) {
+  if (record === null || !Number.isSafeInteger(record.pid) || record.pid < 1) return false;
+  const command = processCommand(record.pid);
+  if (command === null) return false;
+  return typeof record.adapter_bin === "string" && command.includes(record.adapter_bin);
+}
+
+export function serviceIsRunning(home) {
+  return pidIsOurService(readPidFile(home));
+}
+
+export function startService(home, { port = null } = {}) {
+  const state = readState(home);
+  if (state === null) refuseCli("NOT_INSTALLED");
+  if (serviceIsRunning(home)) return { started: false, alreadyRunning: true };
+  const adapterBin = join(home, "current", ADAPTER_BIN_RELATIVE);
+  if (!existsSync(adapterBin)) refuseCli("SERVICE_ADAPTER_ABSENT");
+  const config = readLocalConfig(home);
+  const credential = config.n8n_loopback_credential;
+  if (typeof credential !== "string" || credential.length < 24) {
+    // Presence check only; the value itself is never echoed anywhere.
+    refuseCli("SERVICE_CONFIG_ABSENT", "n8n_loopback_credential not configured (observa config set n8n_loopback_credential ...)");
+  }
+  // HOSTED DELIVERY (v0.1.1). When the pairing step configured a hosted base
+  // URL and connector credential, and this release ships the hosted
+  // composition entry, start THAT instead of the local-receipts-only sealed
+  // path. Structural refusals happen HERE, before a process exists: a
+  // malformed URL or credential shape, or a credential paired for a
+  // DIFFERENT installation, must never start a delivering service.
+  const hostedBaseUrl = config.hosted_base_url ?? null;
+  const hostedCredential = config.hosted_connector_token ?? null;
+  const hostedInstallationId = config.hosted_installation_id ?? null;
+  const anyHostedConfig = [hostedBaseUrl, hostedCredential, hostedInstallationId]
+    .some((value) => typeof value === "string" && value.length > 0);
+  const hostedConfigured = [hostedBaseUrl, hostedCredential, hostedInstallationId]
+    .every((value) => typeof value === "string" && value.length > 0);
+  let hostedDelivery = false;
+  if (anyHostedConfig && !hostedConfigured) refuseCli("HOSTED_DELIVERY_CONFIG_INCOMPLETE");
+  if (hostedConfigured) {
+    if (!HOSTED_BASE_URL_RE.test(hostedBaseUrl)) refuseCli("HOSTED_BASE_URL_SHAPE_REFUSED");
+    if (!MGD1_TOKEN_RE.test(hostedCredential)) refuseCli("HOSTED_CREDENTIAL_SHAPE_REFUSED");
+    if (hostedInstallationId !== state.installation_id) {
+      refuseCli("HOSTED_INSTALLATION_BINDING_MISMATCH");
+    }
+    // Configured hosted delivery with a release that cannot perform it is a
+    // named refusal, never a silent downgrade to local-only.
+    assertHostedTransportAuthorized(home, state);
+    if (!existsSync(HOSTED_BIN)) refuseCli("HOSTED_SERVICE_ENTRY_ABSENT");
+    hostedDelivery = true;
+  }
+  const serviceBin = hostedDelivery ? HOSTED_BIN : adapterBin;
+  const serviceDir = join(home, "service");
+  mkdirSync(serviceDir, { recursive: true, mode: 0o700 });
+  const logFd = openSync(join(serviceDir, "observa-n8n.log"), "a", 0o600);
+  const env = {
+    PATH: process.env.PATH,
+    OBSERVA_N8N_INSTALLATION_ID: state.installation_id,
+    OBSERVA_N8N_CREDENTIAL: credential,
+    OBSERVA_N8N_RECEIPT_PATH: join(serviceDir, "receipts", "observa-n8n-receipts.jsonl"),
+  };
+  if (hostedDelivery) {
+    // The hosted credential travels to the child exactly the way the
+    // loopback credential already does: environment only, never argv (argv
+    // is visible to `ps`), never the log.
+    env.OBSERVA_HOSTED_BASE_URL = hostedBaseUrl;
+    env.OBSERVA_HOSTED_CREDENTIAL = hostedCredential;
+    env.OBSERVA_RELEASE_LIB = join(home, "current", "lib");
+  }
+  const chosenPort = port ?? config.n8n_loopback_port ?? null;
+  if (chosenPort !== null) env.OBSERVA_N8N_PORT = String(chosenPort);
+  mkdirSync(join(serviceDir, "receipts"), { recursive: true, mode: 0o700 });
+  const child = spawn(process.execPath, [serviceBin, "serve"], {
+    cwd: serviceDir,
+    env,
+    detached: true,
+    stdio: ["ignore", logFd, logFd],
+  });
+  child.unref();
+  writeFileSync(pidFilePath(home), `${JSON.stringify({
+    pid: child.pid,
+    adapter_bin: serviceBin,
+    manifest_id: state.current_manifest_id,
+  }, null, 2)}\n`, { mode: 0o600 });
+  return { started: true, pid: child.pid, hostedDelivery };
+}
+
+export function stopService(home) {
+  const record = readPidFile(home);
+  if (!pidIsOurService(record)) {
+    rmSync(pidFilePath(home), { force: true });
+    return { stopped: false, wasRunning: false };
+  }
+  try {
+    process.kill(record.pid, "SIGTERM");
+  } catch {
+    // Already gone between the check and the signal.
+  }
+  const deadline = Date.now() + 5000;
+  while (Date.now() < deadline) {
+    if (!pidIsOurService(record)) break;
+    execFileSync(process.execPath, ["-e", "setTimeout(() => {}, 100)"]);
+  }
+  if (pidIsOurService(record)) {
+    try {
+      process.kill(record.pid, "SIGKILL");
+    } catch {
+      // Gone.
+    }
+  }
+  rmSync(pidFilePath(home), { force: true });
+  return { stopped: true, wasRunning: true };
+}

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

@@ -0,0 +1,87 @@
+// Local installation state. NON-SECRET release facts only, and NOT an
+// authority: the signed manifest stored beside it remains the only thing
+// that authorizes components or mode. Every consumer of this state re-derives
+// the component set and mode from the re-verified manifest and refuses on any
+// divergence — so editing this file can surface as tampering, never as an
+// entitlement.
+//
+// The embedded digest makes casual tampering visible. It is tamper-EVIDENCE,
+// not tamper-PROOF (a local root can always recompute a hash), which is why
+// the authority rule above, not this digest, is the actual boundary.
+
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import {
+  canonicalDigest,
+  exactKeys as sdkExactKeys,
+  snapshotRecord as sdkSnapshotRecord,
+} from "../../../sdk/contracts/canonical.mjs";
+import { parseStrictJson } from "../../../runtime-adapters/n8n/src/strict-json.mjs";
+import { CliRefusal, refuseCli } from "./errors.mjs";
+
+function mapSdkRefusal(fn) {
+  try {
+    return fn();
+  } catch (error) {
+    if (error?.name === "SdkContractError" && typeof error.code === "string") {
+      throw new CliRefusal(error.code);
+    }
+    throw error;
+  }
+}
+
+const snapshotRecord = (value, code) => mapSdkRefusal(() => sdkSnapshotRecord(value, code));
+const exactKeys = (value, expected, code) => mapSdkRefusal(() => sdkExactKeys(value, expected, code));
+import { MANIFEST_ID_PATTERN, TENANT_ID_PATTERN } from "./manifest-schema.mjs";
+import { STATE_SCHEMA_ID, SUPPORTED_MODES } from "./vocabulary.mjs";
+
+const STATE_KEYS = Object.freeze([
+  "schema", "schema_version", "cli_version", "organization_id", "workspace_id",
+  "installation_id", "current_manifest_id", "current_manifest_sha256",
+  "previous_manifest_id", "mode", "installed_at", "state_digest",
+]);
+
+export function statePath(home) {
+  return join(home, "state.json");
+}
+
+export function writeState(home, state) {
+  const record = { ...state, schema: STATE_SCHEMA_ID, schema_version: 1 };
+  delete record.state_digest;
+  record.state_digest = canonicalDigest(record);
+  const path = statePath(home);
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = `${path}.tmp-${process.pid}`;
+  writeFileSync(tmp, `${JSON.stringify(record, null, 2)}\n`, { mode: 0o600 });
+  renameSync(tmp, path);
+  return record;
+}
+
+/** Load and integrity-check the state file. Returns null when not installed. */
+export function readState(home) {
+  let text;
+  try {
+    text = readFileSync(statePath(home), "utf8");
+  } catch {
+    return null;
+  }
+  let parsed;
+  try {
+    parsed = parseStrictJson(text);
+  } catch {
+    refuseCli("STATE_FILE_UNPARSEABLE");
+  }
+  const s = snapshotRecord(parsed, "STATE_FILE_NOT_A_RECORD");
+  exactKeys(s, STATE_KEYS, "STATE_FILE_KEYS_REFUSED");
+  const { state_digest: digest, ...rest } = s;
+  if (canonicalDigest(rest) !== digest) refuseCli("STATE_FILE_TAMPERED");
+  if (s.schema !== STATE_SCHEMA_ID || s.schema_version !== 1) refuseCli("STATE_FILE_SCHEMA_REFUSED");
+  if (!TENANT_ID_PATTERN.test(s.organization_id) || !TENANT_ID_PATTERN.test(s.workspace_id)
+    || !TENANT_ID_PATTERN.test(s.installation_id)) refuseCli("STATE_FILE_IDENTITY_REFUSED");
+  if (!MANIFEST_ID_PATTERN.test(s.current_manifest_id)) refuseCli("STATE_FILE_MANIFEST_ID_REFUSED");
+  if (s.previous_manifest_id !== null && !MANIFEST_ID_PATTERN.test(s.previous_manifest_id)) {
+    refuseCli("STATE_FILE_PREVIOUS_ID_REFUSED");
+  }
+  if (!SUPPORTED_MODES.includes(s.mode)) refuseCli("STATE_FILE_MODE_REFUSED");
+  return s;
+}

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

@@ -0,0 +1,191 @@
+// Status and diagnose: useful non-secret facts, and only non-secret facts.
+// Config values never appear here — only key presence. Both surfaces READ;
+// neither changes anything.
+
+import { existsSync, readFileSync, readlinkSync } from "node:fs";
+import { join } from "node:path";
+import { CliRefusal } from "./errors.mjs";
+import { configPermissionsOk, configPresence, readLocalConfig } from "./config.mjs";
+import { HOSTED_BASE_URL_PATTERN } from "./pair.mjs";
+import { homePaths, loadCurrentInstallation, verifyReleaseIntegrity } from "./install.mjs";
+import { findVerifiedRevocation } from "./manifest-verify.mjs";
+import { serviceIsRunning } from "./service.mjs";
+import { readState } from "./state.mjs";
+import { CLI_VERSION } from "./vocabulary.mjs";
+
+export function collectStatus(home, { trustedKeys }) {
+  const paths = homePaths(home);
+  let state = null;
+  let stateProblem = null;
+  try {
+    state = readState(paths.root);
+  } catch (error) {
+    if (!(error instanceof CliRefusal)) throw error;
+    stateProblem = error.code;
+  }
+  if (state === null && stateProblem === null) {
+    return Object.freeze({
+      installed: false,
+      cli_version: CLI_VERSION,
+      home: paths.root,
+    });
+  }
+  const status = {
+    installed: stateProblem === null,
+    cli_version: CLI_VERSION,
+    home: paths.root,
+    state_problem: stateProblem,
+  };
+  if (state !== null) {
+    let manifest = null;
+    let manifestProblem = null;
+    try {
+      manifest = loadCurrentInstallation(paths.root, { trustedKeys })?.manifest ?? null;
+    } catch (error) {
+      if (!(error instanceof CliRefusal)) throw error;
+      manifestProblem = error.code;
+    }
+    status.installation_id = state.installation_id;
+    status.organization_id = state.organization_id;
+    status.workspace_id = state.workspace_id;
+    status.manifest_id = state.current_manifest_id;
+    status.previous_manifest_id = state.previous_manifest_id;
+    status.mode = state.mode;
+    status.installed_at = state.installed_at;
+    status.manifest_problem = manifestProblem;
+    status.components = manifest === null ? null : manifest.components.map((c) => ({
+      component_id: c.component_id,
+      package_name: c.package_name,
+      package_version: c.package_version,
+      role: c.role,
+    }));
+    status.service = serviceIsRunning(paths.root) ? "running" : "stopped";
+    status.current_link_target = existsSync(paths.currentLink)
+      ? readlinkSync(paths.currentLink)
+      : null;
+    const presence = configPresence(paths.root);
+    status.config_present = presence; // booleans only — never values
+    status.hosted_configured = presence.hosted_base_url && presence.hosted_connector_token
+      && presence.hosted_installation_id;
+    status.hosted_config_incomplete = (presence.hosted_base_url
+      || presence.hosted_connector_token || presence.hosted_installation_id)
+      && !status.hosted_configured;
+  }
+  return Object.freeze(status);
+}
+
+/**
+ * Diagnose: each check is PASS / FAIL / INFO with a non-secret detail.
+ * Never dumps credentials; never prints config values.
+ */
+export function runDiagnose(home, { trustedKeys }) {
+  const paths = homePaths(home);
+  const checks = [];
+  const add = (check, status, detail = "") => checks.push(Object.freeze({ check, status, detail }));
+
+  const [major] = process.versions.node.split(".").map(Number);
+  add("runtime_compatibility", major >= 22 ? "PASS" : "FAIL", `node ${process.versions.node}`);
+
+  let state = null;
+  try {
+    state = readState(paths.root);
+    add("installation_state", "PASS", state === null ? "not installed" : "state integrity ok");
+  } catch (error) {
+    if (!(error instanceof CliRefusal)) throw error;
+    add("installation_state", "FAIL", error.code);
+  }
+  if (state === null) {
+    return Object.freeze({ ok: !checks.some((c) => c.status === "FAIL"), checks });
+  }
+
+  let current = null;
+  try {
+    current = loadCurrentInstallation(paths.root, { trustedKeys });
+    add("manifest_signature", "PASS", current.manifest.manifest_id);
+  } catch (error) {
+    if (!(error instanceof CliRefusal)) throw error;
+    add("manifest_signature", "FAIL", error.code);
+  }
+
+  if (current !== null) {
+    const integrity = verifyReleaseIntegrity(paths.root, current.state.current_manifest_id);
+    add("package_integrity", integrity.ok ? "PASS" : "FAIL",
+      integrity.ok ? `${integrity.record.components.length} components verified` : integrity.problems.join("; "));
+    const versionsOk = integrity.ok && integrity.record.components.every((rc) => {
+      const mc = current.manifest.components.find((m) => m.component_id === rc.component_id);
+      return mc !== undefined
+        && mc.package_version === rc.package_version
+        && mc.artifact_sha256 === rc.artifact_sha256
+        && mc.content_digest === rc.content_digest;
+    });
+    add("component_versions_match_manifest", versionsOk ? "PASS" : "FAIL");
+    let revocation = null;
+    try {
+      revocation = findVerifiedRevocation({
+        revocationDir: paths.revocationsDir,
+        trustedKeys,
+        organizationId: current.state.organization_id,
+        workspaceId: current.state.workspace_id,
+        installationId: current.state.installation_id,
+      });
+      add("revocation", revocation === null ? "PASS" : "FAIL",
+        revocation === null ? "no verified revocation present" : revocation.reason_code);
+    } catch (error) {
+      if (!(error instanceof CliRefusal)) throw error;
+      add("revocation", "FAIL", error.code);
+    }
+  }
+
+  add("service_state", "INFO", serviceIsRunning(paths.root) ? "running" : "stopped");
+
+  const presence = configPresence(paths.root);
+  const requiredKeys = ["n8n_loopback_credential"];
+  for (const key of requiredKeys) {
+    // Presence only. The VALUE of a config key has no path into this report.
+    add(`config_present:${key}`, presence[key] ? "PASS" : "FAIL",
+      presence[key] ? "configured" : "absent");
+  }
+  add("config_permissions", configPermissionsOk(paths.root) ? "PASS" : "FAIL", "owner-only expected");
+  add("hosted_connectivity", "INFO",
+    presence.hosted_base_url && presence.hosted_connector_token
+      ? "configured (liveness not probed offline)"
+      : "not configured");
+
+  // HOSTED DELIVERY, STRUCTURALLY (v0.1.1). Shape checks only, over values
+  // read in-process and reported as booleans: the base URL matches the
+  // transport client's grammar, the credential matches the mgd1 grammar, and
+  // the paired installation is THIS installation. No VALUE — not even the
+  // non-secret ones — travels into a check detail, so this report stays
+  // paste-safe exactly like every line above it.
+  if (presence.hosted_base_url || presence.hosted_connector_token
+    || presence.hosted_installation_id) {
+    const local = readLocalConfig(paths.root);
+    if (presence.hosted_base_url) {
+      add("hosted_base_url_shape",
+        HOSTED_BASE_URL_PATTERN.test(local.hosted_base_url) ? "PASS" : "FAIL",
+        "https://host[:port] (or http on loopback)");
+    }
+    if (presence.hosted_connector_token) {
+      add("hosted_credential_shape",
+        /^mgd1_[a-f0-9]{32}\.[A-Za-z0-9_-]{43}$/u.test(local.hosted_connector_token)
+          ? "PASS" : "FAIL",
+        "mgd1 connector credential expected");
+    }
+    if (presence.hosted_installation_id) {
+      add("hosted_installation_binding",
+        local.hosted_installation_id === state.installation_id ? "PASS" : "FAIL",
+        "paired installation must be this installation");
+    } else {
+      add("hosted_installation_binding", "FAIL", "pairing did not record an installation id");
+    }
+  }
+
+  const logPath = join(paths.serviceDir, "observa-n8n.log");
+  if (existsSync(logPath)) {
+    const tail = readFileSync(logPath, "utf8").slice(-2000);
+    add("service_log_tail_secret_scan",
+      /mgd1_[a-f0-9]{32}\.[A-Za-z0-9_-]{43}/u.test(tail) ? "FAIL" : "PASS");
+  }
+
+  return Object.freeze({ ok: !checks.some((c) => c.status === "FAIL"), checks });
+}