49 lines
2.5 KiB
Markdown
49 lines
2.5 KiB
Markdown
|
# Contract: Identity and Authentication
|
||
|
|
|
||
|
|
## Login
|
||
|
|
|
||
|
|
- `POST /auth/login` — body `{ email, password }`. `401` on any failure (wrong password, no
|
||
|
|
such account, or a deactivated account) with an identical response body/status in every case
|
||
|
|
(FR-002/SC-003) — never a distinguishable "no such user" vs "wrong password." `200` with
|
||
|
|
`{ token, user: { id, email, name, role } }` on success.
|
||
|
|
|
||
|
|
## Self-identity
|
||
|
|
|
||
|
|
- `GET /auth/me` — gated by `fastify.authenticate`. `401` if the token is missing/invalid/
|
||
|
|
expired/revoked. `401` if the account behind a structurally-valid token no longer exists or
|
||
|
|
is deactivated (re-validated against current state, not the token's own claims alone). `200`
|
||
|
|
with `{ id, email, name, role }` on success.
|
||
|
|
|
||
|
|
## Account creation (admin-only)
|
||
|
|
|
||
|
|
- `POST /admin/users` — gated by `fastify.authenticate` + `requireRole('ADMIN')`. Body
|
||
|
|
`{ email, name, role, password }` (`role` one of `ADMIN`/`AGENT`). `403` for a valid non-admin
|
||
|
|
session. `409` if `email` is already in use. `201` with the created `{ id, email, name, role
|
||
|
|
}` (never the password or its hash) on success.
|
||
|
|
|
||
|
|
## Logout
|
||
|
|
|
||
|
|
- `POST /auth/logout` — gated by `fastify.authenticate`. Revokes the calling token's own `jti`
|
||
|
|
(Redis denylist, TTL = remaining lifetime) so it's rejected on any further use even before its
|
||
|
|
natural expiry. `200` on success.
|
||
|
|
|
||
|
|
## Guarantees (callable contract)
|
||
|
|
|
||
|
|
1. **Every route already gated by `fastify.authenticate` across 002-009 continues to accept a
|
||
|
|
valid session and now genuinely rejects a missing/invalid/expired/revoked one** — the gate
|
||
|
|
itself changes from a no-op to a real check; which routes carry the gate is unchanged
|
||
|
|
(FR-006, SC-001).
|
||
|
|
2. **A route additionally gated by `requireRole('ADMIN')` rejects a structurally valid session
|
||
|
|
whose role isn't `ADMIN`, with a response distinguishable from "no valid session at all"**
|
||
|
|
(403 vs 401) (FR-005, SC-002).
|
||
|
|
3. **A login failure never reveals whether the submitted email corresponds to an existing
|
||
|
|
account** — verified by comparing the exact response for a wrong password against a wholly
|
||
|
|
nonexistent email (FR-002, SC-003).
|
||
|
|
4. **No password is ever stored, logged, or returned anywhere in plaintext** — only
|
||
|
|
`passwordHash` is persisted, and no response body (login, self-identity, account creation)
|
||
|
|
ever includes it (FR-003, SC-004).
|
||
|
|
5. **An admin-created account can log in immediately with the password it was created with, no
|
||
|
|
manual step in between** (FR-008, SC-005).
|
||
|
|
6. **A token revoked via logout is rejected on any further use, even before its natural expiry**
|
||
|
|
(FR-009).
|