Skip to main content

​
Encryption & secrets management

Soma uses envelope encryption to secure your secrets, MCP provider credentials and sensitive auth middleware configuration.
Envelope encryption is a strategy where data is encrypted with a Data Encryption Key (DEK), and the DEK itself is encrypted with a Key Encryption Key (KEK). This approach allows for efficient key rotation and limits the exposure of cryptographic material. Some key details:
  • The DEK remains encrypted at all times and is never stored in plaintext. It is stored in a secure cache in memory, in the database and in the soma.yaml file.
  • The KEK is used to encrypt the DEK. This can be configured to use AWS KMS or a local file.
  • Key rotation & migration involves decrypting the DEK with the old KEK, then, encrypting the DEK with the new KEK and storing the new DEK in the database.
  • Secrets are encrypted with the DEK before being stored in the database. They reference a DEK alias and soma decrypts secrets on the fly when needed by looking up the DEK via it’s alias.
  • Soma uses AES-256-GCM (Galois/Counter Mode) for all encryption operations

​
Role of soma.yaml

The soma.yaml file was initially designed around a desired DX:
  1. Developers configure MCP integrations at development time
  2. These integrations often require secrets such as refresh tokens, access tokens, API Keys, client secrets, etc.
  3. Developers want to test these configurations locally first, many of them require an initial handshake process (e.g. OAuth2 Authorization Code Flow)
  4. Once configured locally, we store the encrypted values in the soma.yaml file
  5. When you deploy your agent to an environment, you configure encryption key access in the environment and on start, these secrets are syned into the environment database and cached in memory (all encrypted).
  6. Now your agent “Just Works” (TM) in production.

​
Bridge MCP provider credentials

Bridge is the MCP server that ships with Soma. Agents can use Bridge to securely invoke functions and API endpoints for external systems. Bridge supports the following credential types:
  • No Auth
  • API Key
  • Bearer Token
  • Oauth Authorization Code Flow
  • Oauth Authorization Code Flow with PKCE
Credential rotation via refresh tokens for Oauth Authorization Code Flow and Oauth Authorization Code Flow with PKCE is automatically handled by Bridge. You can use any pre-existing SaaS provider in Bridge or add custom functions with configure which credential type to your agent as per the relevant SDK. You can configure these credentials via the UI when running soma dev and navigating to http://localhost:3000.

​
AI Agent secrets

Because we built an encryption engine around our desired DX, we’ve expanded it’s usage to include general purpose secret management for your agent. These secrets are managed in the same way as MCP provider credentials and are encrypted and decrypted on the fly. You can manage these secrets via the soma CLI whilst the dev server is running (some dev in another terminal). The commands are: soma secret set <secret-name> <secret-value> soma secret list soma secret delete <secret-name>

​
Moniker AI Gateway credentials

TODO: AI Gateway still WIP

​
Soma API security

TODO: WIP docs

​
Internal API endpoints

​
External API endpoints

​
Auth middleware configuration

TODO: Auth middleware still WIP