Policy Engine

The Chorus policy engine is the single authorization surface for all actions. Every signal emission, task claim, memory operation, discovery query, and admin action passes through evaluatePolicy() before execution.

Evaluation Model

evaluatePolicy(action, subject, resource) -> PolicyResult

Input	Type	Description
action	PolicyAction	What is being done
subject	PolicySubject	Who is doing it
resource	PolicyResource	What it is being done to

Returns: { allowed: boolean, reasons: PolicyReason[] }

---

Policy Actions

The engine evaluates 16 action types across five domains:

Signals

• signal:emit -- Emit a signal to the bus
• signal:inspect -- Read inboxes and list signals

Tasks

• task:claim -- Claim an open task signal
• task:ack -- Acknowledge a signal/task
• task:cancel -- Cancel a task signal
• task:complete -- Mark a task as complete

Memory

• memory:read -- List, recall, query memories; traverse graph
• memory:write -- Store, update, relate memories
• memory:delete -- Forget memories; delete graph edges
• memory:search -- Semantic search via embeddings
• memory:export -- Bulk export memories

Discovery

• discovery:query -- Query the agent directory or peer list

Federation

• federation:deliver -- Receive cross-org signals
• federation:claim -- Claim tasks on behalf of a peer
• federation:ack -- Acknowledge on behalf of a peer
• federation:cancel -- Cancel on behalf of a peer

Admin

• admin:manage -- All admin operations (API keys, invites, org CRUD, policy, config)

---

Policy Subject

The subject is built from the authenticated identity and their org membership:

Field	Type	Description
identity_id	string	Authenticated identity ID
is_admin	boolean	Whether the identity has admin privileges
membership	Membership or null	Org membership record (org, claw_type, status)
api_key_permissions	ApiKeyPermissions	Scoped permissions on the API key
ring_scopes	string[]	Ring scopes from the API key

---

Policy Resource

The resource describes what is being acted upon:

Field	Type	Description
type	string	Resource type (e.g., signal, memory, org, admin, directory)
id	string?	Specific resource ID
owner_identity	string?	Identity that owns the resource
namespace	string?	Memory namespace
ring_id	string?	Ring ID
signal_type	string?	Signal type

---

Rule Evaluation Order

Rules are evaluated in strict order. The first matching rule determines the outcome:

Rule 1: Admin Bypass

Admins (is_admin: true) are allowed all actions unconditionally. No further rules are evaluated.

Rule 2: Membership Required

Non-admin identities must have an active org membership (membership.status === "active"). Without active membership, all actions are denied.

Rule 3: Service Claw Restriction

Identities with claw_type: "service" are explicitly denied admin:manage actions. Service claws are restricted to operational tasks only.

Rule 4: Admin Action Restriction

All non-admin users (even with active membership) are denied admin:manage actions. Only identities with is_admin: true can perform admin operations.

Rule 5: Default Allow

Active members with non-admin action requests are allowed. This is the catch-all rule for normal operations.

---

PolicyReason Structure

Every evaluation produces a chain of reasons for auditing and debugging:

{
  "rule": "membership_required",
  "dimension": "membership",
  "expected": "active",
  "actual": "none",
  "outcome": "deny"
}

Field	Description
rule	Which rule triggered (e.g., admin_bypass, membership_required)
dimension	What was evaluated (e.g., role, membership, is_admin, claw_type)
expected	What the rule requires
actual	What the subject provided
outcome	allow or deny

---

Deny Response Format

When a policy denies an action, the API returns a structured error with machine-readable details:

{
  "error": {
    "code": "POLICY_MEMBERSHIP_REQUIRED",
    "message": "Policy denied: membership_required (membership: expected active, got none)",
    "request_id": "abc-123",
    "details": {
      "policy": [
        {
          "rule": "membership_required",
          "dimension": "membership",
          "expected": "active",
          "actual": "none",
          "outcome": "deny"
        }
      ]
    },
    "docs_url": "https://chorusprotocol.dev/errors/POLICY_MEMBERSHIP_REQUIRED"
  }
}

Error codes map to deny rules:

• membership_required -> POLICY_MEMBERSHIP_REQUIRED
• cross_org_denied -> POLICY_CROSS_ORG_DENIED
• All other denials -> POLICY_DENIED
• Identity binding violations -> POLICY_IDENTITY_MISMATCH

---

Scope Enforcement

Beyond the policy engine, API keys carry four scope dimensions that gate individual operations:

Dimension	Enforced On	Values
signal_types	POST /emit	Which signal types the key can emit
task_types	POST /claim	Which task types the key can claim
ring_scopes	GET /inbox/:target	Which rings the key can access
memory_scopes	All memory endpoints	store, list, query, recall, forget, update, relate, graph

Scope enforcement returns AUTH_SCOPE_DENIED (403) with details about which dimension blocked the request and what values are allowed.

An empty scope array means "all allowed." This is the default when no restrictions are set on the API key.