catence 0.2.1-beta.2 → 0.2.1-beta.21

package/docs/deployment/docker.md

@@ -26,6 +26,8 @@ explained in the [beta release notes](../../README.md#beta-releases).
 | Provider credentials | per-athlete secret file, mode 0600 | `catence-data secret set` |
 | API keys | process environment only | `.env` |
 | Chat history + preferences | data home | `console/chat-history.sqlite3` |
+| Console logins + athlete grants | data home (mode 0600, bcrypt hashes) | `console/accounts.json` |
+| Per-account MCP keys + OAuth state | data home (registry 0600; `oauth/` dir 0700) | `mcp-keys.json`, `oauth/` |
 
 Credentials never land in `config.json`; profiles reference environment
 variable *names* (`apiKeyEnv`, `apiBaseEnv`, `apiVersionEnv`). See
@@ -69,10 +71,16 @@ Script options (run `./deploy-console.sh --help` for the full list):
 
 ## 2. Fill in `catence-deploy/.env`
 
+The Console always needs `CHAINLIT_AUTH_SECRET`, plus at least one login
+source: the **environment break-glass account**
+(`CATENCE_CONSOLE_USERNAME` + `CATENCE_CONSOLE_PASSWORD_HASH`, set together or
+not at all) or a **stored Console account** in the data volume (see
+[Console accounts](#console-accounts)). Add one model-provider key either way.
+
 ```sh
-CATENCE_CONSOLE_USERNAME=coach
-CATENCE_CONSOLE_PASSWORD_HASH='…'      # generate: ./catence-deploy/hash-password.sh
 CHAINLIT_AUTH_SECRET='…'               # generate: openssl rand -hex 32
+CATENCE_CONSOLE_USERNAME=coach         # environment break-glass account …
+CATENCE_CONSOLE_PASSWORD_HASH='…'      # generate: ./catence-deploy/hash-password.sh
 OPENAI_API_KEY='…'                     # or ANTHROPIC_API_KEY / OPENCODE_GO_API_KEY …
 OPENAI_API_BASE=''                     # only for OpenAI-compatible endpoints
 OPENCODE_GO_API_KEY='…'                # the OpenCode Go base URLs are pre-filled below
@@ -80,9 +88,14 @@ OPENCODE_GO_API_BASE='https://opencode.ai/zen/go/v1'
 OPENCODE_GO_MESSAGES_API_BASE='https://opencode.ai/zen/go'
 ```
 
-Generate the Console login hash with the scaffold helper (it prompts on the
-terminal, never echoes, and uses the compose project so it works whatever image
-tag the script built):
+Leave the username/hash pair empty to log in with stored accounts instead: the
+script accepts an existing `console/accounts.json` in the data volume and
+starts without the pair. Set both or neither — a lone username without a hash
+fails the deploy with a clear error.
+
+Generate the hash for the environment pair with the scaffold helper (it
+prompts on the terminal, never echoes, and uses the compose project so it works
+whatever image tag the script built):
 
 ```sh
 ./catence-deploy/hash-password.sh
@@ -102,6 +115,67 @@ Then start the stack (or re-run the script, which re-reads the saved `.env`):
 docker compose -f catence-deploy/docker-compose.yml --env-file catence-deploy/.env up -d
 ```
 
+### Console accounts
+
+Stored accounts are the multi-user path: each account has a role and an
+athlete grant list, and the Console enforces both server-side on logins,
+roster/dashboard requests, and agent turns. Accounts live in
+`console/accounts.json` in the data volume (mode 0600, bcrypt hashes only).
+
+Manage them with the `users` command inside the container — via the generated
+helper:
+
+```sh
+./catence-deploy/users.sh add martina --athlete martina   # member: one granted athlete
+./catence-deploy/users.sh add coach --admin               # admin: every athlete
+./catence-deploy/users.sh list
+./catence-deploy/users.sh grant martina sam
+./catence-deploy/users.sh revoke martina sam
+./catence-deploy/users.sh passwd martina
+./catence-deploy/users.sh set-role martina admin
+./catence-deploy/users.sh remove martina
+```
+
+`users.sh` uses `docker compose exec`, so the stack must be running. The long
+forms are:
+
+```sh
+# Interactive: prompts for the password twice
+docker compose -f catence-deploy/docker-compose.yml --env-file catence-deploy/.env exec console \
+  /opt/catence-console/bin/catence-console users add martina --athlete martina
+
+# Non-interactive: read the password from an environment variable
+docker compose -f catence-deploy/docker-compose.yml --env-file catence-deploy/.env run --rm -T \
+  -e CATENCE_CONSOLE_NEW_PASSWORD='…' \
+  --entrypoint /opt/catence-console/bin/catence-console console \
+  users add martina --athlete martina --password-env CATENCE_CONSOLE_NEW_PASSWORD
+```
+
+Before the first start there is no running container **and** no login yet —
+the Console refuses to start without one — so create the first account with
+the one-off form (it prompts for the password):
+
+```sh
+docker compose -f catence-deploy/docker-compose.yml --env-file catence-deploy/.env run --rm \
+  --entrypoint /opt/catence-console/bin/catence-console console users add coach --admin
+```
+
+Roles: `admin` sees every athlete; `member` sees only explicitly granted
+athletes. A member with zero grants can sign in and browse, but has no athlete
+to scope a chat to. The environment pair is a never-persisted break-glass
+admin: it keeps working when the accounts file is lost or the last admin is
+locked out, and unsetting the two variables revokes it.
+
+Accounts gate the Console only. The MCP server has no authentication by
+default — the caller's `athleteId` is trusted — so port 8787 still needs
+loopback or network-layer restriction unless you switch on the bearer gate,
+per-account keys, or OAuth (see
+[Connecting to the Docker-based MCP from outside](#connecting-to-the-docker-based-mcp-from-outside)).
+
+The accounts file is the only copy of your stored logins: keep it in backups
+of the data volume (or bind-mounted home), along with `config.json` and the
+athlete stores.
+
 ## 3. Initialize an athlete store
 
 The data volume already contains a seeded `config.json`, so `setup` accepts
@@ -184,8 +258,9 @@ export OPENCODE_GO_API_KEY='…'                      # any non-empty value pass
 ## 7. Access the Console
 
 Open `http://127.0.0.1:8000` (or the `--bind:--port` you configured) and log in
-with `CATENCE_CONSOLE_USERNAME` and the password whose hash is in
-`CATENCE_CONSOLE_PASSWORD_HASH`.
+with a stored Console account (see [Console accounts](#console-accounts)) or
+with the environment break-glass pair (`CATENCE_CONSOLE_USERNAME` and the
+password whose hash is in `CATENCE_CONSOLE_PASSWORD_HASH`).
 
 ## 8. Verify with doctor
 
@@ -395,11 +470,12 @@ CATENCE_MCP_BIND=0.0.0.0 ./scripts/deploy-console.sh beta
 After deployment, the MCP server is available at
 `http://<tailscale-ip>:8787/mcp` from any device on your tailnet.
 
-**Security note:** The MCP server has **no authentication** — it trusts the
-caller's `athleteId` parameter. When exposing on `0.0.0.0`, you **must**
-restrict access at the network layer (Tailscale ACLs, firewall rules, etc.).
-The Console UI remains on loopback (`127.0.0.1:8000`) and should still be
-fronted by Cloudflare Tunnel or a reverse proxy.
+**Security note:** Without the bearer gate, per-account keys, or OAuth, the MCP
+server has **no authentication** — it trusts the caller's `athleteId`
+parameter. When exposing on `0.0.0.0`, you **must** restrict access at the
+network layer (Tailscale ACLs, firewall rules, etc.). The Console UI remains
+on loopback (`127.0.0.1:8000`) and should still be fronted by Cloudflare
+Tunnel or a reverse proxy.
 
 **Examples: common MCP clients**
 
@@ -425,14 +501,90 @@ claude mcp add --transport http catence -- http://<tailscale-ip>:8787/mcp
 
 ### Why not expose port 8787 directly?
 
-- The MCP server has **no authentication** — it trusts the caller's
-  `athleteId` parameter.
+- Without the bearer gate, per-account keys, or OAuth, the MCP server has
+  **no authentication** — it trusts the caller's `athleteId` parameter.
 - Exposing it would allow any network caller to read all athlete data in the
   catalog.
 - The Console proxies dashboard requests through its **authenticated**
   same-origin route.
 - SSH port forwarding keeps the trust boundary at your SSH credentials.
 
+### Bearer-token authentication for remote MCP clients
+
+To serve the MCP endpoint to a remote MCP client (for example a Mistral Work
+custom connector) over a Cloudflare Tunnel, switch on the native
+bearer-token gate. The deploy scaffold arms it at `/data/mcp-token` (inside
+the data volume, so it survives rebuilds); the file's presence is the switch
+and Catence generates the token itself:
+
+```sh
+# enable from the host (or use the Console Settings once logged in):
+docker compose -f catence-deploy/docker-compose.yml --env-file catence-deploy/.env \
+  exec console catence-data --home /data mcp enable
+
+# print the token for the client's credential flow:
+docker compose -f catence-deploy/docker-compose.yml --env-file catence-deploy/.env \
+  exec console catence-data --home /data mcp token
+
+# disable again:
+docker compose -f catence-deploy/docker-compose.yml --env-file catence-deploy/.env \
+  exec console catence-data --home /data mcp disable
+```
+
+With the gate enabled, every runtime endpoint except `/health` and
+`/api/v1/health` answers `401` without an exact `Authorization: Bearer
+<token>` header — including `/mcp` and the JSON APIs. Toggling takes effect
+without a restart; the Console attaches the header automatically to its own
+runtime calls.
+
+Keep `CATENCE_MCP_BIND=127.0.0.1` (the default): the tunnel client on the
+host forwards to the host-loopback mapping, so the port still never binds a
+LAN interface. Point the tunnel ingress for the MCP hostname at
+`http://127.0.0.1:8787` and complete the client's credential flow with the
+token from `mcp token`. Rotate with `mcp disable && mcp enable` and
+re-authenticate the client. The only additional setup the tunnel needs is
+the ingress rule for the MCP hostname.
+
+A custom host-side token file is still possible: set
+`CATENCE_MCP_TOKEN_FILE=<host path>` in `.env`. The file is then bind-mounted
+read-only at the same path, so it must already exist on the host — enabling
+from the Console cannot create it.
+
+#### Per-account MCP keys and OAuth 2.1 (Docker)
+
+The runtime reads three more environment variables. The deploy script passes
+them into the container, writes them into `catence-deploy/.env`, and validates
+them before rendering the compose file:
+
+| Variable | Default | Meaning |
+| --- | --- | --- |
+| `CATENCE_OAUTH_ENABLED` | empty (disabled) | `1` or `true` runs the OAuth 2.1 authorization server so ChatGPT/Codex connect with their OAuth flow. Startup default — the Console (Settings → MCP Exposure → OAuth 2.1 sign-in) overrides it at runtime. Requires `CATENCE_PUBLIC_URL` when enabled. |
+| `CATENCE_PUBLIC_URL` | empty | Public `https` URL of this server (the tunnel URL; no query string or fragment). It becomes the advertised OAuth issuer. Startup default — overridable in the Console. |
+| `CATENCE_MCP_KEYS_FILE` | `/data/mcp-keys.json` | Per-account MCP key registry, a container path — no host mount needed. Managed with `catence-data mcp key` or the Console (Settings → MCP Exposure → API keys). |
+
+```sh
+# Per-account key for a Console account (the raw token is printed exactly once):
+docker compose -f catence-deploy/docker-compose.yml --env-file catence-deploy/.env \
+  exec console catence-data --home /data mcp key add --account coach
+
+# OAuth for ChatGPT/Codex — preferred: enable in the Console
+#   (Settings → MCP Exposure → OAuth 2.1 sign-in; applies without a restart).
+# Startup defaults, set in catence-deploy/.env and re-run the script:
+#   CATENCE_OAUTH_ENABLED=1
+#   CATENCE_PUBLIC_URL=https://catence-mcp.example.com
+./scripts/deploy-console.sh beta
+```
+
+The script refuses to deploy when `CATENCE_OAUTH_ENABLED` is set without a
+valid https `CATENCE_PUBLIC_URL`. Once a valid Console settings file exists
+(`<catalog-home>/oauth/settings.json`, inside the data volume), it overrides
+these startup values at runtime. The checked-in dev compose
+(`docker-compose.beta.yml`) accepts `CATENCE_OAUTH_ENABLED` and
+`CATENCE_PUBLIC_URL` the same way (empty default = disabled). See
+[local-mcp.md](local-mcp.md#per-account-api-keys) and
+[local-mcp.md](local-mcp.md#oauth-21-chatgptcodex) for the full semantics and
+the client matrix.
+
 ## Exposing the Console safely
 
 Keep the Console port bound to `127.0.0.1` (the default) and front it with a
@@ -472,11 +624,17 @@ docker run --rm -it -v catence-data:/data --entrypoint catence-data catence-cons
 
 Use the same `--entrypoint catence-data` pattern for `secret set` and `sync`.
 
+Console logins work the same way: keep the environment pair together (or
+neither variable), or seed a stored account into the volume with the `users`
+command (see [Console accounts](#console-accounts)).
+
 ## Updating
 
 Docker deployments: re-run `deploy-console.sh beta` (or `stable`); it
 re-resolves the newest versions from the registries and rebuilds. The data
-volume and your `config.json` are preserved.
+volume is preserved, so your `config.json`, the stored Console accounts
+(`console/accounts.json`), chat history, and the athlete stores all survive
+the rebuild.
 
 ```sh
 curl -fsSL https://raw.githubusercontent.com/rifusaki/catence/beta/scripts/deploy-console.sh | bash -s beta

package/docs/deployment/local-console.md

@@ -2,7 +2,8 @@
 
 Catence Console is a password-protected local web chat that starts a matching
 Catence runtime on loopback. It uses Chainlit password login and fails closed
-unless all three authentication variables are supplied.
+unless `CHAINLIT_AUTH_SECRET` and at least one login source — a stored Console
+account or the environment account pair — are configured.
 
 This guide covers the **local** path: the npm package plus the Python Console
 on your machine. The Docker path (one container built from the public
@@ -27,6 +28,7 @@ model.
 | Provider credentials | per-athlete secret file, mode 0600 | `catence-data secret set` |
 | API keys | process environment only | shell exports |
 | Chat history + preferences | data home | `console/chat-history.sqlite3` |
+| Console logins + athlete grants | data home (mode 0600, bcrypt hashes) | `console/accounts.json` |
 
 Credentials never land in `config.json`; profiles reference environment
 variable *names* (`apiKeyEnv`, `apiBaseEnv`, `apiVersionEnv`). See
@@ -75,6 +77,12 @@ printf %s 'strava-client-secret' | catence-data --athlete alex secret set --prov
 Set only the providers you actually sync; `secret set` accepts each field
 independently.
 
+Administrators can also manage any athlete's credentials from **Settings →
+Athletes → Credentials** in the Console. The dialog is write-only — it shows
+each field as configured or not and lets you replace or remove values, but
+values are never displayed. `catence-data --athlete <id> secret remove
+--provider <provider> --field <field>` mirrors the dialog for scripted setups.
+
 ## 4. Sync data and build retrieval context
 
 ```sh
@@ -95,15 +103,28 @@ To add OpenCode Go models, run the
 
 ```sh
 export OPENAI_API_KEY='…'                        # or ANTHROPIC_API_KEY / OPENCODE_GO_API_KEY …
-export CATENCE_CONSOLE_USERNAME='coach'
-export CATENCE_CONSOLE_PASSWORD_HASH="$(catence-console auth hash-password)"
 export CHAINLIT_AUTH_SECRET="$(openssl rand -hex 32)"
 ```
 
-The Console fails closed unless `CATENCE_CONSOLE_USERNAME`,
-`CATENCE_CONSOLE_PASSWORD_HASH` (a bcrypt hash), and `CHAINLIT_AUTH_SECRET`
-are all set. There is one shared account; the username/password pair grants a
-single `console-owner` role.
+`CHAINLIT_AUTH_SECRET` is always required: it signs Chainlit sessions. On top
+of it, the Console needs at least one login source:
+
+- **Stored accounts** (the multi-user path). Each account carries a role and
+  an athlete grant list and lives in `<home>/console/accounts.json`. Create
+  the first one with the users CLI, which prompts for the password twice:
+
+  ```sh
+  catence-console users add coach --admin
+  ```
+
+- **The environment break-glass account**: set both
+  `CATENCE_CONSOLE_USERNAME` and `CATENCE_CONSOLE_PASSWORD_HASH` (the bcrypt
+  hash printed by `catence-console auth hash-password`). The pair is never
+  persisted and always acts as an admin — the way back in when the accounts
+  file is lost.
+
+Roles, grants, and the rest of the CLI are described under
+[Console accounts](#console-accounts).
 
 ## 7. Start the Console
 
@@ -121,7 +142,7 @@ catence-console doctor
 
 ### Manage models in the Console
 
-The **Models** page (header button) manages the model list without editing
+The **Settings → Models** tab manages the model list without editing
 `config.json` by hand:
 
 - Enable/disable toggles hide models from the chat's Model dropdown. Disabled
@@ -137,11 +158,87 @@ The **Models** page (header button) manages the model list without editing
   strict parser used at startup before it replaces the file, and secrets stay
   forbidden (only environment-variable names are ever stored).
 
-The dashboard header has a **Sync data** button that starts the same detached
+**Settings → Status** has a **Sync data** button that starts the same detached
 sync as `catence-data sync --provider all` through the authenticated Console
 origin, shows live progress while the run is active, and displays the last
-completed sync afterwards. Each manual sync also refreshes OpenCode Go model
-profiles first; a discovery failure never blocks the data sync.
+completed sync afterwards; the Dashboard keeps a read-only “Syncing…” pill and
+links there when a write lock makes its data unavailable. Each manual sync also
+refreshes OpenCode Go model profiles first; a discovery failure never blocks the
+data sync.
+
+### Add athletes in the Console
+
+Admins can add a catalog athlete from **Settings → Athletes** (athlete id,
+display name, and optionally “set as default”). The form calls the runtime's
+`POST /api/v1/athletes` through the Console, which rejects members with
+`403 admin_required` and otherwise performs the same catalog write as
+`catence-data athlete add --id <id> --label <label>`. The id must match
+`^[a-z][a-z0-9-]{0,62}$` and must not already exist (`409 athlete_exists`);
+single-store runtimes without a catalog refuse with `400 catalog_required`.
+The roster refreshes immediately, so a new athlete can be granted to members
+and selected in chat without restarting the Console.
+
+## Console accounts
+
+Console accounts are Catence's multi-user login model, enforced entirely by
+the Console: sign-in, the athlete roster, dashboard and athlete-file requests,
+and the athlete scoping of every chat turn are all checked server-side against
+the account's role and athlete grants. The MCP server itself is untouched — it
+has no authentication and trusts the `athleteId` each call names (see
+[local-mcp.md](local-mcp.md#streamable-http-server)); accounts only gate what
+goes through the Console.
+
+| Role | Athlete access |
+| --- | --- |
+| `admin` | Every athlete in the catalog (`athletes: "all"`) |
+| `member` | Only the explicitly granted athletes; zero grants allowed |
+
+Accounts live in `<home>/console/accounts.json` (mode 0600, bcrypt hashes
+only), where `<home>` is `$CATENCE_HOME` or `~/.catence`. The Console re-reads
+the file on every login, so new accounts, password resets, and grant changes
+apply without a restart.
+
+### Manage accounts with the users CLI
+
+```sh
+catence-console users add coach --admin                    # admin: all athletes
+catence-console users add martina --athlete martina        # member with one grant
+catence-console users add sam                              # member, zero grants
+catence-console users list
+catence-console users passwd martina
+catence-console users set-role sam member
+catence-console users grant sam martina
+catence-console users revoke sam martina
+catence-console users remove sam
+```
+
+- `add <username> (--admin | --athlete <id> [--athlete <id> …])` — members
+  default to zero grants; `--admin` cannot be combined with `--athlete` and
+  always stores access to every athlete.
+- `add` and `passwd` prompt for the password twice (never echoed). For
+  automation, `--password-env VAR` reads the password from environment
+  variable `VAR` instead, so it never appears in the command line or shell
+  history.
+- `grant`/`revoke` change a member's athlete list; revoking the last grant
+  leaves a zero-grant member. `set-role` promotes or demotes: promoting to
+  `admin` coerces the grants to `"all"`, demoting to `member` keeps them.
+- `add`/`grant`/`revoke` validate athlete ids against `catalog.json` when it
+  exists, and `--home <dir>` points any subcommand at a non-default catalog.
+
+A member with zero grants can sign in and browse the Console, but there is no
+athlete to scope a chat to: the Athlete selector is disabled with *"You don't
+have access to any athlete yet. Ask an administrator to grant you access."*
+and every chat turn is answered with the same notice. A member that requests
+an athlete outside their grants receives `403 athlete_forbidden`; the Console
+never forwards the request to the runtime.
+
+### The environment break-glass account
+
+`CATENCE_CONSOLE_USERNAME` and `CATENCE_CONSOLE_PASSWORD_HASH` must be set
+together. When they are, the pair always acts as an `admin` and is never
+written to `accounts.json`: unsetting the two variables revokes it. Use it as
+the recovery path when the accounts file is lost or a lockout leaves nobody
+who can grant access — not as the everyday login.
 
 ## Console serve options
 
@@ -167,12 +264,18 @@ chat starts.
 
 ## How multi-athlete works in the Console
 
-The Console shares the same per-athlete stores as MCP, but scoping is
-**server-owned, not model-owned**:
+The Console shares the same per-athlete stores as MCP. Access is layered:
+per-account grants at the login, then server-owned scoping per chat.
 
+- **Per-account grants.** Each stored account is an `admin` (every athlete) or
+  a `member` with an explicit grant list (see
+  [Console accounts](#console-accounts)). The **Athlete** selector and the
+  proxied roster are narrowed to the account's grants; requests that name an
+  ungranted athlete are refused with `403 athlete_forbidden` before they reach
+  the runtime, and a zero-grant member sees no athletes at all.
 - The settings panel has an **Athlete** selector built from
   `GET /api/v1/athletes` on the runtime. The default is the catalog's
-  `defaultAthleteId`.
+  `defaultAthleteId` (for a member, the first granted athlete).
 - On every personal-data tool call, the Console **forces** the selected
   athleteId onto the arguments — the model cannot name or switch athletes, and
   a chat's system message states: *"This Console chat is scoped to athleteId X.
@@ -183,10 +286,14 @@ The Console shares the same per-athlete stores as MCP, but scoping is
   announces *"This chat is scoped to athlete **<id>**."*
 - `list_athletes` is exempt from forcing so the roster can be rendered.
 
-The dashboard is fetched through the authenticated Console origin: Chainlit
-middleware proxies `GET /api/v1/dashboard` and `GET /api/v1/athletes` to the
-runtime only when the Console's JWT cookie is valid (otherwise 401), so raw
-port 8787 does not need to be exposed.
+Console pages and chats reach the runtime through the authenticated Console
+origin: Chainlit middleware proxies the Console's API surface — `GET
+/api/v1/dashboard`, `GET`/`POST /api/v1/athletes` (POST is admin-only),
+`GET`/`PUT /api/v1/athlete-secrets` and `POST /api/v1/athlete-secrets/remove`
+(all admin-only), `GET /api/v1/threads/<id>/generation`, and the models,
+accounts, tool-server, and sync routes — to the runtime only when the Console's
+JWT cookie is valid (otherwise 401), so raw port 8787 does not need to be
+exposed.
 
 ## Model discovery (OpenCode Go)
 
@@ -205,8 +312,8 @@ disappeared from the live catalog.
 npm run discover:opencode-go -- --write ~/.catence/config.json
 ```
 
-Inside the Console's Models page, **Discover OpenCode Go models** runs the
-same merge for the current home without touching athlete data (runtime route
+Inside **Settings → Models**, **Discover OpenCode Go models** runs the same
+merge for the current home without touching athlete data (runtime route
 `POST /api/v1/models/discover`, proxied behind the Console login). Models can
 also be edited in place there — the update action rewrites the `console`
 section atomically and never stores secret values.
@@ -260,4 +367,8 @@ uv tool install --upgrade catence-console
   environment variables; set them in the shell and restart the Console.
 - **Runtime not reachable** — `catence-console doctor --home "$HOME/.catence"
   --mcp-url http://127.0.0.1:8787/mcp` checks the handshake; confirm the
-  runtime is running on that port and the protocol versions agree.
+  runtime is running on that port and the protocol versions agree.
+- **Locked out of the Console** — sign in with the environment break-glass
+  account (`CATENCE_CONSOLE_USERNAME`/`CATENCE_CONSOLE_PASSWORD_HASH`) and
+  restore access with `catence-console users` (reset a password, re-grant
+  athletes, or add a new admin).