docs(auth): document optional authentication setup

- Explain opt-in configuration, protected surfaces, migrations and cookie behavior.
- Document operator CLI, MCP bearer use, cleanup, and supported local origins.
This commit is contained in:
agent committed 2026-11-09 15:50:12 -05:00
1 parent d4d9bceb98
commit 9bdba32a34
5 files changed
+59 -2

No files matched your search

+6
View File
@@ -35,6 +35,12 @@
Everything runs in one container built from the root `Dockerfile`: the server serves the API, MCP and Swagger, and also the built client. See [development.md](development.md) for running it.
## Optional authentication boundary
Account authentication is off unless `AUTH_ENABLED=true`. When enabled, the global guard protects REST and MCP controller routes and the run-events stream. The public routes are `GET /health`, `GET /healthz`, `GET /manifest.json` and `POST /api/v1/auth/login`; the manifest reports the auth-enabled flag so the client can choose its login flow. UI assets and the Swagger UI remain reachable, but API operations require authentication. Protected requests accept a bearer token or the `AUTH_COOKIE_NAME` cookie (`liqa_auth` by default). Browser login sets an HttpOnly, SameSite=Strict cookie and logout revokes the presented token and expires the cookie; HTTPS requests also get the Secure attribute. See [development.md](development.md#enabling-authentication) for operator setup and lifecycle details.
The authentication service stores users and hashed revoked-token identifiers in SQLite. Revocation records are retained through token expiry, then removed at startup and by the `AUTH_REVOKED_TOKEN_CLEANUP_CRON` job (`0 3 * * *` by default); no cleanup job is registered while auth is disabled. Authentication checks that the token is not revoked and that its account still exists, so deleting an account invalidates its outstanding tokens at the next request.
## Server components (`server/src/`)
- **McpService** (`mcp/`) registers the MCP tools and delegates to the services below. Each request gets a fresh MCP server over the Streamable HTTP transport.