Security & Compliance Guide

Security Architecture Overview

The Cascade Protocol follows a local-first, zero-network-call architecture. All data processing occurs on the user's machine. There are no backend services, cloud databases, or remote APIs involved in core protocol operations.

Design Principles

• Local-only processing. The CLI, MCP server, and Swift SDK operate entirely on the local filesystem. No data leaves the device during normal operation.
• Open source. All repositories are public, enabling full code audit. No proprietary dependencies are required for core functionality.
• No telemetry. There are no analytics, crash reporting, phone-home behaviors, or tracking of any kind in the protocol tools or SDK.
• Minimal attack surface. The protocol defines data structure and serialization, not networking. There is no HTTP server, no database daemon, and no listening socket in default operation.

Data Flow Diagram

PHI Handling

Protected Health Information (PHI) under HIPAA includes any individually identifiable health information. The Cascade Protocol stores PHI categories locally in the user's Pod as RDF/Turtle files, organized by data type.

PHI Categories

The protocol defines the following PHI-relevant data categories, each stored in its own directory within the Pod:

Consent Model

The protocol supports category-based consent filtering. When sharing data (e.g., via the MCP server for AI agent access or via export), consumers can specify which PHI categories to include or exclude. Only authorized categories are surfaced.

The consent configuration is defined per Pod using a consent.json file in the Pod root. This allows fine-grained control over which data categories are accessible to external consumers.

// Example consent.json (planned implementation)
{
  "version": "1.0",
  "categories": {
    "medications": { "share": true },
    "conditions": { "share": true },
    "allergies": { "share": true },
    "lab_results": { "share": false },
    "vital_signs": { "share": true },
    "immunizations": { "share": true },
    "demographics": { "share": false }
  },
  "defaultPolicy": "deny"
}

Data Minimization

The protocol follows a share-only-what-is-authorized principle. Export and query operations accept a list of requested data types, and only matching records are returned. There is no "select all" behavior in the MCP server — the agent must explicitly request each data type.

Provenance Model

Every record in the Cascade Protocol carries provenance metadata based on the W3C PROV-O ontology. Provenance distinguishes how data was created and by whom, which is critical for clinical decision-making and regulatory compliance.

Provenance Types

Provenance Attachment

Provenance is attached to every record as RDF triples using the cascade: and prov: namespaces. The following Turtle example demonstrates how provenance metadata is serialized:

@prefix cascade: <https://ns.cascadeprotocol.org/core/v1#> .
@prefix prov: <http://www.w3.org/ns/prov#> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .

<urn:uuid:a1b2c3d4-e5f6-7890-abcd-ef1234567890>
    a clinical:MedicationRecord ;
    cascade:dataProvenance cascade:ClinicalGenerated ;
    cascade:schemaVersion "1.5" ;
    prov:wasAttributedTo <https://id.cascadeprotocol.org/users/patient-123> ;
    prov:generatedAtTime "2026-01-15T10:30:00Z"^^xsd:dateTime ;
    clinical:medicationName "Metoprolol" ;
    clinical:dose "25 mg" ;
    clinical:frequency "twice daily" .

Verifying Provenance

Provenance can be verified by querying the Pod's Turtle files for cascade:dataProvenance triples. The cascade_pod_query MCP tool and the CLI cascade pod read command both return provenance metadata with every record. To audit provenance across all records:

# Query all records and inspect provenance fields
cascade pod read --path ./my-pod

# Or use the MCP server programmatically via cascade_pod_query
# The response includes dataProvenance for each record

Audit Logging

All operations performed through the MCP server are logged to an append-only audit log stored within the Pod at provenance/audit-log.ttl. This log is written in RDF/Turtle format using Cascade Protocol vocabulary.

Log Format

Each audit entry records the following fields:

Example Audit Entry

The following is a real example of the Turtle output written by the audit logger (from cli/src/lib/mcp/audit.ts):

@prefix cascade: <https://ns.cascadeprotocol.org/core/v1#> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
@prefix prov: <http://www.w3.org/ns/prov#> .

# Cascade Protocol Agent Audit Log
# Generated by cascade serve --mcp

<#audit-3f8a91c2-7b4d-4e6f-9a1c-2d3e4f5a6b7c> a cascade:AuditEntry ;
    cascade:timestamp "2026-02-15T14:30:22.451Z"^^xsd:dateTime ;
    cascade:operation "read" ;
    cascade:dataTypes ("medications" "conditions") ;
    cascade:agentId "claude-desktop-v1" ;
    cascade:recordsAccessed 12 .

<#audit-8c1d2e3f-4a5b-6c7d-8e9f-0a1b2c3d4e5f> a cascade:AuditEntry ;
    cascade:timestamp "2026-02-15T14:31:05.789Z"^^xsd:dateTime ;
    cascade:operation "write" ;
    cascade:dataTypes ("medications") ;
    cascade:agentId "claude-desktop-v1" ;
    cascade:recordsAccessed 1 .

Reviewing Audit Logs

Audit logs are standard Turtle files and can be read with any RDF tool or text editor.

# View the raw audit log
cat ./my-pod/provenance/audit-log.ttl

# Count total operations
grep -c "a cascade:AuditEntry" ./my-pod/provenance/audit-log.ttl

# Filter by agent
grep -A5 "agentId" ./my-pod/provenance/audit-log.ttl

AI Agent Access

The Cascade Protocol exposes health data to AI agents via the Model Context Protocol (MCP). The MCP server (cascade serve --mcp) enforces several security controls.

Path Containment

All file operations are validated against a boundary directory to prevent path traversal attacks. The implementation resolves both the target path and the Pod boundary to absolute paths, then verifies containment:

// From cli/src/lib/mcp/tools.ts
function validatePathBoundary(
  resolvedPath: string,
  boundary: string
): boolean {
  const normalizedPath = path.resolve(resolvedPath);
  const normalizedBoundary = path.resolve(boundary);
  return (
    normalizedPath.startsWith(normalizedBoundary + path.sep) ||
    normalizedPath === normalizedBoundary
  );
}

This check runs on every write operation. If the resolved target file path falls outside the Pod directory, the operation is rejected with an error.

Automatic AIGenerated Provenance

All data written through the MCP server is automatically tagged with AIGenerated provenance. This is enforced at the server level — the agent cannot override it. The provenance record includes:

• Provenance type: Always AIGenerated for MCP-written data
• Agent ID: Identifier of the agent (e.g., "claude-desktop-v1"), defaults to "unknown-agent" if not provided
• Timestamp: ISO 8601 datetime of the write operation
• Reason: Optional free-text explanation for why the record was created
• Confidence level: A float between 0.0 and 1.0 indicating the agent's confidence in the data
• Source records: URIs of existing records used to derive the new data

// Provenance metadata returned for every MCP write operation
{
  "type": "AIGenerated",
  "agentId": "claude-desktop-v1",
  "timestamp": "2026-02-15T14:31:05.789Z",
  "reason": "Summarized medication list for visit prep",
  "confidence": 0.92
}

Audit Trail

Every MCP tool invocation — read, write, query, validate, or convert — is logged to the Pod's audit log. See Audit Logging above for format details.

Encryption

Encryption responsibilities are deliberately separated across layers. The protocol itself defines data structure, not encryption — this is an intentional design decision to avoid coupling serialization with security infrastructure.

Protocol Layer (Vocabulary & Serialization)

Application SDK Layer (cascade-sdk-swift)

Infrastructure Layer

Regulatory Considerations

HIPAA (Health Insurance Portability and Accountability Act)

What Cascade helps with

What Cascade does NOT help with

GDPR (General Data Protection Regulation)

What Cascade helps with

21st Century Cures Act

Threat Model

Threats Cascade Mitigates

Threats Cascade Does NOT Mitigate

Open Source Audit

All Cascade Protocol repositories are open source and available for independent audit. No proprietary code or closed-source dependencies are required for core protocol functionality.

Repositories

Verifying No Telemetry

The absence of telemetry, analytics, or phone-home behavior can be verified by searching the codebase for network-related code. The following commands should return no results for core protocol functionality:

# Search for HTTP/network calls in the CLI
grep -r "fetch\|axios\|http\.\|https\.\|XMLHttpRequest\|net\.connect" \
  --include="*.ts" --include="*.js" \
  cli/src/

# Search for analytics or tracking
grep -ri "analytics\|telemetry\|tracking\|phone.home\|beacon" \
  --include="*.ts" --include="*.js" \
  cli/src/

# Search for network calls in the Swift SDK
grep -r "URLSession\|URLRequest\|Alamofire\|Network\.framework" \
  --include="*.swift" \
  Sources/

Dependency Audit

The protocol's runtime dependencies and their purposes are documented below. All are open source.

CLI (TypeScript / Node.js)

Swift SDK

How to Audit

1. Clone the repositories and review the source code directly. All code paths are auditable.
2. Check dependencies with npm ls --production (CLI) or review Package.swift (SDK) for the full dependency tree.
3. Run under network monitoring to confirm no outbound connections during normal operation.
4. Review the audit log after any agent interaction to verify all operations were properly recorded.