testing/cross_backend/login_security.ts

Cross-backend parity suite for login rate limiting + trusted-proxy (X-Forwarded-For) resolution over real HTTP.

Login throttling and client-IP resolution are wired-but-never-crossed: the in-process describe_rate_limiting_tests covers the limiter, and the fuz_http / proxy middleware unit tests cover XFF resolution, but no case exercised either over a real socket on both impls — the limiter is nulled on every standard cross backend and the resolved client IP has no wire-observable downstream there. This dedicated suite spawns a backend with the login limiters enabled + the loopback proxy trusted (see global_setup_login_security.ts), then pins two properties end-to-end:

  • per-IP login limit fires — the first default_login_ip_rate_limit failed logins from one forwarded IP each return 401, and the next returns 429 with the canonical `{error: "rate_limit_exceeded", retry_after} body **and** a Retry-After: ceil(retry_after)` header. The 429 wire shape is the cross-impl contract — TS route_fail(REST_RATE_LIMIT_EXCEEDED, {retry_after}) and Rust route_response::rate_limit_exceeded must agree.
  • trusted-proxy / XFF resolution is honored — distinct X-Forwarded-For IPs get independent buckets: after exhausting one forwarded IP to 429, a *different* forwarded IP is unaffected (401, not 429). A backend that ignored XFF and keyed on the (loopback) TCP peer would 429 the fresh-IP request too — so the 401 proves the limiter keys on the resolved X-Forwarded-For client IP.
  • IPv6 clients share a bucket per /64 — after one forwarded IPv6 address exhausts its bucket, another address in the same /64 is 429 and one in the next /64 is not; the login audit rows keep each full address, never the bucket key. A password change, which shares the per-IP login limiter, from an address in an exhausted /64 is 429 too.
  • a concurrent burst gets at most the cap past the limiter — `2 × ip_limit` wrong logins sent at once from one fresh forwarded IP answer at most ip_limit 401s and 429 for the rest. A limiter checked before the lookup and recorded after the verify lets the whole burst through; each attempt is reserved instead, counted in flight from the check on.
  • a burst of correct logins past the cap waits, then succeeds — attempts count while in flight whatever their outcome, so 2 × ip_limit correct logins at once from one address meet the cap; the ones past it wait for a slot (at most the cap of them) and all answer 200. Runs on a backend that serves concurrent transactions (concurrent_transactions).
  • every X-Forwarded-For line is read — a client that sends its own line ahead of the one the trusted proxy appended can't choose its bucket: after exhausting one forwarded IP, a raw request carrying a spoofed line first and that IP last still 429s. Raw socket only (fetch merges repeated headers into one line), so it runs when base_url is given.
  • a malformed hop stops the walk — a trusted proxy that appends a non-bare-IP token (ip:port here) leaves the client's own entry to its left. After exhausting one forwarded IP, a chain with that IP left of an ip:port entry answers 401, not 429: the walk stopped at the malformed entry and keyed the request on the connection IP (its audit row says so), never on the client-written entry past it.
  • a success does not refund the per-IP budget — the distributed-spray backstop. Failed guesses against *distinct* usernames from one forwarded IP, interleaved with the attacker's own successful logins, must still 429 within a bounded total-request budget. Both spines used to clear the IP bucket on success, which made that budget unbounded: one credential (or, under open signup, none) bought unlimited guesses against arbitrary victims from a single address. Only the account-grain bucket is forgiven now.

Determinism without a limiter reset. Limiter state is in-memory and the per-test _testing_reset wipes only the DB, never the buckets — so each case uses its own forwarded IP and its own (non-existent) username, keeping every bucket independent across cases and across the two impls (separate processes). The login floor is zeroed on both spines, so the failed-login loop stays fast.

Both surfaces are flat REST (POST /api/account/login) on every spine, so this is an imperative suite (not a conformance_table row) — the sibling of origin.ts / identity_parity.ts. Cross-process only: the limiter+proxy wiring is the point, and the in-process counterparts already exist (describe_rate_limiting_tests + the proxy middleware tests). Cited property: docs/security.md §"Rate Limiting" + §"Trusted Proxy / Client IP".

view source

Declarations
#

2 declarations

describe_login_security_cross_tests
#

LoginSecurityCrossTestOptions
#

testing/cross_backend/login_security.ts view source

LoginSecurityCrossTestOptions import type {LoginSecurityCrossTestOptions} from '@fuzdev/fuz_app/testing/cross_backend/login_security.js';

Options for the login-security parity suite.

setup_test

Per-test fixture producer (cross-process only — see the module doc).

type (): Promise<TestFixture>

readonly
returns Promise<TestFixture>

login_path?

REST login route path. Default /api/account/login (the spine convention).

type string

readonly

password_path?

REST password-change route path. Default /api/account/password.

type string

readonly

concurrent_transactions?

Whether the backend serves concurrent logins — each its own database transaction — at once, for the burst-of-correct-logins case. Default false: a backend on one in-process connection (pglet-wasm, PGlite) refuses a second top-level transaction while one runs, so concurrent successful logins answer 500 there whatever the limiter does.

type boolean

readonly

base_url?

The backend's base URL, for the repeated-X-Forwarded-For case, which needs a raw socket to send two header lines. null (the default) skips that case.

type string | null

readonly

Depends on
#