Security &
Audit
The Security module protects patient data and controls who can access what. It manages authentication (login), authorization (permissions), data encryption, and audit logging—the foundation of trust in the system.
What is Security Management?
Security covers four main areas: Authentication (verifying who you are via JWT tokens and passwords), Authorization (what you're allowed to do, controlled by Roles and Permissions), Data Protection (encrypting sensitive data like patient names and phone numbers), and Audit Logging (recording every access and change for accountability).
The system uses a Role-Based Access Control (RBAC) model: users are assigned roles, roles have permissions, and permissions control what you can see and do. On top of this, Record Scope limits which specific patients or records you can access.
Why Does It Exist?
- → Patient privacy — Medical records are sensitive; unauthorized access is illegal (HIPAA, GDPR)
- → Data breaches — Hospital data is valuable on the black market; encryption prevents theft
- → Internal threats — Most data breaches come from inside; audit trails deter misuse
- → Regulatory alignment — HMIS ships HIPAA- and GDPR-oriented technical controls; certification, BAAs, workforce training, and breach notification remain customer responsibilities (see
docs/info/COMPLIANCE-PROGRAM.md)
Compliance posture (honest scope)
HMIS-WEB is not marketed as “HIPAA Ready” or certified. The product provides implementable safeguards—RBAC, audit logs, optional field encryption, DSR APIs, access reviews, break-glass—mapped in docs/info/HIPAA-CONTROL-MATRIX.md. Many matrix rows are Partial: TLS certificate management, encryption at rest, DR execution, training attestation, and regulatory breach letters require hospital process. SOC 2 Type II is roadmap-only per docs/info/SOC2-READINESS.md.
RBAC, audit export, break-glass, retention scheduler, permission catalog parity tests
TLS at rest, DSR erasure cross-store, training LMS, DR drills, BAA execution
Physical controls, background checks, legal breach determination, workforce sanctions
Every Feature Explained
Role-Based Access Control (RBAC)
Users are assigned roles; roles have granular permissions.
Ensures each staff member has exactly the access they need—no more, no less.
Permissions follow the pattern <code>module:action</code> (e.g., <code>patients:view</code>, <code>billing:create</code>). Roles group related permissions (Doctor, Nurse, Reception, Admin).
Record Scoping
Limits which patient records a user can see.
A lab technician shouldn't see every patient, only those with pending tests.
Scopes are <code>self-created</code> (only records I created), <code>self-assigned</code> (patients assigned to me), or <code>all</code> (full access).
JWT Authentication
Secure login using JSON Web Tokens.
Stateless authentication that works across API and web. Tokens expire automatically.
When you log in, the server issues a signed JWT with a unique <code>jti</code>. Logout and password change revoke that access token immediately (Redis blacklist with in-process fallback). Refresh tokens rotate on each use and are revoked on logout.
Patient Portal Link Expiry
Caps how long patient portal QR links remain valid.
Long-lived public links increase exposure if printed or forwarded; a hard ceiling limits risk.
Settings accept <code>patient.portal_qr_expires_days</code> from 1 through <strong>30</strong> days for new tokens (default 3). Values above 30 are rejected at the API. Legacy JWTs issued under the former longer ceiling remain valid until natural expiry. Staff pick the duration when generating a QR from the patient chart; optional module scopes can limit which chart sections a link exposes.
Field-Level Encryption
Sensitive fields (phone numbers, names, addresses) are encrypted in the database.
Even if the database is breached, encrypted fields are unreadable without the key.
Fields are encrypted using AES-256-GCM at the application layer. They are only decrypted when rendering in an authorized UI session.
Audit Logging
Every significant action is recorded: who did what, when, and from where.
Provides accountability. If something goes wrong, you can trace exactly what happened.
Audit logs capture user ID, action type (create, update, delete, view), resource type and ID, timestamp, and IP address. Logs are immutable (append-only).
Permission Catalog
A master list of all permissions in the system.
Ensures consistency between the API (backend) and the web app (frontend).
Permissions are defined in <code>allPermissions.ts</code> on the API side and mirrored in the web permission catalog. A script checks for parity.
Identity Linking (Doctor ↔ User ↔ Employee)
Optional bindings between clinical Doctor profiles, login Users, and HR Employees.
Prevents duplicate identities across clinical, auth, and payroll systems.
Doctor detail and IT onboarding can link the three records so schedules, RBAC, and compensation stay aligned without sharing secrets in the handbook.
Governance Helpdesk & Access Review
Internal tickets, access certification cycles, and break-glass recording.
Hospitals need operational governance beyond raw RBAC.
Governance workspace covers helpdesk queues, periodic access reviews, break-glass emergency access with reason, and SOP documents, all permission-gated and audited.
Clinical Branch Geography
Working-in campus scope layered on module permissions.
Multi-campus hospitals must not leak cross-branch lists while preserving org-wide patient chart continuity.
Session <code>activeBranchId</code> stamps new ops rows. Lists compose <code>branchListWhere</code> with RBAC. Chart-by-id stays org-wide when loading a specific patient. See <code>docs/info/ADR-001-branch-vs-orgunit.md</code>.
MFA & Step-Up Auth
TOTP enrollment and privileged step-up challenges.
Adds a second factor for sensitive settings and high-risk roles.
Routes under <code>/api/v1/auth/mfa/*</code>; login may return <code>mfaRequired</code>. Step-up via <code>x-hmis-step-up</code> header. Documented in <code>docs/info/MFA-AUTHENTICATION.md</code>.
Privacy & DSR APIs
Data-subject request intake, approval, and erasure orchestration.
GDPR and hospital privacy offices need auditable request handling.
<code>POST /api/v1/privacy/dsr</code> with types access/erasure/portability/restriction. Erasure jobs log evidence per store; legal hold blocks purge. See COMPLIANCE-PROGRAM §5.
Vulnerability & Deploy Gates
Automated dependency audit and full deploy regression.
Security controls must be testable before production.
<code>npm run audit:ci</code>, Dependabot, <code>npm run test:deploy</code>, and <code>npm run test:security --prefix api</code>. Hardening baseline in <code>docs/info/SECURITY-HARDENING.md</code> and <code>docs/info/VULNERABILITY-MANAGEMENT.md</code>.
Technical Architecture
| Field | Type | Institutional Role |
|---|---|---|
| mutation_key | UUID | Unique audit trail identifier. |
| initiating_id | UUID | Professional ID of the data consumer. |
| event_scope | Enum | Read, Update, Delete, Export, Login. |
| timestamp_hash | Varchar | Cryptographic hash of the event time for immutability. |
Note: Sensitive fields use AES-256 field-level encryption where applicable.
Governance & Power
audit:viewencryption:manageusers:manageField-Level Encryption
PII fields like phone numbers and names are encrypted at the application layer. Decryption only occurs in authorized UI sessions.
Zero-Trust Mesh
Every internal API call requires a short-lived token, ensuring even service-to-service communication is verified.
Audit Transparency
Governors can view a real-time 'heat-map' of data access across the institution, identifying potential security anomalies.
Enterprise compliance documentation
Hospital IT, security officers, and auditors use the repository docs/ pack alongside in-app governance. Key artifacts (paths relative to HMIS-WEB repo root):
- Compliance program (master index)
docs/info/COMPLIANCE-PROGRAM.md
- HIPAA control matrix
docs/info/HIPAA-CONTROL-MATRIX.md
- Security hardening
docs/info/SECURITY-HARDENING.md
- MFA authentication
docs/info/MFA-AUTHENTICATION.md
- GDPR ROPA
docs/info/GDPR-ROPA.md
- Compliance evidence export
docs/info/COMPLIANCE-EVIDENCE-EXPORT.md
- SOC 2 readiness (roadmap)
docs/info/SOC2-READINESS.md
- Vulnerability management
docs/info/VULNERABILITY-MANAGEMENT.md
- Incident response policy
docs/info/policies/INCIDENT-RESPONSE-POLICY.md
- Penetration test scope
docs/info/PENTEST-SCOPE.md
- Disaster recovery
docs/info/DR-PLAYBOOK.md
- Governance module
docs/info/GOVERNANCE.md
- API contract / OpenAPI
docs/info/API-CONTRACT.md
- Training curriculum
docs/info/training/CURRICULUM.md
- HR customization
docs/info/HR-CUSTOMIZATION.md
Operational controls: access reviews, DR drills, DSR intake, and training completion are recorded under /dashboard/governance/policies and /api/v1/privacy (DSR). See docs/info/policies/INFORMATION-SECURITY-POLICY.md for customer policy template. Policy-as-code checks run via api/test/compliance/complianceMatrix.test.ts.
Related handbook: Systems API · Operations Runbook · Operator Onboarding