Overview
The Web Console architecture is built around a centralized state container,useConsoleAppState, which orchestrates several domain-specific hooks. Communication with the palyrad daemon is handled by the ConsoleApiClient, which enforces CSRF protection and manages authentication headers.
System Data Flow
The following diagram illustrates the relationship between the React UI components, the state management layer, and the backend API. Console Data Flow & Entity Mapping Sources: apps/web/src/console/useConsoleAppState.tsx#164-220, apps/web/src/console/ConsoleSectionContent.tsx#26-107, apps/web/src/consoleApi.ts#1-100Console State Management
TheuseConsoleAppState hook serves as the root of the console’s reactive state. It handles the initial “booting” sequence, session recovery, and section-based navigation.
Key State Properties
booting: A boolean flag that prevents UI rendering until the initial session is verified or a login is required apps/web/src/console/useConsoleAppState.tsx#168.session: Holds theConsoleSessionobject containing the principal name, device ID, and CSRF token apps/web/src/console/useConsoleAppState.tsx#169.section: Tracks the active navigation area (e.g.,overview,usage,operations) apps/web/src/console/useConsoleAppState.tsx#170.
Domain Hooks
To prevent the root state from becoming bloated, logic is delegated to specialized domain hooks:useUsageDomain: Manages token aggregates, latency metrics, and cost estimates apps/web/src/console/sections/UsageSection.tsx#36.useBrowserDomain: Handles browser session profiles and relay tokens apps/web/src/console/useConsoleAppState.tsx#222.useConfigDomain: Manages TOML configuration mutations and validation apps/web/src/console/useConsoleAppState.tsx#223.useSupportDomain: Handles diagnostic bundle generation and system logs apps/web/src/console/useConsoleAppState.tsx#225.
Console API Client
TheConsoleApiClient is a class-based wrapper around the fetch API. It is responsible for standardizing request headers and handling response serialization.
Security Implementation
The client implements a “fail-closed” security model for mutating requests.| Feature | Implementation |
|---|---|
| CSRF Protection | Mutating methods (POST/PUT/DELETE) automatically inject the x-palyra-csrf-token header from the active session apps/web/src/consoleApi.test.ts#44-90. |
| Credentials | All requests include credentials: "include" to support cookie-based session affinity where applicable apps/web/src/consoleApi.test.ts#89. |
| Validation | The client throws a ControlPlaneApiError for non-2xx responses, which the UI uses to trigger error notices apps/web/src/consoleApi.ts#13-16. |
Request Dispatch Logic
The client distinguishes between idempotent (GET) and non-idempotent requests. If a mutating request is attempted without a valid CSRF token in the session, the client throws an error before the request hits the wire apps/web/src/consoleApi.test.ts#92-106. Sources: apps/web/src/consoleApi.ts#1-100, apps/web/src/consoleApi.test.ts#44-106Authentication & Desktop Handoff
Palyra supports a specialized “Desktop Handoff” flow, allowing a user to move from a CLI or Desktop app environment to the Web Console without re-authenticating.Handoff Flow Sequence
Desktop Handoff LogicImplementation Details
- Token Detection: On mount,
useConsoleAppStatechecks for thedesktop_handoff_tokenquery parameter apps/web/src/console/useConsoleAppState.tsx#133-143. - Consumption: The
loadDesktopHandoffSessionfunction attempts to exchange this one-time token for a full session apps/web/src/console/useConsoleAppState.tsx#109-123. - Cleanup: Upon successful exchange,
clearDesktopHandoffTokenFromAddressBaruseswindow.history.replaceStateto remove the sensitive token from the URL without a page reload apps/web/src/console/useConsoleAppState.tsx#145-153. - Retry Strategy: If the initial session check fails due to rate limiting (429) or transient errors, the console performs up to 5 retries with exponential backoff apps/web/src/console/useConsoleAppState.tsx#88-107.
CSRF and Session Security
Security headers are strictly enforced by the daemon and verified by the client.Admin vs Console Security
The daemon distinguishes betweenAdmin and Console surfaces. The Console surface requires session-based authentication, whereas the Admin surface (used by CLI) relies on the Authorization: Bearer <ADMIN_TOKEN> header and specific context headers like x-palyra-principal crates/palyra-daemon/tests/admin_surface.rs#46-61.
Security Headers
Every response from the console API includes strict security headers to prevent common web vulnerabilities:X-Content-Type-Options: nosniffX-Frame-Options: DENYContent-Security-Policy(Restricting script execution)