@mcpherson-ai/observa-local-node 0.1.3

package/distribution/observa-cli/integrations/n8n/observa-external-hook.cjs

@@ -0,0 +1,132 @@
+// n8n backend external hook for automatic, workflow-neutral observation.
+//
+// Loaded once by n8n through EXTERNAL_HOOK_FILES. It reads execution metadata
+// from workflow.postExecute, submits the sealed adapter's ATTEMPT/COMPLETION
+// shapes to the loopback Local Node, and never reads item data, credentials,
+// node parameters, or static workflow data. Every error is contained here:
+// this post-execution observer cannot change the workflow's result.
+const { createHash } = require("node:crypto");
+
+const SAFE = /^[A-Za-z0-9._:-]{1,96}$/;
+const NODE_TYPE = /^[A-Za-z0-9][A-Za-z0-9._:@/-]{0,95}$/;
+const LOOPBACK_URL = /^http:\/\/(127\.0\.0\.1|\[::1\])(:\d{1,5})?$/;
+const CREDENTIAL = /^.{24,256}$/s;
+const MAX_TASK_RUNS = 128;
+const TIMEOUT_MS = 750;
+
+const digest = (value) => createHash("sha256").update(String(value)).digest("hex");
+
+function safeRef(prefix, value) {
+  const direct = `${prefix}.${String(value ?? "")}`;
+  return SAFE.test(direct) ? direct : `${prefix}.h${digest(value).slice(0, 40)}`;
+}
+
+function isoAt(value, fallback) {
+  const number = Number(value);
+  const date = Number.isFinite(number) ? new Date(number) : new Date(fallback);
+  return Number.isFinite(date.getTime()) ? date.toISOString() : new Date().toISOString();
+}
+
+function configuration(env) {
+  const baseUrl = env.OBSERVA_N8N_HOOK_URL;
+  const installationId = env.OBSERVA_N8N_HOOK_INSTALLATION_ID;
+  const deploymentRef = env.OBSERVA_N8N_HOOK_DEPLOYMENT_REF;
+  const credential = env.OBSERVA_N8N_HOOK_CREDENTIAL;
+  if (!LOOPBACK_URL.test(baseUrl ?? "") || !SAFE.test(installationId ?? "")
+    || !SAFE.test(deploymentRef ?? "") || !CREDENTIAL.test(credential ?? "")) return null;
+  return { baseUrl, installationId, deploymentRef, credential };
+}
+
+async function submit(config, phase, payload) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
+  try {
+    await fetch(`${config.baseUrl}/observa/n8n/v1/${phase.toLowerCase()}`, {
+      method: "POST",
+      headers: {
+        authorization: `Bearer ${config.credential}`,
+        "content-type": "application/json",
+      },
+      body: JSON.stringify(payload),
+      signal: controller.signal,
+    });
+  } catch {
+    // Evidence loss is visible in Observa; it is never an n8n execution fault.
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function observePostExecute(fullRunData, workflowData, executionId) {
+  try {
+    const config = configuration(process.env);
+    if (config === null || !SAFE.test(String(workflowData?.id ?? ""))
+      || !SAFE.test(String(executionId ?? ""))) return;
+    const runData = fullRunData?.data?.resultData?.runData;
+    if (runData === null || typeof runData !== "object" || Array.isArray(runData)) return;
+    const nodes = new Map((Array.isArray(workflowData?.nodes) ? workflowData.nodes : [])
+      .filter((node) => node && typeof node.name === "string")
+      .map((node) => [node.name, node]));
+    const workflowRef = safeRef("wf", workflowData.id);
+    const executionRef = safeRef("ex", executionId);
+    const submissions = [];
+    let observed = 0;
+
+    for (const [nodeName, taskRuns] of Object.entries(runData)) {
+      const node = nodes.get(nodeName);
+      if (!node || !NODE_TYPE.test(node.type ?? "") || !Array.isArray(taskRuns)) continue;
+      for (let index = 0; index < taskRuns.length && observed < MAX_TASK_RUNS; index += 1) {
+        const task = taskRuns[index];
+        if (task === null || typeof task !== "object") continue;
+        observed += 1;
+        const nodeRef = safeRef("node", node.id ?? `${nodeName}.${index}`);
+        const correlationRef = `n8nc.${digest(
+          `${workflowData.id}\0${executionId}\0${nodeRef}\0${index}`,
+        ).slice(0, 32)}`;
+        const startedAt = isoAt(task.startTime, fullRunData.startedAt ?? Date.now());
+        const endedAt = isoAt(
+          Number(task.startTime) + Math.max(0, Number(task.executionTime) || 0),
+          fullRunData.stoppedAt ?? Date.now(),
+        );
+        const base = {
+          runtime_kind: "n8n",
+          installation_id: config.installationId,
+          deployment_ref: config.deploymentRef,
+          workflow_ref: workflowRef,
+          execution_ref: executionRef,
+          node_ref: nodeRef,
+          node_type: node.type,
+          native_operation: null,
+          correlation_ref: correlationRef,
+        };
+        submissions.push(submit(config, "ATTEMPT", {
+          ...base, phase: "ATTEMPT", occurred_at: startedAt,
+        }));
+        const workflowFailedHere = fullRunData?.status === "error"
+          && fullRunData?.data?.resultData?.lastNodeExecuted === nodeName;
+        submissions.push(submit(config, "COMPLETION", {
+          ...base,
+          phase: "COMPLETION",
+          outcome: task.error || workflowFailedHere
+            ? "RUNTIME_REPORTED_FAILURE" : "RUNTIME_REPORTED_SUCCESS",
+          occurred_at: endedAt,
+        }));
+      }
+      if (observed >= MAX_TASK_RUNS) break;
+    }
+    await Promise.allSettled(submissions);
+  } catch {
+    // ExternalHooks rethrows hook failures. This hook never lets one escape.
+  }
+}
+
+const exportedHooks = {
+  workflow: {
+    postExecute: [observePostExecute],
+  },
+};
+Object.defineProperty(exportedHooks, "__observa_test", {
+  enumerable: false,
+  value: { configuration, observePostExecute, safeRef },
+});
+module.exports = exportedHooks;

package/distribution/observa-cli/keys/observa-beta-1.public.json

@@ -0,0 +1,7 @@
+{
+  "schema": "observa.release.signing-key.public",
+  "schema_version": 1,
+  "key_id": "observa-beta-1",
+  "algorithm": "Ed25519",
+  "public_key_spki_der_b64": "MCowBQYDK2VwAyEAYmBbdlaWDc79D3v6aBbBgVjph1TLTPSJofPIfTyAEoA"
+}

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

@@ -0,0 +1,143 @@
+// Artifact reading: strict ustar-in-gzip, verify-then-extract.
+//
+// The reader accepts EXACTLY the format the release tooling emits and
+// refuses everything else. That is the structural defense: symlinks,
+// hardlinks, device nodes, pax/gnu extension headers, absolute paths and
+// `..` segments are not "sanitized" — the entry types don't exist in the
+// accepted grammar, so a hostile tarball fails closed before any path is
+// formed. Extraction happens only AFTER the whole archive digest matched the
+// signed manifest, and lifecycle scripts do not run because nothing here
+// executes anything: files are written, never evaluated.
+
+import { createHash } from "node:crypto";
+import { gunzipSync } from "node:zlib";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve, sep } from "node:path";
+import { canonicalJson } from "../../../sdk/contracts/canonical.mjs";
+import { refuseCli } from "./errors.mjs";
+
+const BLOCK = 512;
+const ENTRY_PATH_PATTERN = /^package\/[A-Za-z0-9._/-]{1,98}$/u;
+const MAX_ARCHIVE_BYTES = 64 * 1024 * 1024;
+const MAX_ENTRIES = 512;
+
+export function sha256HexOf(bytes) {
+  return createHash("sha256").update(bytes).digest("hex");
+}
+
+function headerString(block, offset, length) {
+  const slice = block.subarray(offset, offset + length);
+  const nul = slice.indexOf(0);
+  return slice.subarray(0, nul === -1 ? length : nul).toString("utf8");
+}
+
+function headerOctal(block, offset, length, code) {
+  const text = headerString(block, offset, length).trim();
+  if (!/^[0-7]*$/u.test(text) || text === "") refuseCli(code);
+  return Number.parseInt(text, 8);
+}
+
+/**
+ * Parse a release tarball into `[{ path, mode, bytes }]` with `path` already
+ * stripped of the `package/` prefix. Refuses on any structural surprise.
+ */
+export function readArtifactEntries(tgzBytes) {
+  if (!Buffer.isBuffer(tgzBytes) || tgzBytes.length > MAX_ARCHIVE_BYTES) {
+    refuseCli("ARTIFACT_SIZE_REFUSED");
+  }
+  let tar;
+  try {
+    tar = gunzipSync(tgzBytes, { maxOutputLength: MAX_ARCHIVE_BYTES });
+  } catch {
+    refuseCli("ARTIFACT_NOT_GZIP");
+  }
+  if (tar.length % BLOCK !== 0) refuseCli("ARTIFACT_TRUNCATED");
+  const entries = [];
+  const seen = new Set();
+  let offset = 0;
+  while (offset + BLOCK <= tar.length) {
+    const block = tar.subarray(offset, offset + BLOCK);
+    if (block.every((b) => b === 0)) break; // end-of-archive
+    const magic = headerString(block, 257, 6);
+    if (magic !== "ustar") refuseCli("ARTIFACT_HEADER_NOT_USTAR");
+    const typeflag = String.fromCharCode(block[156]);
+    if (typeflag !== "0") refuseCli("ARTIFACT_ENTRY_TYPE_REFUSED");
+    const name = headerString(block, 0, 100);
+    const prefix = headerString(block, 345, 155);
+    if (prefix !== "") refuseCli("ARTIFACT_PREFIX_REFUSED");
+    if (!ENTRY_PATH_PATTERN.test(name) || name.includes("..")) {
+      refuseCli("ARTIFACT_ENTRY_PATH_REFUSED");
+    }
+    const linkname = headerString(block, 157, 100);
+    if (linkname !== "") refuseCli("ARTIFACT_LINKNAME_REFUSED");
+    const mode = headerOctal(block, 100, 8, "ARTIFACT_MODE_REFUSED") & 0o7777;
+    if (mode !== 0o644 && mode !== 0o755) refuseCli("ARTIFACT_MODE_REFUSED");
+    const size = headerOctal(block, 124, 12, "ARTIFACT_SIZE_FIELD_REFUSED");
+    const dataStart = offset + BLOCK;
+    const dataEnd = dataStart + size;
+    if (dataEnd > tar.length) refuseCli("ARTIFACT_TRUNCATED");
+    const path = name.slice("package/".length);
+    if (seen.has(path)) refuseCli("ARTIFACT_DUPLICATE_ENTRY");
+    seen.add(path);
+    entries.push({
+      path,
+      mode: mode === 0o755 ? "0755" : "0644",
+      bytes: Buffer.from(tar.subarray(dataStart, dataEnd)),
+    });
+    if (entries.length > MAX_ENTRIES) refuseCli("ARTIFACT_ENTRY_COUNT_REFUSED");
+    offset = dataEnd + ((BLOCK - (size % BLOCK)) % BLOCK);
+  }
+  if (entries.length === 0) refuseCli("ARTIFACT_EMPTY");
+  return entries;
+}
+
+/**
+ * The artifact's content digest: sha256 over the canonical JSON of the
+ * sorted `{ path, mode, sha256 }` entry list, `package/`-prefixed paths —
+ * exactly what the release tooling computed at build time.
+ */
+export function contentDigestOfEntries(entries) {
+  const list = entries
+    .map((e) => ({ path: `package/${e.path}`, mode: e.mode, sha256: sha256HexOf(e.bytes) }))
+    .sort((a, b) => (a.path < b.path ? -1 : 1));
+  return sha256HexOf(Buffer.from(canonicalJson(list), "utf8"));
+}
+
+/** The wrapper package.json entry, parsed for the lifecycle-script gate. */
+export function wrapperManifestOf(entries) {
+  const wrapper = entries.find((e) => e.path === "package.json");
+  if (wrapper === undefined) refuseCli("ARTIFACT_WRAPPER_ABSENT");
+  let parsed;
+  try {
+    parsed = JSON.parse(wrapper.bytes.toString("utf8"));
+  } catch {
+    refuseCli("ARTIFACT_WRAPPER_UNPARSEABLE");
+  }
+  if (parsed === null || typeof parsed !== "object") refuseCli("ARTIFACT_WRAPPER_UNPARSEABLE");
+  if ("scripts" in parsed) refuseCli("ARTIFACT_LIFECYCLE_SCRIPTS_REFUSED");
+  return parsed;
+}
+
+/**
+ * Extract verified entries into `destinationRoot/<repo-relative path>`.
+ * The wrapper package.json is metadata, not runtime content — it stays out
+ * of the merged runtime tree. Returns the installed file records.
+ */
+export function extractEntries({ entries, destinationRoot }) {
+  const root = resolve(destinationRoot);
+  const installed = [];
+  for (const entry of entries) {
+    if (entry.path === "package.json") continue;
+    const target = resolve(join(root, ...entry.path.split("/")));
+    if (target !== root && !target.startsWith(`${root}${sep}`)) {
+      refuseCli("ARTIFACT_EXTRACTION_ESCAPE_REFUSED");
+    }
+    mkdirSync(dirname(target), { recursive: true });
+    writeFileSync(target, entry.bytes, {
+      mode: entry.mode === "0755" ? 0o755 : 0o644,
+      flag: "wx",
+    });
+    installed.push({ path: entry.path, mode: entry.mode, sha256: sha256HexOf(entry.bytes) });
+  }
+  return installed;
+}

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

@@ -0,0 +1,162 @@
+// Local customer configuration. System credentials stay LOCAL: this file is
+// the only place the CLI touches them, values are never logged, never
+// printed, never diagnosed, never placed in manifests or artifacts, never
+// sent Hosted by the installer. Status and diagnose report KEY PRESENCE
+// ONLY.
+//
+// This is deliberately a thin surface over one owner-only JSON file — the
+// platform already owns richer secret lifecycles (connector credential
+// store, rotation journal); the installer does not grow a second one.
+
+import {
+  chmodSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync,
+} from "node:fs";
+import { randomUUID } from "node:crypto";
+import { join } from "node:path";
+import { parseStrictJson } from "../../../runtime-adapters/n8n/src/strict-json.mjs";
+import { refuseCli } from "./errors.mjs";
+
+// The closed set of local configuration keys. Everything here is
+// customer-local; nothing here ever appears in output.
+export const LOCAL_CONFIG_KEYS = Object.freeze([
+  "n8n_loopback_credential",   // OBSERVA_N8N_CREDENTIAL for the local observer
+  "n8n_loopback_port",         // optional loopback port override
+  "n8n_deployment_ref",        // pairing-selected logical n8n deployment
+  "hosted_base_url",           // where the hosted transport client would connect
+  "hosted_connector_token",    // existing mgd1 connector credential (pairing-owned)
+  "hosted_installation_id",    // the installation the pairing lane bound (non-secret)
+  "hosted_recovery_base_url",  // retained only between unpair and re-pair
+  "hosted_installation_secret",// existing control-plane installation credential
+  "odoo_base_url",             // customer Odoo endpoint (local network)
+  "odoo_database",
+  "odoo_login",
+  "odoo_api_key",              // customer system credential — LOCAL ONLY
+]);
+
+const SECRET_KEYS = Object.freeze([
+  "n8n_loopback_credential", "hosted_connector_token", "hosted_installation_secret",
+  "odoo_api_key",
+]);
+
+export function configPath(home) {
+  return join(home, "config", "local.json");
+}
+
+export function readLocalConfig(home) {
+  let text;
+  try {
+    text = readFileSync(configPath(home), "utf8");
+  } catch {
+    return {};
+  }
+  let parsed;
+  try {
+    parsed = parseStrictJson(text);
+  } catch {
+    refuseCli("LOCAL_CONFIG_UNPARSEABLE");
+  }
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    refuseCli("LOCAL_CONFIG_NOT_A_RECORD");
+  }
+  for (const key of Object.keys(parsed)) {
+    if (!LOCAL_CONFIG_KEYS.includes(key)) refuseCli("LOCAL_CONFIG_KEY_REFUSED");
+    if (typeof parsed[key] !== "string") refuseCli("LOCAL_CONFIG_VALUE_REFUSED");
+  }
+  return parsed;
+}
+
+export function writeLocalConfigValue(home, key, value) {
+  if (!LOCAL_CONFIG_KEYS.includes(key)) refuseCli("LOCAL_CONFIG_KEY_REFUSED");
+  if (typeof value !== "string" || value.length === 0) refuseCli("LOCAL_CONFIG_VALUE_REFUSED");
+  return writeLocalConfigValues(home, { [key]: value });
+}
+
+/**
+ * Atomically update one or more local configuration values.
+ *
+ * Pairing must commit its URL, credential and installation binding as one
+ * unit. Three independent rewrites leave a crash window in which a valid
+ * credential exists without the identity that constrains it. A same-directory
+ * temporary file plus rename makes the old or new complete record visible,
+ * never a partial record.
+ */
+export function writeLocalConfigValues(home, values) {
+  return replaceLocalConfigValues(home, { set: values });
+}
+
+/** Atomically set and remove local values in one owner-only rewrite. */
+export function replaceLocalConfigValues(home, { set = {}, remove = [] } = {}) {
+  if (!Array.isArray(remove)
+    || remove.some((key) => !LOCAL_CONFIG_KEYS.includes(key))) {
+    refuseCli("LOCAL_CONFIG_KEY_REFUSED");
+  }
+  const values = set;
+  if (values === null || typeof values !== "object" || Array.isArray(values)) {
+    refuseCli("LOCAL_CONFIG_NOT_A_RECORD");
+  }
+  for (const [key, value] of Object.entries(values)) {
+    if (!LOCAL_CONFIG_KEYS.includes(key)) refuseCli("LOCAL_CONFIG_KEY_REFUSED");
+    if (typeof value !== "string" || value.length === 0) refuseCli("LOCAL_CONFIG_VALUE_REFUSED");
+  }
+  const existing = readLocalConfig(home);
+  const next = { ...existing, ...values };
+  for (const key of remove) delete next[key];
+  const path = configPath(home);
+  const dir = join(home, "config");
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  chmodSync(dir, 0o700);
+  const temporary = join(dir, `.local.${process.pid}.${randomUUID()}.tmp`);
+  try {
+    writeFileSync(temporary, `${JSON.stringify(next, null, 2)}\n`, {
+      mode: 0o600, flag: "wx",
+    });
+    chmodSync(temporary, 0o600);
+    renameSync(temporary, path);
+    chmodSync(path, 0o600);
+  } finally {
+    rmSync(temporary, { force: true });
+  }
+}
+
+/** Atomically remove only the named local keys, preserving every other
+ * customer setting. Used by `observa unpair` so revocation cleanup never
+ * requires a broad config purge. */
+export function removeLocalConfigValues(home, keys) {
+  if (!Array.isArray(keys) || keys.length === 0
+    || keys.some((key) => !LOCAL_CONFIG_KEYS.includes(key))) {
+    refuseCli("LOCAL_CONFIG_KEY_REFUSED");
+  }
+  const existing = readLocalConfig(home);
+  replaceLocalConfigValues(home, { remove: keys });
+  return Object.freeze({ removed: keys.filter((key) => key in existing) });
+}
+
+export function isPairingOwnedConfigKey(key) {
+  return [
+    "hosted_base_url", "hosted_connector_token", "hosted_installation_id",
+    "hosted_recovery_base_url", "hosted_installation_secret",
+    "n8n_deployment_ref",
+  ].includes(key);
+}
+
+/** Presence-only view — the ONLY shape status/diagnose may see. */
+export function configPresence(home) {
+  const config = readLocalConfig(home);
+  const presence = {};
+  for (const key of LOCAL_CONFIG_KEYS) presence[key] = typeof config[key] === "string" && config[key].length > 0;
+  return presence;
+}
+
+/** True when the config file exists with owner-only permissions. */
+export function configPermissionsOk(home) {
+  try {
+    const mode = statSync(configPath(home)).mode & 0o777;
+    return mode === 0o600;
+  } catch {
+    return true; // absent file is not a permission problem
+  }
+}
+
+export function isSecretConfigKey(key) {
+  return SECRET_KEYS.includes(key);
+}

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

@@ -0,0 +1,21 @@
+// CLI refusals. Closed codes; caller-controlled text is never echoed into a
+// refusal message — a manifest field that failed validation does not get to
+// write the error a human reads. Secrets never appear here because secrets
+// never reach this layer as message material.
+
+const CODE_PATTERN = /^[A-Z][A-Z0-9_]{2,64}$/u;
+
+export class CliRefusal extends Error {
+  constructor(code, detail = "") {
+    if (!CODE_PATTERN.test(code)) throw new TypeError("refusal code malformed");
+    super(detail === "" ? code : `${code}: ${detail}`);
+    this.name = "CliRefusal";
+    this.code = code;
+    this.detail = detail;
+    Object.freeze(this);
+  }
+}
+
+export function refuseCli(code, detail = "") {
+  throw new CliRefusal(code, detail);
+}

package/distribution/observa-cli/src/hosted-delivery.mjs

@@ -0,0 +1,148 @@
+// The Local Node's hosted delivery composition — the "runtime composition
+// supervisor" seam DISCOVERED-SEAMS.md reserved.
+//
+// The sealed n8n adapter's own binary knows only the local receipt
+// transport, by design; the hosted path exists as an INJECTION seam
+// (`new RuntimeObserver({ transport })`). This module owns that injection
+// for an installed Local Node.
+//
+// WHY THE RUNTIME MODULES LOAD DYNAMICALLY: the CLI runs from its own
+// unpacked package, but the runtime components (sealed adapter, hosted
+// transport client, SDK contracts) are installed by the signed manifest into
+// `<home>/current/lib`. The composition therefore resolves them from the
+// INSTALLED release root it is told about — the same bytes the manifest
+// verified — never from paths relative to wherever the CLI happens to sit.
+// In the repository, the release root is simply the repository root, because
+// installed artifacts preserve repository-relative layout.
+//
+// The credential is read from the owner-only config file into process
+// memory and given to the transport client. It has no path into logs,
+// output, thrown errors, or `describe()`.
+//
+// AUTHORITY: NONE. This composes evidence delivery; it decides nothing.
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { readLocalConfig } from "./config.mjs";
+import { refuseCli } from "./errors.mjs";
+import { readState } from "./state.mjs";
+import { HOSTED_BASE_URL_PATTERN } from "./pair.mjs";
+
+const MGD1_TOKEN_PATTERN = /^mgd1_[a-f0-9]{32}\.[A-Za-z0-9_-]{43}$/;
+
+/** The installed-release module paths the composition needs. Their presence
+ * is what makes an installation hosted-delivery capable. */
+const RUNTIME_MODULES = Object.freeze({
+  transportClient: "transport/hosted/src/client.mjs",
+  transportVocabulary: "transport/hosted/src/vocabulary.mjs",
+  adapterVocabulary: "runtime-adapters/n8n/src/vocabulary.mjs",
+  sdkVersion: "sdk/contracts/version.mjs",
+});
+
+export function releaseLibRoot(home) {
+  return join(home, "current", "lib");
+}
+
+export function hostedRuntimePresent(libRoot) {
+  return Object.values(RUNTIME_MODULES)
+    .every((relative) => existsSync(join(libRoot, ...relative.split("/"))));
+}
+
+/** Import the runtime modules from one verified release root. */
+export async function loadHostedRuntime(libRoot) {
+  if (!hostedRuntimePresent(libRoot)) refuseCli("HOSTED_RUNTIME_COMPONENTS_ABSENT", libRoot);
+  const load = (relative) =>
+    import(pathToFileURL(join(libRoot, ...relative.split("/"))).href);
+  const [clientModule, transportVocabulary, adapterVocabulary, sdkVersion] = await Promise.all([
+    load(RUNTIME_MODULES.transportClient),
+    load(RUNTIME_MODULES.transportVocabulary),
+    load(RUNTIME_MODULES.adapterVocabulary),
+    load(RUNTIME_MODULES.sdkVersion),
+  ]);
+  return Object.freeze({ clientModule, transportVocabulary, adapterVocabulary, sdkVersion });
+}
+
+/** The installation's capability report: contract versions only — no path,
+ * no host name, no free text (the hosted gate refuses anything else). */
+export function capabilityReportFrom(runtime) {
+  return Object.freeze({
+    schema: runtime.transportVocabulary.CAPABILITY_REPORT_SCHEMA_ID,
+    transport_protocol_versions:
+      Object.freeze([runtime.transportVocabulary.TRANSPORT_PROTOCOL_VERSION]),
+    runtime_bridge_kind: "n8n",
+    runtime_bridge_version: runtime.adapterVocabulary.ADAPTER_VERSION,
+    h1_contract_version: runtime.sdkVersion.SDK_CONTRACT_VERSION,
+    verification_envelope_version:
+      runtime.sdkVersion.VERIFICATION_ENVELOPE_SCHEMA_VERSION,
+  });
+}
+
+/**
+ * Resolve and structurally verify the hosted delivery configuration for an
+ * INSTALLED Local Node. Every failure is a closed refusal naming what is
+ * missing or divergent — never a value.
+ */
+export function resolveHostedDeliveryConfig(home) {
+  const state = readState(home);
+  if (state === null) refuseCli("NOT_INSTALLED");
+  const config = readLocalConfig(home);
+  const baseUrl = config.hosted_base_url;
+  const credential = config.hosted_connector_token;
+  const pairedInstallationId = config.hosted_installation_id;
+  if (typeof baseUrl !== "string" || baseUrl.length === 0
+    || typeof credential !== "string" || credential.length === 0
+    || typeof pairedInstallationId !== "string" || pairedInstallationId.length === 0) {
+    refuseCli("HOSTED_DELIVERY_NOT_CONFIGURED",
+      "run `observa pair --base-url <url> --code-stdin` first");
+  }
+  if (!HOSTED_BASE_URL_PATTERN.test(baseUrl)) refuseCli("HOSTED_BASE_URL_SHAPE_REFUSED");
+  if (!MGD1_TOKEN_PATTERN.test(credential)) refuseCli("HOSTED_CREDENTIAL_SHAPE_REFUSED");
+  // The paired identity must be THIS installation. A credential paired for a
+  // different installation must never carry this node's evidence — and the
+  // hosted side would refuse it anyway; refusing here keeps the failure
+  // local, named, and before any traffic.
+  if (pairedInstallationId !== state.installation_id) {
+    refuseCli("HOSTED_INSTALLATION_BINDING_MISMATCH");
+  }
+  return Object.freeze({
+    baseUrl,
+    credential,
+    installationId: state.installation_id,
+  });
+}
+
+/**
+ * Build the hosted delivery composition for an installed Local Node: the
+ * generic client (verification envelopes, capability reports) and the
+ * ObservationTransport for `new RuntimeObserver({ transport })`.
+ */
+export async function createLocalNodeHostedDelivery({
+  home, libRoot = releaseLibRoot(home), now = () => new Date(),
+  fetchImpl = globalThis.fetch,
+} = {}) {
+  const resolved = resolveHostedDeliveryConfig(home);
+  const runtime = await loadHostedRuntime(libRoot);
+  const client = runtime.clientModule.createHostedTransportClient({
+    baseUrl: resolved.baseUrl,
+    credential: resolved.credential,
+    installationId: resolved.installationId,
+    fetchImpl,
+    now,
+  });
+  const transport = runtime.clientModule.createHostedObservationTransport({ client });
+  return Object.freeze({
+    client,
+    transport,
+    runtime,
+    installationId: resolved.installationId,
+    /** Deliver the installation's capability report; resolves to the closed
+     * delivery vocabulary, never throws for a delivery failure. */
+    async sendCapabilityReport() {
+      return client.sendCapabilityReport(capabilityReportFrom(runtime));
+    },
+    /** Secret-free description, exactly the client's own. */
+    describe() {
+      return transport.describe();
+    },
+  });
+}

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

@@ -0,0 +1,39 @@
+// The public surface of the Observa CLI package. Installer/orchestrator
+// machinery only — there is no policy, verification, enforcement, or
+// decision surface to export.
+
+export { CliRefusal, refuseCli } from "./errors.mjs";
+export {
+  CLI_ARTIFACT_ID, CLI_AUTHORITY, CLI_POLICY_AUTHORITY, CLI_VERSION,
+  CLI_VERIFICATION_AUTHORITY, CLI_EXECUTION_AUTHORITY_OVER_CUSTOMER_APPS,
+  SUPPORTED_MODES,
+} from "./vocabulary.mjs";
+export {
+  compareExactVersions,
+  validateManifestPayload,
+  validateSignedManifestEnvelope,
+  validateRevocationPayload,
+  validateSignedRevocationEnvelope,
+} from "./manifest-schema.mjs";
+export {
+  loadTrustedKeys,
+  verifySignedManifestText,
+  verifySignedRevocationText,
+  findVerifiedRevocation,
+} from "./manifest-verify.mjs";
+export {
+  contentDigestOfEntries, extractEntries, readArtifactEntries,
+  sha256HexOf, wrapperManifestOf,
+} from "./artifact.mjs";
+export {
+  homePaths, installFromManifestFile, loadCurrentInstallation,
+  releaseDirFor, rollbackToPrevious, uninstall, verifyReleaseIntegrity,
+} from "./install.mjs";
+export { readState, writeState } from "./state.mjs";
+export { acquireLock } from "./lock.mjs";
+export {
+  LOCAL_CONFIG_KEYS, configPresence, configPermissionsOk,
+  isSecretConfigKey, readLocalConfig, writeLocalConfigValue,
+} from "./config.mjs";
+export { serviceIsRunning, startService, stopService } from "./service.mjs";
+export { collectStatus, runDiagnose } from "./status.mjs";