Security Whitepaper

Last updated: 2026-07-20
Audience: Security reviewers, technical partners, investors
Status: Reflects the current repository and deployed dev slice — not a certification document

This whitepaper describes Klugliv’s security architecture and controls as implemented in this codebase. It complements the user-facing Security Overview and the Trust Center.

1. Scope

In scope

• Mobile app (Expo / React Native)
• Marketing website (Vercel — static/SSR; no receipt data)
• Supabase (auth, Postgres, private object storage) — current production data plane
• AWS migration slice: API Gateway HTTP API, Lambda (OCR, media presign), S3, KMS, Secrets Manager, CloudWatch, IAM, budgets
• Third-party OCR (Google Cloud Vision) and optional analytics (PostHog)

Out of scope (today)

• Amazon Cognito mobile cutover (Terraform shell exists; app still on Supabase Auth)
• RDS / VPC data plane (planned Phase 3 migration — not active)
• Formal penetration test reports or SOC 2 Type II attestation

2. Threat model (high level)

We primarily defend against:

We assume clients may be compromised at the device level; server-side authorization remains authoritative.

3. Identity and authentication

Current state

Design note: Moving JWT validation to API Gateway authorizers is on the roadmap; in-app session validation inside Lambda is the current control.

4. Data classification

5. Network and transport

• All client ↔ service traffic uses TLS.
• AWS resources for the migration slice are configured in eu-central-1 (Frankfurt).
• Phase 1 architecture is serverless-first without a VPC/NAT to control cost; VPC is planned when RDS is introduced.

6. Encryption

OCR API keys are not embedded in the mobile app. They are loaded at runtime from Secrets Manager in Lambda.

7. OCR pipeline (AWS slice)

Mobile app ──TLS──► API Gateway ──► Lambda (receipt-ocr)
                                      │
                    ┌─────────────────┼─────────────────┐
                    ▼                 ▼                 ▼
            Secrets Manager      Google Vision      Supabase (auth check)
            (KMS encrypted)      (OCR API)

Controls

• User must present a valid Supabase session for OCR requests.
• Vision API key never returned to the client.
• Receipt image may be sent as base64 in POST today; S3 presigned upload path exists for dual-write migration.

8. Media presign (S3 dual-write)

When EXPO_PUBLIC_AWS_MEDIA_PRESIGN_URL is configured:

• Mobile requests a short-lived presigned PUT URL from Lambda.
• Upload uses SSE-KMS on the receipts bucket.
• Keys align with Supabase storage paths for operational consistency.

9. Infrastructure as code and change management

• AWS resources are managed with Terraform (remote state in S3 + DynamoDB lock).
• GitHub Actions can plan/apply Terraform via OIDC (klugliv-dev-github-deploy role) — no long-lived AWS keys in CI.
• Secret values (Vision key, Supabase URLs) are set out-of-band via CLI — not committed to git.

10. Logging, retention, and monitoring

Practices

• Avoid DEBUG logging of full OCR payloads in production.
• CloudWatch alarms and AWS Budgets provide cost and error signals at dev scale.

11. Third-party and cross-border processing

See Vendor Register and Subprocessors.

Notable cross-border consideration: Google Cloud Vision may process receipt images outside the EU depending on routing and configuration. This is documented in our GDPR readiness review as an area for legal confirmation of transfer mechanisms.

12. Secure development practices

• Monorepo with typed TypeScript (mobile + web).
• .env files with secrets are gitignored; mobile uses public env vars only where appropriate (EXPO_PUBLIC_*).
• DevOps playbook documents security baseline and lessons learned under docs/devops-playbook/.

13. Known gaps and roadmap (honest)

We do not represent these gaps as completed controls.

14. Related documents

• Security Overview
• Incident Response
• GDPR Compliance Review
• Data Retention Policy

15. Contact

hello@klugliv.com — security inquiries and coordinated disclosure welcome.