Security

How Trellaris keeps the credentials it holds — people's sessions, connector tokens, API keys, webhook secrets and your organisation's own secrets — and the standards each mechanism follows. The design decision behind all of it is recorded as ADR-041.

At a glance

Sessions and tokens

However you sign in — company SSO, Google, GitHub — Trellaris opens a session on the server. The session record is the authority: tokens are only ever as valid as the session they belong to.

Access tokens

• JSON Web Tokens (RFC 7519) signed with ES256 — ECDSA on P-256 with SHA-256 (RFC 7518 §3.4) — and valid for 15 minutes.
• Each token names its signing key with a kid, the key's JWK thumbprint (RFC 7638). The public keys are published as a JWK Set (RFC 7517) at /.well-known/jwks.json. A service that only needs to check tokens — the MCP gateway, a remote agent receiving an on-behalf-of token — reads that set and can never mint one.
• The algorithm is fixed, not negotiated, and every token is checked for its issuer, expiry and type; a token signed with the old shared secret (HS256) is refused. This follows the JWT Best Current Practices (RFC 8725).
• Each access token carries its session id. Once the session ends — sign-out, an idle or absolute limit, a detected copy — the token is refused on its next request, not when it would have expired.
• Rotating the signing key keeps the previous public key in the JWK Set, so tokens already issued keep verifying until they expire.

Refresh tokens

A refresh token is opaque and checked against its session on every use. Nothing replayable is stored: the token carries the session id, a generation number and an HMAC (RFC 2104) under a key held — encrypted — in the session record.

• Rotation. Every refresh issues the next token and retires the one presented.
• Reuse detection. If an older token is ever presented again, it has been copied. The session ends and every copy with it, and the event is audited. This is the refresh-token protection the OAuth 2.0 Security Best Current Practice recommends (RFC 9700 §4.14.2).
• No false alarms from your own tabs. Two tabs refreshing in the same instant present the same token; within a 60-second grace window the second receives the same new token rather than being treated as a thief.
• Server-side limits. A session idle for 30 minutes, or 12 hours old, is ended at its next refresh whatever the browser believes, and a person whose account has been deactivated cannot refresh at all.
• Switching organisation ends the current session and opens a new one for the other organisation, so signing out always ends what your browser holds.

The browser never holds a platform token

The web app keeps the tokens in an encrypted Auth.js session cookie marked HttpOnly, Secure and SameSite=Lax (RFC 6265 and its successor draft), which page scripts cannot read. Every API call goes through the app's own /api route, which attaches the token on the server. A script injected into a page therefore has no token to steal. This is the backend-for-frontend pattern described in the IETF guidance on OAuth for browser-based applications.

• Writes authenticated by the cookie must come from the app's own origin: a request the browser labels cross-site (via Sec-Fetch-Site or Origin) is refused.
• A Content-Security-Policy limits where pages can load scripts from and send data to, forbids framing the app, and blocks plugins. The app also sends X-Content-Type-Options: nosniff, a strict referrer policy and a permissions policy.
• The idle logout in the browser is still there, but it is no longer the only control — the server enforces its own.

The vault

Every credential Trellaris stores — in its own table or inside another component's configuration — is sealed and opened through one piece of code.

Envelope encryption

• Each value is encrypted with its own random 256-bit data key using AES-256-GCM, an authenticated encryption scheme (NIST SP 800-38D; the AEAD interface of RFC 5116).
• The data key is wrapped by a key-encryption key. In the cloud that key is an RSA key in Azure Key Vault, and the wrapping is RSA-OAEP with SHA-256 (RFC 8017) performed inside Key Vault: the application asks Key Vault to wrap and unwrap, authorised by its workload identity, and never holds the key. A copy of the database together with the application's environment is not enough to read anything.
• Unwrapped data keys are cached in memory for a few minutes, so Key Vault is not asked on every read.

Bound to where it belongs

Every value is encrypted with associated data naming what it is for, which organisation it belongs to, and exactly where it is stored. A ciphertext copied into another row, another organisation or another purpose fails to decrypt instead of quietly opening as someone else's secret.

Rotation

Each value records which version of the key-encryption key wrapped it. After a rotation, new values use the new version while old ones still open, and a daily re-seal task re-wraps everything under the current version. The same task upgraded every value stored before this design. Administrators can see counts by purpose and key version — never values — at GET /secrets/inventory.

Who may touch a secret

• A connector's client secret is read only from organisation level, so a member's personal secret with the same name can never stand in for it.
• You can point an MCP server — whose address you choose — only at a secret you manage. Otherwise registering a server you control could deliver somebody else's secret to it.
• Every time a secret is decrypted, the audit log records which secret, for what purpose, and for which run — never the value.

Connector tokens

Connectors act as the person who connected them, under a delegated OAuth 2.0 grant (RFC 6749) obtained with PKCE (RFC 7636) and sent to providers as a bearer token (RFC 6750).

• Only the refresh token is stored durably. The access token — an hour of your identity — is kept only in the cache, encrypted, for its own lifetime. A grant that cannot be renewed keeps its access token, because it is all there is.
• Renewed when used. An expiring token is renewed at the moment an agent needs it; if a provider still answers 401, Trellaris renews once and retries once.
• One renewal at a time. Providers that rotate refresh tokens (RFC 9700 §4.14.2) invalidate the old one on use, so renewals of the same connection are serialised across every server, and each renewal is saved the moment it succeeds.
• An outage is not a disconnection. A timeout or a provider error leaves the connection active and retries later. Only a refused grant — the OAuth errors invalid_grant, invalid_client or unauthorized_client (RFC 6749 §5.2) — marks it as needing reconnection, and tells you in your inbox.
• Disconnecting revokes at the provider. Where the provider offers the standard revocation endpoint (RFC 7009) — Google, Salesforce, Zoho, Box — the grant is revoked there as well, and the stored tokens are destroyed. This also happens when an account is deprovisioned through SCIM.

API keys and webhooks

• API keys are high-entropy random values stored only as a SHA-256 hash and shown once. New keys expire after 90 days unless you choose 30, 180 or 365. Each ends with a checksum, so a mistyped or truncated key is refused before any lookup, and a leaked key can be recognised by a scanner without asking the platform.
• Webhook URLs contain a random token that is stored only as a hash and shown once, when the automation is created. If you lose it, issue a new URL from the automation; the old one stops working immediately.
• Webhook signatures use HMAC-SHA256 (RFC 2104) over the request body. The signing secrets — for incoming webhooks and for outgoing deliveries — are stored encrypted in the vault and never returned by the API.

Refusing unsafe configuration

Every signing and encryption secret has a development default so the platform runs with no configuration on a laptop. Outside development those defaults would be published keys, so the API and the worker refuse to start without a token-signing key, with the default master key as the vault's key-encryption key, or with the default exchange secret — and say which setting is missing.

Standards referenced