The Broker¶

The Broker is the only service in a Nexus deployment that holds durable credential material. No other service receives a refresh token, client secret, or plaintext key.

Database schema¶

Table	Purpose
`provider_profiles`	OAuth2 and static provider configuration — client ID, client secret, auth/token URLs, scopes, auth strategy
`connections`	One row per authorization grant — workspace ID, provider ID, status, PKCE verifier, scopes, return URL
`tokens`	Encrypted credential material — one row per connection, enforced by `ON CONFLICT (connection_id) DO UPDATE`
`audit_events`	Append-only event log — consent created, token issued, refresh succeeded or failed, connection cleaned up

Encryption¶

All token material is encrypted with AES-GCM 256-bit using your ENCRYPTION_KEY. The key must be exactly 32 bytes. A fresh 12-byte nonce from crypto/rand is generated per write and prepended to the ciphertext before base64 encoding.

# Generate ENCRYPTION_KEY
openssl rand -base64 32

Losing ENCRYPTION_KEY makes every stored token permanently unreadable. There is no recovery. Key rotation requires a migration that decrypts and re-encrypts every token row.

Token refresh¶

POST /connections/{connection_id}/refresh — the Bridge calls this before each access token expires.

The Broker decrypts the stored token, extracts refresh_token, calls the provider's token endpoint, encrypts the new response, and upserts it into tokens.

Provider response	Broker action
`2xx`	Encrypt and store new token, return it
`4xx`	Set connection status to `attention`, return `attention_required`
`5xx` or network error	Return error without changing connection status — Bridge retries

Static connections (api_key, basic_auth) cannot be refreshed. Calling refresh on a static connection returns 400 static_token.

Connection states¶

Status	Meaning
`pending`	Consent URL issued, user has not yet authorized
`active`	Token stored and usable
`attention`	Refresh failed with a `4xx` — user must re-authorize
`failed`	Unrecoverable. Delete and recreate.

OAuth state signing¶

The Broker signs every OAuth state parameter with HMAC-SHA256 using STATE_KEY. The state encodes {workspace_id, provider_id, nonce, iat} and expires after 10 minutes. Both the Broker and the Gateway must share the same STATE_KEY.

# Generate STATE_KEY
openssl rand -base64 32

Network isolation¶

The Broker should only accept connections from the Gateway's IP range. It should not be reachable from the public internet or from agent processes. The API_KEY on the Broker should be known only to the Gateway.