factory-security

Factory security

Each section leads with Principle (one sentence, stack-agnostic), then Why (constraint → option → tradeoff), then Recipe (the KMS / Resend / Upstash shape we use), and Failure mode when there's one to name.

Sensitive data at rest — encrypted with context binding

Principle. Sensitive data (SSN, government IDs, PHI fields, financial accounts) is KMS-encrypted at rest, with encryption context bound to the row's identity.

Why. Encryption alone protects against database exfiltration but not against row-shuffling — an attacker who can write to the database can swap encrypted blobs between rows, and the system decrypts each happily. Binding the encryption context to the user ID (or org ID) means KMS refuses to decrypt the blob when the context doesn't match — the row-shuffling failure mode becomes a decryption failure, which is loud.

Recipe.

// Encrypt on write
const encryptedSSN = await kms.encrypt(plaintext, {
  keyId: KMS_KEY_ID,
  context: { userId },
});
await db.update(users).set({ ssnEncrypted: encryptedSSN }).where(eq(users.id, userId));

// Decrypt on read — only in the handler that actually needs plaintext
const plaintext = await kms.decrypt(user.ssnEncrypted, { context: { userId } });

// Mask for display — never decrypt for display surfaces
const masked = `***-**-${plaintext.slice(-4)}`;

PHI in email/SMS — BAA at runtime, not in comments

Principle. Provider BAA status for PHI-bearing channels (email, SMS) is asserted at runtime; comments don't enforce.

Why. A // TODO: confirm Resend BAA before prod comment in the email helper is exactly as enforced as no comment at all. A runtime assertion that refuses to send PHI when the BAA-signed env var isn't true is enforcement: the bug becomes an outage, which is loud and gets fixed. Comments rot; assertions don't.

Recipe.

// In src/lib/email/resend.ts
if (process.env.RESEND_BAA_SIGNED !== 'true' && containsPHI(message)) {
  throw new Error('Cannot send PHI without signed BAA. Set RESEND_BAA_SIGNED=true after confirmation.');
}