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_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.
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
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
AUTH_ENABLED=true. When it's off, Liqa behaves as it does today.server/src/config/app.config.ts, documented in.env.example):AUTH_ENABLED- defaultfalseAUTH_JWT_SECRET- JWT signing secret; required when auth is enabled (the server refuses to start without it)AUTH_JWT_EXPIRES_IN- default token lifetime, default24hAUTH_REVOKED_TOKEN_CLEANUP_CRON- schedule for cleaning up expired revoked tokens, default daily (0 3 * * *)Users
userentity + migration:id- UUID v4 primary key (@PrimaryGeneratedColumn("uuid"), like the other entities)login- uniquepasswordHashscryptfromnode:cryptoand 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.timingSafeEqual.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_intervaluses the same format asAUTH_JWT_EXPIRES_IN(e.g.24h,30d) and defaults toAUTH_JWT_EXPIRES_IN.Tokens
idandiat, plusexpderived from the expiration interval.HttpOnly,SameSite=Strictcookie (Securebehind HTTPS), so the run events stream (EventSource, which can't send headers) keeps working.Authorization: Bearer <token>for REST API and MCP calls. The same applies to tokens issued withuser:token.Revocation
revoked_tokenentity + migration:tokenHash(SHA-256 of the token, unique) andexpiresAt(the token'sexp).Authorizationheader: it stores the token's hash with its expiration date and clears the cookie.revoked_token.expiresAtin 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.Authorizationheader and returns 401 otherwise./health,/manifest.json, the static client files andauth/login./manifest.jsonexposes whether auth is enabled, so the client knows whether to show a login page./docs.Client
client/src/ui/components; new strings inen.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.mdand.env.example.Acceptance criteria
AUTH_ENABLEDunset orfalse, all existing tests pass and nothing changes in behavior.user:createcreates a user that can log in.user:tokenissues a working token with the default or a given expiration, and fails for an unknown login.user:deletedeletes the user. Tokens of this user no longer work.test/migrations.spec.ts) passes.