Summit1 SDK v1.3.5

🔥 CRITICAL UPDATE: Version 1.3.5 fixes a critical bug in RLS (Row-Level Security) operations. If you're using RLS, update immediately. See CRITICAL_FIX_v1.3.5.md for details.

A lightweight SDK for bridging base44 applications with Azure PostgreSQL Flexible Server. Includes HIPAA/GDPR compliant audit ledger with field-level hash deltas.

Features

• base44-Compatible API: Familiar entity-based access patterns
• Full CRUD Operations: Create, Read, Update, Delete with filtering, sorting, and pagination
• Row-Level Security (RLS): Multi-tenant data isolation with automatic org_id injection
• HIPAA/GDPR Audit Ledger: Tamper-evident, PHI-free audit trail with cryptographic hash chaining
• Synchronous & Asynchronous Audit: Choose direct DB writes or Azure Service Bus for high volume
• Bulk Operations: Efficient batch create and delete operations
• Connection Pooling: Built-in connection pool for optimal performance
• SSL/TLS Support: Secure connections with certificate validation
• Audit Trail: Automatic tracking of created_by, updated_by, and timestamps

Installation

npm install summit1

For asynchronous audit mode (optional):

npm install @azure/service-bus

Quick Start

Basic Usage (No Audit)

import { createClient } from 'summit1';

const summit1 = createClient({
  host: 'your-db.postgres.database.azure.com',
  user: 'your_user',
  password: 'your_password',
  database: 'your_db'
});

const task = await summit1.entities.tasks.create({ title: 'Hello', status: 'pending' });
const tasks = await summit1.entities.tasks.list();

With RLS

const summit1 = createClient({
  host: 'your-db.postgres.database.azure.com',
  user: 'your_user',
  password: 'your_password',
  database: 'your_db',
  rls: {
    enabled: true,
    userContext: {
      org_id: 'org-123',
      id: 'user-456',
      role: 'admin',
      email: '[email protected]'
    }
  }
});

With Audit Ledger (Synchronous Mode)

const summit1 = createClient({
  host: 'your-db.postgres.database.azure.com',
  user: 'your_user',
  password: 'your_password',
  database: 'your_db',
  rls: {
    enabled: true,
    userContext: {
      org_id: 'org-123',
      id: 'user-456',
      role: 'clinician',
      email: '[email protected]'
    }
  },
  audit: {
    enabled: true,
    mode: 'sync',
    hmacSecret: process.env.HMAC_SECRET
  }
});

// Set per-request context
summit1.setAuditContext({
  requestId: 'req-abc-123',
  clientIp: '203.0.113.50',
  userAgent: 'Mozilla/5.0...'
});

// All CRUD operations are now automatically audited.
// NO PHI is written to the audit ledger - only HMAC-SHA256 hashes.
const patient = await summit1.entities.patients.create({
  name: 'Jane Doe',
  dob: '1985-03-15',
  diagnosis: 'Routine checkup'
});

With Audit Ledger (Asynchronous Mode)

const summit1 = createClient({
  host: 'your-db.postgres.database.azure.com',
  user: 'your_user',
  password: 'your_password',
  database: 'your_db',
  rls: {
    enabled: true,
    userContext: { org_id: 'org-123', id: 'user-456', role: 'clinician', email: '[email protected]' }
  },
  audit: {
    enabled: true,
    mode: 'async',
    hmacSecret: process.env.HMAC_SECRET,
    serviceBusConnectionString: process.env.SERVICE_BUS_CONNECTION_STRING,
    serviceBusQueueName: 'audit-events',
    fallbackToSync: true
  }
});

See AUDIT_SETUP_GUIDE.md for complete setup instructions.

Audit Verification

// Verify a record matches its audit hash
const isValid = await summit1.verifyRecordHash(patient, storedHash, 'patients');

// Verify the entire audit chain for a record
const result = await summit1.verifyAuditChain('patients', 'patient-123');
// { valid: true, totalEntries: 5 }

// Get audit history (metadata only, no PHI)
const history = await summit1.getAuditHistory('patients', 'patient-123');

Database Setup

Run the audit schema migration:

psql -h your-db-host -U your-user -d your-db -f sql/001_create_audit_ledger.sql

API Reference

Client Creation

createClient(config)

Creates a new Summit1 client. See the JSDoc in client.js for all configuration options.

Entity Operations

| Method | Description | |---|---| | create(data) | Create a record | | get(id) | Get a record by ID | | list(options) | List records with filtering, sorting, pagination | | filter(filters, options) | Filter records | | update(id, data) | Update a record | | delete(id) | Delete a record | | deleteMany(filters) | Delete multiple records | | bulkCreate(records) | Create multiple records | | query(sql, params) | Execute raw SQL | | count(filters) | Count matching records |

RLS Methods

| Method | Description | |---|---| | setUserContext(context) | Set RLS user context | | getUserContext() | Get current user context | | isRLSEnabled() | Check if RLS is enabled |

Audit Methods

| Method | Description | |---|---| | setAuditContext(context) | Set per-request audit metadata | | getAuditContext() | Get current audit context | | isAuditEnabled() | Check if audit is enabled | | getAuditMode() | Get audit mode ('sync' or 'async') | | verifyRecordHash(record, hash, table) | Verify record integrity | | verifyAuditChain(table, recordId) | Verify hash chain integrity | | getAuditHistory(table, recordId) | Get audit trail |

Compliance

The audit ledger meets or exceeds:

| Requirement | Status | |---|---| | HIPAA §164.312(b) - Audit Controls | ✅ Exceeded | | HIPAA §164.312(e)(1) - Integrity Controls | ✅ Exceeded | | HIPAA §164.312(c)(1) - Authentication | ✅ Met | | GDPR Article 5(1)(f) - Integrity & Confidentiality | ✅ Exceeded | | GDPR Article 32 - Security of Processing | ✅ Exceeded | | GDPR Article 30 - Record of Processing Activities | ✅ Met |

File Structure

summit1-sdk-v1.3.0/
├── index.js                          # Main entry point
├── client.js                         # Core SDK with RLS + audit hooks
├── package.json                      # v1.3.0
├── LICENSE                           # MIT
├── README.md                         # This file
├── CHANGELOG.md                      # Version history
├── AUDIT_SETUP_GUIDE.md              # Sync vs Async setup guide
├── .env.example                      # Environment variable template
├── .gitignore
├── .npmignore
├── src/
│   └── audit/
│       ├── index.js                  # Audit module exports
│       ├── audit-logger.js           # Core audit engine
│       ├── async-audit-logger.js     # Async wrapper with Service Bus
│       ├── service-bus-publisher.js   # Service Bus publisher
│       └── service-bus-consumer.js    # Service Bus consumer worker
└── sql/
    └── 001_create_audit_ledger.sql   # Database schema migration

License

MIT