HIPAA-Compliant E-Signature API Architecture: BAAs & Encryption (2026)

import express, { Request, Response } from 'express';
import crypto from 'crypto';
import fetch from 'node-fetch';

const app = express();

// Secure configuration loaded from environment
const SIGNBEE_API_KEY = process.env.SIGNBEE_API_KEY || '';
const SIGNBEE_WEBHOOK_SECRET = process.env.SIGNBEE_WEBHOOK_SECRET || '';
const METADATA_SALT = process.env.METADATA_SALT || '';

if (!SIGNBEE_API_KEY || !SIGNBEE_WEBHOOK_SECRET || !METADATA_SALT) {
  throw new Error('Critical configuration missing from environment variables');
}

// Preserve raw body buffer for accurate HMAC webhook signature verification
app.use(express.json({
  verify: (req: any, res, buf) => {
    req.rawBody = buf;
  }
}));

/**
 * Computes a deterministic, salted HMAC-SHA-256 hash from internal patient ID.
 * Prevents exposing PHI (names, MRNs, DOBs) in third-party API logs or dashboards.
 */
function generateObfuscatedKey(patientId: string): string {
  return crypto
    .createHmac('sha256', METADATA_SALT)
    .update(patientId)
    .digest('hex');
}

// 1. Patient Intake & E-Signature Dispatch Endpoint
app.post('/api/healthcare/intake', async (req: Request, res: Response): Promise<void> => {
  try {
    const { patientId, name, email, consentType } = req.body;

    if (!patientId || !name || !email) {
      res.status(400).json({ error: 'Missing required patient intake parameters' });
      return;
    }

    // Input sanitization against script injection
    const sanitizedName = String(name).replace(/<[^>]*>/g, '').trim();
    const sanitizedEmail = String(email).trim().toLowerCase();

    // Generate zero-PHI metadata reference key
    const obfuscatedRefKey = generateObfuscatedKey(patientId);

    // Save internal patient record to encrypted DB (omitted for brevity)
    // await db.patients.create({ data: { id: patientId, obfuscatedRefKey, status: 'PENDING' } });

    // Dynamic Markdown Contract Generation
    const consentMarkdown = `# Medical Treatment Informed Consent Form
    
**Patient Name:** ${sanitizedName}  
**Date:** ${new Date().toISOString().split('T')[0]}  
**Consent Scope:** ${consentType || 'General Clinical Treatment & Telehealth'}

I hereby authorize clinical staff to perform necessary diagnostic tests, medical treatments, and electronic health record updates in accordance with the HIPAA Privacy Rule.

---
*By signing below, you electronically consent to treatment and acknowledge receipt of Privacy Practices.*
`;

    // Dispatch request to Signbee API passing ZERO cleartext PHI in custom metadata
    const response = await fetch('https://api.signb.ee/v1/documents', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${SIGNBEE_API_KEY}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        title: `Patient Informed Consent - Ref ${obfuscatedRefKey.substring(0, 8)}`,
        content: consentMarkdown,
        signers: [{ name: sanitizedName, email: sanitizedEmail }],
        metadata: {
          // PHI-SAFE: Pass ONLY the obfuscated key. Never pass SSN, MRN, or DOB!
          reference_key: obfuscatedRefKey,
          environment: 'production',
        },
      }),
    });

    const data = await response.json();
    if (!response.ok) {
      res.status(response.status).json({ error: 'Failed to create signature request', details: data });
      return;
    }

    res.status(200).json({
      success: true,
      documentId: data.id,
      signingUrl: data.signing_url,
      obfuscatedRefKey,
    });
  } catch (error: any) {
    res.status(500).json({ error: 'Internal server error', message: error.message });
  }
});

// 2. Webhook Callback Endpoint with Cryptographic Signature Validation
app.post('/api/webhooks/signbee', async (req: any, res: Response): Promise<void> => {
  try {
    const signatureHeader = req.headers['x-signbee-signature'] as string;
    if (!signatureHeader || !req.rawBody) {
      res.status(401).json({ error: 'Missing webhook signature or raw body' });
      return;
    }

    // Calculate expected HMAC-SHA-256 signature using raw body buffer
    const computedSignature = crypto
      .createHmac('sha256', SIGNBEE_WEBHOOK_SECRET)
      .update(req.rawBody)
      .digest('hex');

    // Constant-time string comparison to defend against timing attacks
    const isValid = crypto.timingSafeEqual(
      Buffer.from(signatureHeader, 'hex'),
      Buffer.from(computedSignature, 'hex')
    );

    if (!isValid) {
      res.status(403).json({ error: 'Invalid HMAC signature check' });
      return;
    }

    const payload = req.body;
    if (payload.event === 'document.completed') {
      const referenceKey = payload.data?.metadata?.reference_key;
      const auditHash = payload.data?.audit_trail?.sha256_fingerprint;

      // Update local database status PENDING -> SIGNED using referenceKey
      console.log(`[HIPAA Webhook] Successfully processed document signature!`);
      console.log(`Ref Key: ${referenceKey} | SHA-256 Audit Fingerprint: ${auditHash}`);

      // await db.patients.update({ where: { obfuscatedRefKey: referenceKey }, data: { status: 'SIGNED', auditHash } });
    }

    res.status(200).json({ received: true });
  } catch (err: any) {
    res.status(500).json({ error: 'Webhook handler failure', message: err.message });
  }
});

app.listen(4000, () => console.log('HIPAA E-Signature API server listening on port 4000'));

import os
import hmac
import hashlib
import httpx
from datetime import datetime
from fastapi import FastAPI, Request, HTTPException, Header, status
from pydantic import BaseModel, EmailStr

app = FastAPI(title="HIPAA E-Signature Service")

SIGNBEE_API_KEY = os.getenv("SIGNBEE_API_KEY", "")
SIGNBEE_WEBHOOK_SECRET = os.getenv("SIGNBEE_WEBHOOK_SECRET", "")
METADATA_SALT = os.getenv("METADATA_SALT", "")

class PatientIntakeRequest(BaseModel):
    patient_id: str
    name: str
    email: EmailStr
    consent_type: str = "Telehealth & Clinical Care"

def compute_obfuscated_key(patient_id: str) -> str:
    """Generates a salted HMAC-SHA256 hash to protect patient identity in API logs."""
    return hmac.new(
        METADATA_SALT.encode('utf-8'),
        patient_id.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()

@app.post("/api/v1/patient-intake")
async def create_patient_consent(payload: PatientIntakeRequest):
    obfuscated_key = compute_obfuscated_key(payload.patient_id)
    
    consent_markdown = f"""# Telehealth Services Informed Consent
    
**Patient:** {payload.name}  
**Date:** {datetime.utcnow().strftime('%Y-%m-%d')}  
**Scope:** {payload.consent_type}

I hereby consent to receive medical consultation and telehealth services. I acknowledge receipt of HIPAA Notice of Privacy Practices.
"""

    # Zero-PHI Payload: pass ONLY the obfuscated_key in metadata dictionary
    signbee_payload = {
        "title": f"Consent Agreement - Ref {obfuscated_key[:8]}",
        "content": consent_markdown,
        "signers": [{"name": payload.name, "email": payload.email}],
        "metadata": {
            "reference_key": obfuscated_key,
            "system_source": "fastapi-ehr"
        }
    }

    async with httpx.AsyncClient() as client:
        response = await client.post(
            "https://api.signb.ee/v1/documents",
            headers={
                "Authorization": f"Bearer {SIGNBEE_API_KEY}",
                "Content-Type": "application/json"
            },
            json=signbee_payload,
            timeout=15.0
        )
        
    if response.status_code != 200:
        raise HTTPException(
            status_code=response.status_code,
            detail=f"Signbee API error: {response.text}"
        )
        
    res_data = response.json()
    return {
        "status": "success",
        "document_id": res_data.get("id"),
        "signing_url": res_data.get("signing_url"),
        "obfuscated_key": obfuscated_key
    }

@app.post("/api/v1/webhooks/signbee")
async def process_signbee_webhook(request: Request, x_signbee_signature: str = Header(None)):
    if not x_signbee_signature:
        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Missing signature header")
        
    raw_body = await request.body()
    
    # Calculate HMAC-SHA256 digest over raw byte payload
    computed_digest = hmac.new(
        SIGNBEE_WEBHOOK_SECRET.encode('utf-8'),
        raw_body,
        hashlib.sha256
    ).hexdigest()
    
    # Constant-time comparison to eliminate timing side-channel attacks
    if not hmac.compare_digest(x_signbee_signature.lower(), computed_digest.lower()):
        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Invalid HMAC signature")
        
    event_data = await request.json()
    if event_data.get("event") == "document.completed":
        ref_key = event_data.get("data", {}).get("metadata", {}).get("reference_key")
        audit_sha = event_data.get("data", {}).get("audit_trail", {}).get("sha256_fingerprint")
        
        # Perform database update: PENDING -> SIGNED for the patient matching ref_key
        print(f"[FASTAPI HIPAA WEBHOOK] Verified signature for Ref: {ref_key} | SHA: {audit_sha}")
        
    return {"status": "accepted"}