Abridge Security Basics

---
name: abridge-security-basics
description: 'Apply HIPAA-compliant security practices for Abridge clinical AI integrations.

  Use when securing PHI in transit/at rest, configuring access controls,

  implementing audit logging, or preparing for HIPAA security audits.

  Trigger: "abridge security", "abridge HIPAA", "abridge PHI protection",

  "abridge access control", "abridge audit logging".

  '
allowed-tools: Read, Write, Edit, Bash(openssl:*), Grep
version: 1.4.0
license: MIT
author: Jeremy Longshore <jeremy@intentsolutions.io>
tags:
- saas
- healthcare
- ai
- abridge
- security
- hipaa
compatibility: Designed for Claude Code
---
# Abridge Security Basics

## Overview

HIPAA-compliant security configuration for Abridge clinical AI integrations. Abridge handles PHI (Protected Health Information) — security is not optional. This skill covers encryption, access control, audit logging, and BAA requirements.

## HIPAA Security Checklist

| Requirement | Implementation | Status |
|-------------|---------------|--------|
| Encryption in transit | TLS 1.3 enforced | Required |
| Encryption at rest | AES-256 for stored PHI | Required |
| Access control | Role-based with MFA | Required |
| Audit logging | All PHI access logged | Required |
| BAA signed | Business Associate Agreement | Required |
| Minimum necessary | Only access needed PHI | Required |
| Breach notification | 60-day notification plan | Required |

## Prerequisites

- A signed BAA, documented data-flow inventory, and organization-approved
  retention and incident-response policies.
- A non-production environment with synthetic fixtures for security testing;
  never use real PHI to exercise logging, authorization, or TLS controls.
- Named owners for security, privacy, clinical operations, and the EHR
  integration who can approve or block a release.

## Instructions

### Step 1: Enforce TLS and Certificate Pinning

```typescript
// src/security/tls-config.ts
import https from 'https';
import axios from 'axios';

const abridgeHttpsAgent = new https.Agent({
  minVersion: 'TLSv1.3',           // Enforce TLS 1.3 minimum
  rejectUnauthorized: true,         // Never disable cert validation
  // Optional: certificate pinning for Abridge API
  // ca: fs.readFileSync('./certs/abridge-ca.pem'),
});

const secureClient = axios.create({
  baseURL: process.env.ABRIDGE_BASE_URL,
  httpsAgent: abridgeHttpsAgent,
  headers: {
    'Authorization': `Bearer ${process.env.ABRIDGE_CLIENT_SECRET}`,
    'X-Org-Id': process.env.ABRIDGE_ORG_ID!,
    'Strict-Transport-Security': 'max-age=31536000; includeSubDomains',
  },
});
```

### Step 2: PHI-Safe Audit Logger

```typescript
// src/security/audit-logger.ts
interface AuditEntry {
  timestamp: string;
  action: 'create' | 'read' | 'update' | 'delete' | 'access';
  resource_type: 'session' | 'note' | 'transcript' | 'patient_summary';
  resource_id: string;           // Session/note ID (not PHI)
  actor: string;                 // Provider NPI or system ID
  ip_address: string;
  success: boolean;
  // NEVER include: patient name, DOB, SSN, MRN, diagnosis, note content
}

class HipaaAuditLogger {
  private entries: AuditEntry[] = [];

  log(entry: Omit<AuditEntry, 'timestamp'>): void {
    const fullEntry: AuditEntry = {
      ...entry,
      timestamp: new Date().toISOString(),
    };

    // Validate no PHI leaked into audit log
    const serialized = JSON.stringify(fullEntry);
    if (this.containsPhi(serialized)) {
      console.error('CRITICAL: PHI detected in audit entry — entry blocked');
      return;
    }

    this.entries.push(fullEntry);
    // In production: write to HIPAA-compliant log store (CloudWatch, Splunk, etc.)
    console.log(`AUDIT: ${JSON.stringify(fullEntry)}`);
  }

  private containsPhi(text: string): boolean {
    const phiPatterns = [
      /\b\d{3}-\d{2}-\d{4}\b/,        // SSN
      /\b[A-Z]\d{8}\b/,               // MRN pattern
      /\b\d{1,2}\/\d{1,2}\/\d{4}\b/,  // DOB
    ];
    return phiPatterns.some(p => p.test(text));
  }

  getRetentionPolicy(): { minYears: number; note: string } {
    return {
      minYears: 6,
      note: 'HIPAA requires audit logs retained for minimum 6 years',
    };
  }
}

export { HipaaAuditLogger, AuditEntry };
```

### Step 3: Role-Based Access Control

```typescript
// src/security/rbac.ts
type AbridgeRole = 'clinician' | 'nurse' | 'admin' | 'billing' | 'integration_service';

interface AbridgePermissions {
  canCreateSession: boolean;
  canViewNotes: boolean;
  canViewPatientSummary: boolean;
  canExportData: boolean;
  canManageProviders: boolean;
  canAccessBilling: boolean;
}

const ROLE_PERMISSIONS: Record<AbridgeRole, AbridgePermissions> = {
  clinician: {
    canCreateSession: true, canViewNotes: true, canViewPatientSummary: true,
    canExportData: false, canManageProviders: false, canAccessBilling: false,
  },
  nurse: {
    canCreateSession: true, canViewNotes: true, canViewPatientSummary: true,
    canExportData: false, canManageProviders: false, canAccessBilling: false,
  },
  admin: {
    canCreateSession: false, canViewNotes: false, canViewPatientSummary: false,
    canExportData: true, canManageProviders: true, canAccessBilling: true,
  },
  billing: {
    canCreateSession: false, canViewNotes: false, canViewPatientSummary: false,
    canExportData: false, canManageProviders: false, canAccessBilling: true,
  },
  integration_service: {
    canCreateSession: true, canViewNotes: true, canViewPatientSummary: false,
    canExportData: false, canManageProviders: false, canAccessBilling: false,
  },
};

function checkPermission(role: AbridgeRole, action: keyof AbridgePermissions): boolean {
  return ROLE_PERMISSIONS[role]?.[action] ?? false;
}
```

### Step 4: Secrets Management

```typescript
// src/security/secrets.ts
// Never hardcode credentials — use environment or secret manager

async function loadAbridgeSecrets(): Promise<Record<string, string>> {
  // Option 1: Environment variables (minimum viable)
  // Option 2: AWS Secrets Manager / GCP Secret Manager (recommended)
  // Option 3: HashiCorp Vault (enterprise)

  // Example: GCP Secret Manager
  const { SecretManagerServiceClient } = await import('@google-cloud/secret-manager');
  const client = new SecretManagerServiceClient();

  const secrets: Record<string, string> = {};
  const secretNames = ['abridge-client-secret', 'abridge-org-id', 'epic-client-secret'];

  for (const name of secretNames) {
    const [version] = await client.accessSecretVersion({
      name: `projects/${process.env.GCP_PROJECT}/secrets/${name}/versions/latest`,
    });
    secrets[name] = version.payload?.data?.toString() || '';
  }

  return secrets;
}
```

## Output

- TLS 1.3 enforcement with optional cert pinning
- HIPAA-compliant audit logger with PHI leak detection
- Role-based access control matrix
- Secrets loaded from cloud secret manager

## Examples

In a sandbox release check, call a protected endpoint as the
`integration_service` role using a secret-manager-supplied credential and
create an audit entry containing a fictional session ID. Verify TLS policy,
the authorization outcome, and that the log contains no patient name, note
content, MRN, or token. Then attempt an unauthorized export and confirm the
RBAC layer refuses it with a redacted audit record. If PHI detection fires or
an unauthorized request succeeds, halt deployment, revoke the affected access
path if necessary, and investigate before processing any production data.

## Error Handling

| Issue | Cause | Solution |
|-------|-------|----------|
| TLS handshake failure | Server doesn't support TLS 1.3 | Verify Abridge endpoint; check proxy |
| PHI in logs | Audit logger bypass | Add PHI detection to all log paths |
| Permission denied | Wrong role | Check RBAC matrix for required role |

## Resources

- [HIPAA Security Rule](https://www.hhs.gov/hipaa/for-professionals/security/)
- Abridge Security
- [SMART on FHIR Security](https://hl7.org/fhir/smart-app-launch/scopes-and-launch-context.html)

## Next Steps

For production deployment checklist, see `abridge-prod-checklist`.