Add external auth mode that trusts the gateway actor header

[alex-clickhouse]

What

This adds an external authentication mode. With NERVE_AUTH_MODE=external, a gateway in front of Nerve signs people in. The gateway names the person behind each request in the X-Nerve-Actor-Context header, and Nerve acts as that person. Local mode (the default) keeps its behavior.

Stacked on #467. The hosted channel in #465 already verifies gateway-signed tokens (nerve/channels/hosted/auth.py). A later signature check for the actor header can reuse that key handling. This PR also changes files that the stack changes: server.py, the nerve doctor checks, the MCP HTTP endpoint and docs/config.md.

How

Mode

• create_app() reads NERVE_AUTH_MODE once and pins it. A configuration reload does not change the mode. The values are local (also used when the variable is not set) and external. Any other value stops the server and nerve start with an error.
• There is no YAML key. Lockdown drops config.yaml keys and a reload replaces the configuration object, so the environment is the only source.

Requests

• decode_actor_context() splits the compact JWS and decodes its payload. It reads principal_id (a UUID, stored as a lower-case string) and profile.display_name. The signature is not checked. REST requests and the WebSocket upgrade both use this one function, so a later verifier replaces only this function.
• When the header is present, Nerve ignores Authorization, the nerve_token cookie and ?token=. A header that Nerve cannot read gives 401.
• Session tokens and legacy tokens give 401 on REST, /ws, the MCP endpoint and the worker-token route. System and MCP tokens still give the system actor.

Data

• AccountStore.upsert_external_actor() adds the actor_refs row on first sight and writes the display name when it changes. This happens before the request writes rows that refer to the actor through foreign keys. An in-process map skips the statement when the name is the same, so a normal request does not take the SQLite write lock.
• A header that names the system actor makes the system_actor_cannot_be_replaced trigger abort the insert. Nerve gives 401 for this, not 500.

Routes

• The account and setup routes are not registered.
• POST /api/auth/login gives 404.
• GET /api/auth/status adds mode. In external mode it does not read login state, and login keeps the fail-closed value.

Startup

• In external mode, startup creates no account. It keeps the JWT signing secret, which system and MCP tokens use. It deletes a setup token left from local mode.
• nerve doctor does not warn about a missing local account.
• Startup logs a warning that the header is trusted without a signature check.

Why

Hosted agents sign people in at the gateway, so local accounts and session tokens do not apply. Nerve must know which person sends each message so that it can attribute the message.

Limits

Do not deploy this mode yet. Nerve trusts the header without a signature check, so any caller that can reach Nerve can act as any person. Before external mode is used outside a local stack, either only the gateway must be able to reach Nerve, or Nerve must verify the signature. docs/config.md states this.

Testing

• .venv/bin/pytest tests/ -q: 4800 passed, 37 skipped, 0 failed.
• New tests/test_external_auth.py covers:
  • mode parsing, the pin, reloads and startup errors;
  • header decoding: malformed values, values that are not UUIDs, upper-case UUIDs, non-UTF-8 input and JSON that is nested too deep;
  • actor rows: first sight, a name change, and the system actor ID;
  • two principals in concurrent requests, with distinct sessions.created_by_actor_id and messages.actor_id;
  • session tokens refused on REST, /ws, the MCP endpoint and worker-token, while system and MCP tokens work;
  • the removed routes and the mode field;
  • WebSocket admission, a fixed actor per connection, and message attribution;
  • startup, nerve init, nerve start and nerve doctor in external mode.
• Existing tests: only exact-equality checks of GET /api/auth/status changed, to add "mode": "local".

🤖 Generated with Claude Code