relmio 0.5.0 → 0.7.0

package/docs/security.md

@@ -6,6 +6,16 @@ key, a Codex/ChatGPT session, and generated local capabilities. Treat every one
 of these values as password-equivalent. Read this page before offering the
 wizard to another person.
 
+## ChatGPT/Codex sign-in lifetime
+
+ChatGPT/Codex sign-in tokens expire, but the official Codex client refreshes
+them automatically during active use before they expire, so active sessions
+usually continue without another browser login. The official [OpenAI
+authentication documentation](https://learn.chatgpt.com/docs/auth) does not
+publish a fixed 10-day lifetime; do not plan around one. This provider
+credential is separate from Relmio's local capability, which remains valid
+until you rotate it.
+
 ## Trust model
 
 The design assumes:
@@ -26,12 +36,19 @@ For a local Docker endpoint, the design additionally assumes:
   by the same person;
 - a browser origin allowlist is not being used as a substitute for secret
   storage; and
-- a Codex client is trusted with App Server's broad agent and account surface.
+- a raw Codex client is trusted with App Server's broad agent and account
+  surface, while the Chat Adapter bearer is held only by a trusted local
+  backend or development server.
 
 The raw Codex App Server is not a multi-user boundary. It is for a trusted
 native client owned by the same account holder, not a browser, shared service,
 public app, or untrusted plugin.
 
+The Codex Chat Adapter is a separate, narrower contract. It is for a trusted
+local backend or development server owned by the same account holder. Browser
+JavaScript must not call it directly, and it is not for a remote, hosted,
+shared, or production service.
+
 ## Controls implemented by the wizard
 
 - The web server binds only to `127.0.0.1`.
@@ -62,11 +79,12 @@ public app, or untrusted plugin.
 
 - Generated Compose files publish only literal
   `127.0.0.1:<selected-port>:<container-port>` mappings.
-- Every OpenAI `/v1` operation that can reach OpenAI and every Codex WebSocket
-  upgrade requires a random Relmio capability displayed once by the wizard;
-  only its SHA-256 verifier is persisted. Exact-origin CORS `OPTIONS` is a
-  non-forwarding metadata exception. The bearer remains valid until an
-  endpoint update rotates it.
+- Every OpenAI `/v1` operation that can reach OpenAI, every raw Codex WebSocket
+  upgrade, and every Codex Chat Adapter route except `GET /health` requires a
+  random Relmio capability displayed once by the wizard; only its SHA-256
+  verifier is persisted. Exact-origin CORS `OPTIONS` is a non-forwarding
+  exception only for the Platform-backed `/v1` gateway. The bearer remains
+  valid until an endpoint update rotates it.
 - The Platform API key is accepted only for the OpenAI gateway. A transient,
   network-disabled helper receives it over stdin and atomically seeds a private,
   labeled Docker volume that the gateway mounts read-only. No host key file or
@@ -77,9 +95,16 @@ public app, or untrusted plugin.
 - Browser requests to the OpenAI gateway require an exact configured `http`
   or `https` origin. Wildcards and `null` are rejected; requests without an
   `Origin` remain available to authenticated native clients and backends.
-- Codex receives private named credential and workspace volumes. No host
-  directory, Docker socket, SSH key, browser profile, or home directory is
-  mounted into either local service.
+- The Chat Adapter rejects every request carrying an `Origin` header, emits no
+  CORS permission, and exposes only its authenticated Relmio-specific
+  `POST /chat` contract plus readiness and credential-verification probes.
+- Each Codex target receives its own private named credential and workspace
+  volumes. No long-running local endpoint service mounts a host directory,
+  Docker socket, SSH key, browser profile, or host home directory.
+- Chat Adapter turns use a named read-only permission profile with network
+  disabled. Its model-visible filesystem policy denies root by default, allows
+  only Codex's minimal runtime paths and the empty private workspace, and
+  explicitly denies the persisted Codex credential store.
 - Local managed paths use mode `0700`, generated files use owner-only modes,
   symlinks are rejected, and existing unmanaged directories are not
   overwritten.
@@ -89,7 +114,7 @@ public app, or untrusted plugin.
 - Each install uses a random Compose project identity. Containers, networks,
   and volumes must carry matching Relmio ownership labels before update,
   restart, recovery, or sign-in actions are allowed.
-- Both long-running endpoint containers run as a non-root user, drop Linux
+- All three long-running endpoint containers run as a non-root user, drop Linux
   capabilities, set `no-new-privileges`, use a read-only root filesystem, and
   have bounded temporary storage and resource limits.
 - The one-shot OpenAI credential seed helper is the narrow exception: it has no
@@ -97,6 +122,30 @@ public app, or untrusted plugin.
   resource limits; and uses root plus only `CHOWN` long enough to atomically
   make the stdin-seeded volume entry readable by the non-root gateway.
 
+### In-wizard Chat Adapter tester
+
+The Ready screen's Chat Adapter tester is a deliberately narrow convenience
+path, not a browser CORS exception. Its browser calls stay same-origin to the
+setup-token-protected wizard. Only the local wizard server calls the adapter,
+using a server-side `POST /chat` request without an `Origin` header.
+
+The tester accepts only a literal `http://127.0.0.1:PORT` base URL and appends
+`/chat` itself. It refuses `localhost`, IPv6, LAN/private/public addresses,
+credentials, query strings, fragments, redirects, malformed JSON, oversized
+payloads, excessive IDs/ciphertext, concurrent key use, and preview mode. The
+server bounds timeout and response size, validates the upstream shape, and
+returns only a conversation ID plus output with generic redacted errors.
+
+Before a test, the browser obtains an ephemeral RSA-OAEP SHA-256 public key
+from the local wizard, clears the credential input, and retains only ciphertext
+and key ID in page memory. The matching private key remains only in the local
+server's in-memory, time-limited, bounded session map and can be invalidated
+explicitly. Prompts and transcript are not persisted server-side.
+
+This is not encryption at rest or end-to-end encryption. It reduces accidental
+credential transit and storage exposure, but cannot protect a compromised
+browser, extension, or local machine.
+
 ## What “private” means here
 
 Port `10531` is not reachable from the public internet or VPS host through a
@@ -126,11 +175,16 @@ The local capabilities have separate consequences:
 
 - The OpenAI gateway capability can spend through the protected Platform API
   key, subject to that Platform project's permissions and limits.
-- The Codex capability can invoke broad App Server methods inside the isolated
-  container and use its signed-in ChatGPT/Codex session.
+- The raw Codex App Server capability can invoke broad App Server methods
+  inside its isolated container and use its signed-in ChatGPT/Codex session.
+- The separate Chat Adapter bearer can submit chat turns and resume its bounded
+  conversation threads through the signed-in Codex container. Its narrower
+  HTTP surface and model permission profile reduce access, but do not make the
+  bearer safe to expose or share.
 - An origin allowlist does not make a bearer embedded in browser JavaScript
-  private. Use browser access only for private same-owner local development.
-- Do not expose either endpoint on a LAN, public IP, domain, reverse proxy, or
+  private. The Chat Adapter rejects browser origins entirely; keep its bearer
+  in a trusted local backend or development server.
+- Do not expose any local endpoint on a LAN, public IP, domain, reverse proxy, or
   hosted service. Loopback binding and the bearer capability are both required.
 - If a capability is disclosed, update the endpoint to rotate it. If an
   upstream credential may be exposed, revoke or sign out through the provider
@@ -152,12 +206,17 @@ The local capabilities have separate consequences:
   is billed or credited to the associated Platform project; a ChatGPT
   subscription or Codex for Open Source benefit is not substituted for API
   billing.
-- The local Codex option preserves the official App Server JSON-RPC protocol.
+- The raw local Codex option preserves the official App Server JSON-RPC protocol.
   It does not provide `/v1/chat/completions`, `/v1/responses`, or any other
   OpenAI API compatibility route.
 - OpenAI documents App Server WebSocket transport as experimental and
   unsupported for production. It rejects browser-origin requests and is
   limited here to trusted native same-owner clients.
+- The Codex Chat Adapter uses the official App Server lifecycle internally but
+  exposes only Relmio's experimental `POST /chat` contract. It is not
+  `/v1/chat/completions`, `/v1/responses`, or an OpenAI SDK replacement; it
+  rejects browser origins and is limited to trusted local backends or
+  development servers.
 - Acceptance into Codex for Open Source is not treated by Relmio as permission
   to repurpose credentials, share an account, bypass controls, or broaden the
   scope of another agreement. Review the current

package/docs/troubleshooting.md

@@ -9,6 +9,39 @@ wizard or any manual VPS command. The documented commands are sidecar-only and
 do not delete, restart, or rebuild n8n, but they still access your VPS and write
 files there.
 
+## Docker is not running
+
+Start Docker Desktop or Docker Engine and wait until `docker info` and
+`docker compose version` both succeed. Close any stale Relmio wizard tab, start
+one fresh wizard session, and review the local plan again. Do not restart or
+rebuild unrelated containers while checking the local endpoint.
+
+## Authentication fails
+
+Close stale wizard and device-code tabs, keep the newest Relmio terminal open,
+and use only the complete wizard URL printed by that active process. Start one
+fresh ChatGPT device-code attempt and complete the newest code. A ChatGPT
+subscription credential is valid only for the Codex targets; the generic
+OpenAI-compatible `/v1` target requires a separately billed Platform API key.
+ChatGPT/Codex sign-in tokens expire, but the official Codex client refreshes
+them automatically during active use before they expire, so active sessions
+usually continue without another browser login. The official [OpenAI
+authentication documentation](https://learn.chatgpt.com/docs/auth) does not
+publish a fixed 10-day lifetime; do not plan around one. This provider
+credential is separate from Relmio's local capability, which remains valid
+until you rotate it. If Relmio reports the credential is invalid or refresh no
+longer succeeds, select **Start ChatGPT sign-in** again in the active local
+wizard. The VPS sidecar flow labels that action **Refresh ChatGPT sign-in**.
+
+## Local image build failed
+
+The local wizard intentionally does not show Docker build output, filesystem
+paths, or stderr in the browser. Confirm Docker Desktop or Docker Engine is
+running, check that the local disk has room for the image, and confirm your
+network can reach the image registry. Then close the old wizard, start one new
+wizard session, review a fresh plan, and retry. Do not delete an existing
+managed endpoint or rebuild unrelated containers as a workaround.
+
 ## Hosted chat browser extension
 
 The hosted demo at [relmio.vercel.app](https://relmio.vercel.app/) needs the

package/docs/vps-and-n8n.md

@@ -0,0 +1,30 @@
+# VPS and n8n
+
+Relmio installs a separate sidecar project at
+`/docker/n8n-openai-oauth`. It does not edit, rebuild, recreate, stop, or
+restart your existing n8n Compose project or image. The sidecar has no host
+port: n8n reaches it over the shared Docker network at
+`http://n8n-openai-oauth:10531/v1`.
+
+## Wizard route
+
+1. Run the local wizard and complete the fresh ChatGPT sign-in on your own
+   computer.
+2. Enter your VPS address and compare the presented SSH host fingerprint with
+   your provider before authorizing password authentication.
+3. Select an already-running n8n container and one of its existing shared
+   networks.
+4. Review the exact plan. Remote writes begin only after final confirmation.
+5. In n8n, use the private sidecar hostname rather than `127.0.0.1`.
+
+The n8n credential's required API-key field uses `local-only` only as a UI
+placeholder; it is not an OpenAI Platform API key.
+
+## Follow-on guides
+
+- [Configure n8n nodes](./n8n-configuration.md) has copy-ready AI Agent and
+  HTTP Request recipes.
+- [Beginner manual installation](./manual-install.md) is the auditable fallback
+  when the wizard cannot be used.
+- [Troubleshooting](./troubleshooting.md) includes connection, Docker-network,
+  and browser sign-in recovery steps.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "relmio",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Install private local OpenAI API and Codex endpoints with explicit provider credential boundaries, plus the existing isolated n8n sidecar.",
   "keywords": [
     "relmio",

package/src/domain/local-endpoints.js

@@ -1,6 +1,8 @@
 import { validatePort } from "./validation.js";
+import packageManifest from "../../package.json" with { type: "json" };
 
 export const CODEX_CLI_VERSION = "0.147.0";
+const PACKAGE_VERSION = packageManifest.version;
 
 export const LOCAL_TARGETS = Object.freeze({
   "openai-api": Object.freeze({
@@ -19,6 +21,14 @@ export const LOCAL_TARGETS = Object.freeze({
     experimental: true,
     containerPort: 4_500,
   }),
+  "codex-chat": Object.freeze({
+    label: "Codex Chat Adapter",
+    protocol: "relmio-codex-chat-http",
+    upstreamAuth: "chatgpt-via-codex",
+    browserClients: false,
+    experimental: true,
+    containerPort: 14_501,
+  }),
 });
 
 export function validateLocalTarget(value) {
@@ -114,7 +124,9 @@ export function createLocalDeploymentPlan({
   const endpoint =
     safeTarget === "openai-api"
       ? `http://127.0.0.1:${safePort}/v1`
-      : `ws://127.0.0.1:${safePort}`;
+      : safeTarget === "codex-chatgpt"
+        ? `ws://127.0.0.1:${safePort}`
+        : `http://127.0.0.1:${safePort}`;
 
   return {
     target: safeTarget,
@@ -145,8 +157,11 @@ ENTRYPOINT ["node", "/app/gateway.mjs"]
 
 export function createLocalDockerignore(target) {
   const safeTarget = validateLocalTarget(target);
-  return safeTarget === "openai-api"
-    ? "**\n!Dockerfile\n!gateway.mjs\n"
+  if (safeTarget === "openai-api") {
+    return "**\n!Dockerfile\n!gateway.mjs\n";
+  }
+  return safeTarget === "codex-chat"
+    ? "**\n!Dockerfile\n!gateway.mjs\n!config.toml\n!requirements.toml\n"
     : "**\n!Dockerfile\n!config.toml\n!requirements.toml\n";
 }
 
@@ -265,13 +280,29 @@ volumes:
 `;
 }
 
-export function createCodexConfig() {
-  return `approval_policy = "on-request"
+function renderCodexConfig({
+  approvalPolicy,
+  permissionProfile,
+  permissionProfileBase,
+  protectCredentialStore = false,
+}) {
+  const filesystemPermissions = protectCredentialStore
+    ? `
+[permissions.${permissionProfile}.filesystem]
+":root" = "deny"
+":minimal" = "read"
+":tmpdir" = "deny"
+":slash_tmp" = "deny"
+"/workspace" = "read"
+"/home/node/.codex" = "deny"
+`
+    : "";
+  return `approval_policy = "${approvalPolicy}"
 approvals_reviewer = "user"
 allow_login_shell = false
 check_for_update_on_startup = false
 cli_auth_credentials_store = "file"
-default_permissions = "relmio-workspace"
+default_permissions = "${permissionProfile}"
 forced_login_method = "chatgpt"
 web_search = "disabled"
 
@@ -281,10 +312,11 @@ enabled = false
 [feedback]
 enabled = false
 
-[permissions.relmio-workspace]
-extends = ":workspace"
+[permissions.${permissionProfile}]
+extends = "${permissionProfileBase}"
+${filesystemPermissions}
 
-[permissions.relmio-workspace.network]
+[permissions.${permissionProfile}.network]
 enabled = false
 
 [shell_environment_policy]
@@ -315,8 +347,25 @@ tool_suggest = false
 `;
 }
 
-export function createCodexRequirements() {
-  return `allowed_approval_policies = ["on-request"]
+export function createCodexConfig() {
+  return renderCodexConfig({
+    approvalPolicy: "on-request",
+    permissionProfile: "relmio-workspace",
+    permissionProfileBase: ":workspace",
+  });
+}
+
+export function createCodexChatConfig() {
+  return renderCodexConfig({
+    approvalPolicy: "never",
+    permissionProfile: "relmio-chat-readonly",
+    permissionProfileBase: ":read-only",
+    protectCredentialStore: true,
+  });
+}
+
+function renderCodexRequirements({ approvalPolicy, permissionProfile }) {
+  return `allowed_approval_policies = ["${approvalPolicy}"]
 allowed_approvals_reviewers = ["user"]
 allowed_login_methods = ["chatgpt"]
 allowed_web_search_modes = ["disabled"]
@@ -324,10 +373,10 @@ allow_managed_hooks_only = true
 allow_remote_control = false
 check_for_update_on_startup = false
 allow_login_shell = false
-default_permissions = "relmio-workspace"
+default_permissions = "${permissionProfile}"
 
 [allowed_permission_profiles]
-"relmio-workspace" = true
+"${permissionProfile}" = true
 
 [feedback]
 enabled = false
@@ -356,6 +405,20 @@ tool_suggest = false
 `;
 }
 
+export function createCodexRequirements() {
+  return renderCodexRequirements({
+    approvalPolicy: "on-request",
+    permissionProfile: "relmio-workspace",
+  });
+}
+
+export function createCodexChatRequirements() {
+  return renderCodexRequirements({
+    approvalPolicy: "never",
+    permissionProfile: "relmio-chat-readonly",
+  });
+}
+
 export function createCodexDockerfile() {
   return `FROM node:22-bookworm-slim
 
@@ -378,6 +441,113 @@ ENTRYPOINT ["codex"]
 `;
 }
 
+export function createCodexChatDockerfile() {
+  return `FROM node:22-bookworm-slim
+
+WORKDIR /app
+
+RUN apt-get update \\
+    && apt-get install --no-install-recommends -y ca-certificates \\
+    && rm -rf /var/lib/apt/lists/* \\
+    && npm install --global --ignore-scripts @openai/codex@${CODEX_CLI_VERSION} \\
+    && npm cache clean --force \\
+    && mkdir -p /etc/codex /home/node/.codex /workspace \\
+    && chown -R node:node /home/node/.codex /workspace
+
+COPY --chmod=0444 requirements.toml /etc/codex/requirements.toml
+COPY --chown=node:node config.toml /home/node/.codex/config.toml
+COPY --chown=node:node gateway.mjs /app/gateway.mjs
+
+ENV CODEX_HOME=/home/node/.codex
+WORKDIR /workspace
+USER node
+
+ENTRYPOINT ["node", "/app/gateway.mjs"]
+`;
+}
+
+export function createCodexChatComposeFile({ port, tokenSha256, installId }) {
+  const safePort = validateLocalPort(port);
+  const safeVerifier = validateSha256Verifier(tokenSha256);
+  const safeInstallId = validateInstallId(installId);
+  const gatewayImage = `relmio-codex-chat-${safeInstallId}:local`;
+
+  return `services:
+  codex-chat:
+    image: ${gatewayImage}
+    build:
+      context: .
+      dockerfile: Dockerfile
+    restart: unless-stopped
+    init: true
+    environment:
+      RELMIO_GATEWAY_TOKEN_SHA256: ${safeVerifier}
+      RELMIO_GATEWAY_HOST: 0.0.0.0
+      RELMIO_GATEWAY_PORT: "14501"
+      RELMIO_PACKAGE_VERSION: "${PACKAGE_VERSION}"
+    ports:
+      - "127.0.0.1:${safePort}:14501"
+    volumes:
+      - codex-home:/home/node/.codex
+      - codex-workspace:/workspace
+    security_opt:
+      - no-new-privileges:true
+    cap_drop:
+      - ALL
+    read_only: true
+    tmpfs:
+      - /tmp:size=64m,mode=1777,nodev,nosuid
+      - /run:size=16m,mode=0755,nodev,nosuid
+      - /home/node/.cache:uid=1000,gid=1000,mode=0700,nodev,nosuid
+    pids_limit: 128
+    mem_limit: 2g
+    cpus: 2.0
+    ulimits:
+      nofile:
+        soft: 1024
+        hard: 1024
+      core: 0
+    logging:
+      driver: json-file
+      options:
+        max-size: 10m
+        max-file: "3"
+    healthcheck:
+      test:
+        - CMD
+        - node
+        - -e
+        - 'fetch("http://127.0.0.1:14501/health").then((response) => process.exit(response.ok ? 0 : 1)).catch(() => process.exit(1))'
+      interval: 10s
+      timeout: 5s
+      retries: 9
+      start_period: 20s
+    labels:
+      io.relmio.managed: "true"
+      io.relmio.target: "codex-chat"
+      io.relmio.install: "${safeInstallId}"
+
+networks:
+  default:
+    labels:
+      io.relmio.managed: "true"
+      io.relmio.target: "codex-chat"
+      io.relmio.install: "${safeInstallId}"
+
+volumes:
+  codex-home:
+    labels:
+      io.relmio.managed: "true"
+      io.relmio.target: "codex-chat"
+      io.relmio.install: "${safeInstallId}"
+  codex-workspace:
+    labels:
+      io.relmio.managed: "true"
+      io.relmio.target: "codex-chat"
+      io.relmio.install: "${safeInstallId}"
+`;
+}
+
 export function createCodexComposeFile({ port, tokenSha256, installId }) {
   const safePort = validateLocalPort(port);
   const safeVerifier = validateSha256Verifier(tokenSha256);