@cloudstreamsoftware/claude-tools 1.0.0 → 1.1.0

package/skills/compliance-patterns/hipaa/data-archival-strategy.md

@@ -0,0 +1,387 @@
+# HIPAA Data Archival Strategy
+
+## Overview
+
+Zoho Creator retains audit log data for only **1 year** before automatic deletion. HIPAA requires **6 years** of retention. This document defines the automated archival strategy using Zoho Catalyst Cron functions to export audit data to Google BigQuery for long-term, compliant storage.
+
+> **WARNING**: If the monthly archival job fails silently for 12+ months, audit data will be permanently lost with no recovery option. Monitoring and alerting are NOT optional.
+
+---
+
+## Architecture Overview
+
+```
+Zoho Creator (ePHI Forms)
+    |
+    | (Deluge audit logging on every action)
+    v
+HIPAA_Audit_Log Form (Creator)
+    |
+    | (Monthly Catalyst Cron - Day 5 of each month)
+    v
+Catalyst Serverless Function
+    |
+    | (Batch export via Creator API → BigQuery API)
+    v
+Google BigQuery (Long-term storage)
+    |
+    | (Retention policy: 6 years + 90 days)
+    v
+Automated Purge (records older than 6 years + 90 days)
+```
+
+---
+
+## Monthly Automated Export Process
+
+### Schedule
+
+- **When**: 5th of every month at 02:00 UTC
+- **What**: Export all audit records from the previous calendar month
+- **Why Day 5**: Allows buffer for late-arriving records and avoids month-end processing
+
+### Catalyst Cron Function
+
+```javascript
+// File: functions/hipaa_audit_archival/index.js
+// Catalyst Cron Function - Scheduled monthly
+
+const catalyst = require('zcatalyst-sdk-node');
+const { BigQuery } = require('@google-cloud/bigquery');
+
+module.exports = async (cronDetails, context) => {
+  const app = catalyst.initialize(context);
+
+  // Calculate date range for previous month
+  const now = new Date();
+  const startDate = new Date(now.getFullYear(), now.getMonth() - 1, 1);
+  const endDate = new Date(now.getFullYear(), now.getMonth(), 0, 23, 59, 59);
+
+  const batchId = `ARCH-${startDate.getFullYear()}${String(startDate.getMonth()+1).padStart(2,'0')}-${Date.now()}`;
+
+  console.log(`Starting archival batch: ${batchId}`);
+  console.log(`Date range: ${startDate.toISOString()} to ${endDate.toISOString()}`);
+
+  try {
+    // Fetch audit records from Creator
+    const records = await fetchAuditRecords(startDate, endDate);
+    console.log(`Records to archive: ${records.length}`);
+
+    if (records.length === 0) {
+      await sendAlert('WARNING', `No audit records found for ${batchId}. Verify logging is active.`);
+      return;
+    }
+
+    // Transform and upload to BigQuery
+    const bigquery = new BigQuery({ projectId: process.env.GCP_PROJECT_ID });
+    const dataset = bigquery.dataset(process.env.BQ_DATASET);
+    const table = dataset.table('hipaa_audit_logs');
+
+    // Batch insert (max 10,000 rows per insert)
+    const batches = chunkArray(records, 10000);
+    for (const batch of batches) {
+      const rows = batch.map(r => transformRecord(r, batchId));
+      await table.insert(rows);
+    }
+
+    // Mark records as archived in Creator
+    await markRecordsArchived(records, batchId);
+
+    // Log success
+    await logArchivalResult(batchId, records.length, 'SUCCESS');
+
+    console.log(`Archival complete: ${records.length} records in batch ${batchId}`);
+
+  } catch (error) {
+    console.error(`Archival FAILED: ${error.message}`);
+    await sendAlert('CRITICAL', `Audit archival failed for batch ${batchId}: ${error.message}`);
+    await logArchivalResult(batchId, 0, 'FAILED', error.message);
+  }
+};
+
+function transformRecord(record, batchId) {
+  return {
+    audit_id: String(record.Audit_ID),
+    timestamp: new Date(record.Timestamp).toISOString(),
+    user_email: record.User_Email,
+    user_role: record.User_Role,
+    ip_address: record.IP_Address,
+    session_id: record.Session_ID,
+    action_type: record.Action_Type,
+    form_name: record.Form_Name,
+    record_id: record.Record_ID,
+    field_name: record.Field_Name || null,
+    old_value: record.Old_Value || null,
+    new_value: record.New_Value || null,
+    justification: record.Justification || null,
+    client_id: record.Client_ID,
+    source_org: process.env.ZOHO_ORG_ID,
+    archive_date: new Date().toISOString(),
+    archive_batch_id: batchId
+  };
+}
+
+function chunkArray(array, size) {
+  const chunks = [];
+  for (let i = 0; i < array.length; i += size) {
+    chunks.push(array.slice(i, i + size));
+  }
+  return chunks;
+}
+```
+
+### Deluge Companion Script (Record Fetching)
+
+```deluge
+// Workflow: Fetch audit records for archival
+// Called by Catalyst function via Creator API
+
+searchCriteria = "(Timestamp >= \"" + startDate + "\" && Timestamp <= \"" + endDate + "\" && Archived == false)";
+records = zoho.creator.getRecords("your-app", "HIPAA_Audit_Log", searchCriteria, 1, 200);
+
+// Note: Creator API returns max 200 records per call
+// Implement pagination for larger datasets
+```
+
+---
+
+## Data Format Specification
+
+### Export Format: JSON Lines (JSONL)
+
+Each record is exported as a single JSON object per line:
+
+```json
+{"audit_id":"12345","timestamp":"2025-01-15T14:30:22Z","user_email":"nurse@hospital.com","user_role":"Clinical Staff","ip_address":"10.0.1.45","session_id":"sess_abc123","action_type":"Access","form_name":"Patient_Records","record_id":67890,"field_name":null,"old_value":null,"new_value":null,"justification":null,"client_id":"CLT-001","source_org":"org_xyz","archive_date":"2025-02-05T02:00:15Z","archive_batch_id":"ARCH-202501-1707091215000"}
+```
+
+### Field Encryption
+
+> **WARNING**: old_value and new_value fields may contain ePHI. These MUST be encrypted at the application layer before storage in BigQuery.
+
+```javascript
+const crypto = require('crypto');
+
+function encryptValue(plaintext, key) {
+  if (!plaintext) return null;
+  const iv = crypto.randomBytes(16);
+  const cipher = crypto.createCipheriv('aes-256-gcm', Buffer.from(key, 'hex'), iv);
+  let encrypted = cipher.update(plaintext, 'utf8', 'hex');
+  encrypted += cipher.final('hex');
+  const authTag = cipher.getAuthTag().toString('hex');
+  return `${iv.toString('hex')}:${authTag}:${encrypted}`;
+}
+
+function decryptValue(encryptedText, key) {
+  if (!encryptedText) return null;
+  const [ivHex, authTagHex, encrypted] = encryptedText.split(':');
+  const decipher = crypto.createDecipheriv('aes-256-gcm', Buffer.from(key, 'hex'), Buffer.from(ivHex, 'hex'));
+  decipher.setAuthTag(Buffer.from(authTagHex, 'hex'));
+  let decrypted = decipher.update(encrypted, 'hex', 'utf8');
+  decrypted += decipher.final('utf8');
+  return decrypted;
+}
+```
+
+---
+
+## Encryption at Rest
+
+### BigQuery Default Encryption
+
+- **Algorithm**: AES-256
+- **Key Management**: Google-managed keys (default) or Customer-Managed Encryption Keys (CMEK)
+- **Recommendation**: Use CMEK for healthcare clients via Cloud KMS
+
+### CMEK Configuration
+
+```sql
+-- Create dataset with CMEK
+CREATE SCHEMA `project.hipaa_audit_dataset`
+OPTIONS (
+  default_kms_key_name = 'projects/PROJECT/locations/LOCATION/keyRings/RING/cryptoKeys/KEY'
+);
+```
+
+### Key Rotation
+
+- Google-managed keys: Automatic rotation
+- CMEK: Configure 90-day automatic rotation in Cloud KMS
+- Application-layer keys: Rotate annually, re-encrypt on rotation
+
+---
+
+## Retention Policy Configuration
+
+### BigQuery Table-Level Retention
+
+```sql
+-- Set 6-year + 90-day retention (2,281 days)
+ALTER TABLE `project.dataset.hipaa_audit_logs`
+SET OPTIONS (
+  partition_expiration_days = 2281
+);
+```
+
+### Dataset-Level Default Retention
+
+```sql
+ALTER SCHEMA `project.hipaa_audit_dataset`
+SET OPTIONS (
+  default_partition_expiration_days = 2281
+);
+```
+
+> **WARNING**: Test retention policy on a non-production dataset first. Incorrect configuration can result in premature data deletion with no recovery.
+
+---
+
+## Access Controls on Archived Data
+
+### IAM Roles
+
+| Role | Access Level | Assigned To |
+|---|---|---|
+| `bigquery.dataViewer` | Read-only queries | Compliance team |
+| `bigquery.dataEditor` | Insert new records | Archival service account |
+| `bigquery.admin` | Full control | CloudStream admin (break-glass only) |
+| `bigquery.jobUser` | Run queries | Auditors (time-limited) |
+
+### Service Account for Archival
+
+```json
+{
+  "type": "service_account",
+  "project_id": "client-hipaa-project",
+  "purpose": "HIPAA audit archival from Catalyst",
+  "roles": [
+    "roles/bigquery.dataEditor",
+    "roles/bigquery.jobUser"
+  ],
+  "restrictions": {
+    "dataset": "hipaa_audit_dataset",
+    "tables": ["hipaa_audit_logs", "archival_metadata"]
+  }
+}
+```
+
+### Access Logging
+
+Enable BigQuery Data Access audit logs:
+
+```
+Cloud Console → IAM & Admin → Audit Logs
+→ BigQuery API → Enable Data Read, Data Write
+```
+
+---
+
+## Annual Purge of Data Beyond 6 Years
+
+### Automated Purge Process
+
+> **WARNING**: Purging is IRREVERSIBLE. Verify retention calculations thoroughly before enabling automated purge.
+
+```sql
+-- Identify records eligible for purge (older than 6 years + 90 day buffer)
+SELECT COUNT(*) as records_to_purge,
+       MIN(timestamp) as oldest_record,
+       MAX(timestamp) as newest_eligible
+FROM `project.dataset.hipaa_audit_logs`
+WHERE timestamp < TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 2281 DAY);
+
+-- Execute purge (run ONLY after verification)
+DELETE FROM `project.dataset.hipaa_audit_logs`
+WHERE timestamp < TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 2281 DAY);
+```
+
+### Purge Pre-Checks
+
+1. Verify no active litigation holds on the data
+2. Confirm no pending audit requests covering the date range
+3. Get written approval from client compliance officer
+4. Take a final backup before purge (Cloud Storage, 30-day hold)
+5. Document purge action in compliance log
+
+---
+
+## Disaster Recovery for Archived Audits
+
+### Backup Strategy
+
+| Layer | Method | RPO | RTO |
+|---|---|---|---|
+| BigQuery native | Cross-region replication | 0 (synchronous) | Minutes |
+| Monthly snapshot | Export to Cloud Storage (Nearline) | 30 days | Hours |
+| Annual cold backup | Cloud Storage (Archive class) | 1 year | 24 hours |
+
+### Monthly Snapshot Export
+
+```bash
+# Export monthly snapshot to Cloud Storage
+bq extract \
+  --destination_format=AVRO \
+  --compression=SNAPPY \
+  'project:dataset.hipaa_audit_logs$20250101' \
+  'gs://client-hipaa-backups/monthly/2025-01/audit_logs_*.avro'
+```
+
+### Recovery Procedure
+
+1. Identify the gap in BigQuery data
+2. Locate the appropriate backup in Cloud Storage
+3. Load backup data into a staging table
+4. Verify record counts and checksums
+5. Insert missing records into the production table
+6. Validate completeness with date-range queries
+7. Document the recovery in the incident log
+
+---
+
+## Monitoring and Alerting
+
+### Critical Alerts (Immediate Response Required)
+
+| Alert | Condition | Action |
+|---|---|---|
+| Archival job failed | Cron execution error | Investigate and re-run within 48 hours |
+| No records archived | Zero records in monthly batch | Verify audit logging is active |
+| Record count mismatch | Creator count != BigQuery count | Investigate missing records |
+| BigQuery write errors | Insert failures | Check permissions and quotas |
+
+### Weekly Health Check Query
+
+```sql
+-- Verify monthly archival completeness
+SELECT
+  FORMAT_TIMESTAMP('%Y-%m', archive_date) as archive_month,
+  COUNT(*) as records_archived,
+  MIN(timestamp) as earliest_record,
+  MAX(timestamp) as latest_record
+FROM `project.dataset.hipaa_audit_logs`
+GROUP BY archive_month
+ORDER BY archive_month DESC
+LIMIT 13;
+```
+
+---
+
+## Cost Estimation
+
+### BigQuery Storage Costs
+
+| Storage Tier | Price | When Applied |
+|---|---|---|
+| Active storage | $0.02/GB/month | First 90 days after last modification |
+| Long-term storage | $0.01/GB/month | After 90 days unmodified |
+| Query costs | $5/TB scanned | Per query (on-demand pricing) |
+
+### Typical Healthcare Client Costs
+
+| Client Size | Monthly Records | Annual Storage | Annual Query | Total Annual |
+|---|---|---|---|---|
+| Small practice | 5,000 | ~$0.50 | ~$1.00 | ~$1.50 |
+| Mid-size clinic | 50,000 | ~$5.00 | ~$5.00 | ~$10.00 |
+| Hospital system | 500,000 | ~$50.00 | ~$25.00 | ~$75.00 |
+
+> These costs are negligible compared to HIPAA non-compliance penalties. Bill as infrastructure pass-through plus management overhead.

package/skills/compliance-patterns/hipaa/phi-handling.md

@@ -0,0 +1,52 @@
+# PHI Handling in Zoho
+
+## Identifying ePHI Fields
+Electronic Protected Health Information includes:
+- Patient names, addresses, dates (birth, admission, discharge, death)
+- Phone/fax numbers, email addresses
+- SSN, medical record numbers, health plan IDs
+- Account numbers, certificate/license numbers
+- Device identifiers, URLs, IP addresses
+- Biometric identifiers, photographs
+- Any unique identifying number/code
+
+## Creator Field Configuration
+```
+Field: Patient_Name [PHI]
+  - Encryption: ENABLED
+  - Access: Roles [Doctor, Nurse, Admin]
+  - Audit: ON (log all reads and writes)
+  - Reports: HIDDEN by default
+
+Field: Diagnosis_Code [PHI]
+  - Encryption: ENABLED
+  - Access: Roles [Doctor]
+  - Audit: ON
+  - Reports: Aggregates only
+```
+
+## Audit Logging Pattern (Deluge)
+
+> See `audit-requirements.md` for the full HIPAA_Audit_Log schema and BigQuery archival strategy.
+
+```deluge
+// Log all PHI access - fields match HIPAA_Audit_Log form schema
+auditMap = Map();
+auditMap.put("Timestamp", zoho.currenttime);
+auditMap.put("User_Email", zoho.loginuserid);
+auditMap.put("User_Role", zoho.loginuserRole);
+auditMap.put("IP_Address", zoho.ipaddress);
+auditMap.put("Action_Type", "Access");
+auditMap.put("Form_Name", "Patient_Records");
+auditMap.put("Record_ID", input.Record_ID);
+auditMap.put("Field_Name", "Patient_Name,Diagnosis_Code");
+
+zoho.creator.createRecord("app", "HIPAA_Audit_Log", auditMap);
+```
+
+## Data Archival Strategy
+Creator retains audit data for only 1 year. Implement:
+1. Monthly export of audit logs to GCS (Cloud Storage)
+2. BigQuery table for long-term audit retention (6+ years for HIPAA)
+3. Scheduled Catalyst Cron function for automated export
+4. Verify exports before Creator auto-deletion window