From 9bdba32a34afdd8249c19a3d177ccb2b2b3c02e6 Mon Sep 17 00:00:00 2001 From: agent Date: Mon, 9 Nov 2026 15:50:12 -0500 Subject: [PATCH] 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. --- .env.example | 10 ++++++++++ README.md | 2 ++ docs/architecture.md | 6 ++++++ docs/development.md | 30 ++++++++++++++++++++++++++++-- docs/mcp.md | 13 +++++++++++++ 5 files changed, 59 insertions(+), 2 deletions(-) diff --git a/.env.example b/.env.example index cd5d119..e97c15a 100644 --- a/.env.example +++ b/.env.example @@ -8,6 +8,16 @@ # NODE_ENV=development # PORT=3000 +## Optional account authentication (disabled unless explicitly enabled) +# AUTH_ENABLED=true +## Required when AUTH_ENABLED=true. Set a private, high-entropy value outside source control. +# AUTH_JWT_SECRET=replace-with-a-private-random-secret +## Browser cookie name and default JWT lifetime +# AUTH_COOKIE_NAME=liqa_auth +# AUTH_JWT_EXPIRES_IN=24h +## Expired logout revocations are cleaned at startup and on this cron schedule. +# AUTH_REVOKED_TOKEN_CLEANUP_CRON=0 3 * * * + ## Origins allowed to call the API cross-origin (comma separated). Default: the ## Vite dev server (http://localhost:5173) in development, the compose port ## (http://localhost:13000) in production diff --git a/README.md b/README.md index f8e7e1b..7929ca8 100644 --- a/README.md +++ b/README.md @@ -12,6 +12,8 @@ docker compose up -d --build No configuration is needed: every setting has a default. To override one, copy `.env.example` to `.env` and uncomment it. +Authentication is **disabled by default**. To enable operator-managed accounts, set `AUTH_ENABLED=true` and provide a private `AUTH_JWT_SECRET`; then rebuild/restart the service and provision an account with the CLI. See [operator authentication](docs/development.md#operator-account-commands) for setup and browser/API usage. Existing deployments remain unauthenticated until explicitly enabled. + Everything is served from one container at **http://localhost:13000**: the UI at `/`, the REST API at `/api/v1`, MCP at `/mcp`, Swagger at `/docs`. Data is kept in `./data/`. To see it work, import and run the [self-test example](examples/self-test/): a scenario that tests liqa itself using an environment, a credential and snippets. diff --git a/docs/architecture.md b/docs/architecture.md index 9a81a2d..6acf7da 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -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. diff --git a/docs/development.md b/docs/development.md index 970194f..5c5d578 100644 --- a/docs/development.md +++ b/docs/development.md @@ -41,6 +41,11 @@ All settings are validated at startup by `server/src/config/app.config.ts`. | `RUN_LOG_DATA_COLLAPSE_LINES` | `5` | Same, for the number of lines | | `CLIENT_DIR` | *(empty)* | Directory with the built client to serve at `/` (the Docker image sets it to `client`); empty means the server doesn't serve the UI | | `PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH` | _(Playwright default)_ | Path to a Chromium binary to use instead of Playwright's own. Not set in Docker: the image ships Playwright's `chromium-headless-shell` (matching the Playwright version) under `PLAYWRIGHT_BROWSERS_PATH=/ms-playwright`. | +| `AUTH_ENABLED` | `false` | Opt-in account authentication. With the default `false`, the existing UI, REST API and MCP remain available without accounts. | +| `AUTH_JWT_SECRET` | *(empty)* | Required and non-empty when `AUTH_ENABLED=true`. Keep it private and stable across restarts; changing it invalidates existing tokens. | +| `AUTH_COOKIE_NAME` | `liqa_auth` | Name of the browser's HttpOnly session cookie. | +| `AUTH_JWT_EXPIRES_IN` | `24h` | Default lifetime for browser sessions and CLI-issued tokens. Positive durations use `s`, `m`, `h` or `d`. | +| `AUTH_REVOKED_TOKEN_CLEANUP_CRON` | `0 3 * * *` | When expired logout revocations are cleaned. Cleanup also runs once at startup and is disabled when auth is off. | --- @@ -103,9 +108,22 @@ The SQLite schema is managed by TypeORM migrations in `server/src/database/migra The scripts run from `server/`, so `DB_PATH` (default `data/liqa.db`) is relative to it, and they read `server/.env` if present, like the server does. +### Enabling authentication + +Authentication is disabled by default, so a fresh install needs no auth settings. For Docker Compose, set these in the project `.env` (keep it out of version control): + +```dotenv +AUTH_ENABLED=true +AUTH_JWT_SECRET= +``` + +Use a long, randomly generated secret from your secret manager; do not use the placeholder literally or commit a real value. `AUTH_ENABLED` accepts only `true` or `false`. When enabled, startup fails if the signing secret is blank or the configured token lifetime/cleanup schedule is invalid. Rebuild/restart the container after changing its configuration. Compose applies pending migrations before starting the server. For local development, export the same variables in the server process environment (or put them in `server/.env`); run `npm -w server run build` and `npm -w server run migration:run` before account commands or server startup. Migrations add the user and revoked-token tables and are required even when authentication is disabled. + +When auth is enabled, REST and MCP controller routes require a valid bearer token or browser cookie except `GET /health`, `GET /healthz`, `GET /manifest.json`, and `POST /api/v1/auth/login`. Login is public so a browser can establish its session. The manifest exposes whether auth is enabled; health endpoints return service status. The UI assets and Swagger UI at `/docs` remain reachable, while API operations invoked from Swagger require authentication. MCP at `/mcp` and the run-events stream are protected. When auth is disabled, the guard allows existing requests through. + ## Operator account commands -Authentication is opt-in. To manage accounts or issue tokens, set `AUTH_ENABLED=true` and `AUTH_JWT_SECRET` in the same environment used by the server. Apply database migrations before using the commands. Passwords are entered interactively without terminal echo; they are never accepted as command-line arguments. +Authentication is opt-in. To manage accounts or issue tokens, set `AUTH_ENABLED=true` and `AUTH_JWT_SECRET` in the same environment used by the server. Apply database migrations before using the commands. Passwords are entered interactively without terminal echo; they are never accepted as command-line arguments. The CLI uses the same `DB_PATH` as the server; locally it resolves the default `data/liqa.db` relative to `server/`, while inside the container it uses the configured path (normally `/app/data/liqa.db`, persisted by the `./data:/app/data` volume). Build the server and apply migrations locally, then run commands from the server workspace: @@ -128,7 +146,15 @@ docker compose exec liqa node dist/cli.js user:token alice 30m docker compose exec liqa node dist/cli.js user:delete alice ``` -`user:create` asks for a username and two matching passwords. The other commands require an existing username. Lookup output contains only the account id, username, and timestamps. Token output is a bearer credential: handle it as a secret and do not paste it into logs or shared history. User deletion removes the account, so the server rejects that user's previously issued tokens on their next authentication. +`user:create` asks for a username and two matching passwords; password entry is hidden and requires an interactive terminal. A duplicate username, blank username/password, mismatch or invalid input fails with a nonzero exit. The other commands require an existing username; lookup output contains only the account id, username and timestamps. Unknown usernames fail with `No account found for that username.` and a nonzero exit. A token duration must be a positive number followed by `s`, `m`, `h` or `d` (for example `30m`, `1h`, `7d`); omitted duration uses `AUTH_JWT_EXPIRES_IN` (`24h` by default). Token output is a bearer credential: handle it as a secret and do not paste it into logs or shared history. User deletion removes the account, so the server rejects that user's previously issued tokens on their next authentication. General CLI failures print a concise hint to check auth settings, `DB_PATH` and migrations. + +### Browser sessions, logout and development origins + +With auth enabled, the UI asks for credentials at `/login`. `POST /api/v1/auth/login` sets a signed session in an HttpOnly, `SameSite=Strict` cookie (default name `liqa_auth`) whose expiry matches the JWT lifetime. The cookie gets the `Secure` attribute when the request is HTTPS, including when the server sees `X-Forwarded-Proto: https`; serve production traffic over HTTPS and configure trusted proxy headers accordingly. JavaScript cannot read the token. `POST /api/v1/auth/logout` revokes the presented token and clears the cookie. Revoked tokens remain rejected until their expiration; deleted accounts also cause their tokens to be rejected on the next authentication. + +Expired revocation rows are removed at startup and by `AUTH_REVOKED_TOKEN_CLEANUP_CRON` (default `0 3 * * *`, daily at 03:00 server time). The cleanup is not scheduled when authentication is disabled. Browser run notifications use the authenticated `GET /api/v1/scenarios/runs/events` event stream. + +For local Vite development, the server's default CORS origins are `http://localhost:5173` and `http://127.0.0.1:5173` outside production. Vite has no API proxy: set `VITE_API_URL=http://localhost:3000/api/v1` when using a local server, or use `npm -w client run dev:compose-api` to target `http://localhost:13000`. The API's default CORS list also permits the compose origins `http://localhost:13000` and `http://127.0.0.1:13000` in production. Keep the UI and API on the same host name (`localhost` with `localhost`, or `127.0.0.1` with `127.0.0.1`) so the strict cookie remains same-site. For a different origin, set `CORS_ORIGINS` to the exact comma-separated UI origins; use HTTPS in deployed environments. **Changing the schema** (adding or changing an entity): diff --git a/docs/mcp.md b/docs/mcp.md index ee4fa69..3a4edc3 100644 --- a/docs/mcp.md +++ b/docs/mcp.md @@ -2,6 +2,19 @@ The MCP endpoint is exposed at `/mcp` (Streamable HTTP transport), e.g. `http://localhost:13000/mcp` with the compose setup. Each request is served by a fresh MCP server, so there is no MCP session state between calls. +Authentication is disabled by default. When `AUTH_ENABLED=true`, MCP requests must include a valid bearer token from the operator CLI (`user:token`); browser cookies are accepted by the HTTP API, but MCP clients should use the bearer header. For an MCP client that supports custom HTTP headers, configure the endpoint and header like this (replace the synthetic token with a privately issued token): + +```json +{ + "url": "https://liqa.example/mcp", + "headers": { + "Authorization": "Bearer " + } +} +``` + +Keep the token secret and renew it when it expires. See [development.md](development.md#operator-account-commands) for provisioning and token issuance. With auth disabled, omit the authorization header. + The server registers the following tools. All entity IDs are UUIDs; list tools are paginated (`page`, `limit`, and where noted `orderBy` / `orderDir`). Errors are returned as MCP tool errors (`isError: true`) with the message as text. ## Sessions