OpenEvidence Security Basics Skill

OpenEvidence Security Basics

Overview

OpenEvidence provides AI-powered clinical evidence synthesis that processes protected health information (PHI), patient queries, and medical literature references. Integrations must comply with HIPAA requirements for PHI handling, audit logging, and access controls. A breach exposes patient health questions, clinical recommendations, and potentially identifiable medical conditions. Every API interaction must be treated as a HIPAA-regulated transaction.

API Key Management

function createOpenEvidenceClient(): { apiKey: string; baseUrl: string } {
  const apiKey = process.env.OPENEVIDENCE_API_KEY;
  if (!apiKey) {
    throw new Error("Missing OPENEVIDENCE_API_KEY — store in HIPAA-compliant secrets manager");
  }
  // PHI-adjacent access — enforce audit logging on every request
  console.log("OpenEvidence client initialized (key suffix:", apiKey.slice(-4), ")");
  return { apiKey, baseUrl: "https://api.openevidence.com/v1" };
}

Webhook Signature Verification

import crypto from "crypto";
import { Request, Response, NextFunction } from "express";

function verifyOpenEvidenceWebhook(req: Request, res: Response, next: NextFunction): void {
  const signature = req.headers["x-openevidence-signature"] as string;
  const secret = process.env.OPENEVIDENCE_WEBHOOK_SECRET!;
  const expected = crypto.createHmac("sha256", secret).update(req.body).digest("hex");
  if (!signature || !crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
    res.status(401).send("Invalid signature");
    return;
  }
  next();
}

Input Validation

import { z } from "zod";

const ClinicalQuerySchema = z.object({
  query_id: z.string().uuid(),
  clinical_question: z.string().min(10).max(2000),
  specialty: z.enum(["oncology", "cardiology", "neurology", "general", "pediatrics", "emergency"]).optional(),
  evidence_level: z.enum(["systematic_review", "rct", "cohort", "case_report", "expert_opinion"]).optional(),
  include_guidelines: z.boolean().default(true),
});

function validateClinicalQuery(data: unknown) {
  return ClinicalQuerySchema.parse(data);
}

Data Protection

const OPENEVIDENCE_PHI_FIELDS = ["patient_name", "date_of_birth", "mrn", "clinical_question", "diagnosis", "medication_list"];

function redactOpenEvidenceLog(record: Record<string, unknown>): Record<string, unknown> {
  const redacted = { ...record };
  for (const field of OPENEVIDENCE_PHI_FIELDS) {
    if (field in redacted) redacted[field] = "[REDACTED_PHI]";
  }
  return redacted;
}

Security Checklist

[ ] API keys stored in HIPAA-compliant secrets manager
[ ] Separate keys per environment (dev/staging/prod)
[ ] Key rotation scheduled quarterly
[ ] HIPAA audit logging enabled on every API call
[ ] PHI never logged in application logs (field-level redaction)
[ ] BAA (Business Associate Agreement) on file with OpenEvidence
[ ] Clinical query data encrypted at rest and in transit (TLS 1.2+)
[ ] Access controls enforce minimum necessary PHI exposure

Error Handling

| Vulnerability | Risk | Mitigation | |---|---|---| | Leaked API key | Unauthorized access to clinical evidence queries | HIPAA-compliant secrets manager + rotation | | PHI in application logs | HIPAA violation and patient data exposure | Mandatory PHI field redaction | | Missing BAA | Regulatory non-compliance penalty | BAA signed before integration goes live | | Unencrypted clinical data | PHI breach during transit or storage | TLS 1.2+ in transit, AES-256 at rest | | Missing audit trail | HIPAA audit failure | Immutable audit logs for all API interactions |

Resources

Next Steps

See openevidence-prod-checklist.

Agent Skills: OpenEvidence Security Basics

Install this agent skill to your local

Skill Files