Security Architecture

How Agent Constitution protects your rules, decisions, and audit trail at every layer.

Architecture Overview

Agent Constitution is built on a trust-no-one architecture. Your behavioral rules live on your iPhone — never on a server. The relay is a stateless pipe that passes constitution check requests and approval/denial responses between your agent and your phone. It stores nothing. Your audit trail is encrypted in the iOS Keychain. No database, no cloud sync, no data leaving your device without your explicit approval.

Constitution Check Flow

Every agent action follows this path when a rule applies:

On-Device Rules

Your behavioral rules are the core of Agent Constitution — and they never leave your device:

• Rules are stored locally on your device
• Rule definitions are not uploaded to the relay or any server
• When an agent performs a constitution check, the app evaluates the action against your rules locally
• Only the match result (approved/denied + rule name) is sent back through the relay
• Your complete rule set is never exposed to the agent or the relay

Keychain Audit Log

Every constitution check is permanently recorded in a tamper-resistant audit trail:

• Audit entries are stored in the iOS Keychain with kSecAttrAccessibleWhenUnlockedThisDeviceOnly protection
• Not synced to iCloud Keychain — audit data stays on your physical device
• Not included in device backups (iTunes or iCloud)
• Protected by the Secure Enclave on devices that support it
• Each entry records: timestamp, action description, category, matched rule, decision (approved/denied)
• The audit trail cannot be modified by the agent or the relay — only you can clear it from the app

HMAC-SHA256 Signed Relay

Every request to the relay is signed with HMAC-SHA256. The signing payload includes timestamps and nonces to prevent replay attacks. The relay performs timing-safe comparison on every signature and rejects:

• Requests with invalid signatures
• Requests with expired timestamps (clock skew tolerance is tight)
• Requests with previously-seen nonces

HMAC signing is supported on all relay endpoints. Agents that include signing headers get full replay protection and integrity verification.

Push Notification Validation

Constitution check requests delivered via APNs are validated before being shown to you:

• Payload validation — action type, category, description, and request ID are all validated against strict format rules
• Invalid payloads are silently rejected — malformed push notifications cannot trigger the approval sheet
• APNs JWT rotation — authentication tokens for Apple Push Notification service are rotated every 15 minutes
• No sensitive data in push payload — the notification contains only a request ID; the full action details are fetched over the secure channel

Token Security

Authentication tokens are protected at every layer:

• SHA-256 hashed storage — auth tokens are never stored in plaintext on the relay. Only the hash is kept in memory for comparison.
• Timing-safe comparison — all token and signature checks use constant-time comparison to prevent timing side-channel attacks.
• Per-token rate limiting — dual-layer rate limiting by both IP address and token hash prevents abuse even from distributed sources.

Relay Architecture

The relay server is designed to be minimal and ephemeral:

• Short-lived message queues — messages expire within minutes and are automatically purged
• Optional persistent storage — when deployed with Redis, channel state survives restarts. Without Redis, the relay falls back to in-memory storage where a restart clears all state.
• No content logs — the relay never logs the content of constitution checks or decisions
• No user accounts — there are no profiles, no registration, no stored user data
• The relay's only job: receive a check request, hold it briefly, deliver the decision, delete it

Channel Isolation

Each device-agent pair communicates through a unique channel:

• Every channel has its own UUID and authentication token
• Channels are cryptographically isolated — there is no mechanism to read another channel's messages
• Auth tokens are generated during pairing and stored in the iOS Keychain
• Compromising one channel does not affect any other channel on the relay
• You can revoke a channel instantly by unpairing from the app

Self-Hosting

The relay is fully open source. You don't have to trust our hosted instance — you can run your own:

• Deploy to any cloud provider (Fly.io, Railway, AWS, DigitalOcean, etc.)
• Run on your local machine or home server
• Audit every line of code: github.com/arunrlverma/relay4agents
• Point Agent Constitution at your custom relay URL during pairing
• Full control over your infrastructure, your rules

Summary

Agent Constitution is designed around a single principle: you own your rules, and you own every decision. Your behavioral rules never leave your phone. Your audit trail is encrypted on-device. The relay is a stateless pipe that forgets everything. And every request is cryptographically signed.

Questions about our security architecture? Email contact@agentconstitution.com. Security vulnerabilities should be reported privately — do not open a public issue.