Login.Health DB Wrapper

A HIPAA-compliant database wrapper for PostgreSQL that provides secure handling of Protected Health Information (PHI).

Overview

The Login.Health DB Wrapper is a core component of the Login.Health platform, providing developers with a secure and simplified approach to handling protected health information (PHI). This library creates a database abstraction layer that ensures HIPAA compliance while delivering an exceptional developer experience.

HIPAA Compliance Disclaimer

Important: While the Login.Health DB Wrapper provides features that support HIPAA compliance requirements (such as encryption, access controls, and audit logging), the package itself does not guarantee complete HIPAA compliance. This tool helps coordinate some of the technical requirements for compliance but is not a comprehensive compliance solution.

Login.Health is not responsible for ensuring your application's overall HIPAA compliance. Each developer and organization is responsible for:

• Testing and evaluating this package for security and compliance needs
• Implementing proper security controls beyond what this package provides
• Ensuring all aspects of HIPAA compliance are addressed in their application
• Consulting with compliance and legal experts as needed

Use of this package does not transfer compliance responsibility to Login.Health. The ultimate responsibility for HIPAA compliance remains with the healthcare organization and developers implementing this solution.

Features

• PostgreSQL Integration: Seamless connection to PostgreSQL databases
• Schema Definition with PHI Marking: Define database schemas with clear PHI indicators
• Field-Level Encryption: Automatic encryption of PHI fields using AES-256-GCM
• Access Control: Role-based and attribute-based access control with row-level security
• Audit Logging: Comprehensive logging of all data access and modifications
• Developer-Friendly API: Intuitive, ORM-like API for data operations

Installation

npm install @login-health/db-wrapper

Quick Start

// Initialize client
import { HealthDB } from "@login-health/db-wrapper";

const db = new HealthDB({
  // Use environment variables for all sensitive information
  connectionString: process.env.DATABASE_URL,
  applicationId: process.env.APP_ID,
  applicationSecret: process.env.APP_SECRET,
  encryptionKey: process.env.ENCRYPTION_KEY, // Enable encryption with this key
  security: {
    keyId: 'primary-key', // Optional key identifier
    auditLogLevel: 'detailed' // Optional audit logging level
  }
});

// Define a schema (with PHI fields marked)
const patientSchema = db.defineSchema("patient", {
  id: { type: "uuid", primaryKey: true },
  firstName: { type: "string", phi: true },
  lastName: { type: "string", phi: true },
  dateOfBirth: { type: "date", phi: true },
  email: { type: "string", phi: true },
  phoneNumber: { type: "string", phi: true },
  address: { type: "jsonb", phi: true },
  createdAt: { type: "timestamp", default: "now()" },
  updatedAt: { type: "timestamp", default: "now()" },
});

// Create a patient
const patient = await db.patient.create({
  data: {
    firstName: "John",
    lastName: "Doe",
    dateOfBirth: new Date("1980-01-01"),
    email: "[email protected]",
    phoneNumber: "555-123-4567",
    address: {
      street: "123 Main St",
      city: "Anytown",
      state: "CA",
      zipCode: "12345",
    },
  },
});

// Query patients
const patients = await db.patient.findMany({
  where: {
    dateOfBirth: {
      gte: new Date("1980-01-01"),
      lt: new Date("1990-01-01"),
    },
  },
  select: {
    id: true,
    firstName: true,
    lastName: true,
    dateOfBirth: true,
  },
});

Encryption

The DB Wrapper provides field-level encryption for PHI data:

// Fields marked with phi: true are automatically encrypted
const patientSchema = db.defineSchema("patient", {
  id: { type: "uuid", primaryKey: true },
  firstName: { type: "string", phi: true },  // Will be encrypted
  lastName: { type: "string", phi: true },   // Will be encrypted
  email: { type: "string" }                  // Not encrypted
});

// Create a patient - PHI fields are automatically encrypted
const patient = await db.patient.create({
  data: {
    firstName: "John",
    lastName: "Doe",
    email: "[email protected]"
  }
});

// When retrieving data, PHI fields are automatically decrypted
const retrievedPatient = await db.patient.findUnique({
  where: { id: patient.id }
});

// Access the encryption manager for advanced operations
const encryptionManager = db.getEncryptionManager();

// Rotate encryption keys
encryptionManager.rotateKeys({
  preserveOldKeys: true  // Keep old keys for decrypting existing data
});

For more details, see the encryption documentation and key management guide.

Key Management

Proper key management is essential for maintaining access to encrypted data:

// Initialize with a consistent key ID
const db = new HealthDB({
  connectionString: process.env.DATABASE_URL,
  encryptionKey: process.env.ENCRYPTION_KEY,
  security: {
    keyId: process.env.ENCRYPTION_KEY_ID, // Use a consistent key ID
    auditLogLevel: 'detailed'
  }
});

Important: Always use a consistent key ID to avoid "Decryption key not found" errors. See the key management guide for best practices.

Project Structure

login-health-db-wrapper/
├── src/
│   ├── client/           # Main client classes
│   ├── connection/       # Database connection handling
│   ├── schema/           # Schema definition and management
│   ├── crud/             # CRUD operations
│   ├── config/           # Configuration management
│   ├── encryption/       # Encryption functionality
│   ├── utils/            # Utility functions
│   └── types/            # TypeScript type definitions
├── test/                 # Test files
├── examples/             # Example usage
└── docs/                 # Documentation

Development

Prerequisites

• Node.js 16+
• PostgreSQL 12+

Setup

1. Clone the repository
2. Install dependencies: npm install
3. Build the project: npm run build
4. Run tests: npm test

License

Proprietary - Login.Health

Field Aliases

The DB Wrapper supports field aliases, allowing you to define snake_case field names in your schema while using camelCase in your code:

// Define a schema with field aliases
const patientSchema = db.defineSchema("patient", {
  id: { type: "uuid", primaryKey: true },
  first_name: { type: "string", phi: true, alias: "firstName" },
  last_name: { type: "string", phi: true, alias: "lastName" },
  date_of_birth: { type: "date", phi: true, alias: "dateOfBirth" }
});

// You can use either snake_case or camelCase field names in your queries
const patients = await db.patient.findMany({
  select: {
    id: true,
    first_name: true,  // Using snake_case
    lastName: true     // Using camelCase
  }
});