Security model

Chorus is single-org per instance — there is no org-vs-org tenancy boundary to configure. Inside one instance, three primitives do the actual isolation: rings (visibility scope), namespace ACL (per-resource ownership), and federation peer scopes (cross-instance). The policy engine is real but coarse — it is not the isolation story on its own.

This page is generated from the code; claims point at file:line.

The policy engine is coarse on purpose

evaluatePolicy(action, subject, resource) runs five rules in order (src/policy/engine.ts:43-114): admin bypass → active-membership required → service-claw denied admin:manage → non-admin denied admin:manage → default-allow everything else. The last rule means any active org member passes every non-admin action (signal:*, task:*, memory:*, workstream:*) at the engine level.

The fine-grained gating happens outside the engine. Don’t read evaluatePolicy as the whole authorization picture — read it as the admin gate plus a membership check.

Layer 1 — RingScope (visibility)

RingScope (src/identity/ring-scope.ts) is the single authority for “which rings can this identity see,” and it gates signals, execution tasks, and namespaces. Build one per request; the middleware attaches it as c.get("ringScope") (src/middleware/ring-scope.ts).

The effective visible-ring set (visibleRingIds, ring-scope.ts:233-254):

Caller	Visible rings
Admin (is_admin)	every known ring on the instance
Non-admin	rings they are a member of
Non-admin + API-key ring_scopes	memberships ∩ ring_scopes

Signal visibility (canSeeSignal, ring-scope.ts:290-308): broadcast signals (no to_ring) are visible to any authenticated caller; ring-targeted signals only when the ring is in the caller’s visible set. Execution tasks gate the same way (canSeeExecutionTask, ring-scope.ts:356). See Rings & visibility.

Layer 2 — namespace ACL

Memory, workspace, and artifact items live in namespaces. canSeeNamespace (ring-scope.ts:317-344; public wrappers in src/memory/acl.ts:43-96) enforces four shapes:

Namespace	Access rule
agent:<id>	only the owning identity — private even from admins
ring:<id>	active members of that ring
org:<id>	identities with active membership in that org
federated:<…>	identities with an explicit, non-expired share grant

Unknown formats are denied by default (acl.ts:16).

Admin override is broad but not total

Admins see every ring, signal, and execution task — but the admin bypass deliberately does not apply to namespace ACL. A private agent: namespace stays private even from an admin (ring-scope.ts:317, intentional; the memory-ACL tests rely on it). State this split precisely when you describe what an admin can reach.

Layer 3 — federation (cross-instance)

Inbound federation routes are absent by default. They are mounted only when an operator sets FEDERATION_ENABLED=true. Startup then requires an exact canonical public origin and a 32–4096 byte encryption-key file; invalid authority or key configuration aborts before database access.

Federation is v2-only. Its HMAC-SHA256 canonical form binds version, receiver-assigned peer id, key id/generation, method, public authority, raw path/query, RFC 9530 digest of the exact guarded bytes, database-time validity window, and nonce. Legacy/missing/ambiguous versions and v1 proof shapes are rejected before trust lookup. Peer keys are AES-256-GCM encrypted at rest with peer+generation AAD; only current and bounded previous generations verify.

After verification, one SurrealDB transaction claims a peer+hashed-nonce, applies the mutation or durable rejection, records dedicated provenance, and creates a signed receipt. Exact retries recover that receipt; different requests using the nonce fail. Scope checks cover action, signal type, ring, identity, urgency, and peer ownership of task resources.

Federation proof order

An invalid or body-mismatched proof cannot consume the authenticated peer budget. A verified peer still consumes the independent pre-auth socket/client-IP budget, its post-proof peer_id budget, and the nonce exactly once with its mutation. See Federation v2 for trust installation, rotation, outbound receipt verification, and migration behavior.

Egress boundary — attacker-controlled HTTP destinations

Webhook URLs, federation peer endpoints, configured SIWE/ERC RPC endpoints, and ERC-8004 registration URIs all pass through one process-wide safe outbound client. It normalizes HTTP(S) URLs, rejects credentials/fragments/ambiguous syntax and caller-controlled authority or framing headers, resolves the complete A/AAAA set, and rejects every non-global IANA special-purpose destination. Mixed public/private answers fail even when the private address would otherwise be operator-allowlisted.

For an admitted request, the transport connects directly to one of the vetted IPs while retaining the original Host header and TLS SNI/certificate identity. It does not use HTTP_PROXY / HTTPS_PROXY, does not re-resolve inside the transport, and does not follow redirects. DNS is performed again for each delivery, so a URL accepted during create/update is checked against its current addresses immediately before network I/O. One deadline and shared concurrency budget cover DNS through the fully consumed response; URL, headers, request body, response body, and DNS answer count are independently bounded.

Private connectivity is an explicit operator exception: CHORUS_OUTBOUND_PRIVATE_ALLOWLIST binds an exact origin to private CIDRs in RFC1918, RFC6598, loopback, or ULA ranges. It cannot enable link-local/cloud metadata destinations, and it cannot admit a mixed public/private answer. Public error responses expose stable OUTBOUND_* codes without echoing destination queries, response bodies, or low-level causes.

ERC-8004 treats chain ownership as live authorization: ownerOf and tokenURI are read on every resolve. Only bounded, schema-validated registration metadata is cached by the current URI; a cache hit cannot let a previous or incorrect wallet skip the ownership check. Its JSON-RPC client also requires an exact JSON-RPC 2.0 response ID and disables automatic retries.

Known caveats

The isolation primitives above are sound, but several edges are honest limitations. Document them, don’t paper over them.

Embedded /mcp has an independent fail-closed boundary

The server does not mount /mcp unless EMBEDDED_MCP_ENABLED=true. It is dispatched before the Hono application, so it does not inherit Hono middleware; it now implements the boundary directly: exact Host and optional Origin allowlists, mandatory live Bearer resolution on every message, bounded JSON and rate budgets, one-message stateless transports, and no service-host filesystem tools. It retains no credential or MCP session state. The standalone chorus-mcp package remains the recommended agent connection because it can be supervised and upgraded independently.

Inbound abuse boundary

• Bun’s raw socket address is the only pre-auth authority. Forwarding headers are ignored unless the immediate peer is in CHORUS_TRUSTED_PROXY_CIDRS; trusted chains are walked right-to-left with strict hop and byte caps and stop at the first untrusted hop.
• Global, client-IP, API-key, identity, and post-proof federation-peer budgets are independent. Production state is atomic and shared in SurrealDB and a backend error returns 503.
• A required file-backed HMAC key maps subjects into bounded slots; raw authority values are never persisted. Collisions share rather than replace the incumbent budget and are observable.
• Every Hono request body is aggregate-counted before parsing. JSON routes classify required, optional, and empty-only body states and reject malformed/trailing JSON, non-object roots, wrong or duplicate media declarations, unsupported encodings, and invalid UTF-8 before command execution. JSON-RPC batches are fully preflighted before dispatch; mutating notifications and mixed/multiple-mutation batches are rejected as a whole.
• Explicitly enabled /mcp is dispatched outside Hono and therefore retains its separate bounded process-local global/per-key limiter and streamed body guard.

SIWE authority is server-built and purpose-bound

POST /auth/challenge persists the exact EIP-4361 message, its hash, trusted configured domain/URI/scheme, chain, wallet subject, purpose, public intent digest, request ID, and database time bounds. Login, invite, attach, and auth-request handlers accept only those exact bytes and manually compare every field before signature verification. Invalid signatures never consume authority; the matching mutation and one-time consume commit atomically. Request Host/Origin are not authority, verifier chains and RPC transports are explicit startup configuration, and legacy GET /auth/nonce no longer exists.

Login keys are 24-hour session credentials linked to their challenge. POST /auth/logout revokes only the current key; HTTP and stateless MCP re-resolve the key on the next request and reject it immediately. Verifier/RPC exception details are not returned to callers.

Single-org by design

There is no multi-tenant boundary to configure. The policy engine’s cross-org rule is an explicit placeholder (“Currently single-org, so membership existing = same org”, src/policy/engine.ts:95-98), and invite redemption attaches every identity to one auto-created org. Don’t expect org-vs-org isolation — the boundaries are rings, namespaces, and federation peer scopes.

Enrollment is exactly once

Invites are subordinate to an existing active central/admin membership; they cannot bootstrap an empty database or assign admin/central authority. Invite claim, optional purpose-bound challenge, identity, credential, employee membership, and permission propagation commit atomically. Codes created before enrollment v2 are revoked by migration 041, and automatically generated codes use 128 bits of cryptographic randomness.

See Rings & visibility, Memory, and Identities, orgs & membership.