Repository navigation
VaultBox API v2.2.0 — Authorization, Concurrency and Abuse-Resistance Release
VaultBox API v2.2.0 — Authorization, Concurrency and Abuse-Resistance Release
Phase 1 of the v2.5.0 program (issues #39–#52). Security and correctness hardening of the existing API: no endpoint was removed or renamed and no stored data is rewritten. Seven additive migrations. Several behaviors are stricter than v2.1.x (listed below) — read "Behavior changes" before upgrading clients.
What changed
Authorization and account state
- Cross-tenant regression matrix (#50). Two-tenant tests prove that another user's files, folders, upload sessions/parts and download sessions are indistinguishable from unknown IDs, that admin routes reject ordinary accounts and forged tokens, and that suspended/deleted accounts are blocked.
- Plan entitlements (#39). Selecting a paid plan requires a server-side entitlement granted by an HMAC-signed, idempotent
POST /billing/webhookevent; the entitlement check, quota fit and plan switch are one statement under a per-user row lock. - Immediate revocation (#44). Authentication reads status, role and a per-account session version from PostgreSQL on every request (the 10-second Redis cache is gone). Suspension, deletion, demotion and session revocation take effect on the next request on every instance, independent of Redis.
- Commit-time account fence (#45). Every transaction that creates usage re-checks the owner is
ACTIVEunder the owner's row lock, so a request authenticated before a suspension cannot finish creating data afterwards.
Upload and quota integrity
- Completion vs expiry (#40) uses a renewable, fenced lease; part writes (#41) are fenced against completion/abort/expiry; one-shot reservations (#42) are durable and recovered after worker crashes (tested with SIGKILL injection). Lock order is always user, then upload session.
- Idempotency (#43) for
POST /foldersis actor-scoped, durable in PostgreSQL and fair per account.
Abuse resistance and operations
- Rate limits (#46) for login, registration and download-token issuance stay global across replicas through a PostgreSQL fallback and fail closed (
503+Retry-After) when neither Redis nor PostgreSQL can answer; login also has per-account and per-address caps. - Client IP (#47) comes only from an explicit trusted-proxy policy (
TRUST_PROXY), not from a client-controlledX-Forwarded-For; new adminGET /admin/network-diagnosticsshows how an address was derived. - Audit (#48). Audit rows are written in the same transaction as the change they describe (no more committed-change/500 ambiguity); details of new rows contain identifiers and sizes, never file names or e-mail addresses. Existing audit rows are not rewritten and may still contain file names or e-mail addresses.
- Password verification (#49). Uniform login failures (no account enumeration by response), and one bcrypt comparison per attempt at cost 12 in a bounded worker-thread pool (
503+Retry-Afterwhen saturated instead of stalling the API). Timing is uniform for accounts whose stored hash is cost 12 (the dummy hash used for unknown e-mails is cost 12); an account with an older, lower-cost hash still verifies faster, so such accounts should be re-seeded or have their passwords reset (the hash format is unchanged and hashes are not upgraded on login). - Download sessions (#51, #52). Revocable (
DELETE /download-sessions/:id,DELETE /files/:id/download-sessions, and revoked by "log out everywhere"); revoked/expired sessions cannot begin transfers (410) while open streams finish; the bearer value never reaches logs, audit rows or metrics; every response, including refusals, isno-storewithReferrer-Policy: no-referrer.HEADno longer starts a session, and refusals that used to surface as500(missing bytes, unsatisfiable range) are proper404/416JSON errors.
Behavior changes (client and operator impact)
| Change | Impact |
|---|---|
| Paid plans need an entitlement | POST plan selection for paid plans is refused without one. Set PLAN_SWITCH_MODE=demo to keep the old self-service behavior explicitly (e.g. a public demo). |
Malformed Idempotency-Key |
400 (was silently truncated). Valid keys: 1–128 chars of A-Za-z0-9._:~-. |
| Older tokens after reactivation/demotion | 401, sign in again. Tokens issued before v2.2.0 stay valid until the account is next revoked. |
| In-flight writes by a suspended account | 403 ACCOUNT_NOT_ACTIVE; bytes removed, reservation returned. |
Busy POST /folders for an account |
429 IDEMPOTENCY_BUSY (identical in-flight request is still 409). |
| Login failures | One 401 for unknown e-mail, wrong password, and suspended/deleted account with a wrong password; 403 only after a correct password. New caps (30 per account / 15 min, 120 per address / 5 min); 503 when rate-limit storage is unavailable. |
| Download first use | Only a GET that opened its stream sets usedAt / emits DOWNLOAD_SESSION_STARTED. |
| Download session creation | Response includes the non-secret session id; a request authenticated before a revocation gets 401 SESSION_REVOKED. |
npm test |
Runs files serially (shared database); about 40 s. |
Operator actions before/after deploy
TRUST_PROXY(important). Unset in production means "private-network proxies". After deploying, callGET /admin/network-diagnosticsas an admin: ifclientIpis a proxy address, add the proxy's range toTRUST_PROXY, otherwise all clients share one rate-limit bucket (including the 120 / 5 min login cap).- Decide
PLAN_SWITCH_MODE(demofor the public demo) and setBILLING_WEBHOOK_SECRETif you will grant entitlements (the webhook answers503while it is unset). - Optionally tune
PASSWORD_HASH_CONCURRENCY/_QUEUE/_WAIT_MS(defaults 2 / 64 / 5000) andIDEMPOTENCY_*. - Configure your edge/CDN/APM to mask the path after
/download/(seedocs/DEPLOYMENT.md, "Download token lifecycle and URL exposure"). - Runtime stays Node.js 24.22.2 (
.node-version); keep anyNODE_VERSIONoverride off.
Migrations (all additive; run automatically by npm start)
20261104210000_plan_entitlements, 20261104220000_upload_completion_lease, 20261104230000_upload_reservations, 20261104240000_idempotency_keys, 20261104250000_user_auth_version, 20261105100000_rate_limit_windows, 20261105200000_download_token_revocation. Tables/columns added only; no existing data is rewritten.
Rollback
Leave the migrations in place: older builds ignore the new tables and columns. Do not roll back to a build with Node.js 24.19.0. Builds before this release lack the entitlement check (paid plans become self-selectable again), the commit-time account fence, the DB-authoritative authentication and download-session revocation (a URL revoked under v2.2.0 works again until its stored expiry, for as long as the older build runs; lowering DOWNLOAD_TOKEN_EXPIRES_MINUTES does not shorten URLs that already exist, see the rollback section of docs/DEPLOYMENT.md); roll back only if you accept that, otherwise fix forward.
Verification
Every change merged with verify green on its exact head and review findings answered on-thread. On main (9645b28): npm test 201/201 on two consecutive runs against real PostgreSQL and Redis (deterministic interleavings, held row locks, SIGKILL crash injection, multi-process workers, per-guard mutation checks), npm audit --audit-level=high clean (two moderate dev-only nodemon → minimatch advisories remain), all 14 migrations apply to a fresh database, benchmark 0 errors. See issue #68 for per-PR evidence.