access_control.rs.
Admin HTTP and gRPC Authentication
The admin surface (typically listening on port 7142) requires explicit authentication for all requests. It distinguishes between machine-to-machine (CLI/API) access and interactive operator access (Web Console).Principal Binding and Static Tokens
For CLI and programmatic access,palyrad validates a static admin token (provided via PALYRA_ADMIN_TOKEN or config) passed in the Authorization: Bearer <token> header crates/palyra-daemon/tests/admin_surface.rs#48-61.
Every request must also provide context headers to bind the action to a specific principal and device:
x-palyra-principal: The identity performing the action (e.g.,user:opsoradmin:web-console) crates/palyra-daemon/src/gateway.rs#86.x-palyra-device-id: A unique ULID identifying the source hardware crates/palyra-daemon/src/gateway.rs#87.x-palyra-channel: The interface being used (e.g.,cli,web,discord) crates/palyra-daemon/src/gateway.rs#88.
Console Session Security
The Web Console uses a specialized security model to protect against cross-site attacks:- CSRF Protection: Browser-based requests must include a CSRF token validated against the session state crates/palyra-daemon/tests/openai_auth_surface.rs#45-50.
- Security Headers: The daemon enforces strict security headers on all admin responses, including
X-Content-Type-Options: nosniffandX-Frame-Options: DENYcrates/palyra-daemon/tests/admin_surface.rs#44-65. - Rate Limiting: Brute-force attempts on the admin status and auth endpoints are restricted by a middleware-layer rate limiter crates/palyra-daemon/tests/admin_surface.rs#152-173.
Data Flow: Admin Request Validation
The following diagram illustrates how an incoming HTTP request is validated before reaching an admin handler. Title: Admin Request Authentication Flow Sources:[crates/palyra-daemon/src/gateway.rs#40-44](http://crates/palyra-daemon/src/gateway.rs#40-44), [crates/palyra-daemon/tests/admin_surface.rs#29-72](http://crates/palyra-daemon/tests/admin_surface.rs#29-72).
Access Control and RBAC
Palyra implements a Role-Based Access Control (RBAC) system managed byAccessRegistry crates/palyra-daemon/src/access_control.rs#169-188. This system governs permissions for the Compatibility API, workspace management, and sensitive operations.
Roles and Permissions
Permissions are grouped into three primaryWorkspaceRole levels crates/palyra-daemon/src/access_control.rs#74-80:
| Role | Permissions |
|---|---|
| Owner | Full system control, including trust.operate, api_tokens.manage, and rollout.manage crates/palyra-daemon/src/access_control.rs#114-122. |
| Admin | Management of tokens, memberships, and sharing crates/palyra-daemon/src/access_control.rs#124-130. |
| Operator | Usage-only permissions: sessions.use, memory.use, and routines.use crates/palyra-daemon/src/access_control.rs#104-112. |
Feature Flags
The system uses feature flags to gate access to entire subsystems crates/palyra-daemon/src/access_control.rs#18-22:compat_api: Enables the OpenAI-compatible HTTP surface.api_tokens: Enables management of long-lived API keys.rbac: Enforces granular role checks.
[crates/palyra-daemon/src/access_control.rs#137-188](http://crates/palyra-daemon/src/access_control.rs#137-188).
OpenAI Auth Surface
The OpenAI authentication surface manages the lifecycle of credentials used to interact with OpenAI-compatible model providers. This includes both static API keys and OAuth2 flows.Credential Persistence
When a user connects an OpenAI account via the console, the daemon:- Validates the key against the configured
base_url(targeting/v1/models) crates/palyra-daemon/src/openai_auth.rs#189-195. - Stores the sensitive key in the Vault and creates a
VaultRefcrates/palyra-daemon/tests/openai_auth_surface.rs#92-100. - Creates an
AuthProfileRecordin theAuthProfileRegistrypalyra-auth/src/lib.rs#10-21.
OAuth2 and PKCE
For OAuth-based providers, the daemon implements the Authorization Code Flow with PKCE (Proof Key for Code Exchange) crates/palyra-daemon/src/openai_auth.rs#99-107.- State Verification: An
OpenAiOAuthAttemptStateRecordtracks pending exchanges to prevent CSRF during callbacks crates/palyra-daemon/src/openai_auth.rs#52-56. - Token Refresh: The
OAuthRefreshAdapterhandles automatic background rotation of expired access tokens using stored refresh tokens palyra-auth/src/lib.rs#17-20.
[crates/palyra-daemon/src/openai_auth.rs#132-187](http://crates/palyra-daemon/src/openai_auth.rs#132-187), [crates/palyra-daemon/tests/openai_auth_surface.rs#29-62](http://crates/palyra-daemon/tests/openai_auth_surface.rs#29-62).
Compatibility API Security
The Compatibility API (/v1/chat/completions, etc.) allows external tools to use Palyra as an OpenAI-compatible backend. This surface is strictly gated by API tokens managed in access_control.rs.
Token Enforcement
Every request to the compat surface is checked for:- Token Validity: The token must exist in the
AccessRegistryand not be revoked or expired crates/palyra-daemon/src/transport/http/handlers/compat.rs#110. - Scope Verification: The token must possess specific scopes like
compat.chat.createcrates/palyra-daemon/src/transport/http/handlers/compat.rs#4-5. - Rate Limiting: Requests are checked against
rate_limit_per_minutedefined on the token record crates/palyra-daemon/src/transport/http/handlers/compat.rs#111.
Audit Logging
Actions performed via the Compatibility API are logged with thecompat-api channel identifier crates/palyra-daemon/src/transport/http/handlers/compat.rs#11. The touch_compat_api_token function updates the last_used_at_unix_ms and records telemetry for monitoring crates/palyra-daemon/src/transport/http/handlers/compat.rs#114-121.
Sources: [crates/palyra-daemon/src/transport/http/handlers/compat.rs#105-126](http://crates/palyra-daemon/src/transport/http/handlers/compat.rs#105-126), [crates/palyra-daemon/src/access_control.rs#151-173](http://crates/palyra-daemon/src/access_control.rs#151-173).