Schema Design Principles
Palyra utilizes a “Strict Envelope” pattern for all JSON-based communication. This pattern is characterized by several key constraints:- Versioning: Every envelope must contain a
vfield (integer) representing the schema version crates/palyra-common/src/lib.rs#31-32. - Strictness: Schemas are defined with
additionalProperties: falseto prevent silent data degradation and ensure forward compatibility is handled explicitly. - Payload Caps: Hard limits are enforced on the size of payloads and the number of entities (e.g., files) touched in a single operation to prevent resource exhaustion crates/palyra-common/src/workspace_patch.rs#23-39.
Canonical Versions
The system currently tracks two primary version constants:CANONICAL_PROTOCOL_MAJOR: 1CANONICAL_JSON_ENVELOPE_VERSION: 1
Webhook Envelopes (webhook-envelope.v1.json)
The Webhook system uses the WebhookEnvelope to wrap external event data. It provides cryptographic verification and replay protection.
Implementation Details
TheWebhookEnvelope structure and its associated logic are implemented in palyra-common.
| Component | Code Entity | Role |
|---|---|---|
| Data Structure | WebhookEnvelope | The root JSON object containing v, payload, and signature. |
| Verification | WebhookSignatureVerifier | Validates Ed25519 or HMAC signatures against the payload. |
| Replay Guard | ReplayNonceStore | Tracks nonces to prevent duplicate event processing. |
| Parsing | parse_webhook_payload | Validates the JSON structure against the versioned schema. |
Webhook Data Flow
This diagram illustrates the transition from an incoming HTTP request to a validated internal event. Webhook Validation Pipeline Sources: crates/palyra-common/src/webhook.rs#26-29, crates/palyra-common/src/lib.rs#12Agent-to-User Interface (a2ui-envelope.v1.json)
The A2UI system enables agents to render rich UI components (charts, forms, tables) in the Web Console. The envelope supports incremental updates via JSON Patch.
Key Components
- A2uiDocument: The root container for UI state.
- Patching: Uses the
workspace_patchlogic to apply incremental updates to the UI state without re-sending the entire document crates/palyra-common/src/workspace_patch.rs#15-18.
Workspace Patching (message-envelope.v1.json)
Workspace patches are used to communicate filesystem changes within the palyrad daemon. These envelopes are subject to strict safety limits to prevent “zip bomb” style attacks or unauthorized directory traversal.
Workspace Patch Limits
The system enforcesWorkspacePatchLimits before any filesystem mutation occurs:
| Limit | Default Value | Description |
|---|---|---|
max_patch_bytes | 256 KB | Maximum size of the incoming JSON patch string. |
max_files_touched | 64 | Maximum number of files a single patch can modify. |
max_file_bytes | 2 MB | Maximum size allowed for any single file after patching. |
max_preview_bytes | 16 KB | Maximum size of the redacted preview returned to the UI. |
Patch Execution Logic
Theapply_workspace_patch function implements a fail-closed, atomic update mechanism.
Workspace Patch Execution Flow
Sources: crates/palyra-common/src/workspace_patch.rs#23-39, crates/palyra-common/src/workspace_patch.rs#207-213
Configuration Schemas (config-export/import.v1.json)
The daemon configuration is governed by daemon_config_schema. The CLI provides a config validate command to ensure local palyra.toml files adhere to the expected JSON/TOML schema.
Validation Rules
- Daemon Port: Must be a numeric value crates/palyra-cli/tests/config_validate.rs#97-109.
- Bind Addresses: Must be valid IP/Socket addresses crates/palyra-cli/tests/config_validate.rs#112-127.
- gRPC/QUIC Settings: Conditional validation based on whether
quic_enabledis true crates/palyra-cli/tests/config_validate.rs#149-168.
Identity & Certificate Schemas
While identity management primarily uses mTLS, the exchange of pairing proofs and certificates is facilitated by JSON envelopes within thepalyra-identity crate.
Issued Certificate Structure
TheIssuedCertificate schema includes metadata required for the pairing handshake:
sequence: Monotonic counter for certificate rotation crates/palyra-identity/src/ca.rs#18.fingerprint: SHA-256 hash of the certificate for TOFU pinning.issued_at_unix_ms/expires_at_unix_ms: Validity period in milliseconds crates/palyra-identity/src/ca.rs#23-24.
Stored CA Schema
TheStoredCertificateAuthority envelope persists the Root CA state:
certificate_pem: The public CA cert.private_key_pem: The encrypted private key.sequence: The current issuance sequence crates/palyra-identity/src/ca.rs#28-32.