Nautilus/ledgerdock
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Harden auth login against brute-force and refresh security docs

Browse Source
This commit is contained in:
Beda Schmid
2026-03-01 18:24:26 -03:00
parent 9cbbd80f47
commit 4c27fd6483
12 changed files with 715 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
doc/README.md
View File

@@ -6,7 +6,7 @@ This directory contains technical documentation for DMS.
- `../README.md` - project overview, setup, and quick operations
- `architecture-overview.md` - backend, frontend, and infrastructure architecture
- `api-contract.md` - API endpoint contract grouped by route module, including session auth, role and ownership scope, upload limits, and settings or processing-log security constraints
- `api-contract.md` - API endpoint contract grouped by route module, including session auth, login throttle responses, role and ownership scope, upload limits, and settings or processing-log security constraints
- `data-model-reference.md` - database entity definitions and lifecycle states
- `operations-and-configuration.md` - runtime operations, hardened compose defaults, DEV and LIVE security values, and persisted settings configuration behavior
- `frontend-design-foundation.md` - frontend visual system, tokens, UI implementation rules, authenticated media delivery under session auth, processing-log timeline behavior, and settings helper-copy guidance

5
doc/api-contract.md
View File

@@ -16,6 +16,7 @@ Primary implementation modules:
- Authentication is session-based bearer auth.
- Clients authenticate with `POST /auth/login` using username and password.
- Backend issues per-user bearer session tokens and stores hashed session state server-side.
- Login brute-force protection enforces Redis-backed throttle checks keyed by username and source IP.
- Clients send issued tokens as `Authorization: Bearer <token>`.
- `GET /auth/me` returns current identity and role.
- `POST /auth/logout` revokes current session token.
@@ -35,6 +36,10 @@ Ownership rules:
- `POST /auth/login`
- Body model: `AuthLoginRequest`
- Response model: `AuthLoginResponse`
- Additional responses:
- `401` for invalid credentials
- `429` for throttled login attempts, with stable message and `Retry-After` header
- `503` when the login rate-limiter backend is unavailable
- `GET /auth/me`
- Response model: `AuthSessionResponse`
- `POST /auth/logout`

10
doc/operations-and-configuration.md
View File

@@ -51,6 +51,11 @@ docker compose logs -f
- `AUTH_BOOTSTRAP_ADMIN_PASSWORD`
- optional `AUTH_BOOTSTRAP_USER_USERNAME`
- optional `AUTH_BOOTSTRAP_USER_PASSWORD`
- Login brute-force protection is enabled by default and keyed by username and source IP:
- `AUTH_LOGIN_FAILURE_LIMIT`
- `AUTH_LOGIN_FAILURE_WINDOW_SECONDS`
- `AUTH_LOGIN_LOCKOUT_BASE_SECONDS`
- `AUTH_LOGIN_LOCKOUT_MAX_SECONDS`
- Frontend signs in through `/api/v1/auth/login` and stores issued session token in browser session storage.
## DEV And LIVE Configuration Matrix
@@ -67,6 +72,10 @@ Use `.env.example` as baseline. The table below documents user-managed settings
| `REDIS_URL` | `redis://:<password>@redis:6379/0` in isolated local network | `rediss://:<password>@redis.internal:6379/0` |
| `REDIS_SECURITY_MODE` | `compat` or `auto` | `strict` |
| `REDIS_TLS_MODE` | `allow_insecure` or `auto` | `required` |
| `AUTH_LOGIN_FAILURE_LIMIT` | default `5` | tune to identity-protection policy and support requirements |
| `AUTH_LOGIN_FAILURE_WINDOW_SECONDS` | default `900` | tune to identity-protection policy and support requirements |
| `AUTH_LOGIN_LOCKOUT_BASE_SECONDS` | default `30` | tune to identity-protection policy and support requirements |
| `AUTH_LOGIN_LOCKOUT_MAX_SECONDS` | default `900` | tune to identity-protection policy and support requirements |
| `PROVIDER_BASE_URL_ALLOW_HTTP` | `true` only when intentionally testing local HTTP provider endpoints | `false` |
| `PROVIDER_BASE_URL_ALLOW_PRIVATE_NETWORK` | `true` only for trusted local development targets | `false` |
| `PROVIDER_BASE_URL_ALLOWLIST` | allow needed test hosts | explicit production allowlist, for example `["api.openai.com"]` |
@@ -99,6 +108,7 @@ Recommended LIVE pattern:
- legacy `enc-v1` payloads are read for backward compatibility
- new writes use `enc-v2`
- Processing logs default to metadata-only persistence.
- Login endpoint applies escalating temporary lockout on repeated failed credentials using Redis-backed subject keys for username and source IP.
- Markdown export enforces:
- max document count
- max total markdown bytes