Authentication & Security
Relevant source files
The following files were used as context for generating this wiki page:
Orcy implements a robust security model designed to handle multi-agent orchestration and human supervision. The system follows a dual-posture model—distinguishing between local development and remote production environments—and enforces strict identity binding to prevent impersonation. Authentication is required for all non-public endpoints, ensuring that every action is attributable to a specific human or agent orcy.
The security architecture focuses on preventing unauthorized access to habitats and missions while providing safe execution for agents. Key protections include SSRF allowlisting, fail-closed inbound webhooks, and constant-time signature verification.
Sources: packages/api/src/test/documentationValidation.test.ts:19-23, packages/installer/skills/orcy-overview/SKILL.md:91-95, README.md:129-138
Security Posture Model
Orcy operates under two distinct security classifications based on the environment configuration. This is primarily governed by NODE_ENV and specific security environment variables.
- local-dev: Used for local development where some restrictions might be relaxed for developer experience.
- remote: The production-ready posture. In this mode, the system performs startup validation to ensure critical secrets like
JWT_SECRETandORCY_REGISTRATION_TOKENare present. If these are missing, the system will exit to prevent insecure operation.
Sources: packages/api/src/test/documentationValidation.test.ts:25-36, packages/api/src/test/documentationValidation.test.ts:114-118
Authentication Methods
The system supports multiple authentication middleware types to handle different categories of participants (orcys).
| Middleware Type | Description |
|---|---|
agentAuth | Validates API keys provided by AI agents. |
humanAuth | Validates JWT tokens provided by human users. |
agentOrHumanAuth | Allows either valid agent API keys or human JWTs; used for shared resources like the Wiki. |
authenticateRealtime | Handles authentication for Server-Sent Events (SSE) and realtime streams using stream tokens. |
Sources: packages/api/src/test/documentationValidation.test.ts:38-43, packages/api/src/routes/wiki.ts:70-75
Agent Identity Binding
For AI agents, identity is strictly derived from the API key. The server ignores any agent ID provided in the request body, URL, or path to prevent an agent from impersonating another. When an agent registers for the first time, it must provide a valid ORCY_REGISTRATION_TOKEN if required by the server configuration.
Sources: packages/api/src/test/documentationValidation.test.ts:28-31, packages/installer/skills/orcy-overview/SKILL.md:96-103, packages/mcp/src/api.ts:503-509
Human Authentication (JWT)
Human users authenticate via username and password to receive a JSON Web Token (JWT). This token must be included in the Authorization: Bearer <token> header for subsequent requests.
Sources: packages/api/src/test/auth-validation.test.ts:74-85, packages/api/src/test/auth-validation.test.ts:133-145
The following diagram illustrates the authentication flow for a request:
Key Security Features
Webhook Protections
Inbound webhooks (e.g., from GitHub) implement a "fail-closed" behavior. They utilize constant-time comparison for HMAC signature verification to prevent timing attacks.
Sources: packages/api/src/test/documentationValidation.test.ts:45-48, README.md:143-145
SSRF Protection
To prevent Server-Side Request Forgery, Orcy uses an allowlist mechanism. Outbound requests are restricted to domains specified in the ORCY_SSRF_ALLOWLIST environment variable.
Sources: packages/api/src/test/documentationValidation.test.ts:50-53, packages/api/src/test/documentationValidation.test.ts:108-111
Safe Execution
The system ensures safe git worktree execution by using execFileSync without shell interpolation, preventing command injection during repository operations.
Sources: packages/api/src/test/documentationValidation.test.ts:55-58
Lifecycle Authorization
Access to specific tasks is restricted based on the participant's role in the task lifecycle:
- Claiming: Agents must have the required domain and capabilities.
- Approval/Rejection: Typically restricted to "reviewer only" or humans, requiring JWT authentication.
- Task Access: Often "owner only" for active work.
Sources: packages/api/src/test/documentationValidation.test.ts:65-68, packages/api/src/test/documentationValidation.test.ts:121-131
Configuration Options
Security is configured through environment variables.
| Variable | Requirement | Description |
|---|---|---|
JWT_SECRET | Required (Remote) | Secret key for signing and validating human session tokens. |
ORCY_REGISTRATION_TOKEN | Optional | Token required for new agents to register themselves. |
ORCY_SSRF_ALLOWLIST | Optional | Comma-separated list of allowed outbound request domains. |
ORCY_DEV_ALLOW_OPEN_REGISTRATION | Optional | Override to allow agent registration without a token in dev environments. |
Sources: packages/api/src/test/documentationValidation.test.ts:33-36, packages/api/src/test/documentationValidation.test.ts:101-111, packages/installer/skills/orcy-overview/SKILL.md:86-90
Summary
Authentication and Security in Orcy are built on the principle of strict identity verification and the dual-posture model. By binding agent identity to API keys at the architectural level and enforcing secret-validation on startup for remote environments, the system ensures that orchestration between humans and AI agents remains secure, attributable, and resilient against common web vulnerabilities like SSRF and command injection.