Support optional encrypted-at-rest secrets via SOPS

Adds opt-in SOPS support so deployers who want it can encrypt true
secrets (OPENAI_API_KEY, ODYSSEUS_ADMIN_PASSWORD, SEARXNG_SECRET, MCP
OAuth secrets, IMAP passwords, etc.) at rest instead of leaving them
plaintext in .env. Non-secret config (APP_PORT, LLM_HOST, etc.) stays
in .env so PR diffs remain reviewable.

Uses SOPS's idiomatic in-place encryption convention: secrets.env is
encrypted in place with 'sops -e -i secrets.env' and the encrypted file
itself is safe to commit. To edit later: 'sops secrets.env' opens
$EDITOR with decrypted contents and re-encrypts on save.

The feature is only active when /app/secrets.env is present at
container start; existing deployments behave exactly as before. If
secrets.env is present but NOT SOPS-encrypted (detected via the
sops_version marker), the entrypoint refuses to start — that shape is
almost always a packaging mistake.

- Dockerfile: pin sops v3.13.1 (~10MB static Go binary), arch-aware
- docker/entrypoint.sh: wrap gosu with 'sops exec-env' when encrypted
  secrets.env exists; fail loudly if sops is missing, no SOPS_AGE_KEY
  [_FILE] is set, or the file is plaintext
- .sops.yaml: creation rule with placeholder age public key
- secrets.env.example: documents the in-place encryption workflow
- .gitignore: ignore transient decrypt artifacts only — encrypted
  secrets.env is intentionally committable
- SECURITY.md: new 'Encrypting Secrets At Rest' section with the
  age-keygen -> 'sops -e -i' -> compose-mount workflow

Verified end-to-end with the entrypoint exec-ing a sentinel-loaded
container:
  positive (encrypted file mounted, key bound)   -> sentinel in env
  negative (no secrets.env)                      -> entrypoint unchanged
  refuse   (plaintext secrets.env present)       -> exit 1 with hint

Proposed in #233. Naming chosen to avoid colliding with the existing
runtime Bitwarden integration at routes/vault_routes.py.

Author: nickorlabs

.gitignore

@@ -15,6 +15,14 @@ venv/
 .env.bak.*
 !.env.example
 
+# SOPS-encrypted secrets are committable (secrets.env, encrypted in
+# place). Only the transient artifacts left over from manual edit/
+# decrypt sessions should be ignored — never let a fully-plaintext
+# secrets file slip through. See SECURITY.md.
+secrets.env.dec
+secrets.env.bak
+secrets.env.plain
+
 # Data — all user data stays local
 data/
 !services/hwfit/data/

.sops.yaml

@@ -0,0 +1,13 @@
+# SOPS encryption configuration for Odysseus secrets at rest.
+#
+# Before encrypting, copy this file to .sops.yaml.local (or edit in place)
+# and replace the placeholder below with your own age public key.
+#
+# Generate a key with:
+#   age-keygen -o ~/.config/sops/age/keys.txt
+#   age-keygen -y < ~/.config/sops/age/keys.txt   # prints the public key
+#
+# See SECURITY.md ("Encrypting Secrets At Rest") for the full workflow.
+creation_rules:
+  - path_regex: secrets\.env(\.enc)?$
+    age: age1REPLACE_WITH_YOUR_AGE_PUBLIC_KEY

Dockerfile

@@ -20,6 +20,15 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
     gosu \
     && rm -rf /var/lib/apt/lists/*
 
+# Optional opt-in: SOPS for encrypted-at-rest secrets (see SECURITY.md).
+# Small static Go binary; only invoked when /app/secrets.env.enc is present
+# at container start. Pinned by version; arch-aware via dpkg.
+ARG SOPS_VERSION=3.13.1
+RUN arch="$(dpkg --print-architecture)" \
+    && curl -fsSL -o /usr/local/bin/sops \
+       "https://github.com/getsops/sops/releases/download/v${SOPS_VERSION}/sops-v${SOPS_VERSION}.linux.${arch}" \
+    && chmod +x /usr/local/bin/sops
+
 WORKDIR /app
 
 # Install Python deps first (layer cache)

SECURITY.md

@@ -23,6 +23,57 @@ Security fixes are handled on the default branch until formal releases are cut.
 - Treat shell, model-serving, MCP, email, calendar, and vault features as privileged admin functionality.
 - Common internal-only ports are Odysseus `7000`, SearXNG `8080`, ntfy `8091`, ChromaDB `8100`, Ollama `11434`, and local model/provider APIs such as `8000-8020`.
 
+## Encrypting Secrets At Rest (Optional)
+
+By default, secret values (API keys, admin password seed, SearXNG signing key, etc.) live in `.env` as plaintext. The file is gitignored, but any process that reads it (container exec, host backup, snapshot) reveals every secret. For deployments where that's a concern, Odysseus supports [SOPS](https://github.com/getsops/sops) with age keys to encrypt secrets at rest.
+
+This is **opt-in** — the feature is only active when an encrypted `secrets.env` is present at container start. Existing deployments behave exactly as before.
+
+### Setup
+
+1. Install [`age`](https://github.com/FiloSottile/age) on your host and generate a key:
+
+   ```bash
+   mkdir -p ~/.config/sops/age
+   age-keygen -o ~/.config/sops/age/keys.txt
+   age-keygen -y < ~/.config/sops/age/keys.txt   # prints your age public key
+   ```
+
+2. Paste the printed public key into `.sops.yaml` (replace the `age1REPLACE...` placeholder).
+
+3. Copy the example, fill in real secret values, then encrypt in place:
+
+   ```bash
+   cp secrets.env.example secrets.env
+   $EDITOR secrets.env           # fill in real values
+   sops -e -i secrets.env        # encrypt in place — file is now safe to commit
+   ```
+
+   To edit later: `sops secrets.env` opens `$EDITOR` with decrypted contents and re-encrypts on save.
+
+4. Provide the age **private** key to the container by mounting it and pointing `SOPS_AGE_KEY_FILE` at it (`docker-compose.yml`):
+
+   ```yaml
+   services:
+     odysseus:
+       volumes:
+         - ~/.config/sops/age/keys.txt:/run/secrets/sops-age-key:ro
+       environment:
+         - SOPS_AGE_KEY_FILE=/run/secrets/sops-age-key
+   ```
+
+At container start, the entrypoint runs `sops exec-env` to inject secrets as env vars JIT — plaintext never touches the container filesystem. If `secrets.env` is present but **not** SOPS-encrypted, the entrypoint refuses to start (it's almost always a packaging mistake).
+
+### What to put in `secrets.env` vs `.env`
+
+Only true secrets belong in `secrets.env`. Non-secret configuration stays in `.env` because it benefits from plaintext diffs and PR review:
+
+| `.env` (plaintext, gitignored) | `secrets.env` (SOPS-encrypted, committable) |
+|---|---|
+| `APP_PORT`, `LLM_HOST`, `SEARXNG_INSTANCE`, `ALLOWED_ORIGINS`, `CHROMADB_BIND`, `LOCALHOST_BYPASS` | `OPENAI_API_KEY`, `ODYSSEUS_ADMIN_PASSWORD`, `SEARXNG_SECRET`, `INTERNAL_TOOL_TOKEN`, MCP OAuth client secrets, IMAP passwords |
+
+To migrate: move only the secret lines out of your existing `.env` into `secrets.env`, encrypt, and delete those lines from `.env`.
+
 ## Publishing A Fork
 
 Before pushing a public fork, run:

docker/entrypoint.sh

@@ -80,6 +80,39 @@ export VLLM_USE_FLASHINFER_SAMPLER="${VLLM_USE_FLASHINFER_SAMPLER:-0}"
 # vLLM and helper scripts land here because /app is the non-root user's HOME.
 export PATH="/app/.local/bin:$PATH"
 
+# Optional SOPS-encrypted secrets at rest. When /app/secrets.env is
+# present it MUST be SOPS-encrypted (detected via the `sops_version`
+# trailing line). On encrypted, we exec via `sops exec-env` so secrets
+# enter the process as env vars JIT — plaintext never touches the
+# container filesystem. On plaintext, we refuse to start — a plaintext
+# secrets.env in /app is almost always a packaging mistake. See
+# SECURITY.md ("Encrypting Secrets At Rest") for the user-side workflow.
+SECRETS_FILE="/app/secrets.env"
+if [ -f "$SECRETS_FILE" ]; then
+    if ! grep -q '^sops_version' "$SECRETS_FILE"; then
+        echo "entrypoint: $SECRETS_FILE exists but is not SOPS-encrypted; refusing to start" >&2
+        echo "entrypoint: encrypt it with: sops -e -i secrets.env" >&2
+        exit 1
+    fi
+    if ! command -v sops >/dev/null 2>&1; then
+        echo "entrypoint: $SECRETS_FILE is SOPS-encrypted but 'sops' is not on PATH" >&2
+        exit 1
+    fi
+    if [ -z "${SOPS_AGE_KEY_FILE:-}" ] && [ -z "${SOPS_AGE_KEY:-}" ]; then
+        echo "entrypoint: $SECRETS_FILE is SOPS-encrypted but neither SOPS_AGE_KEY_FILE nor SOPS_AGE_KEY is set" >&2
+        exit 1
+    fi
+    # `sops exec-env` takes a single command string (passed to sh -c),
+    # not argv passthrough — so we single-quote each positional arg to
+    # preserve word boundaries when sh re-tokenises.
+    cmd=""
+    for a in "$@"; do
+        qa=$(printf '%s' "$a" | sed "s/'/'\\\\''/g")
+        cmd="$cmd '$qa'"
+    done
+    exec gosu "$PUID:$PGID" sops exec-env "$SECRETS_FILE" "exec$cmd"
+fi
+
 # Drop root and run the actual app. `gosu` is preferred over `su` /
 # `sudo` because it cleans up the process tree (no extra shell layer)
 # so signals (SIGTERM from `docker stop`) reach uvicorn directly.

secrets.env.example

@@ -0,0 +1,27 @@
+# Odysseus — secrets meant for encryption at rest (optional, via SOPS).
+#
+# Workflow (idiomatic SOPS — file is encrypted in place):
+#
+#   cp secrets.env.example secrets.env
+#   $EDITOR secrets.env           # fill in real values (plaintext, on your host only)
+#   sops -e -i secrets.env        # encrypt in place — file now safe to commit
+#
+# To edit later: `sops secrets.env` opens $EDITOR with decrypted contents
+# and re-encrypts on save. Never commit a non-encrypted secrets.env.
+#
+# At container start, the entrypoint runs `sops exec-env` to inject these
+# values as env vars without writing plaintext to disk. Requires
+# SOPS_AGE_KEY_FILE (or SOPS_AGE_KEY) to be set inside the container —
+# see SECURITY.md ("Encrypting Secrets At Rest").
+#
+# Non-secret configuration (APP_PORT, LLM_HOST, SEARXNG_INSTANCE, etc.)
+# stays in .env as today — only true secrets belong here.
+
+# OpenAI / provider API keys
+# OPENAI_API_KEY=
+
+# Pre-seeded admin password used on first boot (delete after first run).
+# ODYSSEUS_ADMIN_PASSWORD=
+
+# SearXNG cookie/CSRF signing key (generate with: openssl rand -hex 32)
+# SEARXNG_SECRET=