@mcpherson-ai/observa-local-node 0.1.3

package/distribution/observa-cli/src/manifest-schema.mjs

@@ -0,0 +1,208 @@
+// Closed schemas for everything the release signature covers.
+//
+// Every schema here is CLOSED: exact key sets, closed enums, exact-format
+// scalars. Unknown fields refuse. Floating versions refuse. "latest" refuses.
+// The validators use the sealed SDK snapshot/exact-keys primitives, so
+// accessor games, prototype games, and revoked proxies fail at the boundary
+// before a single field is trusted.
+
+import {
+  exactKeys as sdkExactKeys,
+  snapshotRecord as sdkSnapshotRecord,
+} from "../../../sdk/contracts/canonical.mjs";
+import { CliRefusal, refuseCli } from "./errors.mjs";
+
+// The sealed SDK primitives throw their own refusal type; the CLI's public
+// surface is CliRefusal with the SAME closed code. Re-throwing preserves the
+// code and drops nothing else of value — SDK refusal messages carry no
+// caller text by design.
+function mapSdkRefusal(fn) {
+  try {
+    return fn();
+  } catch (error) {
+    if (error?.name === "SdkContractError" && typeof error.code === "string") {
+      throw new CliRefusal(error.code);
+    }
+    throw error;
+  }
+}
+
+function snapshotRecord(value, code) {
+  return mapSdkRefusal(() => sdkSnapshotRecord(value, code));
+}
+
+function exactKeys(value, expected, code) {
+  return mapSdkRefusal(() => sdkExactKeys(value, expected, code));
+}
+import {
+  COMPONENT_ROLES,
+  GENERIC_DOMAIN_PACKAGE_NAME,
+  HEALTHCARE_PACKAGE_NAME,
+  HEALTHCARE_PROFILE_PREFIX,
+  MANIFEST_SCHEMA_ID,
+  MAX_MANIFEST_COMPONENTS,
+  REVOCATION_SCHEMA_ID,
+  SIGNED_MANIFEST_SCHEMA_ID,
+  SIGNED_REVOCATION_SCHEMA_ID,
+  SUPPORTED_MANIFEST_SCHEMA_VERSIONS,
+  SUPPORTED_MODES,
+  SUPPORTED_RELEASE_CHANNELS,
+} from "./vocabulary.mjs";
+
+export const KEY_ID_PATTERN = /^[a-z0-9-]{1,40}$/u;
+export const SIGNATURE_PATTERN = /^[A-Za-z0-9_-]{86}$/u;
+export const MANIFEST_ID_PATTERN = /^im-[a-z0-9][a-z0-9-]{6,62}$/u;
+export const REVOCATION_ID_PATTERN = /^rv-[a-z0-9][a-z0-9-]{6,62}$/u;
+export const TENANT_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/u;
+export const PROFILE_ID_PATTERN = /^[a-z0-9][a-z0-9-]{2,63}$/u;
+export const COMPONENT_ID_PATTERN = /^[a-z0-9][a-z0-9-]{2,63}$/u;
+export const PACKAGE_NAME_PATTERN = /^@mcphersonai\/[a-z0-9][a-z0-9-]{1,63}$/u;
+export const EXACT_VERSION_PATTERN = /^\d{1,4}\.\d{1,4}\.\d{1,4}$/u;
+export const SHA256_PATTERN = /^[0-9a-f]{64}$/u;
+export const ARTIFACT_FILENAME_PATTERN = /^[a-z0-9][a-z0-9.-]{3,120}\.tgz$/u;
+export const ISO_INSTANT_PATTERN = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z$/u;
+export const REASON_CODE_PATTERN = /^[A-Z][A-Z0-9_]{2,64}$/u;
+
+const MANIFEST_KEYS = Object.freeze([
+  "schema", "schema_version", "manifest_id", "organization_id", "workspace_id",
+  "installation_id", "release_channel", "mode", "profile_id", "issued_at",
+  "issued_seq", "min_cli_version", "signing_key_id", "previous_manifest_id",
+  "components",
+]);
+const COMPONENT_KEYS = Object.freeze([
+  "component_id", "package_name", "package_version", "role",
+  "artifact_filename", "artifact_sha256", "content_digest",
+]);
+const SIGNED_KEYS = Object.freeze(["schema", "schema_version", "manifest", "signature"]);
+const REVOCATION_KEYS = Object.freeze([
+  "schema", "schema_version", "revocation_id", "organization_id",
+  "workspace_id", "installation_id", "revoked_at", "reason_code",
+  "signing_key_id",
+]);
+const SIGNED_REVOCATION_KEYS = Object.freeze(["schema", "schema_version", "revocation", "signature"]);
+
+function requireString(value, pattern, code) {
+  if (typeof value !== "string" || !pattern.test(value)) refuseCli(code);
+  return value;
+}
+
+export function compareExactVersions(a, b) {
+  const pa = a.split(".").map(Number);
+  const pb = b.split(".").map(Number);
+  for (let i = 0; i < 3; i += 1) {
+    if (pa[i] !== pb[i]) return pa[i] < pb[i] ? -1 : 1;
+  }
+  return 0;
+}
+
+function validateComponentEntry(entry) {
+  const c = snapshotRecord(entry, "MANIFEST_COMPONENT_NOT_A_RECORD");
+  exactKeys(c, COMPONENT_KEYS, "MANIFEST_COMPONENT_KEYS_REFUSED");
+  requireString(c.component_id, COMPONENT_ID_PATTERN, "MANIFEST_COMPONENT_ID_REFUSED");
+  requireString(c.package_name, PACKAGE_NAME_PATTERN, "MANIFEST_PACKAGE_NAME_REFUSED");
+  // The version pattern is the floating-version gate: "^1.2.3", "~1.2.3",
+  // "latest", "*", git URLs and ranges all fail this exact-triple shape.
+  requireString(c.package_version, EXACT_VERSION_PATTERN, "MANIFEST_VERSION_NOT_EXACT");
+  if (!COMPONENT_ROLES.includes(c.role)) refuseCli("MANIFEST_COMPONENT_ROLE_REFUSED");
+  requireString(c.artifact_filename, ARTIFACT_FILENAME_PATTERN, "MANIFEST_ARTIFACT_FILENAME_REFUSED");
+  requireString(c.artifact_sha256, SHA256_PATTERN, "MANIFEST_ARTIFACT_DIGEST_REFUSED");
+  requireString(c.content_digest, SHA256_PATTERN, "MANIFEST_CONTENT_DIGEST_REFUSED");
+  return c;
+}
+
+/** Validate and freeze an installation-manifest payload. */
+export function validateManifestPayload(payload) {
+  const m = snapshotRecord(payload, "MANIFEST_NOT_A_RECORD");
+  exactKeys(m, MANIFEST_KEYS, "MANIFEST_KEYS_REFUSED");
+  if (m.schema !== MANIFEST_SCHEMA_ID) refuseCli("MANIFEST_SCHEMA_ID_REFUSED");
+  if (!SUPPORTED_MANIFEST_SCHEMA_VERSIONS.includes(m.schema_version)) {
+    refuseCli("MANIFEST_SCHEMA_VERSION_UNSUPPORTED");
+  }
+  requireString(m.manifest_id, MANIFEST_ID_PATTERN, "MANIFEST_ID_REFUSED");
+  requireString(m.organization_id, TENANT_ID_PATTERN, "MANIFEST_ORGANIZATION_REFUSED");
+  requireString(m.workspace_id, TENANT_ID_PATTERN, "MANIFEST_WORKSPACE_REFUSED");
+  requireString(m.installation_id, TENANT_ID_PATTERN, "MANIFEST_INSTALLATION_REFUSED");
+  if (!SUPPORTED_RELEASE_CHANNELS.includes(m.release_channel)) {
+    refuseCli("MANIFEST_CHANNEL_REFUSED");
+  }
+  // SHADOW_ONLY is enforced as vocabulary, not as configuration: any other
+  // string — including every enforcement-shaped word — is simply not a mode.
+  if (!SUPPORTED_MODES.includes(m.mode)) refuseCli("MANIFEST_MODE_REFUSED");
+  requireString(m.profile_id, PROFILE_ID_PATTERN, "MANIFEST_PROFILE_REFUSED");
+  requireString(m.issued_at, ISO_INSTANT_PATTERN, "MANIFEST_ISSUED_AT_REFUSED");
+  if (!Number.isSafeInteger(m.issued_seq) || m.issued_seq < 1) {
+    refuseCli("MANIFEST_ISSUED_SEQ_REFUSED");
+  }
+  requireString(m.min_cli_version, EXACT_VERSION_PATTERN, "MANIFEST_MIN_CLI_VERSION_REFUSED");
+  requireString(m.signing_key_id, KEY_ID_PATTERN, "MANIFEST_KEY_ID_REFUSED");
+  if (m.previous_manifest_id !== null) {
+    requireString(m.previous_manifest_id, MANIFEST_ID_PATTERN, "MANIFEST_PREVIOUS_ID_REFUSED");
+  }
+  if (!Array.isArray(m.components) || m.components.length < 1
+    || m.components.length > MAX_MANIFEST_COMPONENTS) {
+    refuseCli("MANIFEST_COMPONENT_SET_REFUSED");
+  }
+  const seenIds = new Set();
+  const seenNames = new Set();
+  for (const entry of m.components) {
+    const c = validateComponentEntry(entry);
+    if (seenIds.has(c.component_id) || seenNames.has(c.package_name)) {
+      refuseCli("MANIFEST_COMPONENT_DUPLICATED");
+    }
+    seenIds.add(c.component_id);
+    seenNames.add(c.package_name);
+    // Domain-contract boundary. The GENERIC contract is the one
+    // domain-contract package admissible in a beta manifest. Everything else
+    // with domain semantics — H2 above all — may only ever appear in a
+    // development-channel manifest whose profile declares itself
+    // healthcare-dev. A generic beta manifest that names H2 is refused
+    // outright, so H2 can never ride in silently (and packaging H2
+    // authorizes no live healthcare use).
+    if (c.package_name === HEALTHCARE_PACKAGE_NAME
+      || (c.role === "domain-contract" && c.package_name !== GENERIC_DOMAIN_PACKAGE_NAME)) {
+      if (m.release_channel !== "development"
+        || !m.profile_id.startsWith(HEALTHCARE_PROFILE_PREFIX)) {
+        refuseCli("MANIFEST_HEALTHCARE_COMPONENT_REFUSED");
+      }
+    }
+  }
+  return m;
+}
+
+/** Validate and freeze a signed-manifest envelope (signature NOT yet checked). */
+export function validateSignedManifestEnvelope(envelope) {
+  const e = snapshotRecord(envelope, "SIGNED_MANIFEST_NOT_A_RECORD");
+  exactKeys(e, SIGNED_KEYS, "SIGNED_MANIFEST_KEYS_REFUSED");
+  if (e.schema !== SIGNED_MANIFEST_SCHEMA_ID) refuseCli("SIGNED_MANIFEST_SCHEMA_ID_REFUSED");
+  if (e.schema_version !== 1) refuseCli("SIGNED_MANIFEST_SCHEMA_VERSION_UNSUPPORTED");
+  requireString(e.signature, SIGNATURE_PATTERN, "SIGNED_MANIFEST_SIGNATURE_SHAPE_REFUSED");
+  const manifest = validateManifestPayload(e.manifest);
+  return Object.freeze({ envelope: e, manifest });
+}
+
+/** Validate and freeze a revocation payload. */
+export function validateRevocationPayload(payload) {
+  const r = snapshotRecord(payload, "REVOCATION_NOT_A_RECORD");
+  exactKeys(r, REVOCATION_KEYS, "REVOCATION_KEYS_REFUSED");
+  if (r.schema !== REVOCATION_SCHEMA_ID) refuseCli("REVOCATION_SCHEMA_ID_REFUSED");
+  if (r.schema_version !== 1) refuseCli("REVOCATION_SCHEMA_VERSION_UNSUPPORTED");
+  requireString(r.revocation_id, REVOCATION_ID_PATTERN, "REVOCATION_ID_REFUSED");
+  requireString(r.organization_id, TENANT_ID_PATTERN, "REVOCATION_ORGANIZATION_REFUSED");
+  requireString(r.workspace_id, TENANT_ID_PATTERN, "REVOCATION_WORKSPACE_REFUSED");
+  requireString(r.installation_id, TENANT_ID_PATTERN, "REVOCATION_INSTALLATION_REFUSED");
+  requireString(r.revoked_at, ISO_INSTANT_PATTERN, "REVOCATION_REVOKED_AT_REFUSED");
+  requireString(r.reason_code, REASON_CODE_PATTERN, "REVOCATION_REASON_REFUSED");
+  requireString(r.signing_key_id, KEY_ID_PATTERN, "REVOCATION_KEY_ID_REFUSED");
+  return r;
+}
+
+/** Validate and freeze a signed-revocation envelope (signature NOT yet checked). */
+export function validateSignedRevocationEnvelope(envelope) {
+  const e = snapshotRecord(envelope, "SIGNED_REVOCATION_NOT_A_RECORD");
+  exactKeys(e, SIGNED_REVOCATION_KEYS, "SIGNED_REVOCATION_KEYS_REFUSED");
+  if (e.schema !== SIGNED_REVOCATION_SCHEMA_ID) refuseCli("SIGNED_REVOCATION_SCHEMA_ID_REFUSED");
+  if (e.schema_version !== 1) refuseCli("SIGNED_REVOCATION_SCHEMA_VERSION_UNSUPPORTED");
+  requireString(e.signature, SIGNATURE_PATTERN, "SIGNED_REVOCATION_SIGNATURE_SHAPE_REFUSED");
+  const revocation = validateRevocationPayload(e.revocation);
+  return Object.freeze({ envelope: e, revocation });
+}

package/distribution/observa-cli/src/manifest-verify.mjs

@@ -0,0 +1,122 @@
+// Customer-side manifest verification. VERIFY ONLY — this module, and this
+// whole package, contains no signing capability: there is no private key
+// type, no sign call, and the authority scan in the test suite bans the
+// signing primitive from ever appearing here.
+//
+// Trust flows one way: a closed map of trusted PUBLIC keys (shipped inside
+// the CLI artifact as JSON records) decides which signatures mean anything.
+// The key id is INSIDE the signed payload, so a valid signature under key A
+// can never be presented as key B's. Parsing is strict (duplicate JSON keys
+// refuse), the schema is closed (unknown fields refuse), and the signed bytes
+// are the canonical serialization of the validated payload.
+
+import { createPublicKey, verify as verifyBytes } from "node:crypto";
+import { readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { canonicalJson } from "../../../sdk/contracts/canonical.mjs";
+import { parseStrictJson } from "../../../runtime-adapters/n8n/src/strict-json.mjs";
+import { refuseCli } from "./errors.mjs";
+import {
+  KEY_ID_PATTERN,
+  validateSignedManifestEnvelope,
+  validateSignedRevocationEnvelope,
+} from "./manifest-schema.mjs";
+import { MAX_SIGNED_DOCUMENT_BYTES } from "./vocabulary.mjs";
+
+const PUBLIC_KEY_SCHEMA_ID = "observa.release.signing-key.public";
+
+/** Load trusted public keys from a directory of `<key-id>.public.json` records. */
+export function loadTrustedKeys(trustDir) {
+  const keys = new Map();
+  let names;
+  try {
+    names = readdirSync(trustDir).filter((n) => n.endsWith(".public.json")).sort();
+  } catch {
+    refuseCli("TRUST_DIRECTORY_UNAVAILABLE");
+  }
+  for (const name of names) {
+    const record = parseStrictJson(readFileSync(join(trustDir, name), "utf8"));
+    if (record.schema !== PUBLIC_KEY_SCHEMA_ID || record.schema_version !== 1) {
+      refuseCli("TRUSTED_KEY_RECORD_REFUSED");
+    }
+    if (typeof record.key_id !== "string" || !KEY_ID_PATTERN.test(record.key_id)) {
+      refuseCli("TRUSTED_KEY_ID_REFUSED");
+    }
+    if (record.algorithm !== "Ed25519") refuseCli("TRUSTED_KEY_ALGORITHM_REFUSED");
+    if (keys.has(record.key_id)) refuseCli("TRUSTED_KEY_DUPLICATED");
+    keys.set(record.key_id, createPublicKey({
+      key: Buffer.from(record.public_key_spki_der_b64, "base64url"),
+      format: "der",
+      type: "spki",
+    }));
+  }
+  if (keys.size < 1) refuseCli("NO_TRUSTED_KEYS");
+  return keys;
+}
+
+function parseSignedDocument(text) {
+  if (typeof text !== "string" || Buffer.byteLength(text, "utf8") > MAX_SIGNED_DOCUMENT_BYTES) {
+    refuseCli("SIGNED_DOCUMENT_TOO_LARGE");
+  }
+  try {
+    // parseStrictJson refuses duplicate keys in the DECODED domain, so
+    // `{"mode":…,"mode":…}` is one refusal, not two readings.
+    return parseStrictJson(text);
+  } catch {
+    refuseCli("SIGNED_DOCUMENT_NOT_STRICT_JSON");
+  }
+  return undefined;
+}
+
+function verifyDetachedSignature({ payload, signature, trustedKeys }) {
+  const keyId = payload.signing_key_id;
+  const publicKey = trustedKeys.get(keyId);
+  if (publicKey === undefined) refuseCli("SIGNING_KEY_UNTRUSTED");
+  const bytes = Buffer.from(canonicalJson(payload), "utf8");
+  const ok = verifyBytes(null, bytes, publicKey, Buffer.from(signature, "base64url"));
+  if (ok !== true) refuseCli("SIGNATURE_INVALID");
+}
+
+/**
+ * Verify a signed installation manifest from raw file text.
+ * Returns the frozen, validated manifest payload — the ONLY object install
+ * logic is allowed to act on.
+ */
+export function verifySignedManifestText(text, { trustedKeys }) {
+  const { envelope, manifest } = validateSignedManifestEnvelope(parseSignedDocument(text));
+  verifyDetachedSignature({ payload: manifest, signature: envelope.signature, trustedKeys });
+  return manifest;
+}
+
+/** Verify a signed revocation record from raw file text. */
+export function verifySignedRevocationText(text, { trustedKeys }) {
+  const { envelope, revocation } = validateSignedRevocationEnvelope(parseSignedDocument(text));
+  verifyDetachedSignature({ payload: revocation, signature: envelope.signature, trustedKeys });
+  return revocation;
+}
+
+/**
+ * Scan a directory for verified revocations matching an installation
+ * identity. Unverifiable revocation files REFUSE (fail closed) rather than
+ * being ignored — a tampered revocation must never read as "not revoked".
+ */
+export function findVerifiedRevocation({ revocationDir, trustedKeys, organizationId, workspaceId, installationId }) {
+  let names = [];
+  try {
+    names = readdirSync(revocationDir).filter((n) => n.endsWith(".revocation.json")).sort();
+  } catch {
+    return null; // no revocation directory yet — nothing delivered
+  }
+  for (const name of names) {
+    const revocation = verifySignedRevocationText(
+      readFileSync(join(revocationDir, name), "utf8"),
+      { trustedKeys },
+    );
+    if (revocation.organization_id === organizationId
+      && revocation.workspace_id === workspaceId
+      && revocation.installation_id === installationId) {
+      return revocation;
+    }
+  }
+  return null;
+}

package/distribution/observa-cli/src/n8n-hook.mjs

@@ -0,0 +1,70 @@
+// Install the packaged n8n global hook and write its owner-only environment.
+// No workflow is edited. The returned/printed value is a path only; neither
+// credential value can enter CLI output.
+import {
+  chmodSync, copyFileSync, mkdirSync, renameSync, rmSync, writeFileSync,
+} from "node:fs";
+import { randomUUID } from "node:crypto";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { refuseCli } from "./errors.mjs";
+import { readLocalConfig } from "./config.mjs";
+import { readState } from "./state.mjs";
+
+const SOURCE_HOOK = fileURLToPath(new URL("../integrations/n8n/observa-external-hook.cjs", import.meta.url));
+const SAFE_VALUE = /^[^\r\n=]{1,512}$/;
+const SAFE_ID = /^[A-Za-z0-9._:-]{1,96}$/;
+
+export function n8nHookPaths(home) {
+  return Object.freeze({
+    hook: join(home, "integrations", "n8n", "observa-external-hook.cjs"),
+    env: join(home, "config", "n8n-external-hook.env"),
+  });
+}
+
+export function prepareN8nHook(home) {
+  const state = readState(home);
+  if (state === null) refuseCli("NOT_INSTALLED");
+  const config = readLocalConfig(home);
+  if (typeof config.n8n_loopback_credential !== "string"
+    || config.n8n_loopback_credential.length < 24) {
+    refuseCli("SERVICE_CONFIG_ABSENT", "n8n_loopback_credential not configured");
+  }
+  const deploymentRef = config.n8n_deployment_ref ?? "n8n-local-node";
+  if (!SAFE_ID.test(state.installation_id) || !SAFE_ID.test(deploymentRef)) {
+    refuseCli("N8N_HOOK_IDENTITY_REFUSED");
+  }
+  const port = config.n8n_loopback_port ?? "6678";
+  if (!/^\d{1,5}$/.test(port) || Number(port) < 1 || Number(port) > 65535) {
+    refuseCli("N8N_HOOK_PORT_REFUSED");
+  }
+  const paths = n8nHookPaths(home);
+  mkdirSync(dirname(paths.hook), { recursive: true, mode: 0o700 });
+  chmodSync(dirname(paths.hook), 0o700);
+  copyFileSync(SOURCE_HOOK, paths.hook);
+  chmodSync(paths.hook, 0o600);
+
+  const values = {
+    EXTERNAL_HOOK_FILES: paths.hook,
+    OBSERVA_N8N_HOOK_URL: `http://127.0.0.1:${port}`,
+    OBSERVA_N8N_HOOK_INSTALLATION_ID: state.installation_id,
+    OBSERVA_N8N_HOOK_DEPLOYMENT_REF: deploymentRef,
+    OBSERVA_N8N_HOOK_CREDENTIAL: config.n8n_loopback_credential,
+  };
+  if (Object.values(values).some((value) => !SAFE_VALUE.test(value))) {
+    refuseCli("N8N_HOOK_ENV_VALUE_REFUSED");
+  }
+  mkdirSync(dirname(paths.env), { recursive: true, mode: 0o700 });
+  chmodSync(dirname(paths.env), 0o700);
+  const temporary = `${paths.env}.${process.pid}.${randomUUID()}.tmp`;
+  try {
+    const text = `${Object.entries(values).map(([key, value]) => `${key}=${value}`).join("\n")}\n`;
+    writeFileSync(temporary, text, { mode: 0o600, flag: "wx" });
+    chmodSync(temporary, 0o600);
+    renameSync(temporary, paths.env);
+    chmodSync(paths.env, 0o600);
+  } finally {
+    rmSync(temporary, { force: true });
+  }
+  return Object.freeze({ configured: true, env_path: paths.env, hook_path: paths.hook });
+}

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

@@ -0,0 +1,149 @@
+// `observa pair` — the runtime-neutral pairing step, as one bounded command.
+//
+// The tester presents ONE pairing code to the Hosted pairing lane
+// (POST /v1/pairing/redeem) and this module stores what comes back where the
+// platform already keeps local secrets: hosted_base_url,
+// hosted_connector_token and hosted_installation_id in the owner-only local
+// config file. The credential value exists in process memory for exactly the
+// storage call; it is never printed, never logged, and has no path into any
+// other output of this command. What IS printed — installation id,
+// credential id, fingerprint, deployment id — is the same non-secret summary
+// the pairing lane itself returns.
+//
+// This is NOT the OpenClaw pairing helper (bin/observa-pair.mjs); that
+// helper stays OpenClaw-specific and untouched. The endpoint here is the
+// runtime-neutral tester lane the beta server exposes for every runtime.
+//
+// AUTHORITY: NONE. Pairing yields transport identity, not permission.
+import { parseStrictJson } from "../../../runtime-adapters/n8n/src/strict-json.mjs";
+import { refuseCli } from "./errors.mjs";
+import { createHash } from "node:crypto";
+import { writeLocalConfigValues } from "./config.mjs";
+
+/** Same grammar as the hosted transport client's base-URL rule: https to any
+ * host, plain http strictly on loopback, no userinfo. Restated here because
+ * `observa pair` must run BEFORE any runtime artifact is installed, when the
+ * transport client's file is not yet on the machine; a repo-level parity test
+ * pins the two spellings equal. */
+export const HOSTED_BASE_URL_PATTERN =
+  /^(https:\/\/[A-Za-z0-9.-]+(:\d{1,5})?|http:\/\/(127\.0\.0\.1|\[::1\])(:\d{1,5})?)$/;
+
+/** The pairing lane's own request grammars (src/beta/v1-pairing.mjs). */
+const PAIRING_CODE_PATTERN = /^[A-Za-z0-9_-]{16,128}$/;
+const DEPLOYMENT_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,95}$/;
+/** The credential shape this CLI will store — the existing mgd1 format,
+ * exactly. Anything else is refused unstored. */
+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}$/;
+
+export const PAIRING_ROUTE = "/v1/pairing/redeem";
+export const DEFAULT_DEPLOYMENT_ID = "n8n-local-node";
+
+const DEFAULT_TIMEOUT_MS = 10_000;
+const MAX_RESPONSE_BYTES = 32 * 1024;
+
+/**
+ * Redeem one pairing code and store the hosted delivery configuration.
+ *
+ * Returns ONLY non-secret facts. Every refusal is a closed CLI code; the
+ * server's response body never travels into a thrown error verbatim, so a
+ * hostile or broken endpoint cannot smuggle content into terminal output.
+ */
+export async function pairHosted({
+  home, baseUrl, pairingCode, deploymentId = DEFAULT_DEPLOYMENT_ID,
+  installationName = null,
+  fetchImpl = globalThis.fetch, timeoutMs = DEFAULT_TIMEOUT_MS,
+}) {
+  if (typeof baseUrl !== "string" || !HOSTED_BASE_URL_PATTERN.test(baseUrl)) {
+    refuseCli("PAIR_BASE_URL_REFUSED", "https://host[:port] (or http on loopback)");
+  }
+  if (typeof pairingCode !== "string" || !PAIRING_CODE_PATTERN.test(pairingCode)) {
+    refuseCli("PAIR_CODE_MALFORMED");
+  }
+  if (typeof deploymentId !== "string" || !DEPLOYMENT_ID_PATTERN.test(deploymentId)) {
+    refuseCli("PAIR_DEPLOYMENT_ID_MALFORMED");
+  }
+
+  const body = {
+    pairing_code: pairingCode,
+    deployment_id: deploymentId,
+    ...(typeof installationName === "string" && installationName.length > 0
+      && installationName.length <= 96
+      ? { installation_name: installationName } : {}),
+  };
+
+  let response;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    response = await fetchImpl(`${baseUrl}${PAIRING_ROUTE}`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(body),
+      signal: controller.signal,
+    });
+  } catch (error) {
+    refuseCli("PAIR_HOSTED_UNREACHABLE",
+      error?.name === "AbortError" ? "timed out" : "connection failed");
+  } finally {
+    clearTimeout(timer);
+  }
+
+  let parsed = null;
+  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 (parsed.paired !== true) {
+    // One bounded reason code from the closed pairing-lane vocabulary; the
+    // rest of the body is discarded.
+    const reason = typeof parsed.reason === "string" && /^[a-z_]{1,64}$/.test(parsed.reason)
+      ? parsed.reason : "pairing_refused";
+    refuseCli("PAIR_REFUSED", reason);
+  }
+
+  const credential = parsed.credential;
+  const installationId = parsed.installation_id;
+  if (typeof credential !== "string" || !MGD1_TOKEN_PATTERN.test(credential)) {
+    refuseCli("PAIR_CREDENTIAL_SHAPE_REFUSED");
+  }
+  if (typeof installationId !== "string" || !WIRE_SAFE_ID_PATTERN.test(installationId)) {
+    refuseCli("PAIR_INSTALLATION_ID_REFUSED");
+  }
+
+  // Success metadata is still untrusted network input. Derive the printable
+  // values locally from the credential instead of echoing arbitrary response
+  // strings (which could contain the credential itself, control characters or
+  // terminal escapes).
+  const credentialId = credential.match(/^mgd1_([a-f0-9]{32})\./)?.[1] ?? null;
+  const fingerprint = `sha256:${createHash("sha256").update(credential).digest("hex").slice(0, 16)}`;
+  if (parsed.credential_id !== credentialId || parsed.fingerprint !== fingerprint) {
+    refuseCli("PAIR_CREDENTIAL_METADATA_DIVERGED");
+  }
+
+  // The one atomic storage step. Owner-only file, value never echoed.
+  writeLocalConfigValues(home, {
+    n8n_deployment_ref: deploymentId,
+    hosted_base_url: baseUrl,
+    hosted_connector_token: credential,
+    hosted_installation_id: installationId,
+  });
+
+  return Object.freeze({
+    paired: true,
+    installation_id: installationId,
+    credential_id: credentialId,
+    fingerprint,
+    deployment_id: deploymentId,
+    hosted_base_url: baseUrl,
+    credential_stored: true,
+  });
+}