paul/picpeak
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

docs(security): correct the rate limiter defaults and how they are set (#1336)

Browse Source 
* docs(security): correct the rate limiter defaults and how they are set

SECURITY_LOGGING.md said rate_limit_max_requests defaults to 1000 and
that the settings are configurable via the admin panel. The code
fallback when no app_settings row exists is 300 (19e125d8), a fresh
install has no row, and there is no admin screen: the settings are
written by PUT /api/admin/settings/security/rate-limit, which nothing
in the frontend calls. The reporter of issue 1287 ran on the 300
default without any way to see it.

The table now carries the real defaults, what the auth budget counts,
the exemptions including the gallery-image one from v3.127.0-beta.0,
and the TRUST_PROXY and shared-NAT caveats.

Relates to issue 1287

* docs(security): note the rate-limit route only updates existing rows

---------

Co-authored-by: Paul Nothaft <paul@MacStudio-von-Paul.local>
This commit is contained in:
Paul Nothaft
2026-09-07 16:35:13 +02:00
committed by GitHub
parent e43216311b
commit 9bbdca9fc5
1 changed files with 7 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files
backend/docs/SECURITY_LOGGING.md
+7 -5
View File
@@ -87,16 +87,18 @@ When rate limits are exceeded, the following is logged:
## Configuration Settings
All rate limiting settings are configurable via the admin panel:
The general limiter reads these keys from `app_settings` (cached for 60 seconds). There is no admin screen for them yet; they are set through `PUT /api/admin/settings/security/rate-limit` (all six fields required) or directly in the table, JSON-encoded. The defaults below are what applies when a key has no row — a fresh install has none. Note that the route only updates rows that already exist: on a fresh install it answers 200 without writing anything, so insert the six rows directly first.
| Setting | Default | Range | Description |
|---------|---------|-------|-------------|
| rate_limit_enabled | true | - | Enable/disable rate limiting |
| rate_limit_window_minutes | 15 | 1-60 | Time window for rate limit |
| rate_limit_max_requests | 1000 | 10-10000 | Max requests for general endpoints |
| rate_limit_auth_max_requests | 5 | 1-100 | Max requests for auth endpoints |
| rate_limit_skip_authenticated | true | - | Skip rate limit for authenticated requests |
| rate_limit_public_endpoints_only | false | - | Only rate limit public endpoints |
| rate_limit_max_requests | 300 | 10-10000 | Per-IP budget for `/api/` requests that are not exempt |
| rate_limit_auth_max_requests | 5 | 1-100 | Per-IP budget of *failed* admin-login / gallery-verify attempts (own bucket) |
| rate_limit_skip_authenticated | true | - | Admin sessions are exempt; since v3.127.0-beta.0 a verified gallery viewer's image requests (thumbnail, preview, hero, photo) are exempt too |
| rate_limit_public_endpoints_only | false | - | Only rate limit `/api/public/*` and `/api/gallery/*` |
The limiter keys on the client IP as Express reports it, so behind a proxy `TRUST_PROXY` has to cover that proxy or every visitor shares one budget. Several people behind one NAT (an office, a household, carrier NAT) share a budget by design; before v3.127.0-beta.0 a large gallery could exhaust it for a single viewer, which surfaced as blank tiles with no error (issue 1287).
## Database Tables