Security

:::info Source Sourced from services/billing-service/SECURITY_MODEL.md in the documentation repo. :::

1. Authentication

• JWT for internal.
• Stripe webhook HMAC signing (5-min window, nonce cache).
• S2S mTLS inter-service.

2. Authorization

• billing:read — tenant admin.
• billing:write — tenant admin.
• billing:admin — platform_admin.
• billing:refund — tenant admin with MFA step-up.
• billing:payout:trigger — platform_admin.

3. PCI DSS Scope (SAQ-A)

• No raw card data in our systems.
• Stripe Elements hosts card collection in iframe.
• We store tokens (processor-side IDs) only.
• Network: TLS 1.3 only; no PAN in any log.
• Tokenization verified by PCI-QSA annual.

4. Multi-Tenant Isolation

• RLS on all tables.
• Stripe customer per (tenant, email) — never shared across tenants.
• Processor webhook tenant inferred from metadata.tenantId; verified against customer → tenant mapping.

5. Tokenization

• Cards: Stripe Elements → token → never touches our servers.
• Bank accounts: Stripe Financial Connections token.
• Tokens stored in payment_methods table; encrypted at rest with tenant DEK.

6. Key Management

• KMS-backed tenant DEKs for payment method encryption.
• Webhook signing secret per-processor in KMS.

7. Webhook Security

• Stripe-Signature HMAC-SHA256 validated.
• 5-min timestamp tolerance.
• Event ID replay protection (PK in webhook_events).
• Invalid webhooks: log + alert, reject with 400.

8. Fraud & Abuse

• Velocity checks per buyer, per tenant, per card.
• 3DS challenge on risk score ≥ threshold.
• AI-assisted fraud scoring (advisory).
• Manual review queue for flagged transactions.

9. Audit

• Every payment, refund, invoice state change → audit log (immutable, Merkle-anchored).
• 7-year retention.

10. Threat Model

Threat	Mitigation
Card data exfiltration	Tokenization (SAQ-A); no PAN storage
Webhook replay	Signature + timestamp + nonce cache
Webhook spoofing	HMAC signature verification
Cross-tenant financial access	RLS + customer-tenant map verified
Refund manipulation	Idempotency; admin MFA step-up; audit
SQL injection	ORM-only; typed filters
Processor key leakage	KMS + restricted IAM; rotate quarterly
Double-charge	Idempotency-Key; Stripe also idempotent
Payout to fraudulent account	Stripe Connect KYC; manual review > $10k
Currency conversion manipulation	Rates from processor; snapshot at order time

11. Compliance

• PCI DSS SAQ-A.
• Tax laws (per jurisdiction): 7-year records.
• GDPR: erasure saga anonymizes PII (legal hold on billing records retained).
• CCPA: data subject requests honored.
• SOC 2 (M3): access controls, audit logs, access reviews.

12. Secrets

• Stripe API keys in KMS; restricted to billing-service IAM.
• Rotation quarterly.
• Test vs live keys per environment.