Please report security vulnerabilities to security@healthwatchers.com. Do not open public GitHub issues for security vulnerabilities.

We aim to respond within 48 hours and will coordinate a fix and disclosure timeline with you.

Clinic Stellar secret keys (starting with S) provide full control over a clinic's Stellar account. A single database breach without encryption would allow an attacker to drain all clinic funds.

Stellar secret keys are encrypted at rest using AES-256-GCM before storage in MongoDB. The implementation is in apps/api/src/modules/clinics/keypair.service.ts.

Key separation: The Stellar keypair encryption uses a dedicated KEYPAIR_ENCRYPTION_KEY environment variable — a separate 32-byte key from the PHI field encryption key (FIELD_ENCRYPTION_KEY). This ensures that compromising one key does not expose both PHI and Stellar secrets.

Storage format:

• encryptedSecretKey: <ciphertext_hex>:<auth_tag_hex> — AES-256-GCM ciphertext with authentication tag
• iv: <iv_hex> — 16-byte random IV stored separately

Guarantees:

• Raw Stellar secret keys (starting with S) are never stored in MongoDB
• Each encryption uses a fresh random IV (no IV reuse)
• GCM authentication tag prevents ciphertext tampering
• Decryption failures are counted via the mongodb_keypair_decryption_failures_total Prometheus metric and trigger a critical alert

Generate a secure key:

openssl rand -hex 32

To rotate the KEYPAIR_ENCRYPTION_KEY:

1. Generate a new key: openssl rand -hex 32
2. Write a migration script that:
   • Reads each ClinicKeypair document
   • Decrypts encryptedSecretKey with the old key
   • Re-encrypts with the new key
   • Updates the document and increments keyVersion
3. Deploy the migration before updating the environment variable
4. Update KEYPAIR_ENCRYPTION_KEY in your secrets manager (AWS Secrets Manager / HashiCorp Vault)

• AWS KMS / HashiCorp Vault: For production, consider wrapping the KEYPAIR_ENCRYPTION_KEY with a KMS-managed Key Encryption Key (KEK). This provides hardware-backed key protection and automatic key rotation.
• Envelope encryption: Store only the encrypted data key in the database; the master key never leaves KMS.

Patient PHI fields (contactNumber, address, dateOfBirth) are encrypted at rest using AES-256-GCM via apps/api/src/lib/encrypt.ts. The encryption key is configured via FIELD_ENCRYPTION_KEY.

• JWT-based authentication with short-lived access tokens and rotating refresh tokens
• Role-based access control (SUPER_ADMIN, CLINIC_ADMIN, DOCTOR, NURSE, ASSISTANT, READ_ONLY)
• MFA support via TOTP

Security-relevant Prometheus alerts are defined in monitoring/alerts.yml:

• StellarKeypairDecryptionFailure — fires immediately on any decryption failure (critical)
• MongoDBPoolHighUtilization — fires when pool utilization > 80% for 2 minutes (warning)
• MongoDBPoolWaitQueueNonEmpty — fires when requests queue for connections (critical)

Health Watchers is designed with HIPAA and GDPR compliance in mind. This document outlines security practices and guidelines.

1. Authentication & Authorization
2. Data Protection
3. API Security
4. Incident Response
5. Compliance
6. Reporting Security Issues

• Minimum 12 characters
• Must contain uppercase, lowercase, numbers, and special characters
• Passwords hashed with bcrypt (cost 12)
• Password reset tokens expire after 1 hour
• Account lockout after 5 failed login attempts (15 minutes)

• TOTP (Time-based One-Time Password) available for admin roles
• Backup codes generated during MFA setup
• MFA required for SUPER_ADMIN and CLINIC_ADMIN roles

• Access tokens expire after 15 minutes
• Refresh tokens expire after 7 days
• Refresh token rotation: new token issued on each refresh
• Tokens stored in secure HTTP-only cookies
• Token revocation on logout

Access tokens are short-lived (15 min) but can be explicitly invalidated before expiry:

• Per-token denylist: Each access token carries a jti (UUID v4) claim. On logout or password change, the jti is stored in Redis with a TTL equal to the token's remaining lifetime. verifyAccessToken rejects any token whose jti is in the denylist.
• Logout-all: POST /api/v1/auth/logout-all stores a per-user invalidation timestamp (user-invalidated:{userId}) in Redis. All access tokens with an iat (issued-at) before that timestamp are rejected, effectively invalidating every active session for the user.
• Graceful degradation: If Redis is unavailable, denylist checks are skipped and tokens remain valid until natural expiry. This is acceptable given the 15-minute access token lifetime.

Redis keys used:

Roles and permissions:

• At Rest: AES-256-GCM encryption for sensitive data
• In Transit: TLS 1.2+ enforced, HTTPS only in production
• Database: MongoDB encryption at rest enabled
• Secrets: AWS Secrets Manager for API keys and private keys

• PHI (Protected Health Information) encrypted at rest
• Passwords never logged or transmitted in plain text
• Stellar private keys stored in secure enclave
• Credit card data: PCI-DSS compliant (tokenized via Stellar)
• Audit logs sanitized to exclude sensitive fields

• Patient records: Retained per HIPAA requirements (6 years minimum)
• Audit logs: Retained for 90 days
• Deleted data: Securely wiped using cryptographic erasure
• Right to be forgotten: Data export and deletion available

• All inputs validated with Zod schemas
• File uploads scanned for malware
• File size limits enforced (max 10MB)
• Allowed file types whitelist

• General endpoints: 100 requests per 15 minutes per IP
• Authentication endpoints: 5 attempts per 15 minutes per IP
• Payment endpoints: 10 requests per 15 minutes per user

• Whitelist specific origins (not *)
• Credentials allowed only for trusted origins
• Preflight requests validated

• Content-Security-Policy (CSP)
• X-Frame-Options: DENY
• X-Content-Type-Options: nosniff
• Strict-Transport-Security (HSTS)
• X-XSS-Protection

• Parameterized queries via Mongoose
• Input sanitization for regex patterns
• No eval() or Function() with user input

If you discover a security vulnerability:

1. Do not publicly disclose the vulnerability

2. Email security@healthwatchers.com with:

   • Description of the vulnerability
   • Steps to reproduce
   • Potential impact
   • Your contact information

3. We will:

   • Acknowledge receipt within 24 hours
   • Investigate and assess severity
   • Develop and test a fix
   • Release a patch and security advisory
   • Credit the reporter (if desired)

• Security incidents logged and tracked
• Incident severity assessed (Critical, High, Medium, Low)
• Affected users notified within 24 hours for Critical/High
• Root cause analysis performed
• Preventive measures implemented

• Business Associate Agreement (BAA) in place
• PHI encryption at rest and in transit
• Access controls and audit logging
• Breach notification procedures
• Annual security risk assessment

• Data processing agreements in place
• Data retention policies enforced
• Right to access, rectification, erasure
• Data portability (export functionality)
• Privacy policy and consent management

• Credit card data tokenized via Stellar
• No credit card storage on servers
• Secure payment processing
• Regular security assessments

1. Code Review: All code reviewed by at least one other developer
2. Dependency Management: Keep dependencies up to date, use npm audit
3. Secrets Management: Never commit secrets, use environment variables
4. Logging: Log security events, but never log sensitive data
5. Testing: Write security tests for authentication and authorization

1. Access Control: Principle of least privilege
2. Monitoring: Monitor logs for suspicious activity
3. Backups: Regular encrypted backups, test restore procedures
4. Updates: Apply security patches promptly
5. Audits: Regular security audits and penetration testing

1. Strong Passwords: Use unique, strong passwords
2. MFA: Enable multi-factor authentication
3. Phishing: Be cautious of suspicious emails
4. Reporting: Report suspicious activity immediately

See SECURITY_CHECKLIST.md for detailed OWASP Top 10 assessment and penetration testing checklist.

• OWASP Top 10
• HIPAA Security Rule
• GDPR
• PCI-DSS
• NIST Cybersecurity Framework

Last Updated: 2026-05-27
Next Review: 2026-08-27