Field-Level Encryption & Security

Relevant source files

The following files were used as context for generating this wiki page:

• apps/api/src/auth/field-cipher.ts
• apps/api/src/auth/tokens.ts
• packages/db/prisma/migrations/20261006184700_row_level_security/migration.sql
• packages/db/prisma/migrations/20261007210000_consultations/migration.sql
• apps/api/src/auth/primitives.test.ts
• README.md

Field-Level Encryption (FLE) and security protocols in this platform ensure that sensitive clinical and authentication data remain protected at rest and during transit. The system employs AES-256-GCM for encrypting specific database fields and enforces strict Tenant Isolation using Postgres Row-Level Security (RLS). These measures prevent unauthorized access to patient data, even in the event of a database compromise or application-level logic errors.

Sources: apps/api/src/auth/field-cipher.ts, packages/db/prisma/migrations/20261006184700_row_level_security/migration.sql

Cryptographic Implementation

The platform uses the FieldCipher class to handle encryption and decryption of sensitive strings. It utilizes the aes-256-gcm algorithm, providing both confidentiality and authenticity.

FieldCipher Mechanism

The encryption process generates a unique 12-byte initialization vector (IV) for every operation, ensuring that identical plaintexts produce different ciphertexts. The resulting encrypted string follows a versioned, four-part format encoded in base64url.

The diagram shows the transformation from plaintext to the versioned ciphertext format used in the database.
Sources: apps/api/src/auth/field-cipher.ts:16-30

Key Security Requirements

• Key Length: The encryption key must be exactly 32 bytes (base64 encoded).
• Format Verification: The decrypt method validates the "v1" version prefix and the presence of all four required components before attempting decryption.
• Tamper Detection: Because GCM is an authenticated encryption mode, the decrypt method throws an error if the authentication tag does not match, detecting any tampering with the ciphertext.

Sources: apps/api/src/auth/field-cipher.ts:10-14, apps/api/src/auth/primitives.test.ts:58-67

Encrypted Fields

The application identifies specific fields that must be encrypted before being stored in the database.

Table	Field	Description
consultations	notes_cipher	Contains clinical notes written by doctors.
users (implied)	TOTP Secrets	Used for multi-factor authentication.

Sources: packages/db/prisma/migrations/20261007210000_consultations/migration.sql:98, apps/api/src/auth/field-cipher.ts:4-7

Database-Level Security

The platform relies on Postgres Row-Level Security (RLS) to enforce tenant isolation at the database layer. This ensures that a request can only access rows belonging to its specific organisation_id.

Role-Based Access Control

The database defines restricted roles that the API assumes during transactions:

• dhc_app: Used for standard tenant-scoped requests. It can only see rows where organisation_id matches the current session's ID.
• dhc_auth: Used for authentication flows. It has access to identity tables (users, sessions) but is explicitly denied access to clinical tables like patients or consultations.

Sources: packages/db/prisma/migrations/20261006184700_row_level_security/migration.sql:1-35

Tenant Isolation Flow

The API establishes the tenant context by setting a local variable within a transaction.

This diagram illustrates how RLS filters data based on the transaction-local organization ID.
Sources: packages/db/prisma/migrations/20261006184700_row_level_security/migration.sql:9-12

Token & Session Security

The TokenService manages the lifecycle of JSON Web Tokens (JWT) used for authentication and Multi-Factor Authentication (MFA).

Token Types and TTL

The system utilizes short-lived tokens to minimize the impact of token theft.

Token Type	Purpose	TTL (Seconds)
Access Token	Standard API authorization	900 (15 minutes)
MFA Token	Intermediate proof of password success	300 (5 minutes)

Sources: apps/api/src/auth/tokens.ts:16-18

Security Constraints

• Signing Algorithm: Tokens are signed using HS256.
• Audience Isolation: Access tokens use the dhc audience, while MFA tokens use dhc-mfa. The TokenService prevents an MFA token from being used as an access token by verifying these audiences.
• Refresh Tokens: Refresh tokens are opaque strings. The database stores only the SHA-256 hash of the refresh token to prevent use if the database is leaked.

Sources: apps/api/src/auth/tokens.ts:25-95, apps/api/src/auth/primitives.test.ts:81-88

Audit Logging Security

The audit_logs table is protected by a trigger that makes it append-only. Any attempt to UPDATE or DELETE an existing audit log entry results in a database exception, preserving the integrity of the clinical audit trail.

Sources: packages/db/prisma/migrations/20261006184700_row_level_security/migration.sql:67-78

Summary

Field-Level Encryption & Security in the Digital Healthcare Platform combines application-level cryptography with database-level isolation. By using FieldCipher for clinical notes and TOTP secrets, and Postgres RLS for tenant boundaries, the system ensures that sensitive healthcare information is only accessible to authorized personnel within the correct organizational context.