palyra-auth crate provides the low-level primitives for managing credentials and OAuth state, while the palyra-control-plane crate defines the models and client used for communication between the operator’s interface (CLI/Web Console) and the daemon.
palyra-auth: Authentication Primitives
Thepalyra-auth crate is responsible for the lifecycle of credentials used by the ModelProvider and other external integrations. It handles storage, validation, and background refreshing of OAuth tokens.
Auth Credentials and Registry
TheAuthProfileRegistry is the central manager for AuthProfileRecord entities crates/palyra-auth/src/lib.rs#21. It supports various credential types including API keys and OAuth2 refresh tokens.
| Entity | Role | Source |
|---|---|---|
AuthCredential | Represents a raw secret or token. | crates/palyra-auth/src/lib.rs#10-16 |
AuthProfileRecord | A named identity containing credentials and metadata. | crates/palyra-auth/src/lib.rs#10-16 |
AuthProfileScope | Defines if a profile is Global or scoped to a specific Principal. | crates/palyra-auth/src/lib.rs#10-16 |
AuthHealthReport | Status of a credential (e.g., Valid, Expired, RateLimited). | crates/palyra-auth/src/lib.rs#10-16 |
OAuth Refresh Logic
For providers like OpenAI that use OAuth2, the crate implements an automated refresh mechanism. TheOAuthRefreshAdapter trait allows for provider-specific refresh implementations crates/palyra-auth/src/lib.rs#17-20.
- Backoff Policy: Uses
compute_backoff_msto handle transient failures during token refresh crates/palyra-auth/src/lib.rs#17-20. - Outcome Tracking:
OAuthRefreshOutcomecategorizes results intoSuccess,TransientFailure, orPermanentFailure(requiring re-authentication) crates/palyra-auth/src/lib.rs#17-20.
palyra-control-plane: Management Interface
Thepalyra-control-plane crate provides the high-level API client and data models used by the Web Console and CLI to manage the daemon.
Control Plane Client
TheControlPlaneClient is a high-level wrapper around reqwest that communicates with the daemon’s Admin API (/console/v1/*) crates/palyra-control-plane/src/client.rs#33-40.
- Session Management: Handles login via
login()and maintains CSRF tokens viaset_csrf_token()crates/palyra-control-plane/src/client.rs#63-83. - Browser Control: Provides methods like
create_browser_session(),navigate_browser_session(), andclick_browser_session()crates/palyra-control-plane/src/client.rs#179-215. - Handoffs: Supports
create_browser_handoff()for transitioning sessions between the CLI and the Web Console crates/palyra-control-plane/src/client.rs#85-91.
Data Models
Themodels.rs file defines the JSON-serializable structures that form the Palyra API contract.
ConsoleSession: Represents an active operator session, including theprincipal,device_id, andcsrf_tokencrates/palyra-control-plane/src/models.rs#19-29.DeploymentPostureSummary: Provides a snapshot of the daemon’s security state, including TLS status and remote bind detections crates/palyra-control-plane/src/models.rs#61-74.AgentRecord: Defines agent configuration, includingworkspace_rootsanddefault_model_profilecrates/palyra-control-plane/src/models.rs#190-203.
OpenAI Auth Integration
The daemon includes a specializedopenai_auth.rs module for handling the OpenAI-specific OAuth flow. This module bridges the palyra-auth primitives with the OpenAI API requirements.
PKCE Flow and Token Exchange
The integration implements Proof Key for Code Exchange (PKCE) to secure the authorization code flow.- Challenge Generation:
generate_pkce_verifier()andpkce_challenge()create the necessary cryptographic strings crates/palyra-daemon/src/openai_auth.rs#99-107. - Authorization URL:
build_authorization_url()constructs the redirect toauth.openai.comcrates/palyra-daemon/src/openai_auth.rs#109-130. - Token Exchange:
exchange_authorization_code()swaps the code for anaccess_tokenandrefresh_tokencrates/palyra-daemon/src/openai_auth.rs#132-187.
Token Validation
Thevalidate_openai_bearer_token() function performs a “smoke test” by calling the /v1/models endpoint to ensure the provided token is functional before saving it to the registry crates/palyra-daemon/src/openai_auth.rs#189-195.
Sources: crates/palyra-daemon/src/openai_auth.rs#1-195
Objectives and Automation Management
Objectives represent long-running goals or “standing orders” assigned to agents. They are managed by theObjectiveRegistry crates/palyra-daemon/src/objectives.rs#169-173.
Objective Structure
AnObjectiveRecord tracks the high-level intent and its current execution state.
| Field | Description |
|---|---|
kind | Objective, Heartbeat, StandingOrder, or Program. |
state | Draft, Active, Paused, Cancelled, or Archived. |
budget | Constraints on max_runs and max_tokens. |
automation | Links the objective to the cron scheduler via ObjectiveAutomationBinding. |
Data Flow: Console to Objective Execution
The following diagram illustrates how an operator’s request in the Web Console flows through the Control Plane into the daemon’s objective registry and scheduler. Control Plane to Objective Flow Sources: crates/palyra-daemon/src/transport/http/handlers/console/objectives.rs#66-130, crates/palyra-daemon/src/objectives.rs#221-228, crates/palyra-control-plane/src/client.rs#89-91Authentication and Session Flow
Theconsole_login_handler manages the transition from an administrative principal and admin_token to a browser-based ConsoleSession secured by cookies and CSRF tokens.
Logic Flow: Console Authentication
Handoff Mechanism
Theconsole_browser_handoff_handler allows the CLI to generate a short-lived URL that automatically logs a browser into the Web Console crates/palyra-daemon/src/transport/http/handlers/console/auth.rs#127-159.
- Mint: CLI calls
create_browser_handoff. - Store: Daemon stores
ConsoleBrowserHandoffwith a 60s TTL crates/palyra-daemon/src/transport/http/handlers/console/auth.rs:5, 141-152. - Consume: Browser navigates to
/consume?token=..., which converts the handoff into a fullConsoleSessioncrates/palyra-daemon/src/transport/http/handlers/console/auth.rs:154-157, 161-170.