Back to home

Security Architecture

How OneSpend protects your financial data

Your Data Is Like Valuables in a Safe Deposit Box
Only you have the key to open it

Think of OneSpend like a bank vault. Your transaction data is locked inside a safe deposit box that only the application can open when you're logged in. Even the people who built the vault can't peek inside your box without the right keys being assembled at runtime. We don't hold a master key -- your data stays encrypted until the moment you need to see it.

How Your Data Flows

Step 1

Email

Bank sends you a notification email

Step 2

Parse

AI reads the email and extracts transaction details

Step 3

Encrypt

Data is encrypted with your unique key

Step 4

Store

Only encrypted blobs are saved to the database

Step 5

Decrypt

Data is decrypted only when you view it

What We CAN'T Do

Read your stored data at rest

Encrypted data is meaningless without the decryption keys assembled at runtime. Database dumps reveal nothing.

Access another user's data

Each user has their own encryption key. There is no shared key or master password.

Modify or delete your emails

We have read-only Gmail access. We cannot send, edit, or delete any email in your inbox.

Sell or share your data

Your financial data is never shared with third parties, advertisers, or data brokers.

Trust Indicators

AES-256-GCM

Military-grade authenticated encryption

HashiCorp Vault

Industry-standard secrets management

CASA Compliance

Cloud Application Security Assessment

What Happens If...

The database is breached

Attackers get encrypted blobs and wrapped keys. Without Vault (which runs separately with its own access controls), the data is computationally infeasible to decrypt. AES-256-GCM has no known practical attacks.

An employee goes rogue

No single person has access to all components needed to decrypt data. Vault access is policy-controlled and audit-logged. Database access alone yields only ciphertext.

A server is compromised

Encryption keys exist in memory only during active request processing. Vault tokens are short-lived and scoped. A compromised server cannot retroactively decrypt data at rest.

Frequently Asked Questions

Technical Deep-Dive

For developers, security researchers, and the curious

Envelope Encryption Architecture

OneSpend uses envelope encryption to protect transaction data. This is the same pattern used by AWS KMS, Google Cloud KMS, and Azure Key Vault.

Key Hierarchy

L0

Vault Transit Key (KEK)

Master key that never leaves Vault. Used to wrap/unwrap user DEKs.

L1

Per-User DEK (Data Encryption Key)

256-bit AES key generated on user creation. Stored only in wrapped (encrypted) form. Unwrapped in memory during request processing.

L2

Encrypted Data Blobs

Transaction data encrypted with the user's DEK. Each blob includes IV and auth tag.

Cryptographic Parameters
ParameterValue
AlgorithmAES-256-GCM (Galois/Counter Mode)
Key size256 bits
IV (nonce)12 bytes, cryptographically random per encryption
Auth tag128 bits (16 bytes)
KEK wrappingVault Transit engine (AES-256-GCM)
Blob formatIV (12B) || ciphertext || auth_tag (16B)
Threat Model
ThreatMitigationResidual Risk
Database breachAll data encrypted with per-user DEKs; DEKs stored only in wrapped formLow -- ciphertext without keys
Vault compromiseVault sealed at rest; requires unseal keys; audit logging; network isolationLow -- requires multiple unseal keys
Application server compromiseDEKs exist in memory only during request; short-lived Vault tokens; no persistent key storageMedium -- active sessions at risk
Insider threatNo single person has all components; Vault policies restrict access; audit trailsLow -- separation of duties
OAuth token theftTokens stored encrypted; scoped to gmail.readonly; refresh tokens rotatedLow -- read-only scope limits blast radius
Man-in-the-middleTLS everywhere; HSTS headers; certificate pinning for API callsVery low
Data Flows

Sync Flow (Background)

  1. Cron service authenticates to Vault with AppRole credentials
  2. Fetches user's wrapped DEK from database
  3. Sends wrapped DEK to Vault Transit for unwrapping (plaintext DEK returned in memory)
  4. Queries Gmail API with user's OAuth token for new transaction emails
  5. Sends email content to Gemini API for transaction extraction
  6. Encrypts extracted transaction data with unwrapped DEK (AES-256-GCM)
  7. Stores encrypted blob in database; DEK is discarded from memory

Read Flow (User Request)

  1. User authenticates via NextAuth session
  2. Application fetches user's wrapped DEK from database
  3. Sends wrapped DEK to Vault Transit for unwrapping
  4. Reads encrypted blobs from database
  5. Decrypts each blob in memory with unwrapped DEK
  6. Returns plaintext transaction data to user's browser over HTTPS
  7. DEK is discarded from memory after request completes

Deletion Flow

  1. User requests deletion (single transaction, all data, or account)
  2. Encrypted blobs are permanently deleted from database
  3. For account deletion: wrapped DEK is destroyed, OAuth tokens revoked, user record removed
  4. Deletion is irreversible -- no backups retain deleted data
Limited Use Compliance

OneSpend's use and transfer of information received from Google APIs adheres to the Google API Services User Data Policy, including the Limited Use requirements. Specifically:

  • Gmail data is used only to provide expense tracking functionality
  • No Gmail data is used for advertising
  • No Gmail data is transferred to third parties except as needed for transaction extraction (Gemini API)
  • No human reads Gmail data unless with explicit user consent, for security, or legal compliance