Security

Hyphen's security model is architectural, not bolted on. Protections are enforced by the execution engine, not by policies that can be bypassed.

Structural Permissioning

Agents can only use tools explicitly declared in the workflow definition. This is enforced at the engine level — the agent's LLM prompt only includes declared tools, and the execution engine rejects any action call not in the allowlist.

{
  "tools": [{ "type": "action", "name": "lookup_ticket" }, { "type": "action", "name": "gmail_send" }]
}

With this declaration, the agent can look up tickets, send emails, and signal completion. It cannot access databases, post to Slack, trigger other workflows, or use any capability not in the list. If the LLM hallucinates a tool call to delete_database, the engine rejects it — the action isn't registered in the tool allowlist.

This isn't a guardrail on top of broad access. The agent literally has no mechanism to invoke undeclared tools.

Secret Leakage Prevention

API keys, tokens, connection strings, and other secrets referenced via orgconfig: are automatically redacted from:

• Workflow run context (returned by status endpoints)
• Agent reasoning traces
• Log output
• Error messages

If an agent's reasoning trace contains a secret value (because the LLM included it in its "thought"), the redaction layer strips it before storage. Secrets resolve at execution time only and are never persisted in plaintext.

SSRF Protection

HTTP actions and agent tool calls that make outbound requests are protected against Server-Side Request Forgery (SSRF). The following are blocked:

• Cloud metadata endpoints (169.254.169.254, metadata.google.internal, etc.)
• Private/internal network ranges (10.x.x.x, 172.16.x.x, 192.168.x.x)
• Loopback addresses (127.0.0.1, localhost)

Requests to blocked addresses fail with a clear error. This prevents agents from being tricked into accessing internal infrastructure.

Prompt Injection Defense

Hyphen implements multiple layers of defense against prompt injection in ReAct agent loops:

Input sanitization. User-provided data that flows into agent prompts is sanitized to prevent instruction override.

Structured output parsing. The engine expects structured JSON responses from the LLM (thought, action, action_input). Freeform responses that don't match the expected format are rejected, preventing the agent from being redirected by injected instructions.

Tool allowlist enforcement. Even if a prompt injection convinces the LLM to attempt an unauthorized action, structural permissioning blocks it at the engine level.

Fork Bomb Prevention

Agents can trigger other workflows via __run_workflow__. To prevent infinite recursion (workflow A triggers workflow B which triggers workflow A), Hyphen enforces depth limits on nested workflow execution.

If the nesting depth exceeds the configured limit, the execution fails with an error rather than running indefinitely.

OAuth CSRF Protection

The OAuth authorization flow uses signed JWT state tokens with short expiration times. This prevents cross-site request forgery attacks during the OAuth callback:

• State token is generated server-side with a secret key
• Token includes the org ID, provider, and expiration
• Callback validates the token signature and expiration before exchanging the authorization code

Rate Limiting

API requests are rate-limited per organization to prevent abuse and ensure fair resource allocation:

Rate limit headers are included in API responses. When limits are exceeded, requests return 429 Too Many Requests with a Retry-After header.

Security Checklist

When deploying Hyphen in production:

• Store all secrets in org config (never hardcode in workflow definitions)
• Use the minimum necessary tool set for each agent (principle of least privilege)
• Set appropriate max_iterations and timeout_ms on ReAct loops
• Configure on_stuck recovery strategies to prevent runaway agents
• Review agent reasoning traces for unexpected behavior patterns
• Enable webhook notifications for agent_paused events to ensure human review is timely
• Use top-level conditions to gate workflows that should only run under specific circumstances

→ Next: Primitives — the five built-in building blocks