relmio 0.2.0

package/scripts/preview.js

@@ -0,0 +1,69 @@
+import { randomBytes } from "node:crypto";
+
+import { startWizardServer } from "../src/web/server.js";
+
+const remote = {
+  close() {},
+};
+const previewCredentialUpdatedAt = new Date().toISOString();
+
+const services = {
+  async getAuthStatus() {
+    return {
+      exists: true,
+      path: "/preview/auth.json",
+      updatedAt: previewCredentialUpdatedAt,
+    };
+  },
+  async readAuthContents() {
+    return Buffer.from('{"preview":true}');
+  },
+  async scanHostFingerprint() {
+    return "SHA256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa";
+  },
+  async connectVerified() {
+    return remote;
+  },
+  async discoverN8n() {
+    return {
+      dockerVersion: "28.3.2",
+      composeVersion: "2.38.2",
+      containers: [
+        {
+          id: "preview",
+          image: "docker.n8n.io/n8nio/n8n",
+          name: "n8n-n8n-1",
+          state: "running",
+        },
+      ],
+    };
+  },
+  async discoverNetworks() {
+    return { networks: ["proxy"], recommended: "proxy" };
+  },
+  async installSidecar() {
+    return {
+      baseUrl: "http://n8n-openai-oauth:10531/v1",
+      apiKeyPlaceholder: "local-only",
+      useResponsesApi: true,
+      models: ["gpt-5.6-sol", "gpt-5.6-terra"],
+      deploymentMode: "created",
+    };
+  },
+};
+
+const sessionToken = randomBytes(32).toString("base64url");
+const wizard = await startWizardServer({
+  sessionToken,
+  services,
+  previewMode: true,
+});
+
+console.log(`${wizard.origin}/?session=${sessionToken}`);
+console.log(
+  "Sanitized preview data only; live ChatGPT sign-in is disabled. Press Control+C to stop.",
+);
+
+process.once("SIGINT", async () => {
+  await wizard.close();
+});

package/src/cli.js

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+
+import { randomBytes } from "node:crypto";
+import { spawn } from "node:child_process";
+
+import { startWizardServer } from "./web/server.js";
+
+function openBrowser(url) {
+  const command =
+    process.platform === "darwin"
+      ? { file: "open", args: [url] }
+      : process.platform === "win32"
+        ? { file: "explorer.exe", args: [url] }
+        : { file: "xdg-open", args: [url] };
+
+  const child = spawn(command.file, command.args, {
+    detached: true,
+    stdio: "ignore",
+    shell: false,
+  });
+  child.once("error", () => {
+    // The URL is also printed, so users can open it manually.
+  });
+  child.unref();
+}
+
+const sessionToken = randomBytes(32).toString("base64url");
+const wizard = await startWizardServer({ sessionToken });
+const url = `${wizard.origin}/?session=${sessionToken}`;
+
+console.log("");
+console.log("Relmio");
+console.log("---------");
+console.log(`Local wizard: ${url}`);
+console.log("");
+console.log("This creates a separate sidecar and never restarts n8n.");
+console.log("Keep this Terminal window open while using the wizard.");
+console.log("Press Control+C to stop.");
+console.log("");
+
+openBrowser(url);
+
+let closing = false;
+async function close() {
+  if (closing) {
+    return;
+  }
+  closing = true;
+  await wizard.close();
+}
+
+process.once("SIGINT", async () => {
+  await close();
+});
+process.once("SIGTERM", async () => {
+  await close();
+});

package/src/domain/safety.js

@@ -0,0 +1,59 @@
+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`;
+
+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`;
+
+const DEPLOYMENT_COMMANDS = Object.freeze([
+  `install -d -m 0755 ${INSTALL_ROOT}`,
+  `install -d -m 0700 -o 1000 -g 1000 ${INSTALL_ROOT}/auth`,
+  `chown 1000:1000 ${INSTALL_ROOT}/auth/auth.json`,
+  `chmod 600 ${INSTALL_ROOT}/auth/auth.json`,
+  `${COMPOSE_PREFIX} config --quiet`,
+  `${COMPOSE_PREFIX} build ${SERVICE_NAME}`,
+  `${COMPOSE_PREFIX} up -d --wait --wait-timeout 60 --no-deps ${SERVICE_NAME}`,
+]);
+
+const VERIFICATION_COMMANDS = Object.freeze({
+  runningService: `${COMPOSE_PREFIX} ps --status running --services`,
+  publicationState: `${COMPOSE_PREFIX} ps --format json ${SERVICE_NAME}`,
+  models: `${COMPOSE_PREFIX} exec -T ${SERVICE_NAME} node -e 'fetch("http://127.0.0.1:10531/v1/models").then(async (response) => { console.log(await response.text()); process.exit(response.ok ? 0 : 1); }).catch(() => process.exit(1))'`,
+  cleanup: `${COMPOSE_PREFIX} rm --force --stop ${SERVICE_NAME}`,
+});
+
+const ALLOWED_SIDECAR_COMMANDS = new Set([
+  PRECHECK_COMMAND,
+  ...DEPLOYMENT_COMMANDS,
+  ...Object.values(VERIFICATION_COMMANDS),
+]);
+
+export function createDeploymentCommands() {
+  return [...DEPLOYMENT_COMMANDS];
+}
+
+export function createVerificationCommands() {
+  return { ...VERIFICATION_COMMANDS };
+}
+
+export function assertSidecarOnlyCommands(commands) {
+  if (!Array.isArray(commands) || commands.length === 0) {
+    throw new TypeError("A sidecar command list is required.");
+  }
+
+  for (const command of commands) {
+    if (
+      typeof command !== "string" ||
+      !ALLOWED_SIDECAR_COMMANDS.has(command)
+    ) {
+      throw new Error(
+        "Command rejected: only the installer-managed sidecar may be changed; n8n must remain untouched.",
+      );
+    }
+  }
+
+  return commands;
+}

package/src/domain/templates.js

@@ -0,0 +1,65 @@
+import { validateDockerName } from "./validation.js";
+
+export const SIDECAR_HOSTNAME = "n8n-openai-oauth";
+
+export function createDockerfile() {
+  return `FROM node:22-bookworm-slim
+
+RUN npm install --global --ignore-scripts openai-oauth@2.0.0 \\
+    && npm cache clean --force
+
+USER node
+
+ENTRYPOINT ["openai-oauth"]
+CMD ["--host", "0.0.0.0", "--port", "10531", "--oauth-file", "/home/node/.codex/auth.json"]
+`;
+}
+
+export function createComposeFile({ networkName }) {
+  const safeNetworkName = validateDockerName(networkName);
+
+  return `services:
+  openai-oauth:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    restart: unless-stopped
+    init: true
+    volumes:
+      - ./auth:/home/node/.codex
+    expose:
+      - "10531"
+    networks:
+      n8n-shared:
+        aliases:
+          - ${SIDECAR_HOSTNAME}
+    security_opt:
+      - no-new-privileges:true
+    cap_drop:
+      - ALL
+    read_only: true
+    tmpfs:
+      - /tmp:size=16m,mode=1777
+      - /home/node/.local:uid=1000,gid=1000,mode=0700
+    pids_limit: 128
+    mem_limit: 512m
+    cpus: 1.0
+    healthcheck:
+      test:
+        - CMD
+        - node
+        - -e
+        - 'fetch("http://127.0.0.1:10531/health").then((response) => process.exit(response.ok ? 0 : 1)).catch(() => process.exit(1))'
+      interval: 30s
+      timeout: 5s
+      retries: 3
+      start_period: 20s
+    labels:
+      io.n8n-openai-oauth.managed: "true"
+
+networks:
+  n8n-shared:
+    external: true
+    name: ${safeNetworkName}
+`;
+}

package/src/domain/validation.js

@@ -0,0 +1,76 @@
+import { isIP } from "node:net";
+
+function requireString(value, label, maxLength) {
+  if (typeof value !== "string") {
+    throw new TypeError(`${label} is invalid.`);
+  }
+
+  const normalized = value.trim();
+  if (
+    normalized.length === 0 ||
+    normalized.length > maxLength ||
+    normalized.startsWith("--")
+  ) {
+    throw new TypeError(`${label} is invalid.`);
+  }
+
+  return normalized;
+}
+
+export function validateHostname(value) {
+  const hostname = requireString(value, "Hostname", 253);
+  if (isIP(hostname)) {
+    return hostname;
+  }
+  if (/^[0-9.]+$/.test(hostname)) {
+    throw new TypeError("Hostname is invalid.");
+  }
+
+  const labels = hostname.split(".");
+  const valid = labels.every(
+    (label) =>
+      label.length <= 63 &&
+      /^[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?$/.test(label),
+  );
+
+  if (!valid) {
+    throw new TypeError("Hostname is invalid.");
+  }
+
+  return hostname.toLowerCase();
+}
+
+export function validatePort(value) {
+  let port = value;
+  if (typeof value !== "number") {
+    const text = requireString(value, "Port", 5);
+    if (!/^\d{1,5}$/.test(text)) {
+      throw new TypeError("Port is invalid.");
+    }
+    port = Number(text);
+  }
+
+  if (!Number.isInteger(port) || port < 1 || port > 65_535) {
+    throw new TypeError("Port is invalid.");
+  }
+
+  return port;
+}
+
+export function validateUsername(value) {
+  const username = requireString(value, "Username", 32);
+  if (!/^[a-z_][a-z0-9_-]{0,31}$/i.test(username)) {
+    throw new TypeError("Username is invalid.");
+  }
+
+  return username;
+}
+
+export function validateDockerName(value) {
+  const name = requireString(value, "Docker name", 128);
+  if (!/^[a-zA-Z0-9][a-zA-Z0-9_.-]{0,127}$/.test(name)) {
+    throw new TypeError("Docker name is invalid.");
+  }
+
+  return name;
+}

package/src/infrastructure/ssh.js

@@ -0,0 +1,268 @@
+import { timingSafeEqual } from "node:crypto";
+import { posix as path } from "node:path";
+import ssh2 from "ssh2";
+
+import { INSTALL_ROOT } from "../domain/safety.js";
+import {
+  validateHostname,
+  validatePort,
+  validateUsername,
+} from "../domain/validation.js";
+
+const { Client } = ssh2;
+const MAX_COMMAND_OUTPUT_BYTES = 1_000_000;
+const FINGERPRINT_PATTERN = /^SHA256:[A-Za-z0-9+/]{43}$/u;
+
+function fingerprintsMatch(left, right) {
+  const leftBuffer = Buffer.from(left);
+  const rightBuffer = Buffer.from(right);
+  return (
+    leftBuffer.length === rightBuffer.length &&
+    timingSafeEqual(leftBuffer, rightBuffer)
+  );
+}
+
+function validateExpectedFingerprint(value) {
+  if (typeof value !== "string" || !FINGERPRINT_PATTERN.test(value)) {
+    throw new TypeError("SSH host fingerprint is invalid.");
+  }
+  return value;
+}
+
+function validatePassword(value) {
+  if (typeof value !== "string" || value.length === 0 || value.length > 1024) {
+    throw new TypeError("An SSH password or agent is required.");
+  }
+  return value;
+}
+
+function validateManagedPath(value) {
+  if (typeof value !== "string") {
+    throw new TypeError("Remote path is invalid.");
+  }
+
+  const normalized = path.normalize(value);
+  if (
+    normalized !== value ||
+    !normalized.startsWith(`${INSTALL_ROOT}/`) ||
+    normalized.includes("\0")
+  ) {
+    throw new TypeError("Remote path must stay inside the sidecar directory.");
+  }
+  return normalized;
+}
+
+export function formatSha256Fingerprint(hexDigest) {
+  if (
+    typeof hexDigest !== "string" ||
+    !/^[a-f0-9]{64}$/iu.test(hexDigest)
+  ) {
+    throw new TypeError("SSH fingerprint digest is invalid.");
+  }
+
+  const base64 = Buffer.from(hexDigest, "hex")
+    .toString("base64")
+    .replace(/=+$/u, "");
+  return `SHA256:${base64}`;
+}
+
+export function buildVerifiedConnectionConfig({
+  host,
+  port,
+  username,
+  password,
+  agent,
+  expectedFingerprint,
+}) {
+  const fingerprint = validateExpectedFingerprint(expectedFingerprint);
+  const auth =
+    typeof password === "string" && password.length > 0
+      ? { password: validatePassword(password) }
+      : typeof agent === "string" && agent.length > 0
+        ? { agent }
+        : null;
+
+  if (!auth) {
+    throw new TypeError("An SSH password or agent is required.");
+  }
+
+  return {
+    host: validateHostname(host),
+    port: validatePort(port),
+    username: validateUsername(username),
+    ...auth,
+    hostHash: "sha256",
+    hostVerifier(hexDigest) {
+      const actual = formatSha256Fingerprint(hexDigest);
+      return fingerprintsMatch(actual, fingerprint);
+    },
+    readyTimeout: 15_000,
+    keepaliveInterval: 10_000,
+    keepaliveCountMax: 3,
+    tryKeyboard: false,
+  };
+}
+
+class SshConnection {
+  constructor(client) {
+    this.client = client;
+    this.lastError = null;
+    client.on("error", (error) => {
+      this.lastError = error;
+    });
+  }
+
+  exec(command) {
+    if (typeof command !== "string" || command.length === 0) {
+      return Promise.reject(new TypeError("Remote command is invalid."));
+    }
+
+    return new Promise((resolve, reject) => {
+      this.client.exec(command, (error, stream) => {
+        if (error) {
+          reject(new Error("The VPS refused to start a remote command."));
+          return;
+        }
+
+        const stdout = [];
+        const stderr = [];
+        let byteCount = 0;
+        let settled = false;
+
+        const append = (target, chunk) => {
+          byteCount += chunk.length;
+          if (byteCount > MAX_COMMAND_OUTPUT_BYTES) {
+            settled = true;
+            stream.destroy();
+            reject(new Error("Remote command output exceeded the safety limit."));
+            return;
+          }
+          target.push(Buffer.from(chunk));
+        };
+
+        stream.on("data", (chunk) => {
+          if (!settled) {
+            append(stdout, chunk);
+          }
+        });
+        stream.stderr.on("data", (chunk) => {
+          if (!settled) {
+            append(stderr, chunk);
+          }
+        });
+        stream.once("error", () => {
+          if (!settled) {
+            settled = true;
+            reject(new Error("The SSH command stream failed."));
+          }
+        });
+        stream.once("close", (code) => {
+          if (!settled) {
+            settled = true;
+            resolve({
+              stdout: Buffer.concat(stdout).toString("utf8"),
+              stderr: Buffer.concat(stderr).toString("utf8"),
+              code: Number.isInteger(code) ? code : 1,
+            });
+          }
+        });
+      });
+    });
+  }
+
+  upload(remotePath, contents, mode = 0o600) {
+    const safePath = validateManagedPath(remotePath);
+    const data = Buffer.isBuffer(contents) ? contents : Buffer.from(contents);
+
+    return new Promise((resolve, reject) => {
+      this.client.sftp((sftpError, sftp) => {
+        if (sftpError) {
+          reject(new Error("The VPS did not allow an SFTP upload."));
+          return;
+        }
+
+        sftp.writeFile(safePath, data, { mode, flag: "w" }, (writeError) => {
+          sftp.end();
+          if (writeError) {
+            reject(new Error("The installer could not upload a sidecar file."));
+          } else {
+            resolve();
+          }
+        });
+      });
+    });
+  }
+
+  close() {
+    this.client.end();
+  }
+}
+
+export async function connectVerified(
+  options,
+  { createClient = () => new Client() } = {},
+) {
+  const config = buildVerifiedConnectionConfig(options);
+
+  return await new Promise((resolve, reject) => {
+    const client = createClient();
+    let settled = false;
+
+    client.once("ready", () => {
+      settled = true;
+      resolve(new SshConnection(client));
+    });
+    client.once("error", () => {
+      if (!settled) {
+        settled = true;
+        reject(
+          new Error(
+            "SSH connection failed. Check the address, password, firewall, and confirmed fingerprint.",
+          ),
+        );
+      }
+    });
+    client.connect(config);
+  });
+}
+
+export function scanHostFingerprint(
+  { host, port },
+  { createClient = () => new Client() } = {},
+) {
+  const safeHost = validateHostname(host);
+  const safePort = validatePort(port);
+
+  return new Promise((resolve, reject) => {
+    const client = createClient();
+    let settled = false;
+
+    client.once("error", () => {
+      if (!settled) {
+        settled = true;
+        reject(
+          new Error(
+            "The VPS did not answer on the SSH port. Check its IP address and firewall.",
+          ),
+        );
+      }
+    });
+
+    client.connect({
+      host: safeHost,
+      port: safePort,
+      username: "fingerprint-scan",
+      hostHash: "sha256",
+      hostVerifier(hexDigest) {
+        if (!settled) {
+          settled = true;
+          resolve(formatSha256Fingerprint(hexDigest));
+          queueMicrotask(() => client.end());
+        }
+        return false;
+      },
+      readyTimeout: 10_000,
+      tryKeyboard: false,
+    });
+  });
+}

package/src/services/discovery.js

@@ -0,0 +1,96 @@
+import { validateDockerName } from "../domain/validation.js";
+
+const DOCKER_VERSION_COMMAND =
+  "docker version --format '{{.Server.Version}}'";
+const COMPOSE_VERSION_COMMAND = "docker compose version --short";
+const RUNNING_CONTAINERS_COMMAND =
+  "docker ps --filter status=running --format '{{json .}}'";
+
+function isOfficialN8nImage(image) {
+  return /(?:^|\/)n8nio\/n8n(?:[:@]|$)/.test(image);
+}
+
+async function runReadOnly(remote, command, label) {
+  const result = await remote.exec(command);
+  if (result.code !== 0) {
+    throw new Error(`${label} failed. Check Docker access on the VPS.`);
+  }
+  return result.stdout.trim();
+}
+
+export function parseDockerPsOutput(output) {
+  if (typeof output !== "string" || output.trim() === "") {
+    return [];
+  }
+
+  try {
+    return output
+      .trim()
+      .split("\n")
+      .map((line) => JSON.parse(line))
+      .filter(
+        (container) =>
+          container.State === "running" &&
+          typeof container.Image === "string" &&
+          isOfficialN8nImage(container.Image),
+      )
+      .map((container) => ({
+        id: String(container.ID),
+        image: container.Image,
+        name: validateDockerName(container.Names),
+        state: container.State,
+      }));
+  } catch {
+    throw new Error(
+      "The installer could not understand Docker's container list.",
+    );
+  }
+}
+
+export async function discoverN8n(remote) {
+  const dockerVersion = await runReadOnly(
+    remote,
+    DOCKER_VERSION_COMMAND,
+    "Docker check",
+  );
+  const composeVersion = await runReadOnly(
+    remote,
+    COMPOSE_VERSION_COMMAND,
+    "Docker Compose check",
+  );
+  const containerOutput = await runReadOnly(
+    remote,
+    RUNNING_CONTAINERS_COMMAND,
+    "n8n discovery",
+  );
+
+  return {
+    dockerVersion,
+    composeVersion,
+    containers: parseDockerPsOutput(containerOutput),
+  };
+}
+
+export function createInspectNetworksCommand(containerName) {
+  const safeName = validateDockerName(containerName);
+  return `docker inspect ${safeName} --format '{{range $name, $_ := .NetworkSettings.Networks}}{{println $name}}{{end}}'`;
+}
+
+export async function discoverNetworks(remote, containerName) {
+  const command = createInspectNetworksCommand(containerName);
+  const output = await runReadOnly(remote, command, "Docker network discovery");
+  const networks = [
+    ...new Set(
+      output
+        .split("\n")
+        .map((name) => name.trim())
+        .filter(Boolean)
+        .map(validateDockerName),
+    ),
+  ];
+
+  return {
+    networks,
+    recommended: networks.includes("proxy") ? "proxy" : (networks[0] ?? null),
+  };
+}