hipaa-safe-code

name	hipaa-safe-code
description	Rules for handling PHI/PII and secrets in this HIPAA-relevant healthcare library. Use whenever code touches patient data, identifiers, logging, error messages, caching, crypto, auth, or configuration/secrets.

HIPAA-safe code

This library backs a healthcare platform. Protected Health Information (PHI) and PII demand specific handling. The single most common violation is identifiers leaking into logs and error messages — guard that first.

Never

• Log or embed PHI/PII — names, DOB, SSN/MRN, addresses, contact info, diagnoses — in log lines, error messages, exceptions, stack traces, analytics, or cache keys. Log opaque IDs or redacted forms instead.
• Hardcode secrets — API keys, tokens, passwords, connection strings, private keys. Read them from config/environment (and .env is unreadable to Claude here by policy).
• Put sensitive data in URLs or query strings (they get logged upstream) — use the body.
• Use weak crypto — no MD5/SHA1 for security, no ECB, no static IV/salt, no Math.random() for anything security-relevant. Use the existing core crypto/auth kits.

Always

• Minimum necessary: functions accept and return only the fields the caller needs; avoid passing whole patient records when an ID suffices.
• Redact at the boundary: when building an error or log message that might include a record, redact identifying fields first. Prefer a shared redaction helper from core over ad-hoc code.
• Validate and parameterize: validate all input; use parameterized Sequelize queries (never string-concatenate SQL).
• Fail closed: on auth/permission ambiguity, deny. Enforce least-privilege role checks.
• Keep an audit trail for access to sensitive data where the kit's role calls for it.

When unsure

If a change involves PHI/PII flow, auth, crypto, or logging, run it past the security-reviewer subagent (or /review-kit) before treating it as done.