Banking Data Encryption#

All provider-specific models in Sure use Rails ActiveRecord Encryption to protect sensitive data at rest. Encryption is applied uniformly across every banking and investment provider (Plaid, SimpleFin, SnapTrade, Binance, Kraken, Coinbase, EnableBanking, Akahu, Wise, Questrade, TrueLayer, and others) via a shared Encryptable concern.

The Encryptable Concern#

app/models/concerns/encryptable.rb is the single source of truth for conditional encryption. It exposes one class method, encryption_ready?, which delegates to ActiveRecordEncryptionConfig.explicitly_configured? 1. All provider models include Encryptable and gate their encrypts declarations behind this check 2.

If encryption is not configured (e.g., a dev environment without keys), the encrypts calls are skipped entirely and fields are stored in plaintext. Encryption is never silently partial.

What Gets Encrypted#

Two broad categories of fields are encrypted across every provider:

1. Credentials & Tokens (*Item models)#

Sensitive auth material on *Item (connection-level) models:

Deterministic vs. non-deterministic: Deterministic encryption produces the same ciphertext for a given plaintext, enabling exact-match queries (e.g., looking up an item by access_token). Non-deterministic encryption is randomized and more secure but prevents querying. Credentials that may be used as lookup keys get deterministic: true; secrets that are only read after lookup (e.g., OAuth secrets) do not.

The unified provider framework introduced in PR #1717 extends this to Provider::Connection (OAuth tokens), Provider::Account (raw payloads), and Provider::FamilyConfig (per-family BYOK credentials).

2. Raw API Payloads (*Account models)#

Every *Account model encrypts its stored provider snapshots. Common fields:

• raw_payload — the full per-account API response
• raw_transactions_payload — accumulated transaction history
• raw_holdings_payload — investment holdings (where applicable)
• Provider-specific variants: raw_liabilities_payload (Plaid, 13), raw_activities_payload (SnapTrade, 14), raw_balances_payload (SnapTrade/Questrade, 15), etc.

Example from SimplefinAccount 16 and PlaidAccount 17.

SimplefinItem also encrypts raw_payload and raw_institution_payload at the item level 18, as do PlaidItem 19, EnableBankingItem 20, and AkahuItem 21.

Encryption Configuration#

config/initializers/active_record_encryption.rb loads keys in this priority order 22:

1. Environment variables — ACTIVE_RECORD_ENCRYPTION_PRIMARY_KEY, ACTIVE_RECORD_ENCRYPTION_DETERMINISTIC_KEY, ACTIVE_RECORD_ENCRYPTION_KEY_DERIVATION_SALT 23. Works for both managed and self-hosted deployments.
2. Rails credentials — config.active_record.encryption block in credentials.yml.enc 24.
3. Auto-generation from SECRET_KEY_BASE (self-hosted only, no credentials present) — keys are derived via SHA-256 from SECRET_KEY_BASE suffixed with :primary_key, :deterministic_key, and :key_derivation_salt 25. This is stable across container restarts.

If only some (but not all) env vars are set, the initializer raises immediately rather than silently falling back 26.

lib/active_record_encryption_config.rb provides the helper methods. explicitly_configured? returns true if all three env vars are present or if credentials are configured 27; this is what encryption_ready? checks. ready? is a broader check that includes runtime-configured state 28.

Key Source Files#