Security Architecture

How relay4agents protects your data at every layer.

Architecture Overview

relay4agents is a stateless relay. There is no database — not SQL, not NoSQL, not Redis, not a file on disk. The relay holds messages in memory only. Data exists for seconds, then it's gone. A server restart produces a completely clean slate. This isn't a limitation — it's the core design principle.

End-to-End Flow

Every data request follows the same path, with biometric approval as the mandatory gate:

HMAC-SHA256 Signing

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 missing or invalid signatures
• Requests with expired timestamps (clock skew tolerance is tight)
• Requests with previously-seen nonces
• Any unsigned request — period

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.

Certificate Pinning

The ClawVault iOS app implements SSL certificate pinning to prevent man-in-the-middle attacks:

• Pins to the ISRG Root X1 (Let's Encrypt) public key hash
• Connections to unauthorized hosts are rejected at the TLS layer
• Protects against compromised CAs, rogue WiFi, and corporate proxies
• Localhost connections are allowed for development only

Push Notification Security

Vault requests delivered via APNs are validated before being acted on:

• Payload validation — request type, reason, and request ID are all validated against strict allowlists and format rules
• Invalid payloads are silently rejected — malformed push notifications cannot trigger the vault approval sheet
• APNs JWT rotation — authentication tokens for Apple Push Notification service are rotated every 15 minutes
• Terra webhook signatures — all incoming health data webhooks are verified against an HMAC signature before processing

Biometric Gates

All vault access in ClawVault requires Face ID or Touch ID. This is non-negotiable:

• Every vault data share requires a fresh biometric authentication
• There is no PIN fallback for vault data — biometric or nothing
• The iOS app uses LAPolicy.deviceOwnerAuthenticationWithBiometrics, not the weaker deviceOwnerAuthentication that allows passcode
• Failed biometric = request denied. The agent receives a rejection, not the data.

Keychain Protection

Vault items (credit cards, SSN, bank accounts, identity) are stored in the iOS Keychain with the strongest available protection:

• Access class: kSecAttrAccessibleWhenUnlockedThisDeviceOnly — the strongest non-biometric protection class
• Not synced to iCloud Keychain — data stays on your physical device
• Not included in device backups (iTunes or iCloud)
• Protected by the Secure Enclave on devices that support it
• If the device is wiped, stolen, or factory reset — vault data is gone

Relay Statelessness

The relay server is aggressively stateless:

• In-memory message queues — no database, no file system, no persistence layer of any kind
• Server restart = clean slate — all queued messages are lost on restart, by design
• No content logs — the relay never logs the content of messages passing through it
• No user accounts — there are no profiles, no registration, no stored credentials
• The relay's only job: receive a message, hold it in RAM briefly, deliver it, 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 ClawVault at your custom relay URL during pairing
• Full control over your infrastructure, your rules

Health Data

ClawVault reads health metrics from Apple HealthKit with read-only access:

• The app never writes to HealthKit — it only reads metrics you've authorized
• Data is streamed in batches through the relay, not stored on it
• Your agent can request specific metrics (steps, heart rate, HRV, sleep, etc.)
• Health data batches expire on the relay after 5 minutes if not pulled
• Compliant with Apple's HealthKit guidelines — data is never used for advertising or sold
• You can revoke HealthKit access at any time in iOS Settings → Privacy → Health

TTL & Auto-Expiry

Nothing lingers on the relay. Every piece of data has a hard expiration:

• Vault responses: 60-second TTL. After 60 seconds, the data is permanently deleted from memory.
• Health data batches: Expire on pull, or after 5 minutes if not pulled.
• Push requests: Expire from the queue if not delivered within their TTL.
• There is no way to retrieve expired data — it doesn't exist anymore.
• TTLs are enforced server-side. The agent cannot extend them.

Summary

relay4agents is designed around a single principle: your data should only exist where it needs to, for as long as it needs to. The relay is a pipe, not a vault. Your phone is the vault — protected by biometrics, Keychain encryption, and your explicit approval for every single request.

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