Trust
Encryption & Key Management Policy
Restricted and confidential data is encrypted both in transit and at rest. Encryption keys are scoped, rotated, and protected with controls appropriate to the sensitivity of the data they cover.
1. Encryption in transit
- All public Bella endpoints are served exclusively over HTTPS. TLS 1.2 or higher is enforced; older protocols (TLS 1.0, TLS 1.1, SSL) are disabled.
- HSTS is set with a long max-age so browsers refuse plaintext downgrades for at least one year.
- Inbound traffic is fronted by Cloudflare; the origin is reached only through encrypted tunnels.
- Internal service-to-service calls within the production environment use TLS where they cross a host boundary and authenticated tokens to identify the caller.
- Outbound calls to subprocessors (Intuit, Plaid, Stripe, Twilio, Telnyx, GCP, OpenAI, Anthropic) are HTTPS-only and validate the remote certificate chain.
2. Encryption at rest
- Database — PostgreSQL storage is encrypted at rest at the disk and snapshot layer using AES-256.
- Restricted columns — OAuth refresh tokens (Intuit), Plaid access tokens, payment-processor credentials, and other restricted-classification fields are additionally encrypted at the column level using PostgreSQL's pgcrypto symmetric encryption. Plaintext is never persisted in a restricted column; ciphertext is what lives in the row. The encryption key is held in a restricted configuration store. Tenant-scoped key derivation is a SOC 2 readiness commitment so a key compromise can be contained to one tenant; the current implementation uses a single platform-wide key.
- Backups — database backups are encrypted at rest with provider-managed keys. Backup retention follows the Data Retention & Disposal Policy.
- Object storage — uploaded files and generated artifacts (audit pack ZIPs, exports, generated documents) are stored encrypted at rest.
- Logs — application and security logs are stored encrypted at rest. Sensitive fields are redacted before logging.
3. Key management
- Storage — encryption keys are stored separately from the data they encrypt. Application-level keys are held in a restricted configuration store accessible only to the application processes that need them.
- Tenant scoping — tenant-scoped key derivation is on the SOC 2 readiness roadmap so a key compromise can be contained to one tenant's data set. The current production implementation uses a single platform-wide encryption key for restricted columns.
- Rotation — keys are rotated on a documented schedule and immediately on suspected compromise. Rotation procedures support re-encryption without downtime for the affected data.
- Cryptographic-shredding for offboarding — once tenant-scoped key derivation is in place (SOC 2 readiness roadmap), cryptographic shredding via per-tenant key rotation will be the offboarding disposal path. Until then, ciphertext on disconnect is hard-deleted from primary storage and ages out of backups on the standard backup retention schedule.
- Algorithm and library selection — Bella uses well-maintained, widely-reviewed cryptographic libraries (PostgreSQL pgcrypto, Node.js built-in crypto module, system OpenSSL). Bella does not implement primitive cryptographic algorithms in application code.
4. Secrets management
- Application secrets (API keys, signing secrets, third-party tokens) live in a restricted configuration store, never in source code, never in logs.
- Pre-commit hooks scan staged changes for accidental secret introduction. Detected secrets block the commit until rotated and removed from history.
- Long-lived shared secrets are avoided in favor of short-lived, scoped credentials wherever the upstream provider supports them.
5. Cryptography in customer-facing features
- Passwords — user passwords are hashed (not encrypted) with bcrypt at a cost factor consistent with current OWASP guidance.
- MFA secrets — TOTP shared secrets are stored in the database, validated server-side, and protected by the database disk-encryption layer. Column-level encryption of TOTP secrets using the pgcrypto helper is on the SOC 2 readiness roadmap.
- OAuth state — OAuth state nonces are signed (HMAC-SHA256) with a dedicated state-signing secret distinct from the JWT issuer secret.
- JWTs — JSON Web Tokens are signed (not encrypted) using a server-only secret. Tokens carry only the minimum claims needed to authorize the request; they do not carry restricted-classification data.
6. Roles and responsibilities
- Policy owner — Bella platform engineering lead.
- Annual review — algorithm selection, key sizes, and library versions are reviewed at least once per calendar year and on disclosure of any material cryptographic weakness in a library Bella depends on.