palyra-auth and managed by the palyra-daemon via the openai_surface and openai_auth modules, ensures that sensitive credentials are never leaked in configuration files, instead persisting them in the secure Vault while referencing them via unique identifiers.
Auth Profile Registry
TheAuthProfileRegistry is the central management entity for credentials. It supports two primary types of credentials: static API keys and managed OAuth tokens. Profiles are scoped to either a global level or bound to a specific agent.
Key Data Structures
AuthProfileRecord: The persistent representation of a profile, including its provider kind, name, and scope crates/palyra-auth/src/models.rs#13-16.AuthCredential: An enum representing either anApiKey(containing a Vault reference) orOauth(containing Vault references for access/refresh tokens and endpoint metadata) crates/palyra-auth/src/models.rs#10-15.AuthProfileScope: Defines where the profile can be used, eitherGlobalorAgent(agent_id)crates/palyra-auth/src/models.rs#13-16.
Code Entity Mapping: Registry to Storage
The following diagram illustrates how theAuthProfileRegistry interacts with the Vault to protect credentials.
Registry and Vault Interaction
Sources: crates/palyra-auth/src/registry.rs#21, crates/palyra-auth/src/models.rs#10-16, crates/palyra-daemon/src/openai_surface.rs#42-48
OAuth Flows and Token Management
Palyra implements robust OAuth 2.0 flows, specifically optimized for OpenAI’s model provider surface. This includes PKCE (Proof Key for Code Exchange) for secure browser-based authorization and background token refreshing.OAuth Lifecycle
- Bootstrap: The user initiates a flow in the Web Console. The daemon generates a PKCE verifier and challenge crates/palyra-daemon/src/openai_auth.rs#99-107.
- Exchange: Upon callback, the daemon exchanges the authorization code for an access token and a refresh token crates/palyra-daemon/src/openai_auth.rs#132-140.
- Persistence: Tokens are stored in the Vault. The
AuthProfileRecordstores theaccess_token_vault_refandrefresh_token_vault_refcrates/palyra-cli/src/commands/auth.rs#161-166. - Refresh: The
OAuthRefreshAdapterhandles background refreshes when tokens expire, using a provider-specific backoff policy crates/palyra-auth/src/refresh.rs#17-20.
Implementation Details
openai_auth.rs: Contains logic for building authorization URLs, PKCE handling, and code exchange crates/palyra-daemon/src/openai_auth.rs#109-130.openai_surface.rs: Orchestrates the connection of API keys and OAuth profiles, including validation against provider endpoints crates/palyra-daemon/src/openai_surface.rs#18-40.
Session Management and Handoff
Thepalyrad daemon manages administrative sessions for the Web Console using a combination of secure cookies and CSRF tokens.
Console Sessions
When a user logs into the console, the daemon issues aConsoleSession which includes a session_token (stored in a SET-COOKIE header) and a csrf_token (returned in the JSON body) crates/palyra-daemon/src/transport/http/handlers/console/auth.rs#101-110.
Browser Handoff
For flows that require a local browser (like OAuth callbacks), Palyra uses a “handoff” mechanism:- A short-lived
ConsoleBrowserHandofftoken is minted crates/palyra-daemon/src/transport/http/handlers/console/auth.rs#140-146. - The browser is redirected to a loopback URL (typically
127.0.0.1) to consume the token and establish a session in the local environment crates/palyra-daemon/src/transport/http/handlers/console/auth.rs#154-157.
Provider Validation and Health
Before saving a profile, Palyra performs active validation to ensure the credentials are functional.- OpenAI Validation: Calls the
/v1/modelsendpoint using the provided bearer token crates/palyra-daemon/src/openai_auth.rs#189-195. - Anthropic Validation: Calls the Anthropic API with specific version headers (
2023-06-01) crates/palyra-daemon/src/openai_surface.rs#12-14. - Health Reporting: The
AuthHealthReportprovides real-time status of all profiles, identifying if they arestatic,managed,expiring, orexpiredcrates/palyra-auth/src/models.rs#11-13.
Auth Surface Testing
The system is verified via integration tests that mock provider responses. For example,openai_auth_surface.rs validates that API keys are correctly persisted as Vault references and that the default profile selection is reflected in the daemon’s configuration crates/palyra-daemon/tests/openai_auth_surface.rs#29-57.
Sources: crates/palyra-daemon/src/openai_surface.rs#34-40, crates/palyra-daemon/src/openai_surface.rs#96-102, apps/web/src/console/hooks/useAuthDomain.ts#96-116
CLI and Web UI Integration
CLI Commands
Thepalyra CLI provides a full suite of commands for managing profiles:
palyra auth profiles list: Lists all configured profiles crates/palyra-cli/src/commands/auth.rs#42-50.palyra auth profiles set: Manually creates or updates a profile with specific Vault references crates/palyra-cli/src/commands/auth.rs#122-139.
Web Console (AuthSection)
The React-basedAuthSection provides a user-friendly interface for the useAuthDomain hook. It allows users to:
- View a “Profile Inventory” with health status apps/web/src/console/sections/AuthSection.tsx#149-160.
- Initiate OAuth bootstrap flows apps/web/src/console/sections/AuthSection.tsx#48.
- Rotate API keys and set default profiles apps/web/src/console/sections/AuthSection.tsx#52-57.