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.

The feature is only active when /app/secrets.env.enc is present at
container start; existing deployments behave exactly as before.

- Dockerfile: pin sops v3.13.1 (~10MB static Go binary), arch-aware
- docker/entrypoint.sh: wrap gosu with 'sops exec-env' when the
  encrypted file exists; fail loudly if sops is missing or no
  SOPS_AGE_KEY[_FILE] is set
- .sops.yaml: creation rule with placeholder age public key
- secrets.env.example: documents which env vars are expected as secrets
- .gitignore: ignore plaintext secrets.env, allow .example and .enc
- SECURITY.md: new 'Encrypting Secrets At Rest' section with the
  age-keygen / sops -e / compose-mount workflow

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

Author: nickorlabs

.gitignore

@@ -14,6 +14,12 @@ venv/
 .env
 !.env.example
 
+# SOPS encrypted-at-rest secrets. Plaintext stays local; the .enc file
+# and the .example template are safe to commit. See SECURITY.md.
+secrets.env
+!secrets.env.example
+!secrets.env.enc
+
 # 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

@@ -19,6 +19,56 @@ Security fixes are handled on the default branch until formal releases are cut.
 - Rotate API keys, webhook secrets, and Odysseus API tokens if they appear in logs, screenshots, demos, or shared chats.
 - Treat shell, model-serving, MCP, email, calendar, and vault features as privileged admin functionality.
 
+## 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 `secrets.env.enc` 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:
+
+   ```bash
+   cp secrets.env.example secrets.env
+   $EDITOR secrets.env
+   sops -e secrets.env > secrets.env.enc
+   shred -u secrets.env       # destroy plaintext; keep only secrets.env.enc
+   ```
+
+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.
+
+### 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.enc` (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

@@ -64,6 +64,25 @@ for cu in /app/.local/lib/python*/site-packages/nvidia/cu13; do
     fi
 done
 
+# Optional SOPS-encrypted secrets at rest. When /app/secrets.env.enc is
+# present, decrypt it via `sops exec-env` so secrets are injected as env
+# vars JIT and plaintext never touches the container filesystem. See
+# SECURITY.md ("Encrypting Secrets At Rest") for the user-side workflow.
+SECRETS_ENC="/app/secrets.env.enc"
+if [ -f "$SECRETS_ENC" ]; then
+    if ! command -v sops >/dev/null 2>&1; then
+        echo "entrypoint: $SECRETS_ENC present but 'sops' is not on PATH" >&2
+        exit 1
+    fi
+    if [ -z "${SOPS_AGE_KEY_FILE:-}" ] && [ -z "${SOPS_AGE_KEY:-}" ]; then
+        echo "entrypoint: $SECRETS_ENC present but neither SOPS_AGE_KEY_FILE nor SOPS_AGE_KEY is set" >&2
+        exit 1
+    fi
+    # POSIX re-exec idiom: sh -c 'exec "$@"' rebuilds argv cleanly so
+    # uvicorn still receives the original positional args intact.
+    exec gosu "$PUID:$PGID" sops exec-env "$SECRETS_ENC" 'exec "$@"' -- "$@"
+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,26 @@
+# Odysseus — secrets meant for encryption at rest (optional, via SOPS).
+#
+# Workflow:
+#   1. Copy this file to secrets.env (gitignored)
+#   2. Fill in real values
+#   3. Encrypt with: sops -e secrets.env > secrets.env.enc
+#   4. Shred plaintext: shred -u secrets.env
+#   5. Commit secrets.env.enc if you want to sync across machines
+#
+# At container start, the entrypoint runs `sops exec-env` to inject these
+# values as env vars without ever 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") for the full guide.
+#
+# 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=