Building HIPAA-Compliant Web Apps, A Developer's Guide

HIPAA is one of those compliance frameworks that developers either treat as a vague legal requirement (dangerous) or an impenetrable bureaucratic maze (also dangerous). The reality is more practical: HIPAA has specific technical requirements, and if you're building a US healthcare web application that handles Protected Health Information (PHI), you need to implement them.

This guide covers the developer-facing requirements. It is not legal advice, if you're launching a healthcare product, get a HIPAA attorney. But this gives you the technical picture.

---

What Counts as PHI

Protected Health Information is individually identifiable health information tied to a person. That means any of the following, combined with health data:

• Name, address, date of birth, phone number, email
• Social Security Number, account numbers, certificate numbers
• Any unique identifier that could identify the individual

The common developer mistake: assuming only medical records are PHI. A user's email address combined with the fact that they have an account on your mental health app is PHI. Their IP address in your logs, tied to a healthcare visit, is PHI.

---

The Technical Safeguards You Must Implement

HIPAA's Security Rule specifies four categories of technical safeguards:

1. Access Controls

// Role-Based Access Control, enforce at the API layer
const PERMISSIONS = {
  'patient': ['read:own_records', 'write:own_profile'],
  'provider': ['read:patient_records', 'write:clinical_notes'],
  'admin': ['read:all', 'write:all', 'delete:records'],
  'billing': ['read:insurance_info', 'write:billing_codes'],
} as const;

function authorize(requiredPermission: string) {
  return (req: Request, res: Response, next: NextFunction) => {
    const userPermissions = PERMISSIONS[req.user.role] || [];
    if (!userPermissions.includes(requiredPermission)) {
      // Log access denial, HIPAA requires audit trails
      auditLog.warn({
        event: 'ACCESS_DENIED',
        userId: req.user.id,
        resource: req.path,
        requiredPermission,
      });
      return res.status(403).json({ error: 'Insufficient permissions' });
    }
    next();
  };
}

Minimum necessary access is a core HIPAA principle, users should only see the PHI they need for their specific role.

2. Audit Controls (This Is Where Most Apps Fall Short)

HIPAA requires you to track who accessed what PHI, when, and from where. Every read, write, and delete of PHI must be logged:

// Audit logging middleware for PHI access
async function auditPhiAccess(
  userId: string,
  action: 'READ' | 'CREATE' | 'UPDATE' | 'DELETE',
  resourceType: string,
  resourceId: string,
  req: Request
) {
  await db.query(`
    INSERT INTO phi_audit_log
      (user_id, action, resource_type, resource_id, ip_address, user_agent, timestamp)
    VALUES ($1, $2, $3, $4, $5, $6, NOW())
  `, [
    userId,
    action,
    resourceType,
    resourceId,
    req.ip,
    req.headers['user-agent'],
  ]);
}

// Usage in a service
async function getPatientRecord(patientId: string, requestingUser: User, req: Request) {
  const record = await db.query('SELECT * FROM patient_records WHERE id = $1', [patientId]);
  await auditPhiAccess(requestingUser.id, 'READ', 'patient_record', patientId, req);
  return record;
}

Audit logs must be retained for at least 6 years and must be tamper-evident. Store them separately from application logs.

3. Transmission Security

All PHI transmitted over any network must be encrypted. In practice:

- HTTPS everywhere, TLS 1.2 minimum (TLS 1.3 preferred)
- HSTS header enforced: Strict-Transport-Security: max-age=31536000; includeSubDomains
- No PHI in URL query parameters (they appear in logs and browser history)
- No PHI in JWT payloads unless the JWT is encrypted (JWE), not just signed (JWS)
- API responses must not include PHI fields not required by the request

4. Encryption at Rest

PHI stored in databases, file systems, or backups must be encrypted at rest:

AWS implementation:
- RDS: enable encryption at rest (uses AES-256 via KMS)
- S3: bucket-level SSE-S3 or SSE-KMS encryption
- EBS volumes: encrypted
- CloudWatch Logs containing PHI: encrypted with KMS key
- Backups: encrypted, verify this explicitly, it's not always default

---

Business Associate Agreements (BAAs)

Every third-party service that handles PHI on your behalf must sign a Business Associate Agreement. This is a legal document, but as a developer you need to know which services require one:

You MUST have a BAA with:

• Your cloud provider (AWS, Azure, GCP, they all offer BAAs)
• Your database hosting provider
• Any logging service that receives PHI (Datadog, Splunk, etc.)
• Email service providers if you send PHI via email (SendGrid, Mailgun)
• Analytics platforms if they receive PHI

Common mistake: Using a third-party error tracking service (Sentry, Bugsnag) without a BAA, and having PHI appear in error reports. Scrub PHI from error objects before they reach external services:

// Sanitize before sending to Sentry
Sentry.configureScope(scope => {
  scope.addEventProcessor(event => {
    // Remove PHI fields from request data
    if (event.request?.data) {
      const { ssn, dob, medicalRecordNumber, ...safe } = event.request.data;
      event.request.data = safe;
    }
    return event;
  });
});

---

Password and Session Requirements

• Passwords must meet complexity requirements (NIST 800-63B is the current US standard)
• Automatic session timeout required, 15 minutes of inactivity is common in healthcare
• MFA strongly recommended and often contractually required by covered entities

// Session timeout middleware
const SESSION_TIMEOUT_MS = 15 * 60 * 1000; // 15 minutes

app.use((req, res, next) => {
  if (req.session?.lastActivity) {
    const timeSinceActivity = Date.now() - req.session.lastActivity;
    if (timeSinceActivity > SESSION_TIMEOUT_MS) {
      req.session.destroy();
      return res.status(401).json({ error: 'SESSION_EXPIRED', message: 'Session timed out due to inactivity' });
    }
  }
  req.session.lastActivity = Date.now();
  next();
});

---

The Breach Notification Reality

HIPAA requires notifying affected individuals within 60 days of discovering a breach. If more than 500 individuals in a US state are affected, you also notify the Secretary of HHS and prominent media outlets in that state.

This means your incident response plan needs to include: breach detection, scope assessment, and notification workflows. Building this after a breach is too late.

---

HIPAA compliance is achievable with disciplined engineering. It's not magic, it's specific technical controls, consistently implemented and documented.

I've built HIPAA-compliant web applications for US healthcare clients and understand both the technical and compliance requirements. If you're building in this space, see my healthcare development work at waqarhabib.com/industries/healthcare-web-apps.

---

Originally published at waqarhabib.com