Add optional user authentication #15

Open
opened 2026-10-07 20:13:14 +03:00 by ars9 · 0 comments
Owner

Summary

Liqa has no authentication: anyone who can reach the server can use the UI, REST API and MCP endpoint, including running code (exec_code, snippets) and reading stored credentials. Add a basic, opt-in authentication system based on a users table and JWTs.

Requirements

Configuration

  • Authentication is off by default and has to be turned on explicitly, e.g. AUTH_ENABLED=true. When it's off, Liqa behaves as it does today.
  • New settings (validated in server/src/config/app.config.ts, documented in .env.example):
    • AUTH_ENABLED - default false
    • AUTH_JWT_SECRET - JWT signing secret; required when auth is enabled (the server refuses to start without it)
    • AUTH_JWT_EXPIRES_IN - default token lifetime, default 24h
    • AUTH_REVOKED_TOKEN_CLEANUP_CRON - schedule for cleaning up expired revoked tokens, default daily (0 3 * * *)

Users

  • New user entity + migration:
    • id - UUID v4 primary key (@PrimaryGeneratedColumn("uuid"), like the other entities)
    • login - unique
    • passwordHash
    • the usual timestamps
  • Hash passwords with scrypt from node:crypto and a random salt per user. Store the salt and scrypt parameters together with the hash (e.g. scrypt$N$r$p$salt$hash) so the parameters can change later.
  • Compare hashes with timingSafeEqual.
  • Users are created only with the CLI command below. There is no registration page and no API for it at this stage.

CLI commands

Both commands work against the configured database (DB_PATH) and must also work inside the Docker container (docker compose exec liqa npm run ...).

  • npm run user:create - creates a user. It asks for the login and password interactively (password not echoed, entered twice), so the password doesn't end up in shell history. It fails if the login already exists.
  • npm run user:get - prints user details.
  • npm run user:delete <id> - deletes the user unconditionally.
  • npm run user:token <id> [expiration_interval] - issues a Bearer token for programmatic use (MCP clients, CI, scripts) and prints it to stdout.
    • expiration_interval uses the same format as AUTH_JWT_EXPIRES_IN (e.g. 24h, 30d) and defaults to AUTH_JWT_EXPIRES_IN.
    • Exits with an error and a non-zero code if the login doesn't exist.

Tokens

  • A token is a JWT containing the user's id and iat, plus exp derived from the expiration interval.
  • On login from the UI, the token goes into an HttpOnly, SameSite=Strict cookie (Secure behind HTTPS), so the run events stream (EventSource, which can't send headers) keeps working.
  • The same token is also accepted as Authorization: Bearer <token> for REST API and MCP calls. The same applies to tokens issued with user:token.

Revocation

  • New revoked_token entity + migration: tokenHash (SHA-256 of the token, unique) and expiresAt (the token's exp).
  • Logout revokes the presented token, whether it came from the cookie or the Authorization header: it stores the token's hash with its expiration date and clears the cookie.
  • The guard rejects tokens whose hash is in revoked_token.
  • Expired entries (expiresAt in the past) are deleted on server start and then periodically by a scheduled job (AUTH_REVOKED_TOKEN_CLEANUP_CRON, daily by default).

Server

  • POST /api/v1/auth/login (sets the cookie and returns the token), POST /api/v1/auth/logout (revokes the token and clears the cookie), GET /api/v1/auth/me.
  • A global guard that, when auth is enabled, accepts a valid, non-revoked JWT from either the cookie or the Authorization header and returns 401 otherwise.
  • Public endpoints stay open: /health, /manifest.json, the static client files and auth/login.
  • /manifest.json exposes whether auth is enabled, so the client knows whether to show a login page.
  • Swagger: register bearer auth so endpoints can be tried from /docs.
  • The scenario scheduler keeps working (it runs in-process and doesn't go through HTTP).

Client

  • Login page (login + password form).
  • On a 401 from the API, redirect to the login page; after logging in, return to the original page.
  • Logout action in the UI.
  • Storybook stories for any new client/src/ui/ components; new strings in en.json.

Docs

  • docs/development.md: enabling auth, and creating users and issuing tokens, both locally and in Docker.
  • docs/mcp.md: passing a Bearer token to an MCP client, e.g. claude mcp add --transport http liqa http://localhost:13000/mcp --header "Authorization: Bearer <token>".
  • docs/architecture.md, README.md and .env.example.

Acceptance criteria

  • With AUTH_ENABLED unset or false, all existing tests pass and nothing changes in behavior.
  • With auth enabled:
    • unauthenticated requests to protected endpoints return 401
    • a valid cookie or Bearer token is accepted
    • expired, tampered and revoked tokens are rejected
    • run notifications work after logging in through the UI
  • user:create creates a user that can log in. user:token issues a working token with the default or a given expiration, and fails for an unknown login.
  • user:delete deletes the user. Tokens of this user no longer work.
  • After logout, the same token returns 401 from both the cookie and the Bearer header.
  • Cleanup deletes expired revoked-token entries and keeps unexpired ones.
  • Server tests cover hashing and verification, login success and failure, guard behavior (cookie, Bearer, public endpoints, revoked tokens), the CLI commands and the cleanup job.
  • Migration test (test/migrations.spec.ts) passes.
## Summary Liqa has no authentication: anyone who can reach the server can use the UI, REST API and MCP endpoint, including running code (`exec_code`, snippets) and reading stored credentials. Add a basic, opt-in authentication system based on a users table and JWTs. ## Requirements ### Configuration - Authentication is **off by default** and has to be turned on explicitly, e.g. `AUTH_ENABLED=true`. When it's off, Liqa behaves as it does today. - New settings (validated in `server/src/config/app.config.ts`, documented in `.env.example`): - `AUTH_ENABLED` - default `false` - `AUTH_JWT_SECRET` - JWT signing secret; required when auth is enabled (the server refuses to start without it) - `AUTH_JWT_EXPIRES_IN` - default token lifetime, default `24h` - `AUTH_REVOKED_TOKEN_CLEANUP_CRON` - schedule for cleaning up expired revoked tokens, default daily (`0 3 * * *`) ### Users - New `user` entity + migration: - `id` - UUID v4 primary key (`@PrimaryGeneratedColumn("uuid")`, like the other entities) - `login` - unique - `passwordHash` - the usual timestamps - Hash passwords with `scrypt` from `node:crypto` and a random salt per user. Store the salt and scrypt parameters together with the hash (e.g. `scrypt$N$r$p$salt$hash`) so the parameters can change later. - Compare hashes with `timingSafeEqual`. - Users are created **only** with the CLI command below. There is no registration page and no API for it at this stage. ### CLI commands Both commands work against the configured database (`DB_PATH`) and must also work inside the Docker container (`docker compose exec liqa npm run ...`). - `npm run user:create` - creates a user. It asks for the login and password interactively (password not echoed, entered twice), so the password doesn't end up in shell history. It fails if the login already exists. - `npm run user:get` - prints user details. - `npm run user:delete <id>` - deletes the user unconditionally. - `npm run user:token <id> [expiration_interval]` - issues a Bearer token for programmatic use (MCP clients, CI, scripts) and prints it to stdout. - `expiration_interval` uses the same format as `AUTH_JWT_EXPIRES_IN` (e.g. `24h`, `30d`) and defaults to `AUTH_JWT_EXPIRES_IN`. - Exits with an error and a non-zero code if the login doesn't exist. ### Tokens - A token is a JWT containing the user's `id` and `iat`, plus `exp` derived from the expiration interval. - On login from the UI, the token goes into an `HttpOnly`, `SameSite=Strict` cookie (`Secure` behind HTTPS), so the run events stream (`EventSource`, which can't send headers) keeps working. - The same token is also accepted as `Authorization: Bearer <token>` for REST API and MCP calls. The same applies to tokens issued with `user:token`. ### Revocation - New `revoked_token` entity + migration: `tokenHash` (SHA-256 of the token, unique) and `expiresAt` (the token's `exp`). - Logout revokes the presented token, whether it came from the cookie or the `Authorization` header: it stores the token's hash with its expiration date and clears the cookie. - The guard rejects tokens whose hash is in `revoked_token`. - Expired entries (`expiresAt` in the past) are deleted on server start and then periodically by a scheduled job (`AUTH_REVOKED_TOKEN_CLEANUP_CRON`, daily by default). ### Server - `POST /api/v1/auth/login` (sets the cookie and returns the token), `POST /api/v1/auth/logout` (revokes the token and clears the cookie), `GET /api/v1/auth/me`. - A global guard that, when auth is enabled, accepts a valid, non-revoked JWT from either the cookie or the `Authorization` header and returns 401 otherwise. - Public endpoints stay open: `/health`, `/manifest.json`, the static client files and `auth/login`. - `/manifest.json` exposes whether auth is enabled, so the client knows whether to show a login page. - Swagger: register bearer auth so endpoints can be tried from `/docs`. - The scenario scheduler keeps working (it runs in-process and doesn't go through HTTP). ### Client - Login page (login + password form). - On a 401 from the API, redirect to the login page; after logging in, return to the original page. - Logout action in the UI. - Storybook stories for any new `client/src/ui/` components; new strings in `en.json`. ### Docs - `docs/development.md`: enabling auth, and creating users and issuing tokens, both locally and in Docker. - `docs/mcp.md`: passing a Bearer token to an MCP client, e.g. `claude mcp add --transport http liqa http://localhost:13000/mcp --header "Authorization: Bearer <token>"`. - `docs/architecture.md`, `README.md` and `.env.example`. ## Acceptance criteria - With `AUTH_ENABLED` unset or `false`, all existing tests pass and nothing changes in behavior. - With auth enabled: - unauthenticated requests to protected endpoints return 401 - a valid cookie or Bearer token is accepted - expired, tampered and revoked tokens are rejected - run notifications work after logging in through the UI - `user:create` creates a user that can log in. `user:token` issues a working token with the default or a given expiration, and fails for an unknown login. - `user:delete` deletes the user. Tokens of this user no longer work. - After logout, the same token returns 401 from both the cookie and the Bearer header. - Cleanup deletes expired revoked-token entries and keeps unexpired ones. - Server tests cover hashing and verification, login success and failure, guard behavior (cookie, Bearer, public endpoints, revoked tokens), the CLI commands and the cleanup job. - Migration test (`test/migrations.spec.ts`) passes.
ars9 added this to the User management milestone 2026-10-07 21:20:22 +03:00
Sign in to join this conversation.
No labels
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: ars9/liqa#15