InfraForge Docs

InfraNotes Core · v2

Welcome

Select a document from the sidebar to read it.

Auth and User Data Isolation Guide

This guide documents authentication endpoints and how to implement frontend flows following user data isolation recommendations in user_data_isolation_recommendations.md.

Auth Endpoints

  • POST /api/auth/register: Register user {full_name, email, username, password}
  • GET /api/auth/verify-email?token=: Verify email token
  • POST /api/auth/resend-verification: {email}
  • POST /api/auth/login: {email, password} → access_token; returns 200 with mfa_required when needed
  • POST /api/auth/login/mfa: {email, password, mfa_code}
  • POST /api/auth/mfa/setup: generate TOTP secret and recovery codes (Bearer)
  • POST /api/auth/mfa/enable: {code} (Bearer)
  • POST /api/auth/mfa/disable (Bearer)
  • POST /api/auth/mfa/verify: {code} to mark session MFA-verified (Bearer)
  • GET /api/auth/mfa/server-time: server TOTP period for sync (dev aid)
  • POST /api/auth/forgot-password: {email}
  • GET /api/auth/verify-reset-token?token=
  • POST /api/auth/reset-password: {token, new_password}
  • POST /api/auth/refresh: via refresh_token cookie
  • POST /api/auth/logout: invalidate session (Bearer)
  • GET /api/auth/profile (Bearer)
  • PUT /api/auth/profile: {name?, password?, setup_mfa?, disable_mfa?} (Bearer)

Trusted devices

  • GET /api/auth/trusted-devices (Bearer)
  • POST /api/auth/trusted-devices: {fingerprint_hash, nickname?, trusted_days?} (Bearer)
  • POST /api/auth/trusted-devices/revoke: {fingerprint_hash} (Bearer)
  • POST /api/auth/trusted-devices/revoke-all (Bearer)

Sessions

  • GET /api/sessions (Bearer)
  • POST /api/sessions/revoke: {session_id} (Bearer)
  • POST /api/sessions/revoke-all (Bearer)

Security dashboard (Bearer)

  • GET /api/security/dashboard/overview?days=
  • GET /api/security/dashboard/timeline?days=
  • GET /api/security/dashboard/anomalies?sensitivity=
  • GET /api/security/location-history?limit=

Frontend Implementation Notes

  • Persist access_token securely; send as Authorization: Bearer ....
  • On login 200 with mfa_required=true, redirect to MFA verify flow; call /api/auth/login/mfa.
  • Handle refresh_token via cookie; refresh by calling /api/auth/refresh and update access token.
  • For trusted device registration, send device fingerprint hash and store nickname; display list allowing revoke.
  • For sessions, show active sessions list; allow revoking one/all; if current revoked, redirect to login.
  • Display security dashboard widgets using dashboard endpoints.

User Data Isolation (Backend-consumer guidance)

  • All list views must scope data to current user by default. Do not expose user_id filters in UI to broaden scope unless team-sharing is explicit.
  • For detail routes, if 401/403, handle as not authorized; do not attempt to enumerate IDs.
  • For Project Finance user flows, use authenticated user token; viewer/admin negative scenarios expect 401/403.

Curl Examples

Register:

curl -s -X POST http://localhost:8080/api/auth/register \
  -H 'Content-Type: application/json' \
  -d '{"full_name":"Jane Doe","email":"jane@example.com","username":"janed","password":"StrongPass123!"}'

Login:

curl -s -X POST http://localhost:8080/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"jane@example.com","password":"StrongPass123!"}'

Profile:

curl -s -H "Authorization: Bearer $TOKEN" http://localhost:8080/api/auth/profile

Sessions:

curl -s -H "Authorization: Bearer $TOKEN" http://localhost:8080/api/sessions

Trusted devices register:

curl -s -X POST http://localhost:8080/api/auth/trusted-devices \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"fingerprint_hash":"devhash-123","nickname":"My Laptop","trusted_days":30}'

Security overview:

curl -s -H "Authorization: Bearer $TOKEN" http://localhost:8080/api/security/dashboard/overview?days=7

Frontend Guide (High-level)

  1. Auth Store
  • Holds accessToken, user, mfaRequired flags. Interceptor refreshes on 401 using /api/auth/refresh.
  1. MFA Flow
  • On mfa_required, route to MFA page; submit code to /api/auth/login/mfa or /api/auth/mfa/verify when session-based.
  1. Trusted Devices UI
  • List devices, register (send fingerprint), revoke. Show trust badge in session info.
  1. Sessions UI
  • List sessions, revoke one/all; if current revoked, force logout.
  1. Security Dashboard Widgets
  • Overview KPIs: failed logins, score; timeline list with paging.
  1. Data Isolation
  • All fetchers scope to current user; handle 401/403 gracefully; never expose raw IDs in URLs to non-owners.