@loicngr/kobo 2.1.25 → 2.1.28

package/AGENTS.md

@@ -6,7 +6,9 @@ Guidance for AI coding agents (Claude Code, Cursor, etc.) working on this reposi
 
 **Kōbō** (工房, Japanese for "workshop") orchestrates Claude Code and OpenAI Codex agents across isolated git worktrees. Each "workspace" is a self-contained mission with its own worktree, branch, agent sessions, optional dev server, optional Notion/Sentry context, and a dedicated MCP tools server. A Vue 3 UI lets the human track progress, read live agent output, review Git changes, and manage the lifecycle. A workspace can switch engines through a handoff to a fresh session while preserving its worktree and history.
 
-Single-user dev tool, local by default. The server binds `127.0.0.1` unless the opt-in "network access" setting is enabled, which binds all interfaces and gates non-loopback API/WS requests behind a shared token. Behind-a-reverse-proxy mode also requires the token for loopback API/WS requests; `/api/health` stays exempt. Host/Origin checks apply separately. No multi-tenant concerns.
+Single-user dev tool, local by default. The server binds `127.0.0.1` unless the opt-in "network access" setting is enabled. Operator HTTP access uses the network token or a 12-hour HttpOnly browser session; browsers use 60-second single-use path-bound tickets for WebSocket upgrades, never the operator token in the URL or localStorage. Behind-a-reverse-proxy mode also gates loopback operator requests. Rotation, network disable and proxy-mode changes revoke sessions, tickets and active WebSockets. `/api/health` stays exempt. Host/Origin checks apply separately; public proxy origin must be declared explicitly. No multi-tenant concerns.
+
+External `/api/mcp` and global stdio require dedicated hashed credentials with tool/workspace grants, expiry and revocation, even on loopback. Manage them through operator-only `/api/mcp-credentials`; global stdio uses `KOBO_MCP_TOKEN`. Managed workspace stdio uses per-launch `KOBO_MCP_SESSION_TOKEN` through OS-loopback-only `/api/internal-mcp`, never the operator token or direct SQLite writes. The backend enforces Plan/read-only permissions and revokes capabilities when stopping begins. Keep report/progress exceptions narrowly scoped. See [SECURITY.md](./SECURITY.md).
 
 ## Tech stack
 
@@ -103,7 +105,8 @@ src/
 │       ├── pages/                  # WorkspacePage, CreatePage, SettingsPage
 │       └── router/
 ├── mcp-server/                     # standalone MCP server spawned per workspace
-│   ├── kobo-tasks-server.ts        # entrypoint, registers tools
+│   ├── kobo-tasks-server.ts        # stdio bridge; forwards discovery/calls to authenticated backend
+│   ├── managed-mcp-dispatcher.ts   # workspace tool definitions/dispatch, executed in backend
 │   └── kobo-tasks-handlers.ts      # pure handlers (list_tasks, mark_task_done)
 ├── shared/                         # model catalogues, prompts, dialogue contracts, shared utilities
 └── __tests__/                      # backend Vitest suites; client tests live under client/src/__tests__/
@@ -149,6 +152,30 @@ src/
 
 Tasks have `role` (`work | finalization`) and structured `verification`. MCP and HTTP share transactional task mutations. An auto-loop task cannot become done without passing reported checks. Finalization runs after all other tasks/criteria, is invalidated by scope changes, and is mandatory before completion. The proof is agent-reported evidence, not server-side execution of arbitrary commands.
 
+## Provider account switching
+
+The usage popover integrates optional `ccswap` for Claude Code and Codex. Select
+accounts for the viewed session's engine, falling back to the workspace engine.
+Missing executable hides account controls; it must not hide existing Claude
+usage. Codex account support is separate from quota snapshot support.
+
+`provider-accounts-service.ts` owns subprocess invocation and sanitization. Use
+provider allowlists, numeric slots and bounded `execFile`, never shell text. Keep
+credential mutations serialized with their validation. Return only display
+metadata; do not forward raw CLI JSON, stderr, tokens or credential paths. Inherit
+the Kōbō process user, HOME, PATH and credential-directory environment: in Docker,
+the CLI must run inside that container, not on the host. Do not install tools or
+perform real switches in tests.
+
+A switch changes the provider-wide credential store, not a workspace identity.
+Do not automatically stop agents, migrate conversations, copy settings/skills or
+promise that an existing process hot-reloads authentication. Invalidate Claude
+quota data around switches and reject results from earlier in-flight polls.
+Keep frontend requests scoped across provider/session changes and handle missing,
+empty, disabled, unrecognized and failed account states without automatic retries.
+See [configuration](./CONFIGURATION.md#switch-claude-code-and-codex-accounts-with-ccswap)
+and [VPS setup](./docs/vps-projects-and-skills.md#switch-engine-accounts-inside-the-container).
+
 ## Persistent memory
 
 Kōbō memory is independent of provider chat history/native memory and shared by Claude Code and Codex. `memoryMode` is a global setting defaulting to `hybrid`: Manual permits reads only; Hybrid applies workspace writes and proposes project/global writes; Automatic applies writes to the explicitly targeted scope. Mode is checked per operation, so a setting change affects existing agent sessions; pending/rejected proposals are never automatically approved or revived. Plan/review/report-only capabilities cannot write.
@@ -268,7 +295,7 @@ also bypasses the auto-loop next-iteration UI path; normal backend immediate
 message delivery pauses a ready loop. Do not flush existing queues on toggle,
 remove compaction/permission/handoff guards, or queue rejected forced sends.
 
-`POST /api/mcp` exposes stateless Streamable HTTP discovery/dialogue tools, behind the existing Host/Origin and network-token gates. The global stdio server forwards dialogue calls through this backend so agent runtime ownership remains centralized. `workspace-message-service.ts` shares delivery with WebSocket chat.
+`POST /api/mcp` exposes stateless Streamable HTTP discovery/dialogue tools, behind Host/Origin, network enablement and dedicated MCP credential gates. The global stdio server forwards dialogue calls through this backend so agent runtime ownership remains centralized. `workspace-message-service.ts` shares delivery with WebSocket chat.
 
 Optional `send_workspace_message.idempotency_key` uses `mcp_message_requests` (migration v43). Reserve before dispatch, preserve fingerprints and terminal outcomes, and never automatically resend an unfinished request after restart. The user event and accepted receipt commit in one SQLite transaction; broadcast follows commit. Dispatch may precede persistence, so interrupted requests are explicitly `delivery_unknown`, not an exactly-once execution promise. The backend alone calls `reconcileMessageRequests` on startup. History retention does not delete the ledger; workspace deletion cascades it.
 

package/CHANGELOG.md

@@ -4,6 +4,21 @@ All notable changes to Kōbō are documented here. The format is based on
 [Keep a Changelog](https://keepachangelog.com/). Each release is an `## <version>`
 section — the in-app "What's new" dialog reads this file.
 
+## 2.1.28
+
+- fix(ci): authenticate packaged mcp smoke tests
+- fix(security): harden authentication and mcp access
+- feat(models): Add Haiku 5.5
+
+## 2.1.27
+
+- fix(security): harden authentication and mcp access
+- feat(models): Add Haiku 5.5
+
+## 2.1.26
+
+- feat: switch Claude and Codex accounts with ccswap
+
 ## 2.1.25
 
 - feat: improve merge options, diff controls and progress reporting

package/CONFIGURATION.md

@@ -887,11 +887,28 @@ destination worktree and sends file/image references to the agent and chat.
 Keyed retries include attachment identity and never upload or send twice. See
 [Sending files and images](src/mcp-server/README.md#sending-files-and-images).
 
-Remote HTTP clients follow the [network access](#network-access) settings and supply the Kōbō token as `Authorization: Bearer <token>` or `X-Kobo-Token`. The endpoint uses the same Host/Origin and reverse-proxy policy as the rest of the backend. No network setting is changed automatically.
+Every external MCP client, including loopback and global stdio clients, must use
+a dedicated MCP key. The operator token and browser session cookie are not accepted
+by `/api/mcp`. Send the MCP key as `Authorization: Bearer <key>`. The endpoint retains the same Host/Origin, network-access and
+reverse-proxy policy. No network setting changes automatically.
+
+Keys are independent, stored only as hashes and have explicit tool and workspace
+grants, optional expiration and individual revocation. The default tool grant is
+read-only; writes and destructive tools require an explicit grant. Each key must
+select workspace IDs or deliberately grant all workspaces. An MCP key cannot
+authenticate to operator REST, terminal or credential-management endpoints.
+
+An authenticated operator manages credentials through `/api/mcp-credentials`:
+GET lists metadata and available tools; POST accepts `name`, optional `tools`,
+`workspaceIds` or `allWorkspaces: true`, and optional ISO `expiresAt`; DELETE
+`/api/mcp-credentials/<id>` revokes one key. Creation returns the raw `token` once.
+Do not send that token to logs, commit it, or reuse it as the operator credential.
 
 See [Connect an external LLM](src/mcp-server/README.md#connect-an-external-llm) for connection examples, tool arguments, cursor polling and authentication details.
 
-The **External LLM access (MCP)** panel within global Network access settings provides copyable URLs and HTTP/stdio configurations for this running installation. Previews use token placeholders; copying a configuration with the real token is a separate action. Set a client name to identify its messages and question answers in workspace history.
+The **External LLM access (MCP)** panel within global Network access settings
+provides HTTP/stdio configuration templates. Supply the dedicated MCP key for the
+intended client. Client names are display labels, not permission identities.
 
 External senders can supply `idempotency_key` once per intended message and reuse it on retries. The durable receipt survives backend restarts and event retention. An uncertain delivery is explicitly reported and never automatically sent again; see the MCP guide for response codes and limitations.
 
@@ -1058,8 +1075,9 @@ To disable network access, toggle it off and restart again.
 
 ### The network access token
 
-When network access is enabled, every non-loopback HTTP request and every
-non-loopback WebSocket connection must supply a shared token.
+When network access is enabled, remote API and WebSocket access requires
+operator authentication. The shared operator token opens a browser session;
+external MCP clients use separate scoped credentials.
 
 - **Auto-generated**: Kōbō generates a random token the first time you enable
   the feature. You never have to type one in.
@@ -1075,11 +1093,12 @@ non-loopback WebSocket connection must supply a shared token.
 
 **Option A: QR code (recommended for phones)**
 
-The Settings panel shows a QR code encoding
-`http://<lan-ip>:<port>/?token=<token>`. Scan it with your phone's camera
-while on the same Wi-Fi network; the browser opens directly to a pre-authenticated
-session. The token is stored in the browser's `localStorage` under
-`kobo:network-token` so subsequent visits don't require re-scanning.
+The Settings panel shows a QR code using a URL fragment (`#token=<token>`),
+which browsers do not send in HTTP requests. The client immediately removes the
+fragment and exchanges the token for a 12-hour HttpOnly, SameSite=Strict session
+cookie (Secure for a configured HTTPS proxy). The operator token is not retained in localStorage.
+Previously stored tokens are removed during migration. Use QR links only on
+trusted devices; do not publish or bookmark a credential-bearing link.
 
 **Option B: manual URL**
 
@@ -1087,22 +1106,27 @@ session. The token is stored in the browser's `localStorage` under
    `http://<lan-ip>:<port>/`).
 2. Open it on the remote device.
 3. A login dialog appears: paste the token from the Settings panel and confirm.
-4. The token is stored in `localStorage`; subsequent visits auto-authenticate.
+4. The HttpOnly session cookie authenticates subsequent visits until expiry or revocation.
 
 **Host machine (localhost)**: connect to `http://localhost:<port>` as usual.
 No token is needed unless **Behind a reverse proxy** is enabled.
 
 ### Token transport
 
-| Connection type | How to supply the token |
+| Connection type | Authentication |
 |---|---|
-| HTTP requests | `X-Kobo-Token: <token>` header |
-| MCP HTTP requests (`/api/mcp`) | `X-Kobo-Token` or `Authorization: Bearer <token>` |
-| WebSocket connections | `?token=<token>` query parameter on the upgrade URL |
-
-The Kōbō browser client handles both automatically once the token is stored in
-`localStorage`. Third-party scripts or API consumers must supply the header or
-query param manually.
+| Browser API requests | HttpOnly session cookie after login |
+| Operator scripts / REST | `X-Kobo-Token: <operator-token>` header |
+| External MCP HTTP (`/api/mcp`) | Dedicated MCP key as `Authorization: Bearer <key>` |
+| Browser WebSocket connections | Short-lived, single-use ticket in the upgrade URL, bound to its WS path |
+
+The browser handles session and ticket exchanges automatically. Tickets expire
+after 60 seconds and cannot be replayed, reused for a different terminal, or used
+after their session expires. The permanent operator token is no longer accepted
+in a WebSocket query string. Rotation, disabling network access or changing proxy
+mode invalidates browser sessions, pending tickets and existing main/terminal
+WebSocket connections. Agent processes are not stopped by credential revocation.
+Server restart also expires browser sessions.
 
 The IP address used for the loopback exemption is taken **from the OS socket**,
 never from forwarded headers (`X-Forwarded-For` etc.), so a remote client cannot
@@ -1154,19 +1178,15 @@ Practical consequences:
   count as the real interface. In development the Quasar dev server is the one
   exception, since it proxies to the backend and so never matches the `Host`;
   the `dev` npm script declares it through `KOBO_DEV_CLIENT_ORIGIN`.
-- **Behind-a-reverse-proxy mode accepts any host by default**, because only the
-  operator knows the expected domain. Declare it with
-  `KOBO_NETWORK_ACCESS_PROXY_HOST` (see below) to close that; the bundled
-  `docker-compose.example.yml` and `docker-compose.local-traefik.yml` do. That
-  mode also disables the loopback exemption, so every `/api/*` request has to
-  carry the token — but the SPA itself is served outside `/api/*` and behind no
-  token, so without a declared hostname a rebinding page can be served the real
-  interface and ask the user to paste their token into it.
+- **Behind-a-reverse-proxy mode requires a declared public hostname.** Set
+  `KOBO_NETWORK_ACCESS_PROXY_HOST`; missing or invalid configuration rejects
+  public requests. Internal loopback clients remain reachable but still require
+  authentication. The bundled proxy Compose files configure this explicitly.
 
 #### `KOBO_NETWORK_ACCESS_PROXY_HOST`
 
-Set it to the domain your proxy serves Kōbō under, and the host check is
-enforced in behind-a-reverse-proxy mode instead of being skipped:
+Set it to the public origin your proxy serves Kōbō under. This is required in
+behind-a-reverse-proxy mode:
 
 ```yaml
 environment:
@@ -1175,9 +1195,33 @@ environment:
   - KOBO_NETWORK_ACCESS_PROXY_HOST=kobo.example.com
 ```
 
-A scheme and a port are accepted and ignored (`https://kobo.example.com:8443`
-reads as `kobo.example.com`). Loopback stays reachable so a local healthcheck
-keeps working. Leaving it unset preserves the previous behaviour.
+A bare hostname means HTTPS. For a nonstandard port, set the complete origin,
+e.g. `https://kobo.example.com:8443`. Browser Origin checks compare the scheme,
+hostname and port exactly. Local HTTP proxy staging must explicitly declare
+`http://kobo.localhost`. Paths, credentials, query strings and fragments are
+invalid. Loopback healthchecks and authenticated internal calls remain reachable.
+Leaving this variable unset rejects public proxy traffic.
+
+### Browser response protections
+
+The server sends `Content-Security-Policy: frame-ancestors 'self'` and
+`X-Frame-Options: SAMEORIGIN`, preserving Kōbō's split panes while blocking
+embedding by another site. It also sends `X-Content-Type-Options: nosniff`,
+`Referrer-Policy: no-referrer` and `Cache-Control: no-store` for API responses.
+The public HTTPS Compose examples add one-year HSTS at Traefik, without applying
+it to subdomains or HTTP-only local staging. Kōbō does not trust forwarded headers
+to decide whether a connection is HTTPS. A broader script/style CSP is not enabled;
+it needs separate compatibility testing with Quasar and Monaco.
+
+Application limits apply per OS peer address (forwarded addresses are not trusted):
+3,000 API requests per minute and 20 login attempts per minute. Requests exceeding
+these limits receive HTTP 429. MCP permits 32 concurrent requests, with at most
+four bodies larger than 1 MiB or of unknown/chunked length; ordinary attachment
+uploads also have four slots. Authentication runs before body buffering. Main
+WebSocket messages are capped at 1 MiB, terminal messages at 128 KiB; sockets
+have per-peer and global caps and inbound message-rate limits. Behind a proxy,
+clients share the proxy peer's bucket, so configure client-IP limits at the proxy
+for deployments with many simultaneous clients.
 
 ### Security caveats
 
@@ -1300,7 +1344,7 @@ retrieved once — see [Token / login flow](#token--login-flow).
 | `${HOME}/.claude.json:/root/.claude.json` | RW | Claude Code auth + MCP server registrations. **Must already exist as a file on the host** (run `claude /login` locally first if it doesn't) — Docker silently creates an empty *directory* instead of erroring on a missing bind-mount source, which breaks auth in a confusing way. |
 | `${HOME}/.claude:/root/.claude` | RW | Claude Code's full state directory (skills/plugins cache, session transcripts, memory) — Claude Code writes into this tree during normal operation. |
 | `${HOME}/.codex:/root/.codex` | RW | Codex's full state directory (`auth.json`, `config.toml`). Harmless to mount even if you only use Claude Code. |
-| `/var/run/docker.sock:/var/run/docker.sock` | RW, enabled in `example.yml`, opt-in in `vps.yml` | Lets the dev-server panel start/stop/tail logs for your projects' own `docker compose` stacks. **DANGER**: grants the container root-equivalent control over the host — anyone who can run a command inside `kobo` can spawn a privileged container that mounts the host filesystem. Remove this line if you don't need the dev-server panel. |
+| `/var/run/docker.sock:/var/run/docker.sock` | RW, opt-in in both `example.yml` and `vps.yml` | Lets the dev-server panel start/stop/tail logs for your projects' own `docker compose` stacks. **DANGER**: grants the container root-equivalent control over the host — anyone who can run a command inside `kobo` can spawn a privileged container that mounts the host filesystem. Leave this mount commented out unless required. |
 
 ### Ports
 
@@ -1316,25 +1360,32 @@ reachable, matching the real production posture.
 
 ### Token / login flow
 
-All four files pre-enable network access via env vars, so there's no interactive Settings-UI step.
-Retrieve the auto-generated token from the container's boot log, then bookmark the token-bearing URL:
+All four files pre-enable network access via environment variables. Startup logs
+never contain the token. Retrieve it deliberately from a trusted local terminal:
 
 ```bash
-docker compose -f <compose-file> logs kobo | grep Token
+docker compose -f <compose-file> exec kobo node -e 'const fs = require("node:fs"); console.log(JSON.parse(fs.readFileSync(process.env.KOBO_HOME + "/settings.json", "utf8")).global.networkAccessToken)'
 ```
 
-Open `http://<host>/?token=<token>` (exact host depends on the file — see the walkthroughs below).
-The token is stored in the browser's `localStorage`, so you only paste it once per browser.
+Open the plain application URL and paste the token into its login dialog. Do not
+put the token in a URL, command argument, log collector or shared transcript.
+For an npm installation, read `networkAccessToken` from your private
+`$KOBO_HOME/settings.json` (default `~/.config/kobo/settings.json`).
+Kōbō restricts its home to mode `0700` and settings, temporary settings and
+settings backups to `0600`, including existing files on startup or the next disk read.
+
+Existing logs from older releases may still contain a valid token. After upgrading,
+rotate it from Settings and apply your log-retention policy to retained copies.
+Kōbō does not delete historical logs automatically.
 
 ### Quick local test — `docker-compose.local.yml`
 
 ```bash
 docker build -t kobo:local .                          # once
 docker compose -f docker-compose.local.yml up -d
-docker compose -f docker-compose.local.yml logs kobo | grep Token
 ```
 
-Open `http://localhost:3000/?token=<token from above>`.
+Open `http://localhost:3000/`; retrieve the token using [Token / login flow](#token--login-flow) if prompted.
 
 By default the file bind-mounts `./kobo-projects` (next to it) at `/projects` — put a real git repo
 in there (or set `KOBO_PROJECTS_DIR` to point elsewhere) before creating a workspace. When you get
@@ -1353,10 +1404,9 @@ and lose all Kōbō state).
 ```bash
 docker build -t kobo:local .                          # once, if not already built
 docker compose -f docker-compose.local-traefik.yml up -d
-docker compose -f docker-compose.local-traefik.yml logs kobo | grep Token
 ```
 
-Open `http://kobo.localhost/?token=<token from above>` — `.localhost` resolves to `127.0.0.1` on
+Open `http://kobo.localhost/` and sign in using [Token / login flow](#token--login-flow) — `.localhost` resolves to `127.0.0.1` on
 most OSes without touching `/etc/hosts`. This exercises the exact routing/auth/mount setup used by
 `docker-compose.example.yml`, minus a real domain and TLS certificate.
 
@@ -1386,17 +1436,16 @@ Before using it:
 2. Replace `kobo.example.com` with your real domain, and `you@example.com` with a real email (Let's Encrypt account).
 3. Populate a `.env` file next to the compose file with `GH_TOKEN` / `GITLAB_TOKEN` if you use the forge integration.
 4. Point every bind mount (`~/.ssh`, `~/.gitconfig`, `~/.claude.json`, `~/.claude`, `~/.codex`) at real paths on the host — see [Volumes](#volumes) for what each one is for, in particular the "`~/.claude.json` must already exist as a file" gotcha.
-5. Decide whether you need the Docker-socket passthrough (dev-server panel). If not, delete that volume line — see the DANGER note in [Volumes](#volumes).
+5. Leave the Docker socket unmounted unless your project workflows require it; opting in grants host-level control. See [Volumes](#volumes).
 6. Network access + behind-a-reverse-proxy are already pre-enabled via the `KOBO_NETWORK_ACCESS_*` env vars in the file — no manual bootstrap step.
 
-Bring it up, grab the token, bookmark the URL:
+Start it, then retrieve the token using the login flow above:
 
 ```bash
 docker compose -f docker-compose.example.yml up -d
-docker compose -f docker-compose.example.yml logs kobo | grep Token
 ```
 
-Open `https://kobo.example.com/?token=<token>`. SSH access: `ssh -p 2222 root@<host>` (key-based
+Open `https://kobo.example.com/` and sign in using [Token / login flow](#token--login-flow). SSH access: `ssh -p 2222 root@<host>` (key-based
 only). See [Ports](#ports) and [Volumes](#volumes) above for the full rationale on the Docker socket
 and SSH tradeoffs before deploying this to a real machine.
 
@@ -1455,9 +1504,8 @@ An old image alone is not a complete rollback after database migrations.
   — check `docker inspect <container> --format '{{json .State.Health}}'`. This should not happen on
   a current image (`/api/health` is exempt from the token gate, see [The image](#the-image)); if you
   see a 401 in the health log on a custom-built image, you're missing that exemption.
-- **`docker compose logs kobo | grep Token` returns nothing** — network access wasn't enabled at
-  boot. Confirm `KOBO_NETWORK_ACCESS_ENABLED=true` is actually set in the `environment:` block for
-  the `kobo` service.
+- **The token is absent from startup logs** — this is intentional. Use the local
+  [token retrieval command](#token--login-flow), then the browser login dialog.
 
 ## Agent runtimes
 
@@ -1473,7 +1521,7 @@ claude /login
 
 Kōbō talks to the embedded [`@anthropic-ai/claude-agent-sdk`](https://github.com/anthropics/claude-agent-sdk-typescript), which reuses the same login. The `claude` CLI is **not** required at runtime; you only need it for `/login`, `mcp add`, and other one-off setup commands. As a fallback you can export `ANTHROPIC_API_KEY` instead.
 
-The model selector is populated from [`src/shared/models.ts`](./src/shared/models.ts), also used by backend validation. This checkout includes Fable 5.1, Mythos 5, Opus 5, Opus 4.8, Sonnet 5 and older variants. Pick the default in **Settings → Agents**. Catalogue entries describe what Kōbō offers; provider access still depends on your account. `auto` leaves model selection to the runtime.
+The model selector is populated from [`src/shared/models.ts`](./src/shared/models.ts), also used by backend validation. This checkout includes Fable 5.1, Mythos 5.1/5, Opus 5.5, Sonnet 5.5, Haiku 5.5 (`claude-haiku-5-5`) and older variants. Pick the default in **Settings → Agents**. Catalogue entries describe what Kōbō offers; provider access still depends on your account. `auto` leaves model selection to the runtime.
 
 #### Immediate chat messages
 
@@ -1549,6 +1597,65 @@ When a Codex session is already working, **Send now** sends a queued chat messag
 
 The selector reads [`src/shared/codex-models.ts`](./src/shared/codex-models.ts). This checkout lists GPT-6 Astra, GPT-5.6 Sol/Terra/Luna, GPT-5.5 and older variants; availability depends on your account and authentication. Kōbō exposes effort values `auto`, `none`, `low`, `medium`, `high`, `xhigh`, and `max`, as declared in the engine's capabilities. The runtime must support the selected model/effort combination. Both selectors switch when you change the engine.
 
+### Switch Claude Code and Codex accounts with ccswap
+
+The usage popover in the chat footer can show the current **managed account**
+and switch to another account registered in [ccswap](https://github.com/errhythm/ccswap).
+It follows the selected session's engine, falling back to the workspace engine.
+Choose an account and explicitly click **Switch account**. Claude Code and Codex
+have separate account lists; switching one does not switch the other.
+
+ccswap is optional and is not bundled with Kōbō. Without its executable, Kōbō
+shows no account selector or installation notice; existing Claude usage indicators
+continue to work. Codex account controls do not imply that Claude-style quota
+buckets are available for Codex.
+
+Install and register accounts **as the same operating-system user and in the
+same environment as the Kōbō server**. The integration uses ccswap's JSON CLI
+(tested with 0.37.0). With `uv` already installed:
+
+```bash
+uv tool install ccswap
+# After logging into Claude Code with each account:
+ccswap add
+# After `codex login` with each Codex account:
+ccswap codex add
+ccswap list --provider claude
+ccswap codex list
+```
+
+Register the current login before switching so ccswap can preserve it. Account
+registration, login renewal, aliases and removal remain CLI operations. A disabled
+account cannot be selected in Kōbō. If no managed account matches the current
+login, the panel reports an unknown account rather than guessing from a slot.
+
+**Scope:** switching changes that provider's active credentials for the server
+user, shared by all Kōbō workspaces and other tools using that same login store.
+It is not a per-workspace account assignment. Kōbō keeps its worktrees, conversation
+history, settings and skills; it does not copy profiles or automatically restart
+agents. The displayed account identifies the active credential store, not proof
+that an already-running process has adopted it. Stop and resume the affected
+sessions if they still use the previous account, especially with Codex. Existing
+API-key or custom-provider authentication can take precedence over a saved login.
+
+The adapter inherits absolute `CLAUDE_CONFIG_DIR` on Linux and `CODEX_HOME`.
+Empty or relative authentication-directory overrides are refused: server and workspace
+processes can have different working directories. Claude switching is also refused
+with `CLAUDE_SECURESTORAGE_CONFIG_DIR` set, or with any nonempty `CLAUDE_CONFIG_DIR`
+on macOS (even the explicit default path), because the corresponding Keychain
+write is not verified by this integration. Use the native login workflow for
+those configurations.
+
+Claude usage is invalidated and refreshed after a switch. A failed refresh is
+not shown as the new account's old quota. Switching failures do not trigger an
+automatic retry: refresh the account list to check the actual state before trying
+again. The server exposes display metadata only, never ccswap's credential files
+or raw command output.
+
+For Docker/VPS, installing ccswap on your PC or on the VPS host is insufficient:
+it must be reachable on **Kōbō's container PATH**, with the same runtime home and
+credential-directory environment. See [VPS account setup](./docs/vps-projects-and-skills.md#switch-engine-accounts-inside-the-container).
+
 ### Permission modes
 
 Claude Code uses SDK permission modes; Codex uses sandbox and approval flags. These controls differ by engine. A Git worktree itself is not a security boundary.

package/README.md

@@ -64,7 +64,8 @@ Kōbō's production build is an installable PWA — use your browser's **Install
 - **Interactive Q&A**: an agent can pause mid-session to ask you a question through the UI instead of guessing.
 
   ![Agent asking a clarifying question, awaiting the user's answer](docs/assets/images/agent-question.png)
-- **Quota-aware**: 5-hour / 7-day Claude usage and Codex rate-limit buckets live in the footer; auto-loops can resume after a reset. Explicit cron/wakeup schedules can also resume work; a manual workspace does not restart solely because its quota resets.
+- **Quota-aware**: 5-hour / 7-day Claude usage is shown in the footer; engine-reported rate limits guide quota waits; auto-loops can resume after a reset. Explicit cron/wakeup schedules can also resume work; a manual workspace does not restart solely because its quota resets.
+- **Account switching**: with optional [ccswap](https://github.com/errhythm/ccswap), view and switch the active Claude Code or Codex account from the usage popover. Credentials are shared across workspaces using that engine; [setup and session behavior](./CONFIGURATION.md#switch-claude-code-and-codex-accounts-with-ccswap).
 - **Disk-space purge**: reclaim a merged workspace's `node_modules`/`vendor` weight without losing its chat history — see [`CONFIGURATION.md`](./CONFIGURATION.md#auto-purge-worktree-on-pr-merged).
 - **Lifecycle scripts**: shell scripts run on setup, cleanup, archive, session end, PR merge, or auto-loop stop, with output streamed into the chat.
 - **Observability**: a per-session timeline (duration, tools, tokens, errors) and a downloadable redacted diagnostic JSON.

package/SECURITY.md

@@ -17,11 +17,37 @@ the account running Kōbō and the selected engine's permission mode. A Git work
 isolates a checkout, not processes, credentials or the filesystem. Only open
 projects and configure executable hooks/integrations you trust.
 
-The default listener is loopback. LAN access uses one shared token; it is not
-per-user authorization. Behind a reverse proxy, enable the corresponding setting
-so loopback API/WebSocket requests also require that token. Health checks are
-exempt. Host and Origin validation remain separate protections. Use HTTPS or a
-trusted private network; do not offer this installation as a shared public service.
+The default listener is loopback. Network access uses an operator token; it is not
+per-user authorization. Browsers exchange it for a 12-hour HttpOnly, SameSite=Strict
+cookie (Secure behind HTTPS proxies), never persist it in localStorage, and obtain
+60-second single-use tickets for each WebSocket path. Rotation, disabling network
+access, or changing proxy mode revokes sessions, pending tickets and active sockets,
+including terminals. Restarting Kōbō also expires sessions. A settings change may
+establish a new session for the browser that performed it using the returned token.
+
+Behind a reverse proxy, enable the corresponding setting and declare the exact
+public origin with `KOBO_NETWORK_ACCESS_PROXY_HOST` (bare domains default to HTTPS).
+Health checks are exempt. Host and Origin validation remain separate protections.
+Use HTTPS or a trusted private network; do not offer this installation as a shared
+public service. Configure HSTS at the HTTPS terminator. The supplied public Compose
+examples include it. Socket and request size/rate/concurrency limits are bounded
+in-process; proxy limits should complement them. Client IPs come from OS sockets,
+so callers behind the same proxy share limits.
+
+External MCP requires a separately issued Bearer credential, including on loopback.
+Each key has explicit tool and workspace grants, optional expiry, and independent
+revocation; only its hash is stored. The UI defaults to read-only tools, selected
+workspaces and 30-day expiry. Operator cookies/tokens cannot authenticate `/api/mcp`,
+and an MCP key cannot authenticate operator APIs or terminal upgrades. Global stdio
+forwards to that endpoint using `KOBO_MCP_TOKEN`; it does not read the database offline.
+
+Managed workspace stdio uses a per-launch `KOBO_MCP_SESSION_TOKEN` through the local
+`/api/internal-mcp` dispatcher. The backend owns authorization and database writes;
+Plan and read-only review launches cannot invoke mutating managed tools even if the
+provider approves a tool. Launch capabilities are revoked when stopping begins.
+Operational progress and narrowly scoped review/handoff reports retain their own
+capabilities. This tool boundary does not sandbox arbitrary code executed by an
+agent or other integrations running as the same OS account.
 
 Git workflow preferences express which automatic actions are wanted. They are not
 a sandbox for arbitrary shell commands or external MCP tools. Claude and Codex
@@ -33,7 +59,8 @@ network token.
 
 KOBO_HOME stores conversations, workspaces, backups and settings. Direct integration
 commands and credentials live in `integrations.json`, written atomically with mode
-0600 on Unix. They are plaintext local secrets: protect the host account and backups.
+0600 on Unix. Settings and their temporary files/backups are also private (0600),
+and new Kōbō home directories use 0700. They are plaintext local secrets: protect the host account and backups.
 They are excluded from settings exports and are never returned by the connection
 status API. A replacement connection must be entered in full. MCP error text and
 stderr are withheld because third-party processes may echo secrets.