phpengine/specs/integrations/browser-api.md

Read this when changing browser-to-server API requests, sessions, CSRF, or JSON response behavior.

Browser JSON API

Implementing Files

File	Key symbols
ui/app/src/api/client.js	apiRequest, getSession, login, logout, navigation/notification functions
src/Core/Api/Api.php	Versioned route registry
src/Core/Api/Controller.php	JSON, request decoding, current user, CSRF, authorization helpers
src/Core/Api/AuthController.php	Session inspection, login, logout
src/Core/Api/*Controller.php	Navigation, configuration, user, and notification handlers

Flow

1. React boot calls getSession() through apiRequest().
2. The client resolves the URL against the Vite asset base, sends same-origin cookies, and accepts JSON.
3. The API reads the PHP session, produces a safe session DTO, and supplies a CSRF token when absent.
4. Later non-GET calls attach the in-memory token as X-CSRF-Token.
5. Controllers validate JSON/authentication/roles/CSRF as applicable, then return explicit JSON DTOs.

Trust Boundaries

Boundary	Mechanism	Location
Client-supplied URL path	API root is derived from same-origin Vite base; client uses fixed resource paths	ui/app/src/api/client.js
Credential input	Requires JSON object plus non-empty string username/password; verifies bcrypt hash server-side	AuthController::login()
Session fixation	Regenerates session ID after successful login	AuthController::login()
Cross-site state change	Session token compared with hash_equals before protected mutations	Controller::validateCsrfToken() and mutation controllers
Authorization	Authentication and role checks run in PHP before data access	Controller::requireAuthentication() / requireRole()
Sensitive output	Controllers return explicit DTOs instead of mapper fields	Controller, UserController, NotificationController
Browser-only route control	React redirects unauthorized users, but does not grant access	ui/app/src/routes.jsx

Config

• Base path: Vite base is /phengine/assets/app/; the API client removes /assets/app to reach application root.
• Credentials: fetch(..., { credentials: 'include' }).
• Cache policy: API responses send Cache-Control: no-store.
• Notification polling: 30,000 ms in NotificationMenu.

See API routes and identity spec.