senke/veza
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
veza/docs/audits/INTEGRATION_AUDIT_BACKEND_FRONTEND.md
senke 9e942bc48b batch 1
2025-12-22 22:00:50 +01:00

17 KiB
Raw Blame History

Integration Audit: Backend ↔ Frontend

Generated: 2025-01-27
Scope: veza-backend-api (Go) ↔ apps/web (React/TypeScript)
Auditor: Cursor AI
Health Score: 4/10

Executive Snapshot

Overall Integration Health: 4/10

The integration surface between backend and frontend shows significant contract drift, authentication inconsistencies, and configuration mismatches. While core flows (login, basic CRUD) function in development, production deployment will expose critical failures due to CORS misconfiguration, missing CSRF protection, type mismatches, and environment variable inconsistencies.

What is working:

  • Basic authentication flow (login/logout) works in dev
  • API client interceptors handle token refresh
  • Response unwrapping in apiClient correctly handles { success, data } format
  • Health check endpoints accessible

What is fragile:

  • CORS configuration will break in production (empty origins = reject all)
  • Multiple auth storage mechanisms cause token sync issues
  • Type mismatches (User.id: string vs number) will cause runtime errors
  • Environment variable naming inconsistencies (VITE_API_BASE_URL vs VITE_API_URL)
  • No CSRF protection for state-changing operations
  • Response format expectations mismatch between deprecated ApiService and apiClient
  • Missing error correlation IDs in frontend error boundaries

Real Architecture

Development Setup

Frontend (apps/web):

  • Vite dev server on http://localhost:3000
  • API calls via apiClient (axios) to VITE_API_URL (default: http://127.0.0.1:8080/api/v1)
  • No proxy configuration in vite.config.ts (direct CORS requests)
  • Token storage: localStorage (access_token, refresh_token)

Backend (veza-backend-api):

  • Gin server on :8080
  • Routes under /api/v1/* (v1 group)
  • CORS middleware: allows http://localhost:3000, http://127.0.0.1:3000, http://localhost:5173, http://127.0.0.1:5173 (dev defaults)
  • Auth: JWT tokens in Authorization: Bearer <token> header

Production Setup (Inferred)

Frontend:

  • Static build served via nginx (see apps/web/nginx.conf)
  • Nginx proxies /api/* to backend-api:8080
  • Environment variables baked at build time (VITE_*)

Backend:

  • CORS origins: REQUIRED via CORS_ALLOWED_ORIGINS env var
  • If CORS_ALLOWED_ORIGINS empty → rejects all origins (strict mode)
  • No proxy rewrite assumptions (routes expect /api/v1 prefix)

Critical Gap: Frontend expects /api/v1 in base URL, but nginx proxy may rewrite paths. No evidence of path rewriting in nginx config.

Contract Map

Frontend Module/Hook HTTP Method + Path Backend Handler Request Shape Response Shape Status
authApi.login() POST /api/v1/auth/login handlers.Login() { email, password, remember_me? } { success: true, data: { user: {...}, token: {...} } } ✅ Match
authApi.register() POST /api/v1/auth/register handlers.Register() { email, username, password } { success: true, data: { user: {...} } } ✅ Match
authApi.refresh() POST /api/v1/auth/refresh handlers.Refresh() { refresh_token } { success: true, data: { access_token, refresh_token, expires_in } } ✅ Match
authApi.getMe() GET /api/v1/auth/me handlers.GetMe() (auth header) { success: true, data: { id, email, role } } ⚠️ Partial (missing user fields)
apiClient.get('/tracks') GET /api/v1/tracks trackHandler.ListTracks() Query params { success: true, data: [...] } ✅ Match
apiClient.get('/tracks/:id') GET /api/v1/tracks/:id trackHandler.GetTrack() (path param) { success: true, data: {...} } ✅ Match
apiClient.post('/tracks') POST /api/v1/tracks trackHandler.UploadTrack() FormData { success: true, data: {...} } ✅ Match
apiClient.get('/users/:id') GET /api/v1/users/:id profileHandler.GetProfile() (path param) { success: true, data: { profile: {...} } } ⚠️ Nested profile key
apiClient.get('/playlists') GET /api/v1/playlists playlistHandler.GetPlaylists() Query params { success: true, data: [...] } ✅ Match
apiClient.post('/chat/token') POST /api/v1/chat/token chatHandler.GetToken() {} { success: true, data: { token } } ✅ Match
apiClient.get('/conversations') GET /api/v1/conversations roomHandler.GetUserRooms() (auth header) { success: true, data: [...] } ✅ Match
apiClient.post('/sessions/logout') POST /api/v1/sessions/logout sessionHandler.Logout() (auth header) { success: true, data: {...} } ✅ Match
apiClient.get('/health') GET /api/v1/health healthHandler.Check() - { success: true, data: {...} } ✅ Match
apiClient.get('/upload/limits') GET /api/v1/upload/limits uploadHandler.GetUploadLimits() - { success: true, data: {...} } ✅ Match
apiService.login() (deprecated) POST /api/v1/auth/login handlers.Login() { email, password } Expects { user, token } in data ❌ Mismatch (expects flat structure)
apiService.getUser() GET /api/v1/users/:id profileHandler.GetProfile() (path param) Expects profile or direct user ⚠️ Handles nested but fragile
2fa-service.ts GET /api/v1/2fa/status ❌ NOT FOUND - - ❌ Endpoint missing
2fa-service.ts POST /api/v1/2fa/setup ❌ NOT FOUND - - ❌ Endpoint missing
playlistService.addCollaborator() POST /api/v1/playlists/:id/collaborators ❌ NOT FOUND - - ❌ Endpoint missing
playlistService.removeCollaborator() DELETE /api/v1/playlists/:id/collaborators/:userId ❌ NOT FOUND - - ❌ Endpoint missing
playlistService.updateCollaborator() PUT /api/v1/playlists/:id/collaborators/:userId ❌ NOT FOUND - - ❌ Endpoint missing
playlistService.search() GET /api/v1/playlists/search ❌ NOT FOUND - - ❌ Endpoint missing
playlistService.share() POST /api/v1/playlists/:id/share ❌ NOT FOUND - - ❌ Endpoint missing
playlistService.getRecommendations() GET /api/v1/playlists/recommendations ❌ NOT FOUND - - ❌ Endpoint missing
trackApi.getTrackDownload() GET /api/v1/tracks/:id/download trackHandler.DownloadTrack() (path param) File stream ✅ Match
trackApi.likeTrack() POST /api/v1/tracks/:id/like trackHandler.LikeTrack() (path param) { success: true, data: {...} } ✅ Match
trackApi.unlikeTrack() DELETE /api/v1/tracks/:id/like trackHandler.UnlikeTrack() (path param) { success: true, data: {...} } ✅ Match
trackApi.deleteTrack() DELETE /api/v1/tracks/:id trackHandler.DeleteTrack() (path param) { success: true, data: {...} } ✅ Match
hlsService.getHLSInfo() GET /api/v1/tracks/:id/hls/info ❌ NOT FOUND - - ❌ Endpoint missing
hlsService.getHLSStatus() GET /api/v1/tracks/:id/hls/status ❌ NOT FOUND - - ❌ Endpoint missing
roleService.assignRole() POST /api/v1/users/:userId/roles ❌ NOT FOUND - - ❌ Endpoint missing
roleService.removeRole() DELETE /api/v1/users/:userId/roles/:roleId ❌ NOT FOUND - - ❌ Endpoint missing
roleService.updateRole() PUT /api/v1/roles/:roleId ❌ NOT FOUND - - ❌ Endpoint missing
roleService.deleteRole() DELETE /api/v1/roles/:roleId ❌ NOT FOUND - - ❌ Endpoint missing
profileService.getProfile() GET /api/v1/users/:userId/profile ❌ NOT FOUND (uses /users/:id instead) - - ⚠️ Path mismatch
profileService.updateProfile() PUT /api/v1/users/:userId/profile ❌ NOT FOUND (uses /users/:id instead) - - ⚠️ Path mismatch
avatarService.deleteAvatar() DELETE /api/v1/users/:userId/avatar ❌ NOT FOUND - - ❌ Endpoint missing
settingsService.updateSettings() PUT /api/v1/users/:userId/settings ❌ NOT FOUND - - ❌ Endpoint missing
notificationsApi.markRead() POST /api/v1/notifications/:id/read ❌ NOT FOUND - - ❌ Endpoint missing
notificationsApi.markAllRead() POST /api/v1/notifications/read-all ❌ NOT FOUND - - ❌ Endpoint missing

Summary: 18 endpoints called by frontend are missing or have path mismatches.

Top 5 Critical Issues (P0)

1. CORS Configuration Will Break Production

Severity: P0
Impact: All API requests will fail in production if CORS_ALLOWED_ORIGINS is not set.

Evidence:

  • veza-backend-api/internal/api/router.go:119-128: CORS middleware applied with config.CORSOrigins
  • veza-backend-api/internal/config/config.go:638-664: getCORSOrigins() returns empty list [] in production if CORS_ALLOWED_ORIGINS unset
  • veza-backend-api/internal/middleware/cors.go:34-37: Empty origins list → isAllowedOrigin() returns false → all CORS requests rejected

Root Cause: Production defaults to strict mode (reject all) but frontend expects CORS to work.

Fix Plan:

  1. Document CORS_ALLOWED_ORIGINS as REQUIRED in production
  2. Add startup validation: fail fast if APP_ENV=production and CORS_ALLOWED_ORIGINS empty
  3. Update deployment docs with example: CORS_ALLOWED_ORIGINS=https://app.veza.com,https://www.veza.com

Tests: E2E test with production-like CORS config.

2. Multiple Auth Storage Mechanisms Cause Token Sync Failures

Severity: P0
Impact: Tokens stored in multiple places (localStorage, Zustand persist, TokenStorage) can desync, causing auth failures.

Evidence:

  • apps/web/src/services/tokenStorage.ts:35-36: Stores in localStorage (keys: veza_access_token, veza_refresh_token)
  • apps/web/src/services/api/client.ts:48-64: Falls back to parsing auth-storage from Zustand if TokenStorage empty
  • apps/web/src/stores/auth.ts: Zustand store also manages auth state
  • apps/web/src/utils/token-manager.ts:25: Also stores in localStorage with different key (veza_access_token)

Root Cause: No single source of truth for token storage.

Fix Plan:

  1. Standardize on TokenStorage class as single source
  2. Remove Zustand token storage (keep only user and isAuthenticated flags)
  3. Remove token-manager.ts or migrate to TokenStorage
  4. Update all code to use TokenStorage.getAccessToken() / TokenStorage.setTokens()

Tests: Test token persistence across page reloads, multiple tabs.

3. Type Mismatch: User.id (string vs number)

Severity: P0
Impact: Runtime errors when accessing user.id in TypeScript, type coercion bugs.

Evidence:

  • apps/web/src/types/api.ts:3: User.id: string ✅
  • apps/web/src/features/auth/types/index.ts: id: number ❌ (inferred from usage)
  • apps/web/src/services/api/auth.ts: Uses number in some places
  • Backend: internal/dto/user_response.go: ID: uuid.UUID (serializes as string)

Root Cause: Inconsistent type definitions across frontend modules.

Fix Plan:

  1. Audit all User type definitions, standardize on id: string
  2. Update apps/web/src/features/auth/types/index.ts to use string
  3. Add TypeScript strict mode checks
  4. Update Zod schemas to validate UUID format

Tests: TypeScript compilation, runtime validation.

4. Deprecated ApiService Expects Wrong Response Format

Severity: P0
Impact: Code using deprecated ApiService will break when backend response format changes.

Evidence:

  • apps/web/src/services/api.ts:238-239: Expects { user, token } directly in data
  • Backend handlers.Login(): Returns { success: true, data: { user: {...}, token: {...} } } ✅
  • apps/web/src/services/api.ts:74-80: Marked as @deprecated but still used in some places

Root Cause: Legacy code expects flat structure, new code expects nested.

Fix Plan:

  1. Complete migration from ApiService to apiClient (see MIGRATION_GUIDE.md)
  2. Remove ApiService class entirely
  3. Update all imports to use apiClient from @/services/api/client

Tests: Verify all API calls use apiClient.

5. Missing CSRF Protection for State-Changing Operations

Severity: P0 (Security)
Impact: Vulnerable to CSRF attacks on POST/PUT/DELETE requests.

Evidence:

  • apps/web/src/services/csrf.ts:14-17: refreshCsrfToken() is a placeholder (not implemented)
  • apps/web/src/services/secure-auth.ts:119: Calls csrfService.refreshCsrfToken() but it does nothing
  • Backend: No CSRF middleware found in veza-backend-api
  • veza-chat-server/src/security/csrf.rs: CSRF exists in chat server but not in backend API

Root Cause: CSRF protection not implemented for REST API.

Fix Plan:

  1. Implement CSRF token generation endpoint: GET /api/v1/csrf-token
  2. Backend: Add CSRF middleware for POST/PUT/DELETE (exclude GET, OPTIONS)
  3. Frontend: Fetch CSRF token on app init, include in X-CSRF-Token header
  4. Update apiClient interceptor to add CSRF header

Tests: CSRF attack simulation, verify tokens validated.

Risk Register

Security Risks

Risk Severity Evidence Mitigation
CORS misconfiguration High Empty origins in prod → reject all Document required env var, add validation
No CSRF protection High csrf.ts placeholder, no backend middleware Implement CSRF tokens (see P0 #5)
Tokens in localStorage Medium XSS can steal tokens Consider httpOnly cookies (requires backend changes)
No SameSite cookie flags Medium Cookies not used, but if added later Set SameSite=Lax for cookies
CORS allows credentials Low Access-Control-Allow-Credentials: true OK if origins whitelisted correctly

Reliability Risks

Risk Severity Evidence Mitigation
Token storage desync High Multiple storage mechanisms Standardize on TokenStorage (see P0 #2)
Type mismatches High User.id string vs number Fix type definitions (see P0 #3)
Missing endpoints Medium 18 endpoints called but not implemented Implement or remove frontend calls
Error parsing inconsistencies Medium Multiple error formats handled Standardize on backend error format
No retry logic for 503/502 Low Handled in apiClient but no exponential backoff Add retry with backoff

Drift Risks

Risk Severity Evidence Mitigation
Response format changes High Deprecated ApiService expects different format Remove ApiService (see P0 #4)
Environment variable naming Medium VITE_API_BASE_URL vs VITE_API_URL Standardize on VITE_API_URL
Path mismatches Medium /users/:userId/profile vs /users/:id Align frontend paths with backend
Field name mismatches Low cover_art_path vs cover_art_url Document field mappings

Recommended Fix Order (1-2 weeks)

Week 1: Critical Fixes

Day 1-2: CORS & Environment

  • Add CORS validation on backend startup (fail if prod + empty origins)
  • Document CORS_ALLOWED_ORIGINS requirement
  • Standardize env var names (VITE_API_URL everywhere)
  • Update deployment configs

Day 3-4: Auth Storage

  • Audit all token storage usage
  • Remove Zustand token storage, keep only flags
  • Remove token-manager.ts or migrate to TokenStorage
  • Test token persistence across reloads

Day 5: Type Safety

  • Fix User.id type (string everywhere)
  • Update Zod schemas
  • Run TypeScript strict checks
  • Fix type errors

Week 2: API Contract & Security

Day 1-2: CSRF Protection

  • Implement backend CSRF endpoint
  • Add CSRF middleware
  • Update frontend to fetch/include tokens
  • Test CSRF protection

Day 3-4: Missing Endpoints

  • Audit all frontend API calls
  • Implement missing endpoints OR remove frontend calls
  • Fix path mismatches (/profile vs /users/:id)
  • Update API documentation

Day 5: Deprecated Code Removal

  • Complete migration from ApiService to apiClient
  • Remove ApiService class
  • Update all imports
  • Verify no regressions

Appendix

Commands Executed

# Searched for route definitions
grep -r "router\.(GET|POST|PUT|DELETE)" veza-backend-api/internal/api/

# Searched for API calls
grep -r "apiClient\.(get|post|put|delete)" apps/web/src/

# Searched for environment variables
grep -r "VITE_" apps/web/

# Searched for CORS configuration
grep -r "CORS" veza-backend-api/internal/

Search Hits Summary

  • Backend routes: 50+ endpoints found in router.go
  • Frontend API calls: 100+ calls found across services
  • Environment variables: 8 VITE_* vars found (inconsistent naming)
  • CORS config: 1 middleware, 1 config function
  • Auth storage: 3 different mechanisms found
  • Type definitions: 5+ User type definitions found

Logs Captured

No runtime logs captured (audit based on code analysis only).

End of Report