curo/kite

Files

T

curo1305 80eb280233 docs(02): phase 2 verification report

4/5 success criteria verified; 1 blocker gap identified: admin JWT
does not return 403 on document content endpoints because api/documents.py
has no auth enforcement (Phase 1 legacy state, deferred to Phase 3 per D-03).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

2026-05-22 20:21:01 +02:00

21 KiB

Raw Blame History

phase, verified, status, score, overrides_applied, re_verification, gaps, human_verification

phase

verified

status

score

overrides_applied

re_verification

gaps

human_verification

02-users-authentication

2026-05-22T18:18:52Z

gaps_found

4/5

false

truth

status

reason

artifacts

missing

Attempting to access document content via an admin JWT returns 403

partial

The documents API (backend/api/documents.py) has no authentication enforcement at all — no get_current_user dependency, no JWT validation. Any request (with or without a JWT) accesses documents. An admin JWT does not receive a 403; it is simply ignored. Admin.py has no document-content endpoints (SEC-07's admin-response clause is met), but the documents API does not reject admin-role tokens or any tokens.

path	issue
backend/api/documents.py	No auth dependency on any endpoint. get_current_user is not imported or used. This is the pre-Phase-3 single-user API state — per D-03 note in STATE.md, auth enforcement on documents is deferred to Phase 3.

Either: add get_current_user + role check to documents.py endpoints NOW to make admin-JWT return 403, OR explicitly scope SC5's 'admin JWT returns 403' clause as a Phase 3 deliverable in ROADMAP.md.

test	expected	why_human
TOTP enrollment end-to-end	User scans otpauth:// link in authenticator app, enters 6-digit code, sees 10 backup codes, checks acknowledgment checkbox, enables 2FA, and thereafter login requires TOTP code	Multi-step UI flow with authenticator app interaction cannot be verified by grep or build

test	expected	why_human
Password reset email delivery	User receives reset email at their address, link expires after 1 hour, following the link and setting a new password returns 200 with 'Please sign in' (no auto-login), user must pass TOTP gate on next login	Requires SMTP/Celery infrastructure running and actual email receipt

test	expected	why_human
Sign out all devices from account settings	Clicking 'Sign out all devices' in AccountView invalidates all active sessions; other browser tabs/devices lose access on next request	Multi-session behavior requires multiple live browser sessions

test	expected	why_human
Admin panel tab navigation	Admin user sees shield icon 'Admin' link in sidebar, can navigate Users / Quotas / AI Config tabs, non-admin user does not see the admin link	UI rendering and role-conditional visibility require browser

Phase 2: Users & Authentication — Verification Report

Phase Goal: Users can register, log in (with optional TOTP 2FA), reset their password, and sign out all active sessions; admins can manage user accounts and assign AI providers — all enforced by a complete FastAPI dependency chain.

Verified: 2026-05-22T18:18:52Z Status: GAPS FOUND Re-verification: No — initial verification

Goal Achievement

Observable Truths (Success Criteria)

#	Truth	Status	Evidence
SC1	New user can register with strength-validated password; HIBP-listed password rejected	VERIFIED	`check_hibp()` in services/auth.py uses k-anonymity SHA-1 prefix (5 chars); `_validate_password_strength()` enforces 12+ chars, upper, lower, digit, special; 4 tests covering register success, duplicate email, weak password, HIBP breach all pass
SC2	User can enroll TOTP authenticator, receive 10 backup codes with acknowledgment gate, TOTP required on every subsequent login, backup code invalidated on first use	VERIFIED	`provision_totp()`, `generate_backup_codes(10)`, `store_backup_codes()` in services/auth.py; `BackupCodesDisplay.vue` has acknowledgment checkbox gating "Enable 2FA" button; `verify_backup_code()` iterates all codes (constant-time) and sets `used_at=now()` on match; Redis replay prevention on `totp_used:{user_id}:{code}` TTL=90s
SC3	User can reset password via email link (1-hour token), no auto-login after reset, returns to TOTP gate	VERIFIED	`create_password_reset_token()` / `decode_password_reset_token()` uses `typ="password-reset"` claim; `/password-reset/confirm` explicitly does NOT return access_token (comment: "AUTH-05 — user must pass TOTP gate on next login"); anti-enumeration: `/password-reset` always returns 202; test `test_password_reset_confirm_valid_no_autologin` passes
SC4	User can trigger "sign out all devices"; other sessions immediately invalidated; reuse of rotated refresh token revokes entire family	VERIFIED	`revoke_all_refresh_tokens()` marks all user's tokens revoked; `rotate_refresh_token()` checks `row.revoked=True` → calls `revoke_all_refresh_tokens()` + `send_security_alert_email.delay()` + raises `ValueError("token_family_revoked")`; `logout_all` endpoint (lines 370-379 api/auth.py) calls `revoke_all_refresh_tokens()`
SC5	Admin can create/deactivate/reset user accounts and assign AI provider; attempting to access document content via admin JWT returns 403	PARTIAL — BLOCKER	Admin CRUD endpoints verified (7 endpoints, `get_current_admin` on all, `_user_to_dict()` whitelist excludes `password_hash`/`credentials_enc`). BUT: `backend/api/documents.py` has NO auth enforcement at all — any request (with or without JWT) accesses documents. An admin JWT is not rejected; it is simply ignored. The 403 clause of SC5 is not met.

Score: 4/5 truths verified

Gap Detail: SC5 — Admin JWT Document Access

Status: PARTIAL / BLOCKER

The documents API (backend/api/documents.py) has no get_current_user or get_current_admin dependency on any endpoint. No JWT is validated. This is the pre-Phase 3 single-user API state, explicitly noted in STATE.md (D-03 decision):

"documents.user_id nullable Phase 1 — D-03 — no auth in Phase 1; Phase 2 migration adds NOT NULL after auth lands"

However, SEC-07 (Phase 2 requirement) states: "Admin role verified on every admin endpoint request; admin cannot access document content, extracted text, or cloud credentials in any response." The admin API endpoints correctly meet the first clause (all protected by get_current_admin) and the second clause (no document content in admin responses via _user_to_dict() whitelist). But the documents API itself is fully open — an admin JWT does not return 403 when accessing document content there.

Phase 3's scope (Document Migration & Multi-User Isolation) will add get_current_user to document endpoints and enforce resource.user_id == current_user.id. Once Phase 3 lands, all users (including admins) will only see their own documents. However, the ROADMAP SC5 specifically says "admin JWT returns 403 for document content" as a Phase 2 deliverable.

Options for resolution:

Add a narrow role-check guard in documents.py now (e.g., admin role in get_current_user → 403) — minimal Phase 2 work
Update ROADMAP.md to scope the "admin JWT → 403 on documents" clause to Phase 3 alongside full auth enforcement
Accept as-is noting Phase 3 fully resolves it (with ROADMAP update)

Required Artifacts

Artifact	Expected	Status	Details
`backend/services/auth.py`	Full auth service layer (Argon2, JWT, refresh, TOTP, backup codes, HIBP)	VERIFIED	428 lines; 16 exported functions; no FastAPI coupling (single mention of "HTTPException" is in module docstring comment, not import or raise)
`backend/deps/auth.py`	`get_current_user` + `get_current_admin` FastAPI dependencies	VERIFIED	Both functions present; `get_current_admin` raises 403 on non-admin role
`backend/api/auth.py`	Register, login, refresh, logout, logout-all, me, change-password, TOTP setup/enable/disable, password-reset, password-reset/confirm	VERIFIED	615 lines; 13 async handlers; all endpoints present
`backend/api/admin.py`	7 admin endpoints with `get_current_admin` on every handler	VERIFIED	380 lines; 7 handlers; `get_current_admin` count = 10; `_user_to_dict()` whitelist
`backend/db/models.py` (BackupCode)	`class BackupCode` with `used_at` nullable field	VERIFIED	`grep -c "class BackupCode"` = 1; `used_at: Mapped[Optional[datetime]]` present
`backend/db/models.py` (password_must_change)	`password_must_change` BOOLEAN column on User	VERIFIED	`grep -c "password_must_change"` = 1
`backend/migrations/versions/0002_add_backup_codes_and_password_must_change.py`	Alembic migration for backup_codes table and password_must_change column	VERIFIED	File exists: `ls migrations/versions/ \| grep backup_codes` returns file
`frontend/src/stores/auth.js`	Pinia store with `accessToken` in `ref()` memory only — no localStorage	VERIFIED	`grep -c "localStorage"` = 0; `accessToken = ref(null)` confirmed
`frontend/src/router/index.js`	`beforeEach` guard with redirect preservation	VERIFIED	`grep -c "beforeEach"` = 1
`frontend/src/views/auth/LoginView.vue`	Three-step login with TOTP + backup code paths	VERIFIED	File exists; contains backup code toggle
`frontend/src/views/auth/RegisterView.vue`	Registration with PasswordStrengthBar	VERIFIED	File exists; contains PasswordStrengthBar import
`frontend/src/views/AdminView.vue`	Tabbed admin panel	VERIFIED	File exists; imports all three tab components
`frontend/src/components/admin/AdminUsersTab.vue`	User CRUD with create/deactivate/reset	VERIFIED	File exists; wired to real API endpoints
`frontend/src/components/layout/AppSidebar.vue`	Role-gated admin link	VERIFIED	`grep -c "role.*admin"` = 1; shield-icon admin link with `v-if`

Key Link Verification

From	To	Via	Status	Details
`api/auth.py`	`services/auth.py`	All auth functions called in handlers	WIRED	`verify_totp()`, `rotate_refresh_token()`, `revoke_all_refresh_tokens()`, `check_hibp()`, etc.
`api/auth.py`	`app.state.redis`	`request.app.state.redis` in login + TOTP enable handlers	WIRED	Lines 212, 489 pass redis_client to `verify_totp()`
`api/admin.py`	`deps/auth.py:get_current_admin`	`Depends(get_current_admin)` on every handler	WIRED	Count = 10; all 7 handlers + deps chain
`api/admin.py`	`main.py`	`app.include_router(admin_router)`	WIRED	Confirmed in main.py
`frontend/src/stores/auth.js`	`frontend/src/api/client.js`	Bearer token injection in `request()`	WIRED	`accessToken` used for `Authorization: Bearer` header
`frontend/src/router/index.js`	`frontend/src/stores/auth.js`	`beforeEach` guard checks `authStore.accessToken`	WIRED	Guard redirects unauthenticated users to `/login?redirect=`
`frontend/src/components/auth/BackupCodesDisplay.vue`	`acknowledged` ref	Gates "Enable 2FA" button	WIRED	`@click="acknowledged && $emit('acknowledged')"`
`api/auth.py`	`tasks/email_tasks.py`	Deferred import `from tasks.email_tasks import send_reset_email` inside handler	WIRED	Pattern confirmed; consistent with document_tasks pattern

Data-Flow Trace (Level 4)

Artifact	Data Variable	Source	Produces Real Data	Status
`backend/services/auth.py:verify_totp`	`redis_client.get(replay_key)`	`app.state.redis` (aioredis)	Yes — real Redis TTL-keyed lookup	FLOWING
`backend/services/auth.py:verify_backup_code`	`rows` from `select(BackupCode)`	PostgreSQL via SQLAlchemy async	Yes — real DB query with `used_at.is_(None)` filter	FLOWING
`backend/api/admin.py:_user_to_dict`	Explicit whitelist dict	User ORM object from DB	Yes — DB-loaded User object, no document fields included	FLOWING
`frontend/src/stores/auth.js:accessToken`	`ref(null)` → set on successful login response	`api/client.js` login response	Yes — set from `data.access_token` on successful auth	FLOWING

Behavioral Spot-Checks

Behavior	Command	Result	Status
All Phase 2 auth tests pass	`python3 -m pytest tests/test_task1_models_config.py tests/test_task2_auth_service.py tests/test_auth_deps.py tests/test_auth_api.py tests/test_auth_totp.py tests/test_admin_api.py -q`	77 passed, 47 warnings in 8.98s	PASS
Frontend builds clean	`npm run build`	Built in 576ms; 11 chunks; exit 0	PASS
No localStorage in auth store	`grep -c "localStorage" frontend/src/stores/auth.js`	0	PASS
httpOnly refresh cookie	`grep -c "httponly\|HttpOnly\|httpOnly" backend/api/auth.py`	6	PASS
CORS locked to settings	`grep -c "cors_origins" backend/main.py`	4	PASS
Rate limiting on auth endpoints	`grep -c "@limiter.limit" backend/api/auth.py`	5 (register, login, refresh, TOTP enable, password-reset)	PASS
get_current_admin on every admin handler	`grep -c "get_current_admin" backend/api/admin.py`	10	PASS
No impersonation in admin.py (code)	`grep -n "impersonat" backend/api/admin.py` shows only comments/docstrings	0 code references	PASS
admin.py never returns password_hash	`_user_to_dict()` whitelist verified	password_hash only at line 186 (constructor write, not response)	PASS
Documents API unauthenticated	`grep -n "get_current_user" backend/api/documents.py`	0 matches — no auth enforcement	FAIL (SC5 gap)

Probe Execution

No declared probes found. Step 7c: SKIPPED (no probe-*.sh files in scripts/).

Requirements Coverage

Requirement	Plan	Description	Status	Evidence
AUTH-01	02-01, 02-02	Register with Argon2 + HIBP check + strength enforcement	SATISFIED	`hash_password()` uses pwdlib Argon2Hasher; `check_hibp()` k-anonymity; strength in `_validate_password_strength()`
AUTH-02	02-01, 02-02	JWT in Pinia memory; refresh in httpOnly SameSite=Strict cookie	SATISFIED	`accessToken = ref(null)` in store; `_set_refresh_cookie()` with httponly=True, samesite="strict"
AUTH-03	02-03	TOTP enrollment with 8-10 backup codes acknowledged before activation	SATISFIED	`generate_backup_codes(10)` + `BackupCodesDisplay.vue` acknowledgment checkbox
AUTH-04	02-02	Login via TOTP or single-use backup code; backup code invalidated on use	SATISFIED	`verify_totp()` and `verify_backup_code()` paths in login handler; `used_at` set on use
AUTH-05	02-03	Password reset via email; no auto-login; returns to TOTP gate	SATISFIED	Confirm endpoint returns 200 + message, no tokens; `revoke_all_refresh_tokens()` called
AUTH-06	02-03	Sign out all active sessions	SATISFIED	`logout_all` endpoint calls `revoke_all_refresh_tokens()`
AUTH-07	02-01	Refresh token family revocation on reuse + security alert	SATISFIED	`rotate_refresh_token()` detects `row.revoked=True` → revoke all + `send_security_alert_email.delay()`
AUTH-08	02-01, 02-03	TOTP single-use within validity window (replay prevention)	SATISFIED	Redis key `totp_used:{user_id}:{code}` TTL=90s in `verify_totp()`
SEC-01	02-02	CSRF protection (SameSite=Strict + Origin validation)	SATISFIED	`OriginValidationMiddleware` + SameSite=Strict on refresh cookie
SEC-02	02-02, 02-03	Rate limiting on auth endpoints (per-IP + per-account)	SATISFIED	slowapi `@limiter.limit()` decorators + Redis per-account counter `login_attempts:{email}`
SEC-03	02-01	Parameterized queries / ORM	SATISFIED	All DB ops use SQLAlchemy ORM; zero raw string interpolation
SEC-05	02-02	CSP + X-Frame-Options + X-Content-Type-Options headers	SATISFIED	`SecurityHeadersMiddleware` in main.py adds all three headers
SEC-06	02-01	Constant-time comparison for all token/code verification	SATISFIED	`pwdlib.verify()` (constant-time); backup code verification iterates ALL rows without early exit
SEC-07	02-04	Admin role on every admin endpoint; admin cannot see document content	PARTIAL	Admin API enforced via `get_current_admin` (VERIFIED). But `backend/api/documents.py` has no auth at all — admin JWT not rejected on document access (SC5 gap)
ADMIN-01	02-04, 02-05	Admin creates user with temp password, `password_must_change=True`	SATISFIED	`POST /api/admin/users` sets `password_must_change=True`; login flow checks flag
ADMIN-02	02-04, 02-05	Admin deactivates user account	SATISFIED	`PATCH /api/admin/users/{id}/status` with sole-admin guard
ADMIN-03	02-04	Admin initiates password reset for user (email, no impersonation)	SATISFIED	`POST /api/admin/users/{id}/password-reset` dispatches `send_reset_email.delay()`
ADMIN-04	02-04, 02-05	Admin views/adjusts quotas with below-usage warning	SATISFIED	`GET/PATCH /api/admin/users/{id}/quota`; `AdminQuotasTab.vue`
ADMIN-05	02-04, 02-05	Admin assigns AI provider/model per user	SATISFIED	`PATCH /api/admin/users/{id}/ai-config`; `AdminAiConfigTab.vue`
ADMIN-07	02-04	Admin impersonation explicitly excluded	SATISFIED	No impersonation endpoint; test_admin_impersonation_not_found asserts 404/422

Anti-Patterns Found

File	Line	Pattern	Severity	Impact
`backend/api/documents.py`	All endpoints	No `get_current_user` dependency — fully unauthenticated	BLOCKER	Admin JWT does not return 403 for document content (SC5 gap); any request accesses all documents
`backend/api/documents.py`	167	Comment: "D-03: user_id is NULLABLE in Phase 1"	INFO	Documented intentional deferral to Phase 3

No TBD/FIXME/XXX markers found in Phase 2 deliverable files.

Human Verification Required

4 items need human testing:

1. TOTP Enrollment End-to-End

Test: Log in as a user, navigate to Account settings, click "Set up two-factor authentication", scan the otpauth:// link with an authenticator app, enter the 6-digit code, view the 10 backup codes screen, check the acknowledgment checkbox, click "Enable 2FA"

Expected: 2FA is enabled; next logout + login requires a TOTP code or backup code; login succeeds with valid code and fails with invalid code

Why human: Multi-step flow requires a real authenticator app; the otpauth:// link rendering (note: QR image is not rendered — only the link text) is a known MVP deviation

2. Password Reset Email Delivery

Test: Trigger password reset for a test account; check the email inbox; follow the reset link; set a new password; attempt to log in without TOTP

Expected: Email arrives with correct reset link; link expires after 1 hour; successful reset returns "Password updated. Please sign in." message (no tokens); login proceeds to TOTP gate if 2FA was enabled

Why human: Requires SMTP server (Celery + email infrastructure) and actual email receipt; anti-enumeration means the 202 response alone can't confirm email dispatch

3. Sign Out All Devices

Test: Log in from two browser tabs; click "Sign out all devices" in Account settings in Tab 1; make an authenticated request in Tab 2

Expected: Tab 2's access token is invalidated on next request; Tab 2 is redirected to login; reusing the revoked refresh token causes full family revocation

Why human: Multi-session testing requires two live sessions; refresh token reuse detection requires timing

4. Admin Panel Role Visibility

Test: Log in as a regular user; verify Admin link is NOT visible in sidebar. Log in as admin; verify "Admin" link with shield icon appears; navigate Users / Quotas / AI Config tabs; create a test user; deactivate them; reset their password

Expected: Non-admin users never see the admin UI; admin can perform all CRUD operations; inline deactivation confirmation shows correct user email

Why human: Visual rendering and role-conditional DOM requires browser; inline confirmation UX requires human interaction

Gaps Summary

1 BLOCKER gap preventing full Phase 2 goal achievement:

SC5 — Admin JWT → 403 on document content

The documents API (backend/api/documents.py) is completely unauthenticated — a Phase 1 legacy state explicitly noted in STATE.md (D-03 decision). An admin JWT does NOT return 403 when accessing document endpoints because the documents API has no JWT validation at all. The admin.py API correctly has no document content endpoints, and _user_to_dict() correctly excludes sensitive fields. But the literal clause of SC5 and SEC-07's "admin cannot access document content...in any response" is not enforced at the document endpoint layer.

Root cause: Phase 2 scope defines auth enforcement on new endpoints (api/auth.py, api/admin.py) but does not retrofit authentication onto the legacy api/documents.py, api/topics.py, or api/settings.py. Phase 3 ("Document Migration & Multi-User Isolation") will add per-user isolation to these endpoints.

Recommended resolution before marking Phase 2 complete:

Narrowest fix: add a current_user: User = Depends(get_current_user) check to document endpoint functions, returning 403 if user.role == "admin" — minimal change, no migration needed
Broader fix: update ROADMAP.md to scope SC5's "admin JWT → 403 on documents" clause as part of Phase 3 auth enforcement (where get_current_user will be added everywhere anyway)

Verified: 2026-05-22T18:18:52Z Verifier: Claude (gsd-verifier)

21 KiB Raw Blame History