remo-cli 2.2.0rc2__tar.gz → 2.2.0rc4__tar.gz

remo_cli-2.2.0rc4/.specify/feature.json

@@ -0,0 +1,3 @@
+{
+  "feature_directory": "specs/012-web-adopt-pairing"
+}

{remo_cli-2.2.0rc2 → remo_cli-2.2.0rc4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: remo-cli
-Version: 2.2.0rc2
+Version: 2.2.0rc4
 Summary: Remote development environment CLI
 License-Expression: MIT
 License-File: LICENSE

{remo_cli-2.2.0rc2 → remo_cli-2.2.0rc4}/docker/Dockerfile

@@ -60,8 +60,14 @@ WORKDIR /app
 #   curl           - AWS CLI/SSM plugin install below, and the container
 #                    healthcheck (compose.example.yml) at runtime
 #   unzip          - AWS CLI v2 install below
+#   gosu           - drops from root to the unprivileged `remo` user in the
+#                    entrypoint AFTER self-healing filesystem permissions
+#                    (see docker/entrypoint.sh). Unlike `su`, it stays PID 1
+#                    with correct signal semantics and adds no setuid-binary
+#                    surface. Packaged for both amd64 and arm64 in Debian, so
+#                    the multi-arch build is unaffected.
 RUN apt-get update && \
-    apt-get install -y --no-install-recommends openssh-client curl unzip && \
+    apt-get install -y --no-install-recommends openssh-client curl unzip gosu && \
     rm -rf /var/lib/apt/lists/*
 
 # Install AWS CLI v2 (needed for SSM proxy), arch-selected via $TARGETARCH.
@@ -85,10 +91,10 @@ RUN if [ "$TARGETARCH" = "arm64" ]; then SM_ARCH="arm64"; else SM_ARCH="64bit";
 # Non-root user (UID/GID 1000 to match compose.example.yml `user: "1000:1000"`).
 RUN useradd -u 1000 -m -s /bin/bash remo
 
-# Install remo-cli[web] system-wide (as root, before USER remo) from the
-# wheel built in stage 2 — avoids needing build tools in this final layer
-# and avoids `pip install --user` (so no PATH fix-up is needed; `remo` /
-# `remo web` land directly on the system PATH for the `remo` user).
+# Install remo-cli[web] system-wide (as root) from the wheel built in stage 2
+# — avoids needing build tools in this final layer and avoids `pip install
+# --user` (so no PATH fix-up is needed; `remo` / `remo web` land directly on
+# the system PATH for the `remo` user the entrypoint drops to).
 COPY --from=wheel-builder /build/wheels/*.whl /tmp/
 RUN pip install --no-cache-dir "$(ls /tmp/*.whl)[web]" && \
     rm /tmp/*.whl
@@ -118,6 +124,19 @@ ENV REMO_WEB_FRONTEND_DIST_DIR=/app/frontend-dist
 # default, FR-052), same as any other containerized service.
 ENV REMO_WEB_BIND_HOST=0.0.0.0
 
-USER remo
-
+# Pin HOME to the `remo` user's home so config-path resolution
+# (core/config.py `Path.home()` / REMO_HOME) is identical whether the
+# entrypoint is running its root-side healing pass or the dropped-to `remo`
+# process — otherwise root's ambient HOME (/root) would resolve the config
+# dir to a different path than the app later reads.
+ENV HOME=/home/remo
+
+# NOTE: intentionally NO `USER remo` here. The image starts as root so the
+# entrypoint can self-heal ownership on a bind-mounted, root-owned config dir
+# and on the /run/remo-ssh tmpfs (which a container *restart* remounts
+# root-owned) BEFORE dropping — via gosu — to the unprivileged `remo` user.
+# The app still ends up running as non-root `remo`; the drop just happens at
+# runtime in the entrypoint instead of at image-build time. A deployer that
+# sets an explicit `--user`/`user:` starts non-root, and the entrypoint skips
+# healing (best-effort) and execs directly. See docker/entrypoint.sh.
 ENTRYPOINT ["/app/docker/entrypoint.sh"]

{remo_cli-2.2.0rc2 → remo_cli-2.2.0rc4}/docker/compose.example.yml

@@ -139,10 +139,31 @@ services:
   #
   #       remo web adopt http://<docker-host>:8080
   #
-  #     which pushes your registry + instance host keys and authorizes the
-  #     service's OWN public key on each instance — your personal private key
-  #     never leaves the workstation. Later registry changes are re-pushed
-  #     with `remo web push`.
+  #     Open http://<docker-host>:8080 in a browser (through your forward-auth
+  #     proxy, see below), click "Copy pairing code", run the command above, and
+  #     paste the code when prompted. It pushes your registry + instance host
+  #     keys and authorizes the service's OWN public key on each instance — your
+  #     personal private key never leaves the workstation. Later registry changes
+  #     are re-pushed with `remo web push` (open the dashboard's "Pair CLI to
+  #     sync" affordance for a fresh code).
+  #
+  # Setup authorization (012-web-adopt-pairing): there is NO static token. The
+  # awaiting-adoption page mints a short-lived, single-use PAIRING CODE; the
+  # /api/v1/setup/* surface is dormant (404) unless a pairing session is live.
+  # Minting a code is gated by OPERATOR AUTHENTICATION:
+  #
+  #   - Recommended: put a forward-auth reverse proxy (Traefik ForwardAuth /
+  #     oauth2-proxy / Authelia / a hola app's SSO) in front. It must (a) gate
+  #     the browser-facing POST /api/v1/pairing/mint so only an authenticated
+  #     operator can mint, while (b) PASSING THROUGH /api/v1/setup/* unchanged
+  #     (the CLI cannot do SSO — it authenticates with the pairing code alone).
+  #     Set REMO_WEB_OPERATOR_AUTH=forward and REMO_WEB_FORWARD_AUTH_HEADER to
+  #     the trusted identity header your proxy injects (e.g. X-Forwarded-User).
+  #     The proxy MUST strip that header from inbound client requests.
+  #
+  #   - Loopback/dev only: REMO_WEB_OPERATOR_AUTH=none mints WITHOUT operator
+  #     auth (a loud, weaker posture surfaced in readiness). Use only when the
+  #     port is loopback-bound or otherwise network-restricted.
   #
   # This service carries `profiles: ["adopted"]` so a plain `docker compose
   # up` still starts only the bind-mount service above. Start this one with:
@@ -154,25 +175,29 @@ services:
     # above — the mode is chosen purely by what is mounted, not by the image.
     image: ghcr.io/get2knowio/remo-web:latest
     ports:
-      # Adoption traffic (the token-gated /api/v1/setup/* calls made by
-      # `remo web adopt`) arrives over this same port. Loopback-only means
-      # the workstation running the CLI must be the Docker host itself —
-      # otherwise bind a LAN IP here deliberately, or keep loopback and run
-      # `remo web adopt --via <docker-host>` to tunnel over SSH.
+      # Adoption traffic (the pairing-code-authenticated /api/v1/setup/* calls
+      # made by `remo web adopt`) arrives over this same port. Loopback-only
+      # means the workstation running the CLI must be the Docker host itself —
+      # otherwise bind a LAN IP here deliberately (behind your forward-auth
+      # proxy), or keep loopback and run `remo web adopt --via <docker-host>`
+      # to tunnel over SSH.
       - "127.0.0.1:8080:8080"
     environment:
-      # REQUIRED for adopted mode: while this is unset/empty the setup API
-      # does not exist at all (every /api/v1/setup/* request gets a plain
-      # 404), so adoption is impossible. Generate a strong random value,
-      # e.g.:
+      # Operator-authentication posture for pairing-code minting (see the notes
+      # above). Choose ONE:
+      #
+      #   Forward auth (recommended, behind an SSO proxy):
+      #     - "REMO_WEB_OPERATOR_AUTH=forward"
+      #     - "REMO_WEB_FORWARD_AUTH_HEADER=X-Forwarded-User"
+      #   (Enabling forward auth without a header name is a fail-fast error.)
       #
-      #   openssl rand -hex 24
+      #   Network-restricted (loopback/dev only — weaker, loudly logged):
+      - "REMO_WEB_OPERATOR_AUTH=none"
       #
-      # and pass the same value to the CLI via $REMO_API_TOKEN (or the
-      # interactive prompt) when running `remo web adopt`.
-      - "REMO_WEB_API_TOKEN=replace-me--generate-with--openssl-rand-hex-24"
+      # There is NO REMO_WEB_API_TOKEN anymore — a value set for it is ignored.
       # The REMO_WEB_ALLOWED_HOSTS / REMO_WEB_ALLOWED_ORIGINS notes on the
-      # service above apply here unchanged.
+      # service above apply here unchanged (the mint endpoint needs the page's
+      # Origin allowlisted; the default 127.0.0.1:8080 origin covers loopback).
     volumes:
       # A writable named state volume at REMO_HOME — the ONLY volume in this
       # mode (no registry mount, no ~/.ssh mounts; presence of those is what
@@ -182,23 +207,39 @@ services:
       # a NEW identity on next boot; it revokes nothing on the instances —
       # remove the old `remo-web@<deployment-id>` authorized_keys line there.
       - "remo-web-state:/home/remo/.config/remo"
-    # Identical hardening to the bind-mount service: adopted mode only moves
-    # WHERE configuration comes from, never loosens the runtime posture.
-    #
-    # The tmpfs mode is pinned because an option-less tmpfs mount is
-    # remounted root-owned 0755 (unwritable to uid 1000) by a container
-    # *restart* — `docker compose restart`, or the restart policy reviving
-    # the process — which would fail the startup runtime-dir check on every
-    # boot after the first. `rw,mode=1777` is exactly what Docker mounts on
-    # first boot anyway; pinning it just makes restarts behave the same.
+    # A PLAIN, option-less tmpfs — no `rw,mode=1777` pin needed anymore. The
+    # image starts as root and its entrypoint re-heals ownership on
+    # /run/remo-ssh on EVERY start, so the well-known Docker quirk (an
+    # option-less tmpfs is remounted root-owned 0755 by a container *restart*)
+    # no longer breaks the startup runtime-dir check on the second boot.
     tmpfs:
-      - "/run/remo-ssh:rw,mode=1777"
+      - "/run/remo-ssh"
     read_only: true
-    user: "1000:1000"
+    # NOTE: no `user:` pin here (unlike the bind-mount service above). This
+    # service starts as ROOT so the entrypoint can self-heal ownership on the
+    # state volume (Docker seeds a fresh named volume root-owned; a bind-mount
+    # host dir is root-owned too) before dropping — via gosu — to the
+    # unprivileged `remo` user. The app STILL runs as non-root `remo`; only
+    # the brief healing pass runs as root. See docker/entrypoint.sh.
     security_opt:
       - "no-new-privileges:true"
+    # Drop everything, then add back ONLY the capabilities the heal-then-drop
+    # entrypoint needs while it is root: CHOWN (fix ownership of the state
+    # dir/tmpfs), DAC_OVERRIDE (traverse/write a dir owned by another uid),
+    # FOWNER (defensive — chmod/utime on files owned by another uid),
+    # SETUID+SETGID (gosu drops to the `remo` uid).
+    # The dropped-to `remo` process holds NONE of these effectively — dropping
+    # uid clears the permitted/effective sets — so the security posture is
+    # unchanged from a plain non-root run; `no-new-privileges` does not block
+    # gosu (dropping privileges is always allowed).
     cap_drop:
       - "ALL"
+    cap_add:
+      - "CHOWN"
+      - "DAC_OVERRIDE"
+      - "FOWNER"
+      - "SETUID"
+      - "SETGID"
     healthcheck:
       # /api/v1/ready answers 200 for BOTH `ready` and `unconfigured` — a
       # container awaiting adoption is healthy and must not crash-loop or

remo_cli-2.2.0rc4/docker/entrypoint.sh

@@ -0,0 +1,88 @@
+#!/usr/bin/env bash
+# docker/entrypoint.sh
+#
+# Container entrypoint for `remo web` (010-web-session-interface, US4;
+# 011-web-adopt).
+#
+# Self-healing permissions model ("start as root, fix perms, drop
+# privileges"). The image starts as root (no `USER remo` in the Dockerfile)
+# so this script can, when it is UID 0, repair ownership on:
+#
+#   * the config dir ($REMO_HOME, default $HOME/.config/remo) — a deployer
+#     that BIND-MOUNTS this dir gets it owned root:root, so the non-root
+#     `remo` process could not create web-identity/ there (adopted mode,
+#     011-web-adopt) and would fail with EACCES on first boot. Docker seeds a
+#     fresh NAMED volume root-owned too, so the same fix covers that path.
+#   * the SSH ControlMaster runtime dir (/run/remo-ssh) — an option-less
+#     tmpfs is remounted root-owned 0755 (unwritable to `remo`) by a container
+#     RESTART, which otherwise fails the startup runtime-dir check on every
+#     boot after the first. Re-healing it on EVERY start makes restarts behave
+#     like the first boot without the deployer pinning `rw,mode=1777`.
+#
+# After healing, it drops to the unprivileged `remo` user via `gosu` and
+# re-execs itself; that second pass takes the non-root branch below (the gate
+# + serve). `gosu` keeps us as PID 1 with correct signal semantics (SIGTERM
+# reaches uvicorn for graceful shutdown) and, unlike a setuid `su`, adds no
+# privilege-escalation surface — compatible with `no-new-privileges:true`.
+#
+# Healing is BEST-EFFORT and never hard-fails startup: a read-only config
+# mount (mount-configured mode) legitimately cannot be chowned, and a deployer
+# may drop CAP_CHOWN. `remo web check` (below) is the real gate on whether the
+# resulting filesystem is actually usable. If the container is started with an
+# explicit non-root `--user`/`user:`, this script is never UID 0, so it skips
+# healing entirely and just runs the gate + serve.
+#
+# The `remo web check --skip-instance-checks` gate runs unguarded under
+# `set -e`: a non-zero exit from the CONFIG gate aborts before `exec remo web
+# serve`, so the container fails fast on genuinely bad config/mounts and never
+# starts serving. `--skip-instance-checks` is deliberate: the startup gate
+# validates only config/mounts/executables, NOT per-instance reachability. A
+# registered instance that is merely powered off or unreachable must NOT
+# prevent the whole service from starting (FR-006/US1); under `restart:
+# unless-stopped` (compose.example.yml), gating on reachability would
+# crash-loop the container whenever any single instance is down. Full
+# per-instance diagnostics remain available via `remo web check` (no flag),
+# and readiness is (correctly) config-only via GET /api/v1/ready.
+#
+# 011-web-adopt (SC-006): *unconfigured* is a PASSING state for this gate. A
+# fresh writable state volume with no registry/key material yet makes `remo
+# web check` report "awaiting adoption" and exit 0, so an adopted-mode
+# container boots cleanly (no crash loop) while it waits for adoption. Only
+# genuinely broken configuration still aborts here.
+
+set -euo pipefail
+
+# Target uid/gid to drop to. Defaults to the image's baked-in `remo` user
+# (1000:1000); override PUID/PGID for a bind-mount host whose directory owner
+# is some other uid/gid.
+PUID="${PUID:-1000}"
+PGID="${PGID:-1000}"
+
+# Paths that must be writable by the dropped-to user. CONFIG_DIR mirrors
+# core/config.py's REMO_HOME resolution; CONTROL_DIR mirrors
+# WebSettings.ssh_control_dir (REMO_WEB_SSH_CONTROL_DIR, default /run/remo-ssh).
+CONFIG_DIR="${REMO_HOME:-${HOME:-/home/remo}/.config/remo}"
+CONTROL_DIR="${REMO_WEB_SSH_CONTROL_DIR:-/run/remo-ssh}"
+
+if [ "$(id -u)" -eq 0 ]; then
+    # Root (the image default): self-heal, then drop. Every step is
+    # best-effort (`|| true`) so a read-only mount or a dropped CAP_CHOWN can
+    # never abort startup — `remo web check` below is the authority.
+    mkdir -p "$CONFIG_DIR" 2>/dev/null || true
+    mkdir -p "$CONTROL_DIR" 2>/dev/null || true
+    chown -R "$PUID:$PGID" "$CONFIG_DIR" 2>/dev/null || true
+    # chmod BEFORE chown so it runs while root still owns the tmpfs (no
+    # CAP_FOWNER needed). 1777 (sticky, world-writable) already lets the
+    # dropped-to user create control sockets, so the chown that follows is
+    # belt-and-suspenders — harmless if it can't change ownership.
+    chmod 1777 "$CONTROL_DIR" 2>/dev/null || true
+    chown "$PUID:$PGID" "$CONTROL_DIR" 2>/dev/null || true
+    # Re-exec this same script as the unprivileged user; the second pass falls
+    # through to the gate + serve below.
+    exec gosu "$PUID:$PGID" "$0" "$@"
+fi
+
+# Unprivileged: either dropped from root above, or started with an explicit
+# non-root `user:` (healing skipped, by design).
+remo web check --skip-instance-checks
+exec remo web serve

{remo_cli-2.2.0rc2 → remo_cli-2.2.0rc4}/docs/web-session-interface.md

@@ -180,30 +180,47 @@ instance — your own LAN, your own tailnet, or behind a reverse proxy you contr
 
 ### Reverse proxies, SSO, and the setup surface
 
-There is exactly one authenticated surface in the service: the **setup API** (`/api/v1/setup/*`) used
-by `remo web adopt`/`remo web push`, gated by a bearer token (`REMO_WEB_API_TOKEN` — see
-[CLI-to-web adoption](#cli-to-web-adoption)). Everything above about the *browser* surface remains
-true regardless of deployment mode:
-
-- **A reverse proxy without SSO does not change the trust model.** Putting the service behind a
-  TLS-terminating proxy (e.g. an hola app behind Traefik) encrypts the transport, but the dashboard
-  and terminals still have no login — the browser surface still needs proxy-level protection
-  (network boundary, allowlisted client IPs, or proxy auth) exactly as described above.
-- **A future forward-auth deployment needs a bypass rule scoped to `/api/v1/setup/*`.** The
-  workstation CLI authenticates with the `Authorization: Bearer` token, not with a browser SSO
-  session, so an SSO/forward-auth layer in front of the service would block adoption unless setup
-  routes are exempted from it. That bypass is defensible because the application itself enforces the
-  bearer token on every setup route — the surface is never unauthenticated. (Documentation-only
-  guidance; no proxy/SSO integration ships with the service.)
-- **Origin-less requests to the setup surface bypass the Origin allowlist — deliberately and
-  safely.** The Origin allowlist is a browser-CSRF defense, and the setup API is bearer-token-only
-  with no ambient credentials: a cross-origin browser request cannot attach an `Authorization`
-  header, and a genuine browser CSRF attempt always carries an `Origin` header — which is still
-  enforced (a present-but-disallowed `Origin` is rejected). This scoped exemption is what lets the
-  Origin-less CLI client reach the setup API, including `--via` tunnels whose
-  `127.0.0.1:<random-port>` origin could never be allowlisted. See the auth section of
-  [`setup-api.md`](../specs/011-web-adopt/contracts/setup-api.md) and the middleware in
-  `src/remo_cli/web/app.py`.
+> **Breaking change (012-web-adopt-pairing):** the static `REMO_WEB_API_TOKEN` gate is **removed**. A
+> value set for that variable is now ignored. Setup access is authorized by an **ephemeral pairing
+> code** minted from the awaiting-adoption page, not a long-lived secret.
+
+The setup API (`/api/v1/setup/*`) used by `remo web adopt`/`remo web push` is **dormant** — every
+route returns `404`, byte-identical to an unknown route — unless a **pairing session** is live. A
+session exists only while an operator is on the awaiting-adoption page (or the dashboard's re-sync
+affordance): opening the page mints a short-lived, single-use pairing code (sliding idle TTL, default
+15 min), the operator copies it to their workstation and pastes it into the CLI, and the code
+authenticates that one adoption/push. See [CLI-to-web adoption](#cli-to-web-adoption).
+
+Two properties make this safe:
+
+- **Minting a code is gated by operator authentication.** The browser-facing
+  `POST /api/v1/pairing/mint` endpoint only mints for an authenticated operator. v1 implements this
+  with **forward auth**: put a proxy (Traefik ForwardAuth / oauth2-proxy / Authelia / a hola app's
+  SSO) in front that terminates sign-on and injects a trusted identity header, and set
+  `REMO_WEB_OPERATOR_AUTH=forward` + `REMO_WEB_FORWARD_AUTH_HEADER=<that header>` (e.g.
+  `X-Forwarded-User`). Enabling forward auth without naming a header is a **fail-fast** startup error.
+  A loopback/dev deployment may instead set `REMO_WEB_OPERATOR_AUTH=none` (network-restricted — mints
+  without operator auth; a loud, weaker posture surfaced in readiness). The check sits behind a
+  pluggable provider seam so an in-app OIDC verifier can be added later.
+- **The proxy must split the two paths.** Forward auth applies **only** to `POST /api/v1/pairing/mint`
+  — the CLI cannot complete an SSO challenge, so the proxy MUST **pass `/api/v1/setup/*` through**
+  unauthenticated at the proxy layer; those routes are authenticated by the pairing code alone. In
+  short: gate `/api/v1/pairing/mint` with SSO, pass `/api/v1/setup/*` through.
+
+**Forward-auth trust boundary.** The service trusts the identity header only because the deployment
+guarantees the proxy sits in front and **sets/strips** that header — so a client cannot reach the app
+directly and spoof it. This is the standard forward-auth boundary; a deployment that exposes the app
+directly (no proxy) MUST use `REMO_WEB_OPERATOR_AUTH=none` and accept the weaker posture.
+
+**Origin-less requests to the setup surface bypass the Origin allowlist — deliberately and safely.**
+The Origin allowlist is a browser-CSRF defense, and the setup API carries no ambient credentials: a
+cross-origin browser request cannot attach an `Authorization` header, and a genuine browser CSRF
+attempt always carries an `Origin` (still enforced). This scoped exemption lets the Origin-less CLI
+reach the setup API, including `--via` tunnels whose `127.0.0.1:<random-port>` origin could never be
+allowlisted. The browser-only `POST /api/v1/pairing/mint` is **not** exempt — it is held to the Origin
+check. See [`setup-api.md`](../specs/012-web-adopt-pairing/contracts/setup-api.md),
+[`pairing-api.md`](../specs/012-web-adopt-pairing/contracts/pairing-api.md), and the middleware in
+`src/remo_cli/web/app.py`.
 
 ## Deployment modes: mounts vs adoption
 
@@ -217,7 +234,7 @@ var that can drift out of sync with reality):
 | SSH identity | **Your personal private key** bind-mounted read-only | A **service-scoped keypair** the container generates itself on first boot (`web-identity/id_ed25519`, comment `remo-web@<deployment-id>`) |
 | Instance host keys | Your `~/.ssh/known_hosts` bind-mounted read-only | Verified host keys pushed by the CLI (`web-identity/known_hosts`) |
 | Volumes | Several read-only bind mounts | **One** writable named volume at `REMO_HOME` (`/home/remo/.config/remo`) — no registry mount, no `~/.ssh` mounts |
-| Required env | — | `REMO_WEB_API_TOKEN` (enables the token-gated setup API; without it adoption is impossible) |
+| Required env | — | `REMO_WEB_OPERATOR_AUTH` (`forward` + `REMO_WEB_FORWARD_AUTH_HEADER`, or `none` for loopback/dev) — gates pairing-code minting; without a provider, minting is disabled and adoption is impossible |
 | Runs where? | Effectively the same machine as your CLI config | Any host — nothing from the workstation is mounted |
 | Registry updates | Edit/sync locally; the mount hot-reloads | `remo web push` after local changes |
 
@@ -235,7 +252,7 @@ From these artifacts the service derives one of four states:
 
 | State | Derivation | `remo web check` | `GET /api/v1/ready` | Browser |
 |---|---|---|---|---|
-| `unconfigured` | `REMO_HOME` writable, no registry (service keypair may already exist — generated, awaiting first push) | PASS: `unconfigured — awaiting adoption; run 'remo web adopt <service-url>' from a workstation` | **`200`** `{"status": "unconfigured", ...}` — healthy-and-waiting must not fail the compose healthcheck or crash-loop `restart: unless-stopped` | "Awaiting adoption" page: explains the state, shows a copy-pastable `remo web adopt <origin>` command, and flips to the dashboard automatically once adoption completes. No instance data, no terminals, no public-key display. |
+| `unconfigured` | `REMO_HOME` writable, no registry (service keypair may already exist — generated, awaiting first push) | PASS: `unconfigured — awaiting adoption; run 'remo web adopt <service-url>' from a workstation` | **`200`** `{"status": "unconfigured", ...}` — healthy-and-waiting must not fail the compose healthcheck or crash-loop `restart: unless-stopped` | "Awaiting adoption" page: explains the state, shows the `remo web adopt <origin>` command, and a **Copy pairing code** button (the code itself is never displayed). Flips to the dashboard automatically once adoption completes. No instance data, no terminals, no public-key display. |
 | `adopted` | `REMO_HOME` writable + service keypair + registry present | PASS: `adopted — configured via 'remo web adopt' (service identity in web-identity/)` | `200` `{"status": "ready", ...}` | Normal dashboard |
 | `mount_configured` | Registry present **and** (`REMO_HOME` not writable — the `:ro` bind mount — or a user SSH identity resolves via `REMO_WEB_SSH_IDENTITY_FILE`/`~/.ssh/id_*`). Explicit mounts are the operator's stated intent, so this wins even if a service keypair also exists. | PASS: `mount_configured — configured via read-only mounts` | `200` `{"status": "ready", ...}` | Normal dashboard |
 | `broken` | Any required artifact present but unreadable, a half-pair service keypair, a registry on a writable volume with nothing able to authenticate, or a missing runtime prerequisite | FAIL with per-check remediation | `503` `{"status": "not_ready", ...}` with actionable detail — unchanged from today | Offline/error indicator |
@@ -270,9 +287,9 @@ The file defines **both deployment modes as alternative services** — run one o
 
   Its differences from `remo-web`: **no bind mounts at all** — a single writable named volume
   (`remo-web-state:/home/remo/.config/remo`) holds the pushed registry, per-instance host keys, and
-  the service identity keypair — plus a required `REMO_WEB_API_TOKEN` environment variable (generate
-  one with `openssl rand -hex 24`). Hardening flags are identical. See
-  [CLI-to-web adoption](#cli-to-web-adoption) for what happens after `up`.
+  the service identity keypair — plus a `REMO_WEB_OPERATOR_AUTH` setting (`forward` behind an SSO
+  proxy, or `none` for loopback/dev) that gates pairing-code minting. Hardening flags are identical.
+  See [CLI-to-web adoption](#cli-to-web-adoption) for what happens after `up`.
 
 ### The published image
 
@@ -358,7 +375,7 @@ tooling.
 | Flag | Value | Why |
 |---|---|---|
 | `read_only` | `true` | The image ships no legitimate reason to write to its own filesystem at runtime — all mutable state is either ephemeral (PTYs, SSH ControlMaster sockets) or lives in the explicit `tmpfs` mount. A read-only rootfs means a compromised process can't persist a backdoor into the image layer. |
-| `user: "1000:1000"` | non-root UID/GID | The image creates a dedicated `remo` user (UID 1000) at build time and drops root via `USER remo` in the Dockerfile before the entrypoint runs. Running as non-root limits what a container-escape or dependency-confusion bug can do to the host. |
+| non-root `remo` (UID 1000) | non-root process | The app always ends up running as the dedicated `remo` user (UID 1000). In the read-only bind-mount service the container is pinned to `user: "1000:1000"`; the adopted-mode service instead starts as **root** and its entrypoint drops to `remo` via `gosu` after self-healing filesystem permissions (chowning a root-owned bind-mounted/named-volume config dir and re-healing the `/run/remo-ssh` tmpfs a restart remounts root-owned). Either way the serving process is non-root, which limits what a container-escape or dependency-confusion bug can do to the host. The adopted service therefore grants back only the minimal capabilities the heal-then-drop needs (`CHOWN`, `DAC_OVERRIDE`, `FOWNER`, `SETUID`, `SETGID`) on top of `cap_drop: ALL`; the dropped-to `remo` process holds none of them effectively. |
 | `security_opt: no-new-privileges:true` | — | Prevents any process in the container (including a compromised one) from gaining privileges via setuid/setgid binaries, closing off a common container-escape vector. |
 | `cap_drop: ALL` | — | The service needs no Linux capabilities at all (it doesn't bind privileged ports, doesn't need `ptrace`, doesn't need raw sockets) — dropping everything removes capabilities an attacker could otherwise abuse. |
 | `restart: unless-stopped` | — | Keeps the service available across host reboots/crashes without fighting an operator's deliberate `docker compose stop`. |
@@ -377,39 +394,38 @@ Both commands live in the base CLI (`src/remo_cli/cli/web.py` → `src/remo_cli/
 stdlib HTTP only) — the `web` extra is **not** required on the workstation:
 
 ```text
-remo web adopt [URL] [--token TEXT] [--via HOST] [--allow-empty] [--yes] [--save]
-remo web push [--allow-empty] [--yes]
+remo web adopt [URL] [--token TEXT] [--via HOST] [--allow-empty] [--yes]
+remo web push  [URL] [--token TEXT] [--via HOST] [--allow-empty] [--yes]
 ```
 
+`--token` carries the **pairing code** (the option name is kept for
+compatibility). Nothing is saved between runs — each adopt/push obtains a fresh
+code from the page.
+
 ### First-time adoption walkthrough
 
 **1. Deploy the container.** Via Compose (`docker compose --profile adopted up -d`, see
-[Docker Compose deployment](#docker-compose-deployment)) or as an **hola app** — the hola app
-manifest prompts for or generates the admin token at install time and supplies it to the container
-as `REMO_WEB_API_TOKEN`; either way the operator's job is the same: a writable state volume plus the
-token. Within ~30 seconds the container is up in the `unconfigured` state, has minted its
-service-scoped keypair, and the browser shows the "awaiting adoption" page with the exact command to
-run.
+[Docker Compose deployment](#docker-compose-deployment)) or as an **hola app** — set
+`REMO_WEB_OPERATOR_AUTH` (`forward` behind the hola app's SSO, plus `REMO_WEB_FORWARD_AUTH_HEADER`;
+or `none` for a loopback/dev deployment) so the page can mint pairing codes. Within ~30 seconds the
+container is up in the `unconfigured` state, has minted its service-scoped keypair, and the browser
+shows the "awaiting adoption" page.
 
-**2. Run `remo web adopt` on the workstation.** Inputs resolve in this order:
+**2. Copy the pairing code and run `remo web adopt`.** On the awaiting-adoption page (reached through
+your SSO proxy), click **Copy pairing code** — the code lands on your clipboard and is never
+displayed. On the workstation, inputs resolve in this order:
 
 | Input | Resolution order |
 |---|---|
 | Service URL | argument → `REMO_API_URL` env var → interactive prompt |
-| API token | `--token` → `REMO_API_TOKEN` env var → interactive prompt (hidden input) |
-
-`REMO_API_URL`/`REMO_API_TOKEN` are the workstation-side counterparts of the service's
-`REMO_WEB_API_TOKEN` — set them (e.g. exported by your shell profile, or handed out by the hola app
-install output) and the command runs prompt-free:
+| Pairing code | `--token` → `REMO_API_TOKEN` env var → interactive prompt (hidden input) |
 
 ```bash
-export REMO_API_URL=http://docker-host.lan:8080
-export REMO_API_TOKEN=<the value you set as REMO_WEB_API_TOKEN>
-remo web adopt
+remo web adopt http://docker-host.lan:8080    # paste the code at the prompt
 ```
 
 The flow then: checks the service's state (aborting clearly if the target is mount-configured or the
-token is rejected), fetches the service's public key and deployment id, and — per direct-access
+code is no longer valid), fetches the service's public key and deployment id, and — per direct-access
 instance, with a bounded per-instance time budget so one slow instance delays only itself —
 `ssh-keyscan`s the host, verifies the scanned key against your own trusted `~/.ssh/known_hosts`
 record (`ssh-keygen -F`, so hashed known_hosts files work; the service itself **never** makes a
@@ -437,52 +453,50 @@ asymmetric-network case (e.g. the instance is only reachable via workstation-spe
 config such as ProxyJump, or a firewall between the container host and the instance), not an
 adoption failure.
 
-**5. Saved credentials (explicit consent).** On success the CLI offers to save the service URL and
-token to `~/.config/remo/web-service.json` (written atomically, mode `0600`) so that later
-`remo web push` runs are zero-argument. Saving requires explicit consent — an interactive yes, or
-the `--save` flag; `--yes` alone never saves. v1 stores a single default deployment. The file also
-records the service's `deployment_id` and a per-instance push cache (see below).
+**5. No saved credentials.** Nothing durable is saved (there is no long-lived secret to save). A later
+`remo web push` obtains a fresh pairing code the same way. The workstation keeps only a **non-secret**
+push cache at `~/.config/remo/web-service.json` (mode `0600`): the service `deployment_id` mapped to
+per-instance host-key fingerprints, used to skip re-keyscanning unchanged instances. No URL and no
+code are ever stored.
 
 The command exits `0` when the flow completes — per-instance skips/flags are reported in the
-summary, not fatal — and `1` only on hard failure (auth rejection, mount-configured target, empty
-registry without `--allow-empty`, tunnel failure, payload rejected). Re-running adopt is idempotent:
-same summary, zero changes, still exactly one `remo-web@` line per instance.
-
-### The setup API and `REMO_WEB_API_TOKEN`
-
-The CLI talks to four token-gated endpoints under `/api/v1/setup/*`
-([`setup-api.md`](../specs/011-web-adopt/contracts/setup-api.md)): `GET /status`, `GET /identity`,
-`PUT /registry`, `POST /verify`. Every route requires `Authorization: Bearer <REMO_WEB_API_TOKEN>`,
-compared in constant time:
-
-- **Unset/empty token → the setup surface does not exist.** Every `/api/v1/setup/*` request gets a
-  plain `404`, indistinguishable from an absent feature — fail closed, never open. All other
-  functionality (dashboard, terminals, health) is unaffected. A bind-mount deployment that never
-  sets the token therefore exposes no setup surface at all.
-- **Wrong/missing header → `401`** with no further detail; the attempt is logged without the
-  presented credential. The token value and `Authorization` headers are covered by the service's
-  existing log redaction (`src/remo_cli/web/logging_config.py`).
-- **Rotation = redeploy with a new value.** The token is deploy-time configuration; change it in the
-  Compose file or hola app settings and restart, then re-run `remo web adopt` with the new token
-  (saved workstation credentials with the old token fail with a clear re-auth message).
+summary, not fatal — and `1` only on hard failure (dormant setup surface / expired code,
+mount-configured target, empty registry without `--allow-empty`, tunnel failure, payload rejected).
+Re-running adopt (with a fresh code) is idempotent: same summary, zero changes, still exactly one
+`remo-web@` line per instance.
+
+### The setup API and pairing codes
+
+The CLI talks to four endpoints under `/api/v1/setup/*`
+([`setup-api.md`](../specs/012-web-adopt-pairing/contracts/setup-api.md)): `GET /status`,
+`GET /identity`, `PUT /registry`, `POST /verify`. The surface is **dormant** unless a pairing session
+is live; each route requires `Authorization: Bearer <pairing-code>`, compared in constant time:
+
+- **No live session → the setup surface does not exist.** Every `/api/v1/setup/*` request gets a plain
+  `404`, indistinguishable from an absent feature — fail closed. A session is live only while an
+  operator is on the awaiting-adoption page (or the dashboard re-sync affordance).
+- **Wrong/missing/expired code → the same dormant `404`** — never a distinguishable `401` that would
+  reveal a session exists. The attempt is logged without the presented code; codes and `Authorization`
+  headers are covered by the service's log redaction (`src/remo_cli/web/logging_config.py`).
+- **The session ends when the flow completes** (on the terminal `POST /verify`), and a code is
+  single-use per handoff — reopening the page mints a fresh one and invalidates the prior. There is no
+  rotation to manage: codes are ephemeral by construction.
 
 ### Ongoing pushes: `remo web push`
 
 After the initial adoption, local registry changes (a `remo <provider> sync`, a new `create`, a
-removal) are re-synced with a zero-argument push:
+removal) are re-synced. Open the dashboard's **Pair CLI to sync** affordance, copy a fresh code, then:
 
 ```bash
-remo incus sync my-incus-host    # e.g. registers a new instance locally
-remo web push                    # re-sync it to the adopted service
+remo incus sync my-incus-host                   # e.g. registers a new instance locally
+remo web push http://docker-host.lan:8080       # paste the code; re-sync to the service
 ```
 
-`remo web push` loads the saved credentials, verifies the service still has the same
-`deployment_id` (a mismatch means the state volume was reset — it aborts with re-adopt guidance),
-then runs the adopt flow with **delta behavior**: only new or changed instances are re-keyscanned
-and re-authorized; instances unchanged since the last successful push skip that work entirely and
-are reported as `unchanged` (their previously verified host keys are reused, since every push
-replaces the service's host-keys file wholesale). If no credentials were saved, `push` behaves
-exactly like first-time `adopt`, prompting for URL and token.
+`remo web push` resolves URL + code the same way `adopt` does (every run), reads the service's
+`deployment_id`, and runs the adopt flow with **delta behavior**: only new or changed instances are
+re-keyscanned and re-authorized; instances unchanged since the last successful push (per the non-secret
+push cache for that `deployment_id`) skip that work and are reported as `unchanged` (their previously
+verified host keys are reused, since every push replaces the service's host-keys file wholesale).
 
 **Mirror semantics — removals propagate, authorization does not.** The push is an exact mirror: the
 workstation registry is the source of truth, so an instance you removed locally disappears from the
@@ -623,12 +637,13 @@ interactive session (only `remo-host capabilities` is invoked, never `sessions a
 
 | Failure | What it means | Fix |
 |---|---|---|
-| `/api/v1/setup/*` returns `404` for everything | `REMO_WEB_API_TOKEN` is unset or empty — the setup surface is disabled entirely (fail closed). | Set `REMO_WEB_API_TOKEN` in the deployment (Compose `environment:` / hola app setting) and restart. |
-| `remo web adopt` fails with an auth error (`401`) | The token you supplied doesn't match the service's `REMO_WEB_API_TOKEN`. | Re-check `REMO_API_TOKEN`/`--token` against the deployed value; after a token rotation, re-run adopt with the new value. |
+| `/api/v1/setup/*` returns `404` for everything | No pairing session is live — the surface is dormant (fail closed). | Open the awaiting-adoption page (through your SSO proxy) to mint a code; if the page can't mint, set `REMO_WEB_OPERATOR_AUTH` (`forward` + header, or `none` for loopback). |
+| `remo web adopt`/`push` fails: "pairing code is no longer valid … dormant" | The code expired (idle TTL), was rotated by reopening the page, or was already used. | Reopen the adopt page (or the dashboard's "Pair CLI to sync" affordance) for a fresh code and retry. |
+| Mint page shows "you are not signed in" / `POST /pairing/mint` returns `403` | Forward auth is required but the request reached the service without the trusted identity header. | Ensure the request goes through the SSO proxy that injects `REMO_WEB_FORWARD_AUTH_HEADER`; verify the proxy sets and strips it. |
 | adopt fails: deployment "configured via read-only mounts" | The target is a bind-mount deployment (`mount_configured`) — its configuration is operator-provided and read-only, so adoption does not apply. | Update the mounted files instead, or deploy the adopted-mode service (writable state volume, no mounts) if you want adoption. |
 | adopt refuses: empty registry | Your local registry has no instances — pushing would wipe a previously adopted service (a classic wrong-workstation accident). | Register/sync instances first, or pass `--allow-empty` if wiping is intentional. |
 | `--via` fails naming `REMO_WEB_ALLOWED_HOSTS` | Tunneled requests arrive with a `127.0.0.1` Host header, which the service's Host allowlist rejects. | Add `127.0.0.1` to `REMO_WEB_ALLOWED_HOSTS` (the default includes it). |
-| `remo web push` aborts: service identity changed | The saved `deployment_id` no longer matches the service — its state volume was reset and it minted a new identity. | Re-run `remo web adopt` (this replaces the stale `remo-web@` entries on your instances with the new key). |
+| After a service state-volume reset, instances keep a stale `remo-web@` line | The reset service minted a new identity; a fresh `remo web adopt` authorizes the new key but does not remove the old line. | Re-run `remo web adopt`, then delete the stale `remo-web@<old-id>` line from each instance's `~/.ssh/authorized_keys`. |
 | Summary line `security_flagged` (potential MITM warning) | The instance's scanned host key doesn't match your workstation's trusted record; nothing was pushed for it. | Investigate before trusting. If the instance was legitimately rebuilt: `ssh-keygen -R <host>`, reconnect once to re-trust, re-run adopt. |
 | Verify report: "reachable from workstation but not from the service" | Asymmetric reachability — the CLI reached the instance but the container cannot (DNS, routing, firewall, or workstation-only SSH config like ProxyJump). | Fix the network path from the container host to the instance; the adoption itself succeeded. |
 
@@ -688,7 +703,10 @@ locally with zero configuration; a container overrides everything via env alone.
 | `REMO_WEB_SSH_CONTROL_DIR` | `/run/remo-ssh` | Writable directory for SSH ControlMaster sockets (must be tmpfs or otherwise writable under a read-only rootfs). |
 | `REMO_WEB_FRONTEND_DIST_DIR` | `<repo_root>/frontend/dist` (resolved relative to the installed package) | Directory the built frontend SPA is served from. The Docker image overrides this to `/app/frontend-dist`, matching where the multi-stage build actually copies the built assets. |
 | `REMO_WEB_SSH_IDENTITY_FILE` | *(unset — falls back to the service keypair under `web-identity/`, then `~/.ssh/id_ed25519`/`id_ecdsa`/`id_rsa`/`id_dsa`)* | Explicit path to the SSH private key used for readiness/`remo web check`'s identity check, when it isn't one of the conventional filenames. |
-| `REMO_WEB_API_TOKEN` | *(unset)* | Admin bearer token for the setup API (`/api/v1/setup/*`) used by `remo web adopt`/`remo web push`. **Fail-closed**: while unset or empty, the setup surface is disabled entirely — every setup route returns a plain `404` — and adoption is impossible; all other functionality is unaffected. Verified with a constant-time comparison and covered by log redaction. Rotation = redeploy with a new value (then re-run `remo web adopt` with it). Generate with e.g. `openssl rand -hex 24`. |
+| `REMO_WEB_OPERATOR_AUTH` | *(unset — minting disabled)* | Operator-authentication posture gating pairing-code minting (`POST /api/v1/pairing/mint`). `forward` requires a trusted proxy-injected identity header (`REMO_WEB_FORWARD_AUTH_HEADER`); `none` mints without operator auth (network-restricted — a loud, weaker posture for loopback/dev). While unset, minting is disabled and adoption is impossible (fail closed). |
+| `REMO_WEB_FORWARD_AUTH_HEADER` | *(unset)* | Name of the trusted identity header your forward-auth proxy injects (e.g. `X-Forwarded-User`, `Remote-User`). **Required** when `REMO_WEB_OPERATOR_AUTH=forward`; enabling forward auth without it is a fail-fast startup error. The proxy MUST set and strip this header. |
+| `REMO_WEB_PAIRING_TTL_S` | `900.0` | Sliding idle TTL (seconds) for a pairing session — it expires this long after the last successful setup call (default 15 min). |
+| `REMO_WEB_API_TOKEN` | *(removed — ignored)* | **Removed in 012.** The static setup-API token is gone; a value set here is ignored (a one-line "now ignored" note is logged at startup). Setup access is authorized by ephemeral pairing codes. |
 
 `remo web serve --host`/`--port` are convenience overrides for local runs; every other setting is env-var-only.
 
@@ -700,4 +718,4 @@ Two variables configure the **CLI** (not the service — hence no `REMO_WEB_` pr
 | Variable | Used as |
 |---|---|
 | `REMO_API_URL` | Service URL fallback when no URL argument is given (before falling back to an interactive prompt). |
-| `REMO_API_TOKEN` | API token fallback when `--token` is not given (before falling back to a hidden interactive prompt). Set it to the same value as the service's `REMO_WEB_API_TOKEN`. |
+| `REMO_API_TOKEN` | Pairing-code fallback when `--token` is not given (before falling back to a hidden interactive prompt). Set it to a code freshly minted from the adopt page. |