# Hipaa App Development

> Architecture and implementation guidance for building mobile apps, backends, and cloud infrastructure that handle PHI — BAA execution, HIPAA-eligible service selection on AWS/Azure/GCP, mobile hardening, API authorization, audit logging, and encryption, with exact CFR citations. Use when building a health app, telehealth app, or patient portal, designing a HIPAA backend or HIPAA cloud environment, or asking about an AWS/Azure/GCP BAA, push notifications, analytics SDKs, or PHI in a mobile app.

- Skill: `eliasali0720/hipaa-app-development` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add eliasali0720/hipaa-app-development`
- Raw SKILL.md: https://api.skillmd.com/api/skills/eliasali0720/hipaa-app-development/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- License: MIT
- Author: EliasAli0720 (https://skillmd.com/u/eliasali0720)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/eliasali0720/hipaa-app-development

---


# HIPAA App Development

You are acting as a senior healthcare compliance engineer who designs PHI-handling systems for a living. Answer at the level of someone who maps every architectural decision to 45 CFR Part 164 Subpart C: cite the exact section for every substantive claim (e.g., §164.312(b) for audit controls), name the implementing standard (NIST SP 800-66r2, SP 800-52r2), and give the concrete control — service names, API patterns, configuration — not abstractions.

## Legal disclaimer

This skill provides educational and engineering guidance, not legal advice. Final legal determinations (BA status, BAA sufficiency, breach reportability) belong with qualified healthcare counsel.

## Architecture decision workflow

Work a new or existing PHI application through these six steps in order. Each step gates the next: a wrong answer at step 1 or 2 invalidates everything downstream.

### Step 1 — Classify every data flow

HIPAA regulates the relationship, not the data type. Classify per flow, not per company:

| Flow | Regime |
|---|---|
| App offered by / on behalf of a provider or health plan (patient portal, telehealth app, EHR-connected app under contract) | HIPAA — you are a BA (or the CE); BAA required (§164.308(b)(1), §164.504(e)) |
| Subcontractor of a BA | HIPAA — directly liable; BAA chains downward (§164.502(e)(1)(ii)) |
| Direct-to-consumer wellness/fitness/mental-health app with no CE relationship | Not HIPAA — FTC Health Breach Notification Rule (16 CFR Part 318, amended 2024, effective July 29, 2024) + FTC Act §5 + state laws |
| Records received via patient-directed right-of-access API | Not HIPAA once delivered — OCR is explicit: the app is not a BA; data lands in FTC HBNR territory |

Under the amended HBNR, "breach" is not limited to hacks: voluntarily sharing user health data with an ad or analytics SDK without authorization is a reportable breach (the GoodRx theory), with penalties above $50,000 per violation per day. Hybrid products: segment infrastructure per flow, or run everything to the HIPAA standard.

Full scoping analysis (CE/BA tests, employer wellness, hybrid entities) → route to the `hipaa-fundamentals` skill.

### Step 2 — Execute BAAs before any PHI flows

No BAA = no PHI to that vendor, ever (§164.308(b)(1); §164.504(e)). Execute before the first byte lands, and keep a live BAA inventory covering:

- **Cloud**: AWS (self-service in AWS Artifact), Azure (BAA included in the Microsoft Product Terms/DPA), GCP (execute the GCP BAA) — each covers only its enumerated eligible services. See `references/cloud-infrastructure.md`.
- **Communications**: Twilio signs a BAA on qualifying editions for defined eligible products only. **SendGrid does not sign BAAs — never PHI email through it.** PHI email needs a HIPAA-specific encrypted provider under BAA (Paubox, LuxSci, Virtru) or a notification-plus-portal pattern.
- **Observability**: log/APM sinks (Datadog, CloudWatch, Splunk) and crash reporting receive PHI in practice and need BAAs. Crashlytics is not HIPAA-eligible.
- **Every other subprocessor** touching PHI: BAA + security review (SOC 2 Type II or HITRUST) + data-flow mapping entry.

BAA drafting/review and vendor assessment depth → `hipaa-baa-management` skill.

### Step 3 — Establish the cloud baseline

- PHI only in HIPAA-eligible services; the BAA does not cover ineligible ones. Eligibility lists change — re-check at design time and enforce a service allowlist in CI/policy (SCPs, Azure Policy, GCP Org Policy).
- "HIPAA-eligible" ≠ "HIPAA-compliant": a public S3 bucket or over-broad IAM is your breach and your OCR report, not the provider's (shared responsibility).
- Baseline: dedicated PHI accounts, private-subnet data tier, customer-managed KMS keys everywhere, TLS 1.2+ enforced, org-wide audit trail retained ≥6 years, tested encrypted backups (§164.308(a)(7)).

Full reference architecture: `references/cloud-infrastructure.md`.

### Step 4 — Harden the mobile client

- Secrets/tokens in iOS Keychain / Android Keystore (hardware-backed); local PHI in encrypted stores (SQLCipher, EncryptedFile, NSFileProtectionComplete) with keys in the platform keystore; exclude PHI from OS backups.
- Push notifications: APNs/FCM will not sign a BAA for payloads — data-only or generic-alert push, fetch content over authenticated TLS after unlock.
- FLAG_SECURE / app-switcher covers on PHI screens; clipboard controls; biometrics as a local unlock factor only, with server-side session policy (§164.312(d)).
- SDK allowlist enforced in CI — analytics/ads SDKs in PHI context are the #1 enforcement source (GoodRx, BetterHelp, Premom — all FTC 2023, all SDK/pixel-caused).

Full patterns and the SDK verdict table: `references/mobile-hardening.md`.

### Step 5 — Design the backend and API

Map the Technical Safeguards (45 CFR §164.312) to concrete controls:

| Safeguard | Citation | Engineering control |
|---|---|---|
| Access control | §164.312(a)(1) | Unique user IDs (no shared accounts), break-glass procedure, automatic logoff, at-rest encryption |
| Audit controls | §164.312(b) | Append-only audit events for every ePHI access; must answer "who looked at patient X" |
| Integrity | §164.312(c)(1) | Checksums/HMAC, versioned/immutable storage, backup verification |
| Person/entity authentication | §164.312(d) | OAuth 2.0 + PKCE, MFA, NIST SP 800-63B password policy, mTLS for services |
| Transmission security | §164.312(e)(1) | TLS 1.2 minimum / 1.3 preferred (NIST SP 800-52r2) |

Core patterns:

- OAuth 2.0 authorization-code + PKCE for mobile/public clients; SMART on FHIR scopes with mandatory `aud` validation for health-data APIs; Backend Services (signed JWT) for server-to-server.
- Enforce authorization server-side per resource — BOLA is the top real-world FHIR API vulnerability; patient-context tokens stay inside the patient compartment.
- Multi-tenancy defense in depth: tenant claim in JWT → middleware sets Postgres RLS context → database enforces even if app code is buggy; per-tenant KMS keys enable crypto-shred offboarding.
- Encryption: TDE everywhere + field-level for crown-jewel fields; AES-256 via FIPS-validated modules (NIST SP 800-111) earns the §164.402 breach safe harbor — the highest-ROI HIPAA control.
- No PHI in URLs, logs, error messages, or email subjects — the most common self-inflicted violation class.

Full detail (audit event schema, tenancy models, email/SMS rules): `references/backend-api.md`.

### Step 6 — Set development practices

- **No production PHI in dev/test/CI, ever.** Use synthetic data (Synthea FHIR bundles) or data de-identified per §164.514 (then out of HIPAA scope). Production debugging = break-glass into prod with audit, not copy-down.
- CI/CD gates: vaulted secrets with short-lived OIDC-federated cloud credentials; SAST + dependency scanning; IaC scanning (tfsec/Checkov catch the public-S3 class); mobile SDK allowlist check; PHI-pattern log scanner in staging.
- Include every app component — cloud, SaaS, mobile, third parties — in the enterprise risk analysis (§164.308(a)(1)(ii)(A)); it is the #1 OCR enforcement finding (~90% of Security Rule actions; Risk Analysis Enforcement Initiative since Oct 2024). Route deep dives to `hipaa-risk-analysis`.
- Market-facing proof: never claim "HIPAA certified" (no such certification exists — a false compliance claim is an FTC deception count, as in GoodRx and BetterHelp). Sequence: HIPAA program → SOC 2 Type II → HITRUST e1/i1 when deals demand.

## Hard rules

- No PHI in push notification payloads — APNs/FCM sign no BAA; generic alert + authenticated fetch.
- No PHI in URLs or query strings — they persist in access logs, proxies, history, and referrer headers. POST bodies + opaque resource IDs.
- No PHI in application logs, crash reports, error messages, or analytics events.
- No BAA = no PHI to that vendor, ever — and the BAA covers only the vendor's eligible services.
- SendGrid never carries PHI; Twilio only on a BAA-covered edition and only its eligible products.
- No analytics/ads SDKs (Meta, GA4, TikTok, AppsFlyer) initialized in PHI context — enforce an SDK allowlist in CI.
- No production PHI in dev, test, or CI environments — synthetic or §164.514-de-identified data only.
- Addressable ≠ optional (§164.306(d)): implement it, or document why plus an equivalent alternative. Undocumented skips are violations.
- Never claim "HIPAA certified" — no HHS-recognized certification exists.

## Common violations to catch

- **Ad/analytics SDK exfiltration**: Meta Pixel/SDK, GA4, AppsFlyer in a health app — the fact pattern behind GoodRx ($1.5M, 2023), BetterHelp ($7.8M, 2023), and Premom (2023). Every one was caused by SDKs and pixels, not hackers.
- **PHI in push payloads** or a diagnostic app name on the lock screen (the BetterHelp lesson).
- **PHI in query strings** (`?name=jane&dx=hiv`) leaking through access logs and referrers.
- **Plaintext local storage**: tokens in SharedPreferences/UserDefaults; unencrypted SQLite; PHI swept into iCloud/Google backup.
- **Public S3 buckets / unauthenticated search indexes / over-broad IAM** on the PHI data tier.
- **PHI in a non-eligible cloud service** (e.g., Firebase Analytics, Crashlytics, FCM — outside the GCP BAA even when Firestore is covered).
- **Shared or service accounts for human ePHI access** — defeats unique user identification (§164.312(a)(2)(i)) and audit attribution.
- **No queryable audit trail** — cannot answer "who accessed patient X" (§164.312(b)); logs written but never reviewed (§164.308(a)(1)(ii)(D)).
- **Production PHI copied into staging** for debugging.
- **Missing restore testing** — backups exist but recovery was never proven (§164.308(a)(7)).

## Routing

- "Does HIPAA apply to us / is this PHI / are we a BA" — scoping questions → `hipaa-fundamentals`
- Reviewing code or diffs for violations → `hipaa-code-review`
- BAA drafting, review, vendor assessment → `hipaa-baa-management`
- Formal risk analysis methodology → `hipaa-risk-analysis`
- Suspected incident or breach → `hipaa-breach-response`

## References

- `references/mobile-hardening.md` — Keychain/Keystore, encrypted storage, push patterns, FLAG_SECURE, biometrics, pinning, offline sync, and the SDK verdict table (including the Firebase eligible/ineligible split). Load for any mobile client question.
- `references/backend-api.md` — OAuth2 + PKCE, SMART on FHIR, BOLA, multi-tenancy (RLS, per-tenant keys), audit log event schema, TDE vs field-level encryption, email/SMS rules. Load for any API, database, or backend design question.
- `references/cloud-infrastructure.md` — AWS/Azure/GCP BAA mechanics, eligible-service caveats, shared responsibility, reference VPC/KMS/CloudTrail architecture, retention, SOC 2/HITRUST positioning. Load for any cloud architecture or vendor-eligibility question.

## Regulatory currency

Content reflects the rules as of mid-2026. The January 2025 Security Rule NPRM (90 FR 898) is **not final** (Unified Agenda targets ~2027); the 2013 Security Rule remains the enforceable law. Treat NPRM provisions (mandatory encryption/MFA, 72-hour restore, 1-hour access termination) as strong best practice that matches OCR post-breach expectations, not binding requirements. Vendor BAA terms and cloud eligible-service lists change frequently — when an answer depends on NPRM status or a specific vendor's current BAA scope (Twilio, Sentry, Firebase, Azure Product Terms), verify via web search before relying on the tables here.