mirror of
https://github.com/azaion/admin.git
synced 2026-06-21 16:51:10 +00:00
[AZ-529] [AZ-530] Cycle-2 documentation refresh
Refreshes _docs/02_document/ to reflect the cycle-2 auth-modernization
+ CMMC hardening landings (AZ-531..AZ-538). Authoritative source for
the ripple set is ripple_log_cycle2.md.
Covered:
- architecture.md (section 1 rewritten, ADRs 6-9 added)
- data_model.md (sessions, audit_events, user columns, migrations)
- system-flows.md (F1 rewritten; F11-F17 added; F2/F7/F9 minor)
- module-layout.md (cycle-2 sub-component table)
- diagrams/flows/flow_login.md (dual-token + MFA)
- components/{01_data_layer,03_auth_and_security,05_admin_api}
- modules/ (12 new, 8 modified — full Argon2id/ES256/MFA/refresh
/mission/session/audit/jwks rollup)
- tests/{blackbox,security,traceability-matrix}
Step 13 (Update Docs) output for cycle 2.
Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Oleksandr Bezdieniezhnykh
@@ -811,3 +811,665 @@ The scenarios `FT-P-21`, `FT-P-22`, `FT-P-23` are retained here as ID placeholde
|
||||
**Max execution time**: 5s
|
||||
|
||||
Note: AZ-197 AC-1 (resource download works without `Hardware`) is implicitly covered by the existing FT-P-09 / FT-P-10 scenarios once their request bodies are aligned with the new wire shape. AZ-197 AC-3..AC-8 are internal-signature / build-system invariants and are verified at build/CI time, not via a blackbox HTTP scenario.
|
||||
|
||||
---
|
||||
|
||||
## Cycle 2 Additions (2026-05-14) — Auth Modernization (AZ-529 + AZ-530)
|
||||
|
||||
The scenarios below were appended during the existing-code cycle 2 Test-Spec Sync (autodev Step 12) for the eight tasks under AZ-529 (Auth Mechanism Modernization) and AZ-530 (CMMC Compliance Hardening): AZ-531 (refresh-token flow), AZ-532 (asymmetric signing + JWKS), AZ-533 (mission-token UAV), AZ-534 (TOTP 2FA), AZ-535 (logout + revocation), AZ-536 (Argon2id), AZ-537 (rate-limit + lockout), AZ-538 (CORS HTTPS-only + HSTS). Numbering continues from FT-P-23 / FT-N-16. Security-only ACs live in `security-tests.md`.
|
||||
|
||||
### Argon2id Password Hashing (AZ-536)
|
||||
|
||||
#### FT-P-24: Legacy SHA-384 Password Still Validates
|
||||
|
||||
**Summary**: A user whose `password_hash` is in the pre-AZ-536 unsalted SHA-384 format can still log in with the correct password.
|
||||
**Traces to**: AZ-536 AC-2
|
||||
**Category**: Authentication
|
||||
|
||||
**Preconditions**:
|
||||
- Seed user `legacy@azaion.com` with `password_hash` set to `Convert.ToBase64String(SHA384.HashData("LegacyPwd1!"))` (the historical format)
|
||||
|
||||
**Input data**: `{"email":"legacy@azaion.com","password":"LegacyPwd1!"}`
|
||||
|
||||
**Steps**:
|
||||
|
||||
| Step | Consumer Action | Expected System Response |
|
||||
|------|----------------|------------------------|
|
||||
| 1 | POST /login with the legacy user's credentials | HTTP 200, dual-token body (per AZ-531) |
|
||||
|
||||
**Expected outcome**: HTTP 200, login succeeds against legacy hash format
|
||||
**Max execution time**: 5s (note: Argon2id verify cost is incurred only on the post-login re-hash)
|
||||
|
||||
---
|
||||
|
||||
#### FT-P-25: Successful Legacy Login Re-Hashes to Argon2id
|
||||
|
||||
**Summary**: After FT-P-24 succeeds, the user's `password_hash` is silently upgraded to Argon2id PHC format and the same plaintext continues to validate.
|
||||
**Traces to**: AZ-536 AC-3
|
||||
**Category**: Authentication
|
||||
|
||||
**Preconditions**:
|
||||
- FT-P-24 has just executed successfully for `legacy@azaion.com`
|
||||
|
||||
**Input data**: `{"email":"legacy@azaion.com","password":"LegacyPwd1!"}`
|
||||
|
||||
**Steps**:
|
||||
|
||||
| Step | Consumer Action | Expected System Response |
|
||||
|------|----------------|------------------------|
|
||||
| 1 | Read `users.password_hash` for `legacy@azaion.com` directly from DB | Value starts with `$argon2id$v=19$m=` and parses to m ≥ 65536, t ≥ 3, p ≥ 1 |
|
||||
| 2 | POST /login with the same plaintext password again | HTTP 200, dual-token body |
|
||||
|
||||
**Expected outcome**: Hash format upgraded to Argon2id PHC; subsequent login still works
|
||||
**Max execution time**: 5s
|
||||
|
||||
---
|
||||
|
||||
#### FT-N-17: Wrong Password Fails for Both Hash Formats
|
||||
|
||||
**Summary**: Wrong password is rejected with the same error (`WrongPassword`) regardless of whether the stored hash is legacy SHA-384 or Argon2id.
|
||||
**Traces to**: AZ-536 AC-4
|
||||
**Category**: Authentication
|
||||
|
||||
**Preconditions**:
|
||||
- One user with legacy SHA-384 hash, one user with Argon2id hash already in DB
|
||||
|
||||
**Input data**: Wrong password against each user
|
||||
|
||||
**Steps**:
|
||||
|
||||
| Step | Consumer Action | Expected System Response |
|
||||
|------|----------------|------------------------|
|
||||
| 1 | POST /login (legacy user, wrong pwd) | HTTP 409, ExceptionEnum=WrongPassword (code 30) |
|
||||
| 2 | POST /login (Argon2id user, wrong pwd) | HTTP 409, ExceptionEnum=WrongPassword (code 30) |
|
||||
|
||||
**Expected outcome**: Same error code on both code paths; no information leak about hash format
|
||||
**Max execution time**: 5s per attempt (Argon2id cost incurred regardless of success/failure)
|
||||
|
||||
---
|
||||
|
||||
### /login Rate Limit + Account Lockout (AZ-537)
|
||||
|
||||
#### FT-P-26: Successful Login Resets the Failed-Attempt Counter
|
||||
|
||||
**Summary**: After some wrong-password attempts (within budget), a successful login zeros `failed_login_count` and clears `lockout_until`.
|
||||
**Traces to**: AZ-537 AC-4
|
||||
**Category**: Authentication
|
||||
|
||||
**Preconditions**:
|
||||
- User `alice@azaion.com` exists with Argon2id-hashed password
|
||||
|
||||
**Input data**: 5 wrong-password attempts followed by 1 correct attempt
|
||||
|
||||
**Steps**:
|
||||
|
||||
| Step | Consumer Action | Expected System Response |
|
||||
|------|----------------|------------------------|
|
||||
| 1 | POST /login with wrong pwd × 5 (within rate-limit budget) | HTTP 409 each (WrongPassword) |
|
||||
| 2 | Read `users.failed_login_count` for alice | Value = 5 |
|
||||
| 3 | POST /login with correct pwd | HTTP 200, dual-token body |
|
||||
| 4 | Read `users.failed_login_count` and `lockout_until` for alice | `failed_login_count = 0`, `lockout_until IS NULL` |
|
||||
|
||||
**Expected outcome**: Counter reset on success
|
||||
**Max execution time**: 30s (5× Argon2id verifies)
|
||||
|
||||
---
|
||||
|
||||
#### FT-P-27: Lockout Auto-Expires After Configured Duration
|
||||
|
||||
**Summary**: A locked account becomes loginable again automatically once `lockout_until < now()`.
|
||||
**Traces to**: AZ-537 AC-5
|
||||
**Category**: Authentication
|
||||
|
||||
**Preconditions**:
|
||||
- `Auth:Lockout:DurationMinutes` set to a small value (e.g. 1 minute) in the test env so the test does not have to wait 15 min
|
||||
- User `bob@azaion.com` exists with Argon2id hash
|
||||
|
||||
**Input data**: 10 wrong attempts to trigger lockout, then a correct attempt after the duration window
|
||||
|
||||
**Steps**:
|
||||
|
||||
| Step | Consumer Action | Expected System Response |
|
||||
|------|----------------|------------------------|
|
||||
| 1 | POST /login with wrong pwd × 10 | first 9 → 409 WrongPassword; the 10th → 423 Locked OR 409 followed by lockout flag |
|
||||
| 2 | POST /login with correct pwd immediately | HTTP 423 Locked (account is locked) |
|
||||
| 3 | Wait `Auth:Lockout:DurationMinutes + 1s` | — |
|
||||
| 4 | POST /login with correct pwd | HTTP 200, dual-token body |
|
||||
|
||||
**Expected outcome**: 423 → 200 transition once the lockout window expires
|
||||
**Max execution time**: 90s (depends on configured lockout duration in test env)
|
||||
|
||||
---
|
||||
|
||||
### CORS HTTPS-Only + HSTS (AZ-538)
|
||||
|
||||
#### FT-P-28: HTTPS Origin Preflight Succeeds
|
||||
|
||||
**Summary**: The CORS allow-list still admits the canonical `https://admin.azaion.com` origin and echoes the credentials flag.
|
||||
**Traces to**: AZ-538 AC-2
|
||||
**Category**: Cross-Origin
|
||||
|
||||
**Preconditions**:
|
||||
- Admin API running with `AdminCorsPolicy` configured (post-AZ-538)
|
||||
|
||||
**Input data**:
|
||||
- Method: OPTIONS
|
||||
- Path: /login
|
||||
- Header: `Origin: https://admin.azaion.com`
|
||||
- Header: `Access-Control-Request-Method: POST`
|
||||
|
||||
**Steps**:
|
||||
|
||||
| Step | Consumer Action | Expected System Response |
|
||||
|------|----------------|------------------------|
|
||||
| 1 | OPTIONS /login with the headers above | HTTP 204; `Access-Control-Allow-Origin: https://admin.azaion.com`; `Access-Control-Allow-Credentials: true` |
|
||||
|
||||
**Expected outcome**: HTTPS origin preflight succeeds with credentials flag
|
||||
**Max execution time**: 5s
|
||||
|
||||
---
|
||||
|
||||
#### FT-P-29: Development Env — No HTTPS Redirect, No HSTS
|
||||
|
||||
**Summary**: When `ASPNETCORE_ENVIRONMENT=Development`, plain HTTP requests to localhost still serve 200 responses with no `Strict-Transport-Security` header.
|
||||
**Traces to**: AZ-538 AC-5
|
||||
**Category**: Cross-Origin
|
||||
|
||||
**Preconditions**:
|
||||
- Admin API running with `ASPNETCORE_ENVIRONMENT=Development` (the default test container env)
|
||||
|
||||
**Input data**: GET http://localhost:8080/health/live
|
||||
|
||||
**Steps**:
|
||||
|
||||
| Step | Consumer Action | Expected System Response |
|
||||
|------|----------------|------------------------|
|
||||
| 1 | GET http://localhost:8080/health/live | HTTP 200; no `Strict-Transport-Security` header; no 307 redirect |
|
||||
|
||||
**Expected outcome**: Dev workflow preserved — no redirect, no HSTS
|
||||
**Max execution time**: 5s
|
||||
|
||||
---
|
||||
|
||||
### Refresh-Token Flow (AZ-531)
|
||||
|
||||
#### FT-P-30: /login Returns Dual Tokens
|
||||
|
||||
**Summary**: Successful login returns both a short-lived access token (≈15 min) and an opaque refresh token; a `sessions` row is created.
|
||||
**Traces to**: AZ-531 AC-1
|
||||
**Category**: Authentication
|
||||
|
||||
**Preconditions**:
|
||||
- Seed user without MFA enabled
|
||||
|
||||
**Input data**: Valid email + password
|
||||
|
||||
**Steps**:
|
||||
|
||||
| Step | Consumer Action | Expected System Response |
|
||||
|------|----------------|------------------------|
|
||||
| 1 | POST /login | HTTP 200; body has `access_token` (JWT), `access_exp` ≈ now+15m ±60s, `refresh_token` (opaque ≥43 chars), `refresh_exp` |
|
||||
| 2 | Decode `access_token` payload | Contains `sub`, `iss`, `aud`, `exp`, `jti`, `sid` claims |
|
||||
| 3 | Query `sessions` table by `user_id` | Exactly one row with non-null `refresh_hash`, non-null `family_id`, `revoked_at IS NULL` |
|
||||
|
||||
**Expected outcome**: Dual tokens issued, session row persisted, access token has short TTL
|
||||
**Max execution time**: 5s
|
||||
|
||||
---
|
||||
|
||||
#### FT-P-31: /token/refresh Rotates the Refresh Token
|
||||
|
||||
**Summary**: A valid refresh token is exchanged for a new access + new refresh; the previous refresh is invalidated; the session chain extends via `parent_session_id`.
|
||||
**Traces to**: AZ-531 AC-2
|
||||
**Category**: Authentication
|
||||
|
||||
**Preconditions**:
|
||||
- FT-P-30 just produced refresh token R1
|
||||
|
||||
**Input data**: `{"refresh_token":"<R1>"}`
|
||||
|
||||
**Steps**:
|
||||
|
||||
| Step | Consumer Action | Expected System Response |
|
||||
|------|----------------|------------------------|
|
||||
| 1 | POST /token/refresh with R1 | HTTP 200; body has new `access_token`, new `refresh_token` (R2 ≠ R1), new `access_exp`, new `refresh_exp` |
|
||||
| 2 | POST /token/refresh with R1 again (same call) | HTTP 401 (R1 has been rotated; see AC-3 reuse-detection in NFT-SEC-08) |
|
||||
| 3 | Inspect `sessions` table | Original row's `refresh_hash` rotated; new row has `parent_session_id` chained to the previous row |
|
||||
|
||||
**Expected outcome**: Rotation succeeds; old refresh dies; chain is preserved
|
||||
**Max execution time**: 5s
|
||||
|
||||
---
|
||||
|
||||
#### FT-P-32: Refresh Sliding + Absolute Expiry
|
||||
|
||||
**Summary**: Refresh tokens slide on use up to the per-family absolute cap (12 h since the family's first issue); after the absolute cap, refresh fails.
|
||||
**Traces to**: AZ-531 AC-4
|
||||
**Category**: Authentication
|
||||
|
||||
**Preconditions**:
|
||||
- A `sessions` family with `family_first_issued_at` set to `now() - 11h59m` (verified via DB seed) and a current valid refresh token R-current
|
||||
|
||||
**Input data**: `{"refresh_token":"<R-current>"}`, called near and past the absolute cap
|
||||
|
||||
**Steps**:
|
||||
|
||||
| Step | Consumer Action | Expected System Response |
|
||||
|------|----------------|------------------------|
|
||||
| 1 | POST /token/refresh at family-age 11h59m | HTTP 200, rotation succeeds; sliding window extended |
|
||||
| 2 | Seed another family with `family_first_issued_at = now() - 12h01s` | — |
|
||||
| 3 | POST /token/refresh on that family | HTTP 401, body indicates absolute-expiry violation |
|
||||
|
||||
**Expected outcome**: Sliding works inside 12 h; absolute cap rejects beyond
|
||||
**Max execution time**: 5s
|
||||
|
||||
---
|
||||
|
||||
### Asymmetric Signing + JWKS (AZ-532)
|
||||
|
||||
#### FT-P-33: GET /.well-known/jwks.json Serves the Active Public Key
|
||||
|
||||
**Summary**: The JWKS endpoint is anonymous, cacheable, and returns a well-formed JWKS containing the active EC P-256 public key with `kid`.
|
||||
**Traces to**: AZ-532 AC-2
|
||||
**Category**: Cryptography / Discovery
|
||||
|
||||
**Preconditions**:
|
||||
- Admin running with an ES256 keypair loaded from `secrets/jwt_signing_key.pem`
|
||||
|
||||
**Input data**: None (anonymous GET)
|
||||
|
||||
**Steps**:
|
||||
|
||||
| Step | Consumer Action | Expected System Response |
|
||||
|------|----------------|------------------------|
|
||||
| 1 | GET /.well-known/jwks.json (no JWT) | HTTP 200; `Content-Type: application/json`; `Cache-Control: public, max-age=3600` |
|
||||
| 2 | Parse body | `{"keys":[{"kty":"EC","crv":"P-256","kid":<non-empty>,"x":<base64url>,"y":<base64url>,"alg":"ES256","use":"sig"}, …]}` |
|
||||
|
||||
**Expected outcome**: JWKS shape matches RFC 7517; cache headers present
|
||||
**Max execution time**: 5s
|
||||
|
||||
---
|
||||
|
||||
#### FT-P-34: Two-Key Overlap During Rotation
|
||||
|
||||
**Summary**: When two signing keys are configured (`kid-A` active + `kid-B` standby), JWKS exposes both; tokens signed with the active key continue to verify; switching the active flag to `kid-B` produces `kid-B`-stamped tokens that also verify.
|
||||
**Traces to**: AZ-532 AC-3
|
||||
**Category**: Cryptography / Rotation
|
||||
|
||||
**Preconditions**:
|
||||
- Two keys configured in `secrets/`: `jwt_signing_key_a.pem` (active), `jwt_signing_key_b.pem` (standby)
|
||||
|
||||
**Input data**: Sequenced login + rotation toggle
|
||||
|
||||
**Steps**:
|
||||
|
||||
| Step | Consumer Action | Expected System Response |
|
||||
|------|----------------|------------------------|
|
||||
| 1 | GET /.well-known/jwks.json | Both `kid-A` and `kid-B` appear in `keys` array |
|
||||
| 2 | POST /login | Returned access token has `kid: kid-A` in header |
|
||||
| 3 | Toggle active key → `kid-B` (test-only admin endpoint or env reload) | — |
|
||||
| 4 | POST /login again | Returned access token has `kid: kid-B` in header |
|
||||
| 5 | Use either token against any protected endpoint | HTTP 200 (both verify against their respective public keys in JWKS) |
|
||||
|
||||
**Expected outcome**: Overlap window allows both keys; verifiers can keep working through rotation
|
||||
**Max execution time**: 10s
|
||||
|
||||
---
|
||||
|
||||
### Mission-Token Issuance for UAV (AZ-533)
|
||||
|
||||
#### FT-P-35: POST /sessions/mission Issues a Long-Lived Mission Token
|
||||
|
||||
**Summary**: An authenticated pilot session can mint a mission-class access token with a duration ≈ `planned_duration_h + 1h` and no refresh token.
|
||||
**Traces to**: AZ-533 AC-1
|
||||
**Category**: Mission Sessions
|
||||
|
||||
**Preconditions**:
|
||||
- Pilot user with valid (post-AZ-531) access token; MFA already proven within the session (post-AZ-534)
|
||||
- Aircraft user `UAV-117` with `Role=CompanionPC` exists
|
||||
|
||||
**Input data**: `{"mission_id":"M-2026-05-14-042","aircraft_id":"UAV-117","planned_duration_h":9,"requested_scope":["GPS"]}`
|
||||
|
||||
**Steps**:
|
||||
|
||||
| Step | Consumer Action | Expected System Response |
|
||||
|------|----------------|------------------------|
|
||||
| 1 | POST /sessions/mission with the body above + pilot access token | HTTP 200; body has `access_token`, no `refresh_token`, `exp` ≈ now + 10h ±60s |
|
||||
| 2 | Decode token payload | `token_class = "mission"` |
|
||||
| 3 | Query `sessions` table | Row with `class='mission'`, `aircraft_id='UAV-117'`, `revoked_at IS NULL` |
|
||||
|
||||
**Expected outcome**: Long-lived mission token issued; session persisted with class marker
|
||||
**Max execution time**: 5s
|
||||
|
||||
---
|
||||
|
||||
#### FT-P-36: Mission Token Carries Scope Claims
|
||||
|
||||
**Summary**: The mission token's payload exposes `mission_id`, `aircraft_id`, `aud`, `permissions`, `sid`, `jti`.
|
||||
**Traces to**: AZ-533 AC-3
|
||||
**Category**: Mission Sessions
|
||||
|
||||
**Preconditions**:
|
||||
- FT-P-35 just produced a mission token
|
||||
|
||||
**Input data**: The mission token from FT-P-35
|
||||
|
||||
**Steps**:
|
||||
|
||||
| Step | Consumer Action | Expected System Response |
|
||||
|------|----------------|------------------------|
|
||||
| 1 | Decode mission token payload | `mission_id == "M-2026-05-14-042"`, `aircraft_id == "UAV-117"`, `aud == "satellite-provider"`, `permissions` contains `"GPS"`, `sid` non-empty, `jti` non-empty |
|
||||
|
||||
**Expected outcome**: All scope claims present and correctly populated
|
||||
**Max execution time**: 5s
|
||||
|
||||
---
|
||||
|
||||
#### FT-P-37: Mission Token Auto-Revoked on Aircraft Reconnect
|
||||
|
||||
**Summary**: When the aircraft user behind a mission session calls `/login` or `/token/refresh` again, every open mission session for that aircraft is marked `revoked_reason='post_flight_reconnect'` and the mission token stops working.
|
||||
**Traces to**: AZ-533 AC-4
|
||||
**Category**: Mission Sessions
|
||||
|
||||
**Preconditions**:
|
||||
- Open mission session for `UAV-117` from FT-P-35 (token MT)
|
||||
|
||||
**Input data**: A `/login` from the `UAV-117` companion PC user
|
||||
|
||||
**Steps**:
|
||||
|
||||
| Step | Consumer Action | Expected System Response |
|
||||
|------|----------------|------------------------|
|
||||
| 1 | POST /login as `UAV-117` (CompanionPC creds) | HTTP 200, dual tokens (per AZ-531) |
|
||||
| 2 | Query `sessions` row for the original mission MT | `revoked_at` set; `revoked_reason = 'post_flight_reconnect'` |
|
||||
| 3 | Use MT against any protected endpoint | HTTP 401 |
|
||||
|
||||
**Expected outcome**: Reconnect implicitly revokes outstanding mission sessions for the same aircraft
|
||||
**Max execution time**: 10s
|
||||
|
||||
---
|
||||
|
||||
#### FT-N-18: POST /sessions/mission Requires Authentication
|
||||
|
||||
**Summary**: Without an Authorization header, mission-token issuance is rejected at the gateway.
|
||||
**Traces to**: AZ-533 AC-5
|
||||
**Category**: Mission Sessions
|
||||
|
||||
**Preconditions**: None
|
||||
|
||||
**Input data**: Same body as FT-P-35, no Authorization header
|
||||
|
||||
**Steps**:
|
||||
|
||||
| Step | Consumer Action | Expected System Response |
|
||||
|------|----------------|------------------------|
|
||||
| 1 | POST /sessions/mission with no JWT | HTTP 401 |
|
||||
|
||||
**Expected outcome**: Unauthenticated mission requests are rejected
|
||||
**Max execution time**: 5s
|
||||
|
||||
---
|
||||
|
||||
#### FT-N-19: POST /sessions/mission Rejects Over-Cap Duration
|
||||
|
||||
**Summary**: A request for `planned_duration_h > 12` is rejected with HTTP 400 and a descriptive error message.
|
||||
**Traces to**: AZ-533 AC-2
|
||||
**Category**: Mission Sessions
|
||||
|
||||
**Preconditions**:
|
||||
- Authenticated pilot session (with MFA `amr=mfa`)
|
||||
|
||||
**Input data**: `{"mission_id":"M-2026-05-14-099","aircraft_id":"UAV-117","planned_duration_h":15,"requested_scope":["GPS"]}`
|
||||
|
||||
**Steps**:
|
||||
|
||||
| Step | Consumer Action | Expected System Response |
|
||||
|------|----------------|------------------------|
|
||||
| 1 | POST /sessions/mission with the over-cap body | HTTP 400; response body contains `"planned_duration_h must be ≤ 12"` |
|
||||
|
||||
**Expected outcome**: 400 with cap-violation message; no session row created
|
||||
**Max execution time**: 5s
|
||||
|
||||
---
|
||||
|
||||
### TOTP-Based 2FA at Login (AZ-534)
|
||||
|
||||
#### FT-P-38: POST /users/me/mfa/enroll Returns Usable Secret + Recovery Codes
|
||||
|
||||
**Summary**: A user without MFA can begin enrollment and receives a 32-char base32 TOTP secret, an `otpauth://` URL, a base64 PNG QR, and 10 recovery codes (≥12 chars each).
|
||||
**Traces to**: AZ-534 AC-1
|
||||
**Category**: MFA Enrollment
|
||||
|
||||
**Preconditions**:
|
||||
- Authenticated user `mfauser@azaion.com`, `mfa_enabled = false`
|
||||
|
||||
**Input data**: `{"password":"<plaintext>"}`
|
||||
|
||||
**Steps**:
|
||||
|
||||
| Step | Consumer Action | Expected System Response |
|
||||
|------|----------------|------------------------|
|
||||
| 1 | POST /users/me/mfa/enroll with the body above | HTTP 200; body has `secret` (32-char base32), `otpauth_url` (matches `^otpauth://totp/`), `qr_png_base64` (non-empty), `recovery_codes` (length = 10, each ≥ 12 chars, base32) |
|
||||
| 2 | Read `users.mfa_enabled` for the user | Value still `false` (only flips after `confirm`) |
|
||||
|
||||
**Expected outcome**: Enrollment package returned; `mfa_enabled` not yet flipped
|
||||
**Max execution time**: 5s
|
||||
|
||||
---
|
||||
|
||||
#### FT-P-39: POST /users/me/mfa/confirm Activates MFA
|
||||
|
||||
**Summary**: Submitting a valid TOTP code from the just-issued secret completes enrollment and flips `mfa_enabled = true`.
|
||||
**Traces to**: AZ-534 AC-2
|
||||
**Category**: MFA Enrollment
|
||||
|
||||
**Preconditions**:
|
||||
- FT-P-38 just executed for the same user; the test holds the returned `secret`
|
||||
|
||||
**Input data**: `{"code":"<TOTP code computed from secret at current time>"}`
|
||||
|
||||
**Steps**:
|
||||
|
||||
| Step | Consumer Action | Expected System Response |
|
||||
|------|----------------|------------------------|
|
||||
| 1 | Compute current 6-digit TOTP from `secret` (RFC 6238, 30 s window) | 6 digits |
|
||||
| 2 | POST /users/me/mfa/confirm with the code | HTTP 200 |
|
||||
| 3 | Read `users.mfa_enabled` and `users.mfa_enrolled_at` | `mfa_enabled = true`, `mfa_enrolled_at` non-null |
|
||||
|
||||
**Expected outcome**: MFA activated; subsequent /login goes through the two-step flow
|
||||
**Max execution time**: 5s
|
||||
|
||||
---
|
||||
|
||||
#### FT-P-40: Two-Step Login With TOTP
|
||||
|
||||
**Summary**: When a user has MFA enabled, `/login` returns an MFA-required envelope with a short-lived `mfa_token`; calling `/login/mfa` with the `mfa_token` + a valid TOTP code yields the real access + refresh; the access token's `amr` claim contains both `pwd` and `mfa`.
|
||||
**Traces to**: AZ-534 AC-3
|
||||
**Category**: Authentication / MFA
|
||||
|
||||
**Preconditions**:
|
||||
- User from FT-P-39 (MFA enabled)
|
||||
|
||||
**Input data**: Valid email + password, then `mfa_token` + TOTP code
|
||||
|
||||
**Steps**:
|
||||
|
||||
| Step | Consumer Action | Expected System Response |
|
||||
|------|----------------|------------------------|
|
||||
| 1 | POST /login with email + password | HTTP 200; body = `{ "mfa_required": true, "mfa_token": "<short-lived JWT>", "expires_in": 300 }`; no access/refresh present |
|
||||
| 2 | POST /login/mfa with `{ "mfa_token": "<from step 1>", "code": "<TOTP>" }` | HTTP 200; body has access + refresh tokens |
|
||||
| 3 | Decode access token | `amr` claim = `["pwd","mfa"]` |
|
||||
|
||||
**Expected outcome**: Two-step flow completes; access token's `amr` reflects both factors
|
||||
**Max execution time**: 10s
|
||||
|
||||
---
|
||||
|
||||
#### FT-P-41: Recovery Code Substitutes for TOTP and Burns On Use
|
||||
|
||||
**Summary**: A recovery code may be used in place of a TOTP code at `/login/mfa`. The same code on a subsequent attempt fails (single-use). The successful access token's `amr` claim records `recovery`.
|
||||
**Traces to**: AZ-534 AC-4
|
||||
**Category**: Authentication / MFA
|
||||
|
||||
**Preconditions**:
|
||||
- User from FT-P-39; the test holds the `recovery_codes` array from FT-P-38
|
||||
|
||||
**Input data**: First recovery code, then re-use of the same code
|
||||
|
||||
**Steps**:
|
||||
|
||||
| Step | Consumer Action | Expected System Response |
|
||||
|------|----------------|------------------------|
|
||||
| 1 | POST /login → get `mfa_token` | HTTP 200, MFA-required envelope |
|
||||
| 2 | POST /login/mfa with `{ "mfa_token", "code": "<recovery_codes[0]>" }` | HTTP 200, access + refresh issued; `amr` = `["pwd","mfa","recovery"]` |
|
||||
| 3 | POST /login → get a new `mfa_token` | HTTP 200, MFA-required envelope |
|
||||
| 4 | POST /login/mfa with the SAME recovery code | HTTP 401 (recovery code burned) |
|
||||
|
||||
**Expected outcome**: Recovery code works once, then is rejected
|
||||
**Max execution time**: 10s
|
||||
|
||||
---
|
||||
|
||||
#### FT-P-42: POST /users/me/mfa/disable Removes MFA
|
||||
|
||||
**Summary**: Submitting password + a valid TOTP code disables MFA; subsequent `/login` returns access + refresh directly without the two-step flow.
|
||||
**Traces to**: AZ-534 AC-5
|
||||
**Category**: MFA Enrollment
|
||||
|
||||
**Preconditions**:
|
||||
- User from FT-P-39
|
||||
|
||||
**Input data**: `{"password":"<plaintext>","code":"<TOTP>"}`
|
||||
|
||||
**Steps**:
|
||||
|
||||
| Step | Consumer Action | Expected System Response |
|
||||
|------|----------------|------------------------|
|
||||
| 1 | POST /users/me/mfa/disable | HTTP 200 |
|
||||
| 2 | Read `users.mfa_enabled` | `false` |
|
||||
| 3 | POST /login with email + password | HTTP 200; body has access + refresh directly (no `mfa_required`) |
|
||||
|
||||
**Expected outcome**: MFA disabled, single-step login restored
|
||||
**Max execution time**: 5s
|
||||
|
||||
---
|
||||
|
||||
### Logout + Revocation Surface (AZ-535)
|
||||
|
||||
#### FT-P-43: POST /logout Revokes the Current Session
|
||||
|
||||
**Summary**: A POST /logout with a valid access token marks the session row revoked and disables the paired refresh token.
|
||||
**Traces to**: AZ-535 AC-1
|
||||
**Category**: Session Lifecycle
|
||||
|
||||
**Preconditions**:
|
||||
- Active session from a prior /login (access token A, refresh token R)
|
||||
|
||||
**Input data**: Authorization header `Bearer <A>`, empty body
|
||||
|
||||
**Steps**:
|
||||
|
||||
| Step | Consumer Action | Expected System Response |
|
||||
|------|----------------|------------------------|
|
||||
| 1 | POST /logout with bearer A | HTTP 200 |
|
||||
| 2 | Query the session row | `revoked_at` set; `revoked_reason = 'user_logout'` |
|
||||
| 3 | POST /token/refresh with R | HTTP 401 |
|
||||
|
||||
**Expected outcome**: Session revoked, refresh dies immediately
|
||||
**Max execution time**: 5s
|
||||
|
||||
---
|
||||
|
||||
#### FT-P-44: POST /logout/all Revokes Every Session for the User
|
||||
|
||||
**Summary**: A user with multiple active sessions can sign out of all of them in one call.
|
||||
**Traces to**: AZ-535 AC-2
|
||||
**Category**: Session Lifecycle
|
||||
|
||||
**Preconditions**:
|
||||
- User with three active sessions S1/S2/S3 (each from a separate /login)
|
||||
|
||||
**Input data**: Authorization header `Bearer <A from S1>`, empty body
|
||||
|
||||
**Steps**:
|
||||
|
||||
| Step | Consumer Action | Expected System Response |
|
||||
|------|----------------|------------------------|
|
||||
| 1 | POST /logout/all from S1 | HTTP 200 |
|
||||
| 2 | Query `sessions` for the user | All three rows have `revoked_at` set |
|
||||
| 3 | POST /token/refresh with the refresh tokens of S1/S2/S3 | All three return HTTP 401 |
|
||||
|
||||
**Expected outcome**: Every session for the user is revoked
|
||||
**Max execution time**: 10s
|
||||
|
||||
---
|
||||
|
||||
#### FT-P-45: POST /sessions/{sid}/revoke Lets Admin Kill Any Session
|
||||
|
||||
**Summary**: An Admin-role JWT can revoke any other user's session by id; the revoked row records the admin's user id.
|
||||
**Traces to**: AZ-535 AC-3
|
||||
**Category**: Admin Session Management
|
||||
|
||||
**Preconditions**:
|
||||
- Admin user with valid (post-AZ-531) access token
|
||||
- Target user with active session SID-X
|
||||
|
||||
**Input data**: Authorization header `Bearer <admin access>`, path `/sessions/<SID-X>/revoke`
|
||||
|
||||
**Steps**:
|
||||
|
||||
| Step | Consumer Action | Expected System Response |
|
||||
|------|----------------|------------------------|
|
||||
| 1 | POST /sessions/SID-X/revoke as admin | HTTP 200 |
|
||||
| 2 | Query the SID-X row | `revoked_at` set; `revoked_by_user_id` = admin's user id |
|
||||
| 3 | POST /token/refresh with SID-X's refresh | HTTP 401 |
|
||||
|
||||
**Expected outcome**: Admin-driven revocation works and records actor
|
||||
**Max execution time**: 5s
|
||||
|
||||
---
|
||||
|
||||
#### FT-P-46: GET /sessions/revoked?since=… Returns Recent, Non-Expired Revocations
|
||||
|
||||
**Summary**: A verifier identity (`Role=Service`) polls the snapshot endpoint and gets the recently-revoked, still-valid sessions; expired entries are auto-pruned.
|
||||
**Traces to**: AZ-535 AC-4
|
||||
**Category**: Verifier Snapshot
|
||||
|
||||
**Preconditions**:
|
||||
- 5 sessions revoked in the last hour, 2 of which already have `exp < now()`
|
||||
- Verifier identity (Service role) with valid bearer
|
||||
|
||||
**Input data**: Authorization header `Bearer <verifier access>`, query `?since=<unix-ts 1h ago>`
|
||||
|
||||
**Steps**:
|
||||
|
||||
| Step | Consumer Action | Expected System Response |
|
||||
|------|----------------|------------------------|
|
||||
| 1 | GET /sessions/revoked?since=<ts> with verifier bearer | HTTP 200; `Cache-Control: no-cache`; body is JSON array of length 3 |
|
||||
| 2 | Inspect each entry | `{ jti, sid, exp }` shape; no expired entries present |
|
||||
|
||||
**Expected outcome**: 3 non-expired revocations returned; expired ones pruned
|
||||
**Max execution time**: 5s
|
||||
|
||||
---
|
||||
|
||||
#### FT-P-47: POST /logout Is Idempotent
|
||||
|
||||
**Summary**: Logging out a session that is already revoked returns 200 with `already_revoked: true` and does not write to the DB.
|
||||
**Traces to**: AZ-535 AC-5
|
||||
**Category**: Session Lifecycle
|
||||
|
||||
**Preconditions**:
|
||||
- Already-revoked session from FT-P-43
|
||||
|
||||
**Input data**: Authorization header `Bearer <still-valid-but-stale access>`, empty body
|
||||
|
||||
**Steps**:
|
||||
|
||||
| Step | Consumer Action | Expected System Response |
|
||||
|------|----------------|------------------------|
|
||||
| 1 | POST /logout again | HTTP 200; body `{ "already_revoked": true }` |
|
||||
| 2 | Query the session row's `updated_at` (or equivalent audit column) | Unchanged from before step 1 |
|
||||
|
||||
**Expected outcome**: Idempotent — no second DB mutation
|
||||
**Max execution time**: 5s
|
||||
|
||||
Reference in New Issue
Block a user