The JWT verifier pins HS256, requires a generated base64url secret representing at least 32 bytes, validates issuer and audience, and requires the correct token purpose, UUID subject/session/token identifiers, issued-at and expiry. Access lifetimes cannot exceed five minutes. Bearer credentials are accepted only in Authorization headers. No query-string or shared-API-key fallback is implemented.
Each access token is bound to an active PostgreSQL session and its current active user on every protected request. Roles come from the database. Revoking a session therefore rejects its unexpired JWTs as well as refreshes on subsequent requests; requests already authorized and in progress can finish. Database failure fails authentication closed rather than allowing offline verification.
Refresh tokens contain 48 random bytes and are opaque. Only SHA-256 hashes are persisted. Each single-use token belongs to a session family with an absolute seven-day expiry. Transactions lock user then session, consume the old token and insert the replacement atomically. Consumed hashes remain until expiry. Replaying one commits family revocation before returning 401. Clients must serialize refresh requests and require login after an ambiguous/lost refresh response. There is no replay grace window.
Passwords use bcrypt with cost 12 on both creation and update. Minimum length is 12 characters and the maximum is 72 UTF-8 bytes; longer passwords are rejected rather than silently truncated. Unknown usernames are compared against a dummy hash. Invalid credentials use a common response. Email usernames normalize to lowercase before uniqueness checks. Password columns are excluded from default database selects and serialization, and token responses explicitly pick safe profile fields. Request logs omit bodies, credentials and query strings.
The first admin is created through an explicit database-connected CLI. All subsequent user management and counts require an admin; there is no anonymous registration. Readers can read shop records, writers can change shop records, admins additionally manage users. All roles can access their own profile, change their password and terminate sessions. Password, email, role and activation updates revoke affected sessions in the same transaction. An advisory transaction lock protects the last active admin against concurrent demotion/deactivation.
- Use HTTPS outside local development, verified database TLS for remote PostgreSQL, and a unique randomly generated signing secret from a secret manager. Do not use the example CI secret in deployments. JWT payloads are readable, so no passwords or confidential profile values are embedded.
- Login is limited to ten source-IP requests per minute and ten account attempts per fifteen-minute window. Refresh allows thirty source-IP requests per minute. Other routes retain the p6 limit of 120 per minute; password changes permit five per minute. The account counter is atomic in PostgreSQL and resets after a successful login or cooldown. The source-IP limiter is process-local; use a shared ingress limit for multi-instance deployments. Account throttling can temporarily deny login to a targeted account; alert on sustained failures. Configure trusted proxy boundaries explicitly rather than trusting arbitrary forwarding headers.
- This API returns refresh tokens in JSON for non-cookie clients. Browser deployments should use a same-origin backend-for-frontend with a Secure, HttpOnly, SameSite cookie and appropriate CSRF protection for persistent login. Do not persist tokens in browser localStorage/sessionStorage or URLs. Keeping tokens only in memory provides a session that ends on page reload. CORS is an origin allowlist and is not authentication.
- Rotate the signing secret through deployment configuration. All instances must agree on issuer, audience and key. Rotation immediately invalidates old access JWTs; existing valid opaque refresh sessions can obtain JWTs under the new key. To invalidate every login session after a compromise, revoke all auth_session rows as well. Automated multi-key rollover, MFA, email verification, password-reset email and external identity-provider integration are outside this project.
- Run the cleanup CLI daily to remove absolutely expired sessions and their refresh history, and stale login counters. Never remove consumed hashes for a still-live session: they are needed for replay detection. Cleanup is retryable.
- Use a least-privilege database role, backups, monitoring and an ingress request/body/concurrency limit. Do not enable TypeORM synchronize in deployed environments. The Docker image runs as the node user; the host API port is loopback-bound by default.
- RFC 8725, JSON Web Token Best Current Practices: algorithm, issuer, audience and token-purpose validation.
- OWASP JSON Web Token Cheat Sheet: token handling and revocation.
- OWASP Session Management Cheat Sheet: browser storage and session controls.