relmio 0.8.0 → 0.9.0

package/src/cli.js

@@ -23,9 +23,14 @@ export function isCliEntryPath(entryPath, realpath = realpathSync) {
 }
 
 export function cliMode(argumentsList) {
-  return argumentsList.length === 1 &&
+  if (
+    argumentsList.length === 1 &&
     (argumentsList[0] === "--version" || argumentsList[0] === "-v")
-    ? "version"
+  ) {
+    return "version";
+  }
+  return argumentsList.length === 1 && argumentsList[0] === "assistant"
+    ? "assistant"
     : "wizard";
 }
 
@@ -41,8 +46,12 @@ export async function runCli({
   log = console.log,
   readPackage = () => readFile(packageJsonUrl, "utf8"),
   isInteractive = hasInteractiveTerminal,
+  startServer = startWizardServer,
+  open = openBrowser,
+  attachReopen = attachBrowserReopenOnEnter,
 } = {}) {
-  if (cliMode(argumentsList) === "version") {
+  const mode = cliMode(argumentsList);
+  if (mode === "version") {
     const packageJson = JSON.parse(await readPackage());
     if (typeof packageJson.version !== "string" || packageJson.version === "") {
       throw new Error("Relmio package metadata does not contain a version.");
@@ -59,21 +68,25 @@ export async function runCli({
   }
 
   const sessionToken = randomBytes(32).toString("base64url");
-  const wizard = await startWizardServer({ sessionToken });
-  const url = `${wizard.origin}/?session=${sessionToken}`;
+  const wizard = await startServer({ sessionToken });
+  const url = `${wizard.origin}${mode === "assistant" ? "/assistant" : "/"}?session=${sessionToken}`;
 
   log("");
   log("Relmio");
   log("---------");
   log(`Local wizard: ${url}`);
   log("");
-  log("This creates a separate sidecar and never restarts n8n.");
+  log(
+    mode === "assistant"
+      ? "This creates only the separate AI Assistant companion and never restarts n8n."
+      : "This creates a separate sidecar and never restarts n8n.",
+  );
   log("Keep this Terminal window open while using the wizard.");
   log("Press Control+C to stop.");
   log("");
 
-  openBrowser(url);
-  const detachBrowserReopen = attachBrowserReopenOnEnter({ url });
+  open(url);
+  const detachBrowserReopen = attachReopen({ url });
 
   let closing = false;
   async function close() {

package/src/domain/assistant-templates.js

@@ -0,0 +1,207 @@
+import {
+  getAssistantContainerNames,
+  getAssistantLabels,
+  validateAssistantInstallation,
+  validateAssistantSearxngSelection,
+} from "./assistant.js";
+import { validateDockerName } from "./validation.js";
+
+export const ASSISTANT_COMPANION_IMAGES = Object.freeze({
+  api: "ghcr.io/n8n-io/n8n-sandbox-service-api:1.1.1@sha256:21672029fee08495e2398cff7fc370ff60ce0e7c461610732bf2f5265cb75704",
+  runner: "ghcr.io/n8n-io/n8n-sandbox-service-runner-dind:1.1.1@sha256:9de7a8aad7f0d2293716daff40206be60577a59a2c2dae641dd9a425c18bf6fd",
+  sandbox: "ghcr.io/n8n-io/n8n-sandbox-service-sandbox:1.1.0@sha256:16f62fb90a4ce61ef74925f62ea76bb11eb2a5598888b7c0651100c7944ed2d8",
+  searxng: "ghcr.io/searxng/searxng:2026.8.28-a30b2d474@sha256:addd2cf36efb4b9815a2820a522aef7cce4da0d1c0e4527f6675f5663332fc9b",
+});
+
+const SANDBOX_SECRET_FIELDS = Object.freeze([
+  "sandboxApiKey",
+  "runnerRegistrationToken",
+  "runnerApiKey",
+]);
+
+function createSecret(randomBytes) {
+  const value = randomBytes(32);
+  if (!Buffer.isBuffer(value) || value.length !== 32) {
+    throw new TypeError("The local secret generator is unavailable.");
+  }
+  return value.toString("base64url");
+}
+
+function getRequiredSecretFields(includeSearxng) {
+  validateAssistantSearxngSelection(includeSearxng);
+  return [...SANDBOX_SECRET_FIELDS, "searxngSecret"];
+}
+
+export function createAssistantSecrets({ randomBytes, includeSearxng }) {
+  if (typeof randomBytes !== "function") {
+    throw new TypeError("A cryptographic random-byte generator is required.");
+  }
+  const selectedSearxng = validateAssistantSearxngSelection(includeSearxng);
+  const secrets = {
+    sandboxApiKey: createSecret(randomBytes),
+    runnerRegistrationToken: createSecret(randomBytes),
+    runnerApiKey: createSecret(randomBytes),
+    searxngSecret: createSecret(randomBytes),
+  };
+  if (new Set(Object.values(secrets)).size !== getRequiredSecretFields(selectedSearxng).length) {
+    throw new TypeError("AI Assistant secrets must be independently generated.");
+  }
+  return secrets;
+}
+
+export function createAssistantEnv(secrets, { includeSearxng }) {
+  const selectedSearxng = validateAssistantSearxngSelection(includeSearxng);
+  const requiredSecretFields = getRequiredSecretFields(selectedSearxng);
+  if (
+    !secrets ||
+    requiredSecretFields.some(
+      (field) =>
+        typeof secrets[field] !== "string" ||
+        !/^[A-Za-z0-9_-]{43}$/u.test(secrets[field]),
+    )
+  ) {
+    throw new TypeError("AI Assistant secrets are invalid.");
+  }
+  const searxngEnv = `SEARXNG_SECRET=${secrets.searxngSecret}
+`;
+  return `SANDBOX_API_KEYS=${secrets.sandboxApiKey}
+SANDBOX_API_RUNNER_REGISTRATION_TOKEN=${secrets.runnerRegistrationToken}
+SANDBOX_API_RUNNER_API_KEY=${secrets.runnerApiKey}
+${searxngEnv}`;
+}
+
+export function createSearxngSettings() {
+  return `use_default_settings: true
+search:
+  formats:
+    - html
+    - json
+`;
+}
+
+export function createAssistantComposeFile({ networkName, installation }) {
+  const safeNetworkName = validateDockerName(networkName);
+  const safeInstallation = validateAssistantInstallation(installation);
+  const containerNames = getAssistantContainerNames(safeInstallation);
+  const labels = getAssistantLabels(safeInstallation);
+
+  return `volumes:
+  sandbox-tls:
+    name: ${safeInstallation.projectName}-sandbox-tls
+    labels:
+      io.relmio.ai-assistant.managed: "${labels["io.relmio.ai-assistant.managed"]}"
+      io.relmio.ai-assistant.install-id: "${labels["io.relmio.ai-assistant.install-id"]}"
+
+services:
+  relmio-sandbox-certs:
+    container_name: ${containerNames.certs}
+    image: ${ASSISTANT_COMPANION_IMAGES.api}
+    user: '0:0'
+    entrypoint: ['sh', '-c']
+    command:
+      - >
+        bootstrap-mtls.sh --out-dir /tls --api-san relmio-sandbox-api
+        --control-san-prefix relmio-sandbox-runner &&
+        chown -R sandbox-api:sandbox-api /tls/api
+    environment:
+      NUM_RUNNERS: '1'
+    volumes:
+      - sandbox-tls:/tls
+    networks:
+      - assistant-internal
+    labels:
+      io.relmio.ai-assistant.managed: "${labels["io.relmio.ai-assistant.managed"]}"
+      io.relmio.ai-assistant.install-id: "${labels["io.relmio.ai-assistant.install-id"]}"
+
+  relmio-sandbox-api:
+    container_name: ${containerNames.api}
+    image: ${ASSISTANT_COMPANION_IMAGES.api}
+    depends_on:
+      relmio-sandbox-certs:
+        condition: service_completed_successfully
+    environment:
+      SANDBOX_API_KEYS: \${SANDBOX_API_KEYS}
+      SANDBOX_API_RUNNER_REGISTRATION_TOKEN: \${SANDBOX_API_RUNNER_REGISTRATION_TOKEN}
+      SANDBOX_API_RUNNER_API_KEY: \${SANDBOX_API_RUNNER_API_KEY}
+      SANDBOX_API_GRPC_TLS_CERT_FILE: /tls/api/grpc-server.crt
+      SANDBOX_API_GRPC_TLS_KEY_FILE: /tls/api/grpc-server.key
+      SANDBOX_API_GRPC_TLS_CLIENT_CA_FILE: /tls/api/ca.crt
+      SANDBOX_API_RUNNER_CONTROL_GRPC_TLS_CA_FILE: /tls/api/ca.crt
+      SANDBOX_API_RUNNER_CONTROL_GRPC_TLS_CERT_FILE: /tls/api/control-grpc-api-client.crt
+      SANDBOX_API_RUNNER_CONTROL_GRPC_TLS_KEY_FILE: /tls/api/control-grpc-api-client.key
+      SANDBOX_API_RUNNER_CONTROL_GRPC_TLS_SERVER_NAME: relmio-sandbox-runner-1
+    volumes:
+      - sandbox-tls:/tls:ro
+    healthcheck:
+      test: ["CMD", "wget", "-qO-", "http://localhost:8080/healthz"]
+      interval: 5s
+      timeout: 3s
+      retries: 5
+      start_period: 10s
+    networks:
+      assistant-internal:
+      n8n-shared:
+        aliases:
+          - ${safeInstallation.sandboxAlias}
+    labels:
+      io.relmio.ai-assistant.managed: "${labels["io.relmio.ai-assistant.managed"]}"
+      io.relmio.ai-assistant.install-id: "${labels["io.relmio.ai-assistant.install-id"]}"
+
+  relmio-sandbox-runner-1:
+    container_name: ${containerNames.runner}
+    image: ${ASSISTANT_COMPANION_IMAGES.runner}
+    privileged: true
+    depends_on:
+      relmio-sandbox-api:
+        condition: service_healthy
+    environment:
+      SANDBOX_RUNNER_API_KEYS: \${SANDBOX_API_RUNNER_API_KEY}
+      SANDBOX_RUNNER_REGISTRATION_TOKEN: \${SANDBOX_API_RUNNER_REGISTRATION_TOKEN}
+      SANDBOX_RUNNER_API_GRPC_ADDR: relmio-sandbox-api:9090
+      SANDBOX_RUNNER_HTTP_BASE_URL: http://relmio-sandbox-runner-1:8080
+      SANDBOX_RUNNER_CONTROL_GRPC_LISTEN_ADDR: ':9091'
+      SANDBOX_RUNNER_CONTROL_GRPC_ADVERTISE_ADDR: relmio-sandbox-runner-1:9091
+      SANDBOX_RUNNER_ID: runner-1
+      SANDBOX_RUNNER_DOCKER_SANDBOX_IMAGE: ${ASSISTANT_COMPANION_IMAGES.sandbox}
+      SANDBOX_RUNNER_REGISTRATION_GRPC_CA_FILE: /tls/runner/ca.crt
+      SANDBOX_RUNNER_REGISTRATION_GRPC_CERT_FILE: /tls/runner/grpc-client.crt
+      SANDBOX_RUNNER_REGISTRATION_GRPC_KEY_FILE: /tls/runner/grpc-client.key
+      SANDBOX_RUNNER_REGISTRATION_GRPC_SERVER_NAME: relmio-sandbox-api
+      SANDBOX_RUNNER_CONTROL_GRPC_TLS_CERT_FILE: /tls/runner/control-grpc-server.crt
+      SANDBOX_RUNNER_CONTROL_GRPC_TLS_KEY_FILE: /tls/runner/control-grpc-server.key
+      SANDBOX_RUNNER_CONTROL_GRPC_TLS_CLIENT_CA_FILE: /tls/runner/ca.crt
+    volumes:
+      - sandbox-tls:/tls:ro
+    networks:
+      - assistant-internal
+    labels:
+      io.relmio.ai-assistant.managed: "${labels["io.relmio.ai-assistant.managed"]}"
+      io.relmio.ai-assistant.install-id: "${labels["io.relmio.ai-assistant.install-id"]}"
+
+${safeInstallation.includeSearxng ? `  relmio-searxng:
+    container_name: ${containerNames.searxng}
+    image: ${ASSISTANT_COMPANION_IMAGES.searxng}
+    environment:
+      SEARXNG_SECRET: \${SEARXNG_SECRET}
+    volumes:
+      - ./searxng-settings.yml:/etc/searxng/settings.yml:ro
+    networks:
+      n8n-shared:
+        aliases:
+          - ${safeInstallation.searxngAlias}
+    labels:
+      io.relmio.ai-assistant.managed: "${labels["io.relmio.ai-assistant.managed"]}"
+      io.relmio.ai-assistant.install-id: "${labels["io.relmio.ai-assistant.install-id"]}"
+
+` : ""}networks:
+
+  assistant-internal:
+    name: ${safeInstallation.projectName}-internal
+    labels:
+      io.relmio.ai-assistant.managed: "${labels["io.relmio.ai-assistant.managed"]}"
+      io.relmio.ai-assistant.install-id: "${labels["io.relmio.ai-assistant.install-id"]}"
+  n8n-shared:
+    external: true
+    name: ${safeNetworkName}
+`;
+}

package/src/domain/assistant.js

@@ -0,0 +1,363 @@
+import {
+  INSTALL_ROOT,
+  MANAGED_MARKER_PATH,
+  SHARED_ROOT_MARKER_CONTENT,
+  SHARED_ROOT_MARKER_PATH,
+  SIDECAR_MARKER_CONTENT,
+} from "./safety.js";
+import { validateDockerName } from "./validation.js";
+
+export const ASSISTANT_ROOT = INSTALL_ROOT + "/assistant-sandbox";
+export const ASSISTANT_MARKER_PATH =
+  ASSISTANT_ROOT + "/.managed-by-relmio-ai-assistant";
+export { SHARED_ROOT_MARKER_PATH as ASSISTANT_ROOT_MARKER_PATH };
+
+const ASSISTANT_MARKER_VERSION = 2;
+const LEGACY_ASSISTANT_MARKER_VERSION = 1;
+const INSTALL_ID_PATTERN = /^[a-f0-9]{32}$/u;
+const PROJECT_NAME_PATTERN = /^relmio-ai-[a-f0-9]{32}$/u;
+const SANDBOX_ALIAS_PATTERN = /^relmio-ai-sandbox-[a-f0-9]{32}$/u;
+const SEARXNG_ALIAS_PATTERN = /^relmio-ai-searxng-[a-f0-9]{32}$/u;
+const MAX_MARKER_BYTES = 512;
+
+const MANAGED_LABEL = "io.relmio.ai-assistant.managed";
+const INSTALL_ID_LABEL = "io.relmio.ai-assistant.install-id";
+const EXPECTED_MANAGED_LABEL_VALUE = "true";
+const SANDBOX_SERVICE_NAMES = Object.freeze([
+  "relmio-sandbox-certs",
+  "relmio-sandbox-api",
+  "relmio-sandbox-runner-1",
+]);
+const SEARXNG_SERVICE_NAME = "relmio-searxng";
+
+const ROOT_PRECHECK =
+  "if [ -e " + INSTALL_ROOT + " ]; then " +
+  "if [ -L " + INSTALL_ROOT + " ] || [ ! -d " + INSTALL_ROOT + " ] || " +
+  "[ -L " + SHARED_ROOT_MARKER_PATH + " ] || [ -L " + MANAGED_MARKER_PATH + " ]; then exit 43; " +
+  "elif [ -e " + SHARED_ROOT_MARKER_PATH + " ]; then " +
+  "if [ ! -f " + SHARED_ROOT_MARKER_PATH + " ] || [ \"$(cat " + SHARED_ROOT_MARKER_PATH + ")\" != \"" +
+  SHARED_ROOT_MARKER_CONTENT.trim() + "\" ]; then exit 42; fi; " +
+  "elif [ -f " + MANAGED_MARKER_PATH + " ] && [ \"$(cat " +
+  MANAGED_MARKER_PATH + ")\" = \"" + SIDECAR_MARKER_CONTENT.trim() +
+  "\" ]; then :; else exit 42; fi; fi";
+
+export const ASSISTANT_PRECHECK_COMMAND =
+  ROOT_PRECHECK + "; if [ -L " + ASSISTANT_ROOT + " ]; then exit 43; " +
+  "elif [ -e " + ASSISTANT_ROOT + " ]; then " +
+  "if [ ! -d " + ASSISTANT_ROOT + " ]; then exit 42; " +
+  "elif [ -L " + ASSISTANT_MARKER_PATH + " ] || [ -L " +
+  ASSISTANT_ROOT + "/docker-compose.yml ] || [ -L " +
+  ASSISTANT_ROOT + "/searxng-settings.yml ] || [ -L " +
+  ASSISTANT_ROOT + "/.env ]; then exit 43; " +
+  "elif [ ! -f " + ASSISTANT_MARKER_PATH + " ]; then exit 42; " +
+  "else printf '%s\\n' managed; cat " + ASSISTANT_MARKER_PATH +
+  "; fi; else printf '%s\\n' new; fi";
+
+function createInstallHex(randomBytes) {
+  const value = randomBytes(16);
+  if (!Buffer.isBuffer(value) || value.length !== 16) {
+    throw new TypeError("A cryptographic AI Assistant install generator is required.");
+  }
+  return value.toString("hex");
+}
+
+function objectHasExactKeys(value, keys) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const actual = Object.keys(value).sort();
+  const expected = [...keys].sort();
+  return actual.length === expected.length &&
+    actual.every((key, index) => key === expected[index]);
+}
+
+export function validateAssistantInstallation(value) {
+  const legacyKeys = [
+    "version",
+    "installId",
+    "projectName",
+    "sandboxAlias",
+    "searxngAlias",
+  ];
+  if (
+    value?.version === LEGACY_ASSISTANT_MARKER_VERSION &&
+    objectHasExactKeys(value, legacyKeys)
+  ) {
+    return validateAssistantInstallation({
+      ...value,
+      version: ASSISTANT_MARKER_VERSION,
+      includeSearxng: true,
+    });
+  }
+  const requiredKeys = [...legacyKeys, "includeSearxng"];
+  if (
+    !objectHasExactKeys(value, requiredKeys) ||
+    value.version !== ASSISTANT_MARKER_VERSION ||
+    typeof value.installId !== "string" ||
+    !INSTALL_ID_PATTERN.test(value.installId) ||
+    typeof value.projectName !== "string" ||
+    !PROJECT_NAME_PATTERN.test(value.projectName) ||
+    typeof value.sandboxAlias !== "string" ||
+    !SANDBOX_ALIAS_PATTERN.test(value.sandboxAlias) ||
+    typeof value.searxngAlias !== "string" ||
+    !SEARXNG_ALIAS_PATTERN.test(value.searxngAlias) ||
+    typeof value.includeSearxng !== "boolean" ||
+    value.sandboxAlias === value.searxngAlias ||
+    value.sandboxAlias.endsWith(value.installId) ||
+    value.searxngAlias.endsWith(value.installId) ||
+    value.sandboxAlias.slice(-32) === value.searxngAlias.slice(-32)
+  ) {
+    throw new TypeError("The AI Assistant installation marker is invalid.");
+  }
+  return {
+    version: ASSISTANT_MARKER_VERSION,
+    installId: value.installId,
+    projectName: value.projectName,
+    sandboxAlias: value.sandboxAlias,
+    searxngAlias: value.searxngAlias,
+    includeSearxng: value.includeSearxng,
+  };
+}
+
+export function validateAssistantSearxngSelection(includeSearxng) {
+  if (typeof includeSearxng !== "boolean") {
+    throw new TypeError("Choose whether to include optional SearXNG web search.");
+  }
+  return includeSearxng;
+}
+
+export function createAssistantInstallation({ randomBytes, includeSearxng }) {
+  if (typeof randomBytes !== "function") {
+    throw new TypeError("A cryptographic AI Assistant install generator is required.");
+  }
+  const selectedSearxng = validateAssistantSearxngSelection(includeSearxng);
+  const installId = createInstallHex(randomBytes);
+  const projectSuffix = createInstallHex(randomBytes);
+  const sandboxSuffix = createInstallHex(randomBytes);
+  const searxngSuffix = createInstallHex(randomBytes);
+  return validateAssistantInstallation({
+    version: ASSISTANT_MARKER_VERSION,
+    installId,
+    projectName: "relmio-ai-" + projectSuffix,
+    sandboxAlias: "relmio-ai-sandbox-" + sandboxSuffix,
+    searxngAlias: "relmio-ai-searxng-" + searxngSuffix,
+    includeSearxng: selectedSearxng,
+  });
+}
+
+export function serializeAssistantMarker(installation) {
+  return JSON.stringify(validateAssistantInstallation(installation)) + "\n";
+}
+
+export function parseAssistantMarker(contents) {
+  if (
+    typeof contents !== "string" ||
+    contents.length === 0 ||
+    Buffer.byteLength(contents, "utf8") > MAX_MARKER_BYTES
+  ) {
+    throw new TypeError("The AI Assistant installation marker is invalid.");
+  }
+  try {
+    return validateAssistantInstallation(JSON.parse(contents));
+  } catch {
+    throw new TypeError("The AI Assistant installation marker is invalid.");
+  }
+}
+
+export function parseAssistantPrecheck(output) {
+  if (typeof output !== "string" || output.length === 0) {
+    throw new TypeError("The VPS AI Assistant install-directory check returned an invalid state.");
+  }
+  if (output === "new\n") return { state: "new", installation: null };
+  if (!output.startsWith("managed\n")) {
+    throw new TypeError("The VPS AI Assistant install-directory check returned an invalid state.");
+  }
+  return {
+    state: "managed",
+    installation: parseAssistantMarker(output.slice("managed\n".length)),
+  };
+}
+
+function composePrefix(installation) {
+  const safeInstallation = validateAssistantInstallation(installation);
+  return "docker compose --project-name " + safeInstallation.projectName +
+    " --file " + ASSISTANT_ROOT + "/docker-compose.yml";
+}
+
+export function getAssistantServiceNames(installation) {
+  const safeInstallation = validateAssistantInstallation(installation);
+  return safeInstallation.includeSearxng
+    ? [...SANDBOX_SERVICE_NAMES, SEARXNG_SERVICE_NAME]
+    : [...SANDBOX_SERVICE_NAMES];
+}
+
+export function getAssistantContainerNames(installation) {
+  const safeInstallation = validateAssistantInstallation(installation);
+  const prefix = "relmio-ai-" + safeInstallation.installId.slice(0, 16) + "-";
+  return {
+    certs: prefix + "certs",
+    api: prefix + "api",
+    runner: prefix + "runner",
+    ...(safeInstallation.includeSearxng ? { searxng: prefix + "search" } : {}),
+  };
+}
+
+function validateAssistantStartupScope(installation, startupScope) {
+  if (startupScope === "all") return getAssistantServiceNames(installation);
+  if (startupScope === "searxng" && installation.includeSearxng) {
+    return [SEARXNG_SERVICE_NAME];
+  }
+  throw new TypeError("The AI Assistant startup scope is invalid.");
+}
+
+export function createAssistantDeploymentCommands({ installation, startupScope = "all" }) {
+  const safeInstallation = validateAssistantInstallation(installation);
+  const prefix = composePrefix(safeInstallation);
+  const publicPaths = [ASSISTANT_ROOT + "/docker-compose.yml"];
+  if (safeInstallation.includeSearxng) {
+    publicPaths.push(ASSISTANT_ROOT + "/searxng-settings.yml");
+  }
+  const startupServices = validateAssistantStartupScope(safeInstallation, startupScope);
+  return [
+    "install -d -m 0755 " + INSTALL_ROOT,
+    "install -d -m 0700 " + ASSISTANT_ROOT,
+    "chmod 600 " + SHARED_ROOT_MARKER_PATH + " " + ASSISTANT_MARKER_PATH +
+      " " + ASSISTANT_ROOT + "/.env",
+    "chmod 644 " + publicPaths.join(" "),
+    "test \"$(stat -c '%a' " + SHARED_ROOT_MARKER_PATH + ")\" = 600 && " +
+      "test \"$(stat -c '%a' " + ASSISTANT_MARKER_PATH + ")\" = 600 && " +
+      "test \"$(stat -c '%a' " + ASSISTANT_ROOT + "/.env)\" = 600",
+    publicPaths.map(
+      (path) => "test \"$(stat -c '%a' " + path + ")\" = 644",
+    ).join(" && "),
+    prefix + " config --quiet",
+    prefix + " up -d --wait --wait-timeout 90 " + startupServices.join(" "),
+  ];
+}
+
+export function createAssistantVerificationCommands({ installation, cleanupScope = "project" }) {
+  const safeInstallation = validateAssistantInstallation(installation);
+  const services = getAssistantServiceNames(safeInstallation).filter(
+    (service) => service !== "relmio-sandbox-certs",
+  );
+  if (cleanupScope !== "project" && cleanupScope !== "searxng") {
+    throw new TypeError("The AI Assistant cleanup scope is invalid.");
+  }
+  if (cleanupScope === "searxng" && !safeInstallation.includeSearxng) {
+    throw new TypeError("The AI Assistant cleanup scope is invalid.");
+  }
+  const prefix = composePrefix(safeInstallation);
+  return {
+    health: prefix +
+      " exec -T relmio-sandbox-api wget -qO- http://127.0.0.1:8080/healthz",
+    runningServices: prefix + " ps --status running --services",
+    publicationState: prefix + " ps --format json " + services.join(" "),
+    cleanup: cleanupScope === "searxng"
+      ? prefix + " rm -sf " + SEARXNG_SERVICE_NAME
+      : prefix + " down --volumes",
+  };
+}
+
+export function getAssistantManagedResourceNames(installation) {
+  const safeInstallation = validateAssistantInstallation(installation);
+  return {
+    containers: Object.values(getAssistantContainerNames(safeInstallation)),
+    network: safeInstallation.projectName + "-internal",
+    volume: safeInstallation.projectName + "-sandbox-tls",
+  };
+}
+
+function createAttestationCommand(resource, installation) {
+  const safeInstallation = validateAssistantInstallation(installation);
+  const filter = "--filter \"label=com.docker.compose.project=" +
+    safeInstallation.projectName + "\"";
+  if (resource === "containers") {
+    return "docker container ls -a " + filter +
+      " --format '{{.Label \"" + INSTALL_ID_LABEL + "\"}}|{{.Label \"" +
+      MANAGED_LABEL + "\"}}'";
+  }
+  if (resource === "networks") {
+    return "docker network ls " + filter +
+      " --format '{{.Label \"" + INSTALL_ID_LABEL + "\"}}|{{.Label \"" +
+      MANAGED_LABEL + "\"}}'";
+  }
+  return "docker volume ls " + filter +
+    " --format '{{.Label \"" + INSTALL_ID_LABEL + "\"}}|{{.Label \"" +
+    MANAGED_LABEL + "\"}}'";
+}
+
+export function createAssistantOwnershipAttestationCommands({ installation }) {
+  return {
+    containers: createAttestationCommand("containers", installation),
+    networks: createAttestationCommand("networks", installation),
+    volumes: createAttestationCommand("volumes", installation),
+  };
+}
+
+function createExactResourceCommand(kind, names) {
+  const nameField = kind === "containers" ? ".Names" : ".Name";
+  const format = " --format '{{" + nameField + "}}|{{.Label \"" + INSTALL_ID_LABEL +
+    "\"}}|{{.Label \"" + MANAGED_LABEL + "\"}}'";
+  if (kind === "containers") {
+    return names.containers.map(
+      (name) => "docker container ls -a --filter \"name=" + name + "\"" + format,
+    ).join(" && ");
+  }
+  if (kind === "network") {
+    return "docker network ls --filter \"name=" + names.network + "\"" + format;
+  }
+  return "docker volume ls --filter \"name=" + names.volume + "\"" + format;
+}
+
+export function createAssistantExactResourceAttestationCommands({ installation }) {
+  const names = getAssistantManagedResourceNames(installation);
+  return {
+    containers: createExactResourceCommand("containers", names),
+    network: createExactResourceCommand("network", names),
+    volume: createExactResourceCommand("volume", names),
+  };
+}
+
+export function createAssistantNetworkCollisionCommand({ networkName, installation }) {
+  const safeNetworkName = validateDockerName(networkName);
+  validateAssistantInstallation(installation);
+  return "ids=$(docker network inspect " + safeNetworkName +
+    " --format '{{range $id, $_ := .Containers}}{{$id}}{{\"\\n\"}}{{end}}') && " +
+    "if [ -n \"$ids\" ]; then printf '%s\\n' \"$ids\" | xargs -r docker inspect --format '{{.Id}}|{{index .Config.Labels \"" +
+    INSTALL_ID_LABEL + "\"}}|{{with index .NetworkSettings.Networks \"" +
+    safeNetworkName + "\"}}{{join .Aliases \",\"}}{{end}}'; fi";
+}
+
+export function getAssistantLabels(installation) {
+  const safeInstallation = validateAssistantInstallation(installation);
+  return {
+    [MANAGED_LABEL]: EXPECTED_MANAGED_LABEL_VALUE,
+    [INSTALL_ID_LABEL]: safeInstallation.installId,
+  };
+}
+
+export function assertAssistantOnlyCommands({
+  commands,
+  installation,
+  networkName,
+  startupScope = "all",
+  cleanupScope = "project",
+}) {
+  if (!Array.isArray(commands) || commands.length === 0) {
+    throw new TypeError("An AI Assistant command list is required.");
+  }
+  const allowed = new Set([
+    ASSISTANT_PRECHECK_COMMAND,
+    createAssistantNetworkCollisionCommand({ networkName, installation }),
+    ...Object.values(createAssistantOwnershipAttestationCommands({ installation })),
+    ...Object.values(createAssistantExactResourceAttestationCommands({ installation })),
+    ...createAssistantDeploymentCommands({ installation, startupScope }),
+    ...Object.values(createAssistantVerificationCommands({ installation, cleanupScope })),
+  ]);
+  for (const command of commands) {
+    if (typeof command !== "string" || !allowed.has(command)) {
+      throw new Error(
+        "Command rejected: only the managed AI Assistant companion may be changed; n8n must remain untouched.",
+      );
+    }
+  }
+  return commands;
+}

package/src/domain/safety.js

@@ -2,11 +2,14 @@ export const INSTALL_ROOT = "/docker/n8n-openai-oauth";
 export const PROJECT_NAME = "n8n-openai-oauth";
 export const SERVICE_NAME = "openai-oauth";
 export const MANAGED_MARKER_PATH = `${INSTALL_ROOT}/.managed-by-n8n-openai-oauth`;
+export const SHARED_ROOT_MARKER_PATH = `${INSTALL_ROOT}/.managed-by-relmio-root`;
+export const SHARED_ROOT_MARKER_CONTENT = "relmio-managed-root:v1\n";
+export const SIDECAR_MARKER_CONTENT = "Managed by n8n-openai-oauth-setup.\n";
 
 const COMPOSE_PREFIX =
   "docker compose --project-name n8n-openai-oauth --file /docker/n8n-openai-oauth/docker-compose.yml";
 
-export const PRECHECK_COMMAND = `if [ -e ${INSTALL_ROOT} ]; then if [ -f ${MANAGED_MARKER_PATH} ]; then printf '%s\\n' managed; else exit 42; fi; else printf '%s\\n' new; fi`;
+export const PRECHECK_COMMAND = `if [ -e ${INSTALL_ROOT} ]; then if [ -L ${INSTALL_ROOT} ] || [ ! -d ${INSTALL_ROOT} ] || [ -L ${SHARED_ROOT_MARKER_PATH} ] || [ -L ${MANAGED_MARKER_PATH} ]; then exit 43; elif [ -e ${SHARED_ROOT_MARKER_PATH} ]; then if [ ! -f ${SHARED_ROOT_MARKER_PATH} ] || [ "$(cat ${SHARED_ROOT_MARKER_PATH})" != "${SHARED_ROOT_MARKER_CONTENT.trim()}" ]; then exit 42; elif [ -e ${MANAGED_MARKER_PATH} ]; then if [ ! -f ${MANAGED_MARKER_PATH} ] || [ "$(cat ${MANAGED_MARKER_PATH})" != "${SIDECAR_MARKER_CONTENT.trim()}" ]; then exit 42; else printf '%s\\n' managed; fi; else printf '%s\\n' new; fi; elif [ -f ${MANAGED_MARKER_PATH} ] && [ "$(cat ${MANAGED_MARKER_PATH})" = "${SIDECAR_MARKER_CONTENT.trim()}" ]; then printf '%s\\n' managed; else exit 42; fi; else printf '%s\\n' new; fi`;
 
 const DEPLOYMENT_COMMANDS = Object.freeze([
   `install -d -m 0755 ${INSTALL_ROOT}`,