From 281732e0026e96c1e2f5a4cd3eb3b4e984486f26 Mon Sep 17 00:00:00 2001 From: Bradley Gauthier <2234748+bradleygauthier@users.noreply.github.com> Date: Sun, 8 Mar 2026 16:48:52 -0500 Subject: [PATCH] Expand compliance into per-framework mappings Replace the single docs/compliance.md with a docs/compliance/ directory containing individual mapping documents for 11 regulatory frameworks (NIST SP 800-53, NIST AI RMF, EU AI Act, SOC 2, ISO 27001, HIPAA, GDPR, PCI DSS, FedRAMP, FINRA, CMMC). Update README with compliance summary table, update cross-references in docs, and add parametrized tests to verify all framework files exist. --- README.md | 26 ++- docs/README.md | 2 +- docs/architecture.md | 2 +- docs/compliance.md | 203 ------------------ docs/compliance/README.md | 63 ++++++ docs/compliance/cmmc.md | 45 ++++ docs/compliance/eu-ai-act.md | 40 ++++ docs/compliance/fedramp.md | 63 ++++++ docs/compliance/finra.md | 44 ++++ docs/compliance/gdpr.md | 58 +++++ docs/compliance/hipaa.md | 37 ++++ docs/compliance/iso27001.md | 17 ++ docs/compliance/nist-ai-rmf.md | 49 +++++ docs/compliance/nist-sp-800-53.md | 36 ++++ docs/compliance/pci-dss.md | 36 ++++ docs/compliance/soc2.md | 17 ++ docs/security.md | 2 +- docs/why-capsules.md | 2 +- .../python/tests/test_protocol_structure.py | 27 ++- 19 files changed, 559 insertions(+), 210 deletions(-) delete mode 100644 docs/compliance.md create mode 100644 docs/compliance/README.md create mode 100644 docs/compliance/cmmc.md create mode 100644 docs/compliance/eu-ai-act.md create mode 100644 docs/compliance/fedramp.md create mode 100644 docs/compliance/finra.md create mode 100644 docs/compliance/gdpr.md create mode 100644 docs/compliance/hipaa.md create mode 100644 docs/compliance/iso27001.md create mode 100644 docs/compliance/nist-ai-rmf.md create mode 100644 docs/compliance/nist-sp-800-53.md create mode 100644 docs/compliance/pci-dss.md create mode 100644 docs/compliance/soc2.md diff --git a/README.md b/README.md index 8c395ce..d585d24 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ Every AI action produces a Capsule — a tamper-evident, content-addressable rec [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) [![CPS](https://img.shields.io/badge/CPS-v1.0-orange.svg)](./spec/) -[![Conformance](https://img.shields.io/badge/Conformance-16_vectors-brightgreen.svg)](./conformance/) +[![Conformance](https://img.shields.io/badge/Conformance-16_vectors-ff69b4.svg)](./conformance/) [![FIPS](https://img.shields.io/badge/Crypto-FIPS_202%20·%20186--5%20·%20204-purple.svg)](#cryptographic-seal) [![Coverage](https://img.shields.io/badge/Coverage-100%25-brightgreen.svg)](./reference/python/) @@ -229,13 +229,35 @@ See the [TypeScript reference documentation](./reference/typescript/) for the fu --- +## Compliance + +Capsule maps to 11 regulatory frameworks at the protocol level. Each mapping documents which controls the protocol satisfies and which require complementary application-level controls. + +| Framework | Controls | Focus | +|---|---|---| +| [NIST SP 800-53](./docs/compliance/nist-sp-800-53.md) | AU-2 through AU-12, SC-13, SC-28, SI-7 | Audit, integrity, crypto | +| [NIST AI RMF](./docs/compliance/nist-ai-rmf.md) | GOVERN, MAP, MEASURE, MANAGE | AI risk management | +| [EU AI Act](./docs/compliance/eu-ai-act.md) | Articles 12, 13, 14 | Record-keeping, transparency, oversight | +| [SOC 2](./docs/compliance/soc2.md) | CC6.1, CC7.2, CC7.3, CC7.4, CC8.1 | Trust Services Criteria | +| [ISO 27001](./docs/compliance/iso27001.md) | A.8.15 through A.8.25 | Annex A controls | +| [HIPAA](./docs/compliance/hipaa.md) | §164.308, §164.312 | Security Rule safeguards | +| [GDPR](./docs/compliance/gdpr.md) | Articles 5, 25, 30, 32, 35 | Data protection | +| [PCI DSS](./docs/compliance/pci-dss.md) | Req 10, 11.5, 11.6 | Logging, change detection | +| [FedRAMP](./docs/compliance/fedramp.md) | AU-9(3), AU-10, SI-7, CM-3 | Federal cloud | +| [FINRA](./docs/compliance/finra.md) | SEC 17a-4, REC-2, Rule 3110 | Financial recordkeeping | +| [CMMC](./docs/compliance/cmmc.md) | AU.L2-3.3.x, SC.L2-3.13.x | DoD CUI protection | + +See the [compliance overview](./docs/compliance/) for FIPS algorithm details and scope. + +--- + ## Documentation | Document | Audience | |---|---| | [Architecture](./docs/architecture.md) | Developers, Auditors | | [Security Evaluation](./docs/security.md) | CISOs, Security Teams | -| [Compliance Mapping](./docs/compliance.md) | Regulators, GRC | +| [Compliance Mapping](./docs/compliance/) | Regulators, GRC | | [Why Capsules](./docs/why-capsules.md) | Decision-Makers, Architects | | [Implementor's Guide](./docs/implementors-guide.md) | SDK Authors | diff --git a/docs/README.md b/docs/README.md index 758c973..2b53a75 100644 --- a/docs/README.md +++ b/docs/README.md @@ -9,7 +9,7 @@ These documents explain the Capsule Protocol — why it exists, how it works, an | [Why Capsules](./why-capsules.md) | Decision-Makers, Architects | The case for cryptographic AI memory | | [Architecture](./architecture.md) | Developers, Auditors | 6-section model, sealing, hash chain | | [Security Evaluation](./security.md) | CISOs, Security Teams | Cryptographic guarantees and key management | -| [Compliance Mapping](./compliance.md) | Regulators, GRC | NIST, EU AI Act, SOC 2, ISO 27001 | +| [Compliance Mapping](./compliance/) | Regulators, GRC | NIST, EU AI Act, SOC 2, ISO 27001, HIPAA, GDPR | | [Implementor's Guide](./implementors-guide.md) | SDK Authors | How to build a conformant implementation | ## Normative Specification diff --git a/docs/architecture.md b/docs/architecture.md index 89c9eac..25f7098 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -369,7 +369,7 @@ Capsules can form parent-child hierarchies: `WORKFLOW` (parent) -> `AGENT` (chil - [Why Capsules](./why-capsules.md) — The case for cryptographic AI memory - [Security Evaluation](./security.md) — Cryptographic guarantees for CISOs -- [Compliance Mapping](./compliance.md) — Regulatory framework alignment +- [Compliance Mapping](./compliance/) — Regulatory framework alignment - [CPS Specification](../spec/) — Protocol rules for SDK authors - [Python Reference](../reference/python/) — Python API reference and quickstart diff --git a/docs/compliance.md b/docs/compliance.md deleted file mode 100644 index c2c300b..0000000 --- a/docs/compliance.md +++ /dev/null @@ -1,203 +0,0 @@ ---- -title: "Regulatory Compliance Mapping" -description: "How Capsule maps to NIST SP 800-53, NIST AI RMF, EU AI Act, SOC 2, and ISO 27001 controls." -date_modified: "2026-03-07" -classification: "Public" -ai_context: | - Compliance mapping for Capsule across major regulatory frameworks. - Covers NIST SP 800-53 (AU, SC, SI families), NIST AI RMF (GOVERN, MAP, - MEASURE, MANAGE), EU AI Act (Articles 12, 13, 14), SOC 2 Trust Services - Criteria, ISO 27001, and FIPS algorithm compliance. Each mapping identifies - the specific Capsule capability that addresses the control. ---- - -# Regulatory Compliance Mapping - -> **How Capsule maps to the frameworks your auditors care about.** - -*Capsule v1.0.0 — March 2026* -*Classification: Public* - ---- - -## FIPS Algorithm Compliance - -Before mapping to controls, the foundational question: are the cryptographic algorithms standards-compliant? - -| Algorithm | FIPS Standard | Status | Capsule Usage | -|---|---|---|---| -| SHA3-256 | FIPS 202 (SHA-3) | Published August 2015 | Content hashing for every Capsule | -| Ed25519 | FIPS 186-5 (Digital Signatures) | Published February 2023 | Required signature on every Capsule | -| ML-DSA-65 | FIPS 204 (ML-DSA) | Published August 2024 | Optional post-quantum dual signature | - -All three algorithms are NIST-standardized. No deprecated or non-standard cryptography is used. - ---- - -## NIST SP 800-53 Rev. 5 - -Security and privacy controls for information systems. Capsule addresses controls in the Audit (AU), System and Communications Protection (SC), and System and Information Integrity (SI) families. - -### Audit and Accountability (AU) - -| Control | Title | How Capsule Addresses It | -|---|---|---| -| **AU-2** | Event Logging | Every AI action produces a Capsule. The `CapsuleType` enum defines 8 event categories: agent, tool, system, kill, workflow, chat, vault, auth. | -| **AU-3** | Content of Audit Records | Each Capsule contains 6 sections: Trigger (who/what/when), Context (system state), Reasoning (why), Authority (approval), Execution (how), Outcome (result). | -| **AU-3(1)** | Additional Audit Information | `correlation_id` links related Capsules across distributed operations. `parent_id` creates hierarchical relationships. `session_id` groups conversation turns. | -| **AU-8** | Time Stamps | `trigger.timestamp` records UTC time of action initiation. `signed_at` records UTC time of cryptographic sealing. Both are timezone-aware. | -| **AU-9** | Protection of Audit Information | SHA3-256 hash + Ed25519 signature prevents undetected modification. Hash chain prevents undetected deletion or insertion. | -| **AU-10** | Non-repudiation | Ed25519 digital signatures provide non-repudiation via `signed_by` (key fingerprint). `verify_with_key()` enables third-party verification. | -| **AU-11** | Audit Record Retention | Capsules are persisted in SQLite or PostgreSQL. Retention policies are configurable at the storage layer. | -| **AU-12** | Audit Record Generation | Capsule creation is application-initiated at the moment of action. The `seal_and_store()` convenience method ensures atomic chain + seal + store. | - -### System and Communications Protection (SC) - -| Control | Title | How Capsule Addresses It | -|---|---|---| -| **SC-13** | Cryptographic Protection | SHA3-256 (FIPS 202) for integrity, Ed25519 (FIPS 186-5) for signatures, ML-DSA-65 (FIPS 204) for quantum resistance. | -| **SC-28** | Protection of Information at Rest | Sealed Capsules are integrity-protected via cryptographic signatures. Storage-level encryption is configurable at the database layer. | - -### System and Information Integrity (SI) - -| Control | Title | How Capsule Addresses It | -|---|---|---| -| **SI-7** | Software, Firmware, and Information Integrity | `chain.verify()` detects any modification, deletion, or insertion in the audit trail. | -| **SI-7(1)** | Integrity Checks | Verification can run anytime: `seal.verify(capsule)` for individual records, `chain.verify()` for the entire chain. | - ---- - -## NIST AI Risk Management Framework (AI RMF 1.0) - -The AI RMF organizes AI risk management into four functions: GOVERN, MAP, MEASURE, MANAGE. - -### GOVERN - -*Cultivate and implement a culture of AI risk management.* - -| Practice | How Capsule Supports It | -|---|---| -| Establish accountability structures | Authority section records who approved each action (`autonomous`, `human_approved`, `policy`, `escalated`) | -| Document AI decision-making processes | Reasoning section captures analysis, options considered, selected option, and confidence before execution | -| Maintain audit trails | Hash-chained Capsules provide an immutable, tamper-evident record of every AI action | - -### MAP - -*Contextualize AI risks.* - -| Practice | How Capsule Supports It | -|---|---| -| Identify AI system components | Capsule Types map to system components: AGENT, TOOL, WORKFLOW, CHAT, VAULT | -| Document operating context | Context section records agent_id, session_id, and environment state at time of action | -| Track data lineage | Execution section records tool calls with arguments, results, and errors | - -### MEASURE - -*Analyze, assess, and track AI risks.* - -| Practice | How Capsule Supports It | -|---|---| -| Quantify model confidence | `reasoning.confidence` (0.0 to 1.0) records model-reported confidence per action | -| Track performance metrics | `outcome.metrics` captures duration, token usage, cost, and custom metrics | -| Monitor for anomalies | `outcome.status` values (`success`, `failure`, `partial`, `blocked`) enable monitoring | - -### MANAGE - -*Prioritize and act on AI risks.* - -| Practice | How Capsule Supports It | -|---|---| -| Implement kill switches | `CapsuleType.KILL` records kill switch activations with authority chain | -| Enable human oversight | Authority section's `escalation_reason` and `approver` fields document human-in-the-loop decisions | -| Verify system integrity | `chain.verify()` provides one-call integrity verification of the entire audit trail | - ---- - -## EU AI Act - -The EU AI Act (Regulation 2024/1689) establishes requirements for AI systems operating in the EU. - -### Article 12: Record-keeping - -*High-risk AI systems shall be designed with logging capabilities that record events relevant to the functioning of the AI system.* - -| Requirement | How Capsule Addresses It | -|---|---| -| Automatic logging of events | Every AI action produces a Capsule (the axiom: for all actions, there exists a Capsule) | -| Traceability of results | Execution section records tool calls; Outcome section records results and side effects | -| Monitoring of operation | Chain provides temporal ordering; session_id groups related interactions | -| Identification of risks | Reasoning section captures risk assessment in `ReasoningOption.risks` | - -### Article 13: Transparency - -*High-risk AI systems shall be designed to ensure their operation is sufficiently transparent.* - -| Requirement | How Capsule Addresses It | -|---|---| -| Understandable output | Outcome section includes human-readable `summary` field | -| Explanation of decisions | Reasoning section captures analysis, options, and rationale *before* execution | -| Information for deployers | Capsules are queryable via storage backends; all fields are machine-readable | - -### Article 14: Human Oversight - -*High-risk AI systems shall be designed to be effectively overseen by natural persons.* - -| Requirement | How Capsule Addresses It | -|---|---| -| Human-in-the-loop capability | Authority section supports `human_approved` type with `approver` identity | -| Ability to intervene | Kill switch Capsules (`CapsuleType.KILL`) record intervention events | -| Override capability | Authority section's `escalation_reason` documents why human override occurred | - ---- - -## SOC 2 Trust Services Criteria - -SOC 2 Type II audit mappings for the Security and Availability trust service categories. - -| Criterion | Title | How Capsule Addresses It | -|---|---|---| -| **CC6.1** | Logical access security | Ed25519 key-based signing; key files restricted to owner (0600 permissions) | -| **CC7.2** | System monitoring | Every AI action produces a Capsule; chain provides complete operational history | -| **CC7.3** | Detection of unauthorized changes | `chain.verify()` detects any modification, deletion, or insertion | -| **CC7.4** | Incident response data | Capsules contain full context (6 sections) for post-incident analysis | -| **CC8.1** | Change management | Each Capsule records what changed (`outcome.side_effects`), who approved it (`authority`), and why (`reasoning`) | - ---- - -## ISO 27001:2022 - -Selected controls from Annex A. - -| Control | Title | How Capsule Addresses It | -|---|---|---| -| **A.8.15** | Logging | Every AI action produces a Capsule with 6 auditable sections | -| **A.8.16** | Monitoring activities | Chain provides temporal ordering; `type_filter` enables monitoring by event category | -| **A.8.17** | Clock synchronization | `trigger.timestamp` and `signed_at` use timezone-aware UTC | -| **A.8.24** | Use of cryptography | SHA3-256 (FIPS 202), Ed25519 (FIPS 186-5), ML-DSA-65 (FIPS 204) | -| **A.8.25** | Secure development lifecycle | 350 automated tests with 100% coverage; strict mypy; ruff linting; `filterwarnings = ["error"]` | - ---- - -## Cross-Language Conformance - -Capsule sealed in any language can be verified in any other. The Capsule Protocol Specification (CPS) defines: - -- Byte-level canonical JSON serialization rules -- 16 golden test vectors covering all CapsuleTypes, Unicode, fractional timestamps, chain sequences, empty vs null, deep nesting, and failure paths -- SHA3-256 hash determinism across implementations - -The Python reference implementation is available now. Cross-language SDKs (TypeScript, Go, Rust) are planned. All must produce byte-identical canonical JSON and matching SHA3-256 hashes for the golden test vectors. - -See [CPS Specification](../spec/) for protocol details. - ---- - -## Related Documentation - -- [Security Evaluation](./security.md) — Cryptographic architecture, key management, attack surface -- [Architecture](./architecture.md) — 6-section model, sealing process, hash chain -- [CPS Specification](../spec/) — Protocol rules and golden test vectors - ---- - -*Capsule v1.0.0 — Quantum Pipes Technologies, LLC* diff --git a/docs/compliance/README.md b/docs/compliance/README.md new file mode 100644 index 0000000..c062153 --- /dev/null +++ b/docs/compliance/README.md @@ -0,0 +1,63 @@ +# Regulatory Compliance Mapping + +> **How the Capsule protocol maps to the frameworks your auditors care about.** + +--- + +## Scope + +This directory maps **protocol-level** capabilities to regulatory controls. Every mapping describes what the Capsule Protocol Specification (CPS) itself provides: structured records, cryptographic sealing, hash chain integrity, and cross-language verification. + +Application-level controls (access management, network security, operational procedures) are the responsibility of the deployment environment, not the protocol. + +--- + +## FIPS Algorithm Compliance + +| Algorithm | FIPS Standard | Status | Capsule Usage | +|---|---|---|---| +| SHA3-256 | FIPS 202 (SHA-3) | Published August 2015 | Content hashing for every Capsule | +| Ed25519 | FIPS 186-5 (Digital Signatures) | Published February 2023 | Required signature on every Capsule | +| ML-DSA-65 | FIPS 204 (ML-DSA) | Published August 2024 | Optional post-quantum dual signature | + +All three algorithms are NIST-standardized. No deprecated or non-standard cryptography is used. + +--- + +## Framework Mappings + +| Framework | Controls Mapped | Document | +|---|---|---| +| [NIST SP 800-53 Rev. 5](./nist-sp-800-53.md) | AU-2 through AU-12, SC-13, SC-28, SI-7 | Audit, integrity, crypto | +| [NIST AI RMF 1.0](./nist-ai-rmf.md) | GOVERN, MAP, MEASURE, MANAGE | AI risk management | +| [EU AI Act](./eu-ai-act.md) | Articles 12, 13, 14 | Record-keeping, transparency, oversight | +| [SOC 2 Type II](./soc2.md) | CC6.1, CC7.2, CC7.3, CC7.4, CC8.1 | Trust Services Criteria | +| [ISO 27001:2022](./iso27001.md) | A.8.15, A.8.16, A.8.17, A.8.24, A.8.25 | Annex A controls | +| [HIPAA](./hipaa.md) | §164.308, §164.312 | Security Rule safeguards | +| [GDPR](./gdpr.md) | Articles 5, 25, 30, 32, 35 | Data protection principles | +| [PCI DSS v4.0](./pci-dss.md) | Req 10, Req 11.5, Req 11.6 | Logging, monitoring, change detection | +| [FedRAMP](./fedramp.md) | AU-9(3), AU-10, SI-7(1-7), SC-8(1), SC-28(1), CM-3 | Federal cloud authorization | +| [FINRA](./finra.md) | SEC 17a-4, REC-2, Rule 3110 | Financial recordkeeping, supervision | +| [CMMC 2.0](./cmmc.md) | AU.L2-3.3.x, SC.L2-3.13.x, AC.L2-3.1.12 | DoD contractor CUI protection | + +--- + +## Cross-Language Conformance + +Capsule sealed in any language can be verified in any other. The Capsule Protocol Specification (CPS) defines: + +- Byte-level canonical JSON serialization rules +- 16 golden test vectors covering all CapsuleTypes, Unicode, fractional timestamps, chain sequences, empty vs null, deep nesting, and failure paths +- SHA3-256 hash determinism across implementations + +Python and TypeScript reference implementations are available now. All conformant implementations produce byte-identical canonical JSON and matching SHA3-256 hashes for the golden test vectors. + +See [CPS Specification](../../spec/) for protocol details. + +--- + +## Related Documentation + +- [Security Evaluation](../security.md) -- Cryptographic architecture, key management, attack surface +- [Architecture](../architecture.md) -- 6-section model, sealing process, hash chain +- [CPS Specification](../../spec/) -- Protocol rules and golden test vectors diff --git a/docs/compliance/cmmc.md b/docs/compliance/cmmc.md new file mode 100644 index 0000000..2ede436 --- /dev/null +++ b/docs/compliance/cmmc.md @@ -0,0 +1,45 @@ +# CMMC 2.0 + +The Cybersecurity Maturity Model Certification (CMMC) 2.0 is required for Department of Defense contractors handling Controlled Unclassified Information (CUI). CMMC Level 2 aligns with NIST SP 800-171 Rev. 2 (110 controls). Capsule provides protocol-level capabilities that address audit, integrity, and cryptographic protection requirements. + +--- + +## Audit and Accountability (AU) + +| Control | Requirement | How Capsule Addresses It | +|---|---|---| +| **AU.L2-3.3.1** | Create audit records for defined events | Every AI action produces a Capsule. `CapsuleType` defines 8 event categories. 6 sections capture the complete lifecycle. | +| **AU.L2-3.3.2** | Unique user accountability | `trigger.user_id` and `trigger.source` attribute actions to specific users or agents. `signed_by` identifies the signing key. | +| **AU.L2-3.3.4** | Alert on audit logging process failure | `outcome.status = "failure"` records action failures. Kill switch Capsules record system-level interventions. Applications can alert on chain verification failures. | +| **AU.L2-3.3.5** | Correlate audit review, analysis, and reporting | `correlation_id` links related Capsules. `parent_id` creates hierarchical relationships. `session_id` groups conversation turns. | +| **AU.L2-3.3.8** | Protect audit information from unauthorized access, modification, and deletion | SHA3-256 hash + Ed25519 signature prevents undetected modification. Hash chain prevents undetected deletion or insertion. Key files restricted to owner (`0600` permissions). | +| **AU.L2-3.3.9** | Manage and retain audit logs | Capsules are persisted in SQLite or PostgreSQL. `storage.list()` with pagination. Retention policies configurable at the storage layer. | + +## System and Communications Protection (SC) + +| Control | Requirement | How Capsule Addresses It | +|---|---|---| +| **SC.L2-3.13.8** | Implement cryptographic mechanisms to prevent unauthorized disclosure during transmission | Capsule hashes are self-verifying independent of transport. Recompute SHA3-256 and compare to stored hash on receipt. | +| **SC.L2-3.13.10** | Establish and manage cryptographic keys | Ed25519 keys auto-generated with `0600` permissions and `umask(0o077)`. ML-DSA-65 keys for post-quantum protection. `verify_with_key()` supports key rotation verification. | +| **SC.L2-3.13.11** | Employ FIPS-validated cryptography | SHA3-256 (FIPS 202), Ed25519 (FIPS 186-5), ML-DSA-65 (FIPS 204). All algorithms are NIST-standardized. | + +## Access Control (AC) + +| Control | Requirement | How Capsule Addresses It | +|---|---|---| +| **AC.L2-3.1.12** | Monitor and control remote access sessions | `CapsuleType.AUTH` records authentication events. Authority section records approval chains. Session tracking via `session_id`. | + +## Complementary Controls + +The following CMMC requirements are outside the protocol's scope: + +- **AC.L2-3.1.1 through 3.1.11** Access control policies and enforcement -- application-level +- **IA** Identification and authentication -- application-level +- **IR** Incident response -- organizational (though Capsules provide evidence for investigation) +- **MP** Media protection -- physical security +- **PE** Physical protection -- facility security +- **PS** Personnel security -- organizational + +--- + +[Back to Compliance Overview](./README.md) diff --git a/docs/compliance/eu-ai-act.md b/docs/compliance/eu-ai-act.md new file mode 100644 index 0000000..fdfdc04 --- /dev/null +++ b/docs/compliance/eu-ai-act.md @@ -0,0 +1,40 @@ +# EU AI Act + +The EU AI Act (Regulation 2024/1689) establishes requirements for AI systems operating in the EU. Key obligations take effect August 2, 2026. + +--- + +## Article 12: Record-keeping + +*High-risk AI systems shall be designed with logging capabilities that record events relevant to the functioning of the AI system.* + +| Requirement | How Capsule Addresses It | +|---|---| +| Automatic logging of events | Every AI action produces a Capsule (the axiom: for all actions, there exists a Capsule) | +| Traceability of results | Execution section records tool calls; Outcome section records results and side effects | +| Monitoring of operation | Chain provides temporal ordering; session_id groups related interactions | +| Identification of risks | Reasoning section captures risk assessment in `ReasoningOption.risks` | + +## Article 13: Transparency + +*High-risk AI systems shall be designed to ensure their operation is sufficiently transparent.* + +| Requirement | How Capsule Addresses It | +|---|---| +| Understandable output | Outcome section includes human-readable `summary` field | +| Explanation of decisions | Reasoning section captures analysis, options, and rationale *before* execution | +| Information for deployers | Capsules are queryable via storage backends; all fields are machine-readable | + +## Article 14: Human Oversight + +*High-risk AI systems shall be designed to be effectively overseen by natural persons.* + +| Requirement | How Capsule Addresses It | +|---|---| +| Human-in-the-loop capability | Authority section supports `human_approved` type with `approver` identity | +| Ability to intervene | Kill switch Capsules (`CapsuleType.KILL`) record intervention events | +| Override capability | Authority section's `escalation_reason` documents why human override occurred | + +--- + +[Back to Compliance Overview](./README.md) diff --git a/docs/compliance/fedramp.md b/docs/compliance/fedramp.md new file mode 100644 index 0000000..0cbfb5e --- /dev/null +++ b/docs/compliance/fedramp.md @@ -0,0 +1,63 @@ +# FedRAMP (NIST SP 800-53 Rev. 5) + +The Federal Risk and Authorization Management Program (FedRAMP) standardizes security assessment for cloud services used by federal agencies. FedRAMP controls are drawn from NIST SP 800-53 Rev. 5. Capsule provides protocol-level capabilities that address controls in the Audit (AU), System and Communications Protection (SC), System and Information Integrity (SI), and Configuration Management (CM) families. + +For the core AU, SC, and SI mappings shared with NIST SP 800-53, see [nist-sp-800-53.md](./nist-sp-800-53.md). This document covers additional FedRAMP-specific requirements and higher-baseline enhancements. + +--- + +## FedRAMP-Specific Enhancements + +### Audit and Accountability (AU) + +| Control | Title | Baseline | How Capsule Addresses It | +|---|---|---|---| +| **AU-9(3)** | Cryptographic Protection of Audit Information | High | SHA3-256 (FIPS 202) integrity hashing + Ed25519 (FIPS 186-5) signatures on every Capsule. Optional ML-DSA-65 (FIPS 204) post-quantum dual signatures. | +| **AU-10** | Non-repudiation | High | Ed25519 digital signatures with `signed_by` key fingerprint. `verify_with_key()` enables independent third-party verification. | + +### System and Information Integrity (SI) + +| Control | Title | Baseline | How Capsule Addresses It | +|---|---|---|---| +| **SI-7(1)** | Integrity Checks | Moderate | `seal.verify(capsule)` for individual records, `chain.verify()` for the full chain. Both can run at startup, on schedule, or on demand. | +| **SI-7(2)** | Automated Notifications of Integrity Violations | High | `chain.verify()` returns `broken_at` with the Capsule ID where integrity failed. Applications can alert on this. | +| **SI-7(5)** | Automated Response to Integrity Violations | High | Kill switch Capsules (`CapsuleType.KILL`) record automated termination events when integrity violations are detected. | +| **SI-7(7)** | Integration of Detection and Response | Moderate | Chain verification results include Capsule context (6 sections) for direct incident response integration. | + +### System and Communications Protection (SC) + +| Control | Title | Baseline | How Capsule Addresses It | +|---|---|---|---| +| **SC-8(1)** | Cryptographic Protection (Transmission) | Moderate | Capsule hashes are self-verifying: recompute SHA3-256 from content and compare to stored hash. Verification is independent of transport layer. | +| **SC-28(1)** | Cryptographic Protection (At Rest) | Moderate | Sealed Capsules are integrity-protected via cryptographic signatures. Storage-level encryption is configurable at the database layer. | + +### Configuration Management (CM) + +| Control | Title | Baseline | How Capsule Addresses It | +|---|---|---|---| +| **CM-3** | Configuration Change Control | Moderate | Each Capsule records what changed (`outcome.side_effects`), who approved it (`authority`), and why (`reasoning`). Hash chain provides tamper-evident change history. | + +## Air-Gapped Operation + +Capsule is designed for air-gapped federal environments: + +- Zero runtime network dependencies +- No telemetry, analytics, or license server +- All cryptographic operations use local key material +- SQLite storage requires no network access +- FIPS-approved algorithms throughout (SHA3-256, Ed25519, ML-DSA-65) + +## Complementary Controls + +The following FedRAMP control families are outside the protocol's scope: + +- **AC** Access control -- application-level authentication and authorization +- **AT** Awareness and training -- organizational +- **CA** Assessment, authorization, and monitoring -- organizational +- **CP** Contingency planning -- infrastructure-level +- **IA** Identification and authentication -- application-level +- **IR** Incident response procedures -- organizational (though Capsules provide the evidence for incident investigation) + +--- + +[Back to Compliance Overview](./README.md) diff --git a/docs/compliance/finra.md b/docs/compliance/finra.md new file mode 100644 index 0000000..eec39a4 --- /dev/null +++ b/docs/compliance/finra.md @@ -0,0 +1,44 @@ +# FINRA + +FINRA (Financial Industry Regulatory Authority) cybersecurity rules govern broker-dealers and financial services firms. Key regulations include SEC Rule 17a-4 (electronic recordkeeping), Regulation S-P (privacy), Regulation S-ID (identity theft), and FINRA Rules 3110 (supervision) and 4370 (business continuity). + +Capsule provides protocol-level capabilities that address recordkeeping integrity, record authenticity, and supervisory audit requirements. + +--- + +## SEC Rule 17a-4: Electronic Recordkeeping + +| Requirement | How Capsule Addresses It | +|---|---| +| Records must be preserved in non-rewriteable, non-erasable (WORM) format | Capsules are sealed with SHA3-256 + Ed25519 at the moment of action. Any modification changes the hash and invalidates the signature. Hash chain makes the record sequence tamper-evident. | +| 2 years of immediately accessible records; 3-6 years archive | Capsules are persisted in SQLite or PostgreSQL with configurable retention. `storage.list()` provides paginated retrieval. | +| Records must be indexed and searchable | Capsules are queryable by type (`CapsuleType`), time range, tenant, session, and chain position. | + +## Record Authenticity (REC-2) + +| Requirement | How Capsule Addresses It | +|---|---| +| Digital signatures to verify record origin | Ed25519 signature on every Capsule with `signed_by` key fingerprint. Optional ML-DSA-65 (FIPS 204) post-quantum dual signature. | +| Hash verification to detect unauthorized modification | SHA3-256 content hash. `seal.verify(capsule)` recomputes the hash from content and compares to the stored hash. | +| Audit trails to detect unauthorized modifications | Hash chain links each Capsule to the previous via `previous_hash`. `chain.verify()` detects any modification, deletion, or insertion in the sequence. | + +## FINRA Rule 3110: Supervision + +| Requirement | How Capsule Addresses It | +|---|---| +| Written supervisory procedures | Authority section records authorization type (`autonomous`, `human_approved`, `policy`, `escalated`), policy references, and approval chains. | +| Review of supervisory activities | Capsules are structured, machine-readable records. Reasoning section captures pre-execution deliberation for supervisory review. | +| Evidence of supervision | Each Capsule's Authority section documents who or what approved the action and why escalation occurred (if applicable). | + +## Complementary Controls + +The following FINRA requirements are outside the protocol's scope: + +- **Reg S-P** Customer data privacy -- application-level data handling +- **Reg S-ID** Identity theft prevention -- application-level identity management +- **Rule 4370** Business continuity planning -- organizational +- **WORM storage enforcement** -- Capsule provides tamper-evidence at the protocol layer; WORM storage enforcement is a deployment-level concern (e.g., S3 Object Lock, immutable storage) + +--- + +[Back to Compliance Overview](./README.md) diff --git a/docs/compliance/gdpr.md b/docs/compliance/gdpr.md new file mode 100644 index 0000000..200d70e --- /dev/null +++ b/docs/compliance/gdpr.md @@ -0,0 +1,58 @@ +# GDPR + +The General Data Protection Regulation (EU 2016/679) governs how organizations process personal data of EU residents. Capsule provides protocol-level capabilities that support integrity, accountability, records of processing, and data protection by design. + +--- + +## Data Protection Principles (Article 5) + +| Principle | Article | How Capsule Addresses It | +|---|---|---| +| **Integrity and confidentiality** | Art. 5(1)(f) | SHA3-256 hash + Ed25519 signature seals every Capsule. Hash chain detects modification, deletion, or insertion. | +| **Accountability** | Art. 5(2) | Every AI action produces a Capsule with 6 auditable sections. Authority section records who approved the action. Chain provides a verifiable audit trail. | + +## Data Protection by Design (Article 25) + +| Requirement | How Capsule Addresses It | +|---|---| +| Technical measures at design time | Cryptographic sealing is built into the protocol, not added as an afterthought. Every Capsule is sealed at the moment of action. | +| Audit without content exposure | `reasoning.prompt_hash` records the SHA3-256 hash of a prompt for audit purposes without storing the prompt content itself. | +| Structured minimization | The 6-section model separates concerns: auditors reviewing authority need not access execution details. `capsule://` URI fragments address individual sections. | + +## Records of Processing Activities (Article 30) + +| Requirement | How Capsule Addresses It | +|---|---| +| Maintain records of processing | Each Capsule is a structured record of a processing activity: what triggered it, what data context existed, why the AI decided to act, who authorized it, what tools were called, and what the outcome was. | +| Categories of processing | `CapsuleType` categorizes processing activities: agent, tool, system, kill, workflow, chat, vault, auth. | +| Description of technical measures | Capsule metadata records cryptographic algorithms (SHA3-256, Ed25519, ML-DSA-65), key fingerprints, and chain position. | + +## Security of Processing (Article 32) + +| Measure | How Capsule Addresses It | +|---|---| +| Integrity of processing | SHA3-256 content hash detects any modification. Ed25519 signature authenticates the record. Hash chain detects deletion or insertion. | +| Ability to restore availability | Capsules are self-verifying: given the content and the hash, any party can confirm integrity without trusting the storage layer. | +| Process for regular testing | `chain.verify()` provides one-call integrity verification. `seal.verify(capsule)` tests individual records. Both can run on any schedule. | + +## Data Protection Impact Assessment (Article 35) + +| Requirement | How Capsule Addresses It | +|---|---| +| Systematic description of processing | Reasoning section captures analysis, options considered, and rationale before execution. | +| Assessment of necessity | `reasoning.confidence` records the AI's assessed confidence (0.0 to 1.0). `ReasoningOption.rejection_reason` documents why alternatives were not chosen. | +| Assessment of risks | `ReasoningOption.risks` captures identified risks per option. `ReasoningOption.estimated_impact` records scope and severity. | + +## Complementary Controls + +The following GDPR requirements are outside the protocol's scope and must be addressed by the deployment environment: + +- **Art. 5(1)(a)** Lawfulness, fairness, transparency -- legal basis for processing +- **Art. 5(1)(b)** Purpose limitation -- organizational data governance +- **Art. 5(1)(e)** Storage limitation -- retention policies at the application layer +- **Art. 15-22** Data subject rights (access, erasure, portability) -- application-level data management +- **Art. 32** Encryption at rest/in transit -- storage and transport layer encryption + +--- + +[Back to Compliance Overview](./README.md) diff --git a/docs/compliance/hipaa.md b/docs/compliance/hipaa.md new file mode 100644 index 0000000..bb00c53 --- /dev/null +++ b/docs/compliance/hipaa.md @@ -0,0 +1,37 @@ +# HIPAA Security Rule + +The HIPAA Security Rule (45 CFR Part 164, Subparts A and C) establishes standards for protecting electronic Protected Health Information (ePHI). Capsule provides protocol-level capabilities that support technical safeguards for integrity, audit controls, and authentication. + +HIPAA has no formal certification. Compliance is demonstrated through risk analysis, attestation, and audit readiness. + +--- + +## Technical Safeguards (§164.312) + +| Standard | Specification | How Capsule Addresses It | +|---|---|---| +| **§164.312(b)** | Audit controls | Every AI action produces a sealed Capsule with 6 auditable sections. `chain.verify()` confirms the complete audit trail is intact. Hash chain provides tamper-evident temporal ordering. | +| **§164.312(c)(1)** | Integrity | SHA3-256 hash + Ed25519 signature on every Capsule. Any modification to content changes the hash and invalidates the signature. `seal.verify(capsule)` detects tampering. | +| **§164.312(c)(2)** | Mechanism to authenticate ePHI | Ed25519 digital signatures authenticate each record. `signed_by` identifies the signing key. `verify_with_key()` enables third-party verification of record authenticity. | +| **§164.312(e)(2)** | Integrity controls (transmission) | Capsule hashes are self-verifying: recompute SHA3-256 from content and compare to stored hash. Verification is independent of transport layer. | + +## Administrative Safeguards (§164.308) + +| Standard | Specification | How Capsule Addresses It | +|---|---|---| +| **§164.308(a)(1)(ii)(D)** | Information system activity review | Capsules are queryable by type, time range, tenant, and session. Chain provides complete operational history for review. | +| **§164.308(a)(5)(ii)(C)** | Log-in monitoring | `CapsuleType.AUTH` records authentication events with authority chain (e.g., MFA escalation). | +| **§164.308(a)(6)(ii)** | Response and reporting | Capsules contain full context (Trigger, Context, Reasoning, Authority, Execution, Outcome) for incident investigation. Kill switch Capsules record intervention events. | + +## Complementary Controls + +The following HIPAA requirements are outside the protocol's scope and must be addressed by the deployment environment: + +- **§164.312(a)(1)** Access control -- application-level authentication and authorization +- **§164.312(d)** Person or entity authentication -- user identity management +- **§164.312(e)(1)** Transmission security (encryption) -- TLS at the transport layer +- **§164.308(a)(3)** Workforce security -- organizational HR and access policies + +--- + +[Back to Compliance Overview](./README.md) diff --git a/docs/compliance/iso27001.md b/docs/compliance/iso27001.md new file mode 100644 index 0000000..9358b2b --- /dev/null +++ b/docs/compliance/iso27001.md @@ -0,0 +1,17 @@ +# ISO 27001:2022 + +Selected controls from Annex A relevant to the Capsule protocol. + +--- + +| Control | Title | How Capsule Addresses It | +|---|---|---| +| **A.8.15** | Logging | Every AI action produces a Capsule with 6 auditable sections | +| **A.8.16** | Monitoring activities | Chain provides temporal ordering; `type_filter` enables monitoring by event category | +| **A.8.17** | Clock synchronization | `trigger.timestamp` and `signed_at` use timezone-aware UTC | +| **A.8.24** | Use of cryptography | SHA3-256 (FIPS 202), Ed25519 (FIPS 186-5), ML-DSA-65 (FIPS 204) | +| **A.8.25** | Secure development lifecycle | 500+ automated tests with 100% coverage; strict mypy; ruff linting; `filterwarnings = ["error"]` | + +--- + +[Back to Compliance Overview](./README.md) diff --git a/docs/compliance/nist-ai-rmf.md b/docs/compliance/nist-ai-rmf.md new file mode 100644 index 0000000..e8d3f3c --- /dev/null +++ b/docs/compliance/nist-ai-rmf.md @@ -0,0 +1,49 @@ +# NIST AI Risk Management Framework (AI RMF 1.0) + +The AI RMF organizes AI risk management into four functions: GOVERN, MAP, MEASURE, MANAGE. + +--- + +## GOVERN + +*Cultivate and implement a culture of AI risk management.* + +| Practice | How Capsule Supports It | +|---|---| +| Establish accountability structures | Authority section records who approved each action (`autonomous`, `human_approved`, `policy`, `escalated`) | +| Document AI decision-making processes | Reasoning section captures analysis, options considered, selected option, and confidence before execution | +| Maintain audit trails | Hash-chained Capsules provide an immutable, tamper-evident record of every AI action | + +## MAP + +*Contextualize AI risks.* + +| Practice | How Capsule Supports It | +|---|---| +| Identify AI system components | Capsule Types map to system components: AGENT, TOOL, WORKFLOW, CHAT, VAULT | +| Document operating context | Context section records agent_id, session_id, and environment state at time of action | +| Track data lineage | Execution section records tool calls with arguments, results, and errors | + +## MEASURE + +*Analyze, assess, and track AI risks.* + +| Practice | How Capsule Supports It | +|---|---| +| Quantify model confidence | `reasoning.confidence` (0.0 to 1.0) records model-reported confidence per action | +| Track performance metrics | `outcome.metrics` captures duration, token usage, cost, and custom metrics | +| Monitor for anomalies | `outcome.status` values (`success`, `failure`, `partial`, `blocked`) enable monitoring | + +## MANAGE + +*Prioritize and act on AI risks.* + +| Practice | How Capsule Supports It | +|---|---| +| Implement kill switches | `CapsuleType.KILL` records kill switch activations with authority chain | +| Enable human oversight | Authority section's `escalation_reason` and `approver` fields document human-in-the-loop decisions | +| Verify system integrity | `chain.verify()` provides one-call integrity verification of the entire audit trail | + +--- + +[Back to Compliance Overview](./README.md) diff --git a/docs/compliance/nist-sp-800-53.md b/docs/compliance/nist-sp-800-53.md new file mode 100644 index 0000000..5d9d312 --- /dev/null +++ b/docs/compliance/nist-sp-800-53.md @@ -0,0 +1,36 @@ +# NIST SP 800-53 Rev. 5 + +Security and privacy controls for information systems. Capsule addresses controls in the Audit (AU), System and Communications Protection (SC), and System and Information Integrity (SI) families. + +--- + +## Audit and Accountability (AU) + +| Control | Title | How Capsule Addresses It | +|---|---|---| +| **AU-2** | Event Logging | Every AI action produces a Capsule. The `CapsuleType` enum defines 8 event categories: agent, tool, system, kill, workflow, chat, vault, auth. | +| **AU-3** | Content of Audit Records | Each Capsule contains 6 sections: Trigger (who/what/when), Context (system state), Reasoning (why), Authority (approval), Execution (how), Outcome (result). | +| **AU-3(1)** | Additional Audit Information | `correlation_id` links related Capsules across distributed operations. `parent_id` creates hierarchical relationships. `session_id` groups conversation turns. | +| **AU-8** | Time Stamps | `trigger.timestamp` records UTC time of action initiation. `signed_at` records UTC time of cryptographic sealing. Both are timezone-aware. | +| **AU-9** | Protection of Audit Information | SHA3-256 hash + Ed25519 signature prevents undetected modification. Hash chain prevents undetected deletion or insertion. | +| **AU-10** | Non-repudiation | Ed25519 digital signatures provide non-repudiation via `signed_by` (key fingerprint). `verify_with_key()` enables third-party verification. | +| **AU-11** | Audit Record Retention | Capsules are persisted in SQLite or PostgreSQL. Retention policies are configurable at the storage layer. | +| **AU-12** | Audit Record Generation | Capsule creation is application-initiated at the moment of action. The `seal_and_store()` convenience method ensures atomic chain + seal + store. | + +## System and Communications Protection (SC) + +| Control | Title | How Capsule Addresses It | +|---|---|---| +| **SC-13** | Cryptographic Protection | SHA3-256 (FIPS 202) for integrity, Ed25519 (FIPS 186-5) for signatures, ML-DSA-65 (FIPS 204) for quantum resistance. | +| **SC-28** | Protection of Information at Rest | Sealed Capsules are integrity-protected via cryptographic signatures. Storage-level encryption is configurable at the database layer. | + +## System and Information Integrity (SI) + +| Control | Title | How Capsule Addresses It | +|---|---|---| +| **SI-7** | Software, Firmware, and Information Integrity | `chain.verify()` detects any modification, deletion, or insertion in the audit trail. | +| **SI-7(1)** | Integrity Checks | Verification can run anytime: `seal.verify(capsule)` for individual records, `chain.verify()` for the entire chain. | + +--- + +[Back to Compliance Overview](./README.md) diff --git a/docs/compliance/pci-dss.md b/docs/compliance/pci-dss.md new file mode 100644 index 0000000..ca962d1 --- /dev/null +++ b/docs/compliance/pci-dss.md @@ -0,0 +1,36 @@ +# PCI DSS v4.0 + +The Payment Card Industry Data Security Standard (PCI DSS) v4.0.1 establishes security requirements for organizations that store, process, or transmit cardholder data. Capsule provides protocol-level capabilities that support audit logging, integrity verification, and change detection requirements. + +--- + +## Requirement 10: Log and Monitor All Access + +| Sub-Requirement | Title | How Capsule Addresses It | +|---|---|---| +| **10.2** | Audit logs record actions | Each Capsule records: who triggered the action (`trigger.user_id`, `trigger.source`), event type (`CapsuleType`), timestamp (`trigger.timestamp`, `signed_at`), success/failure (`outcome.status`), and affected data (`execution.tool_calls`, `outcome.side_effects`). | +| **10.3** | Access to audit logs restricted and protected from alteration | SHA3-256 hash + Ed25519 signature on every Capsule. Hash chain detects any modification, deletion, or insertion. `chain.verify()` confirms the complete trail is intact. | +| **10.4.1.1** | Automated audit log reviews | Capsules are machine-readable and queryable by type, time range, status, and tenant. Structured 6-section format enables automated analysis. | +| **10.7.2** | Detection of failures of critical security control systems | `outcome.status = "failure"` and `outcome.status = "blocked"` record control failures. Kill switch Capsules (`CapsuleType.KILL`) record system-level interventions. | +| **10.7.3** | Response to failures of critical security control systems | Capsules provide full context (Trigger, Context, Reasoning, Authority, Execution, Outcome) for incident investigation and response. | + +## Requirement 11: Test Security Regularly + +| Sub-Requirement | Title | How Capsule Addresses It | +|---|---|---| +| **11.5** | Change-detection mechanisms | `chain.verify()` detects unauthorized changes to any record. SHA3-256 hash comparison identifies which record was modified. | +| **11.6** | Detect and prevent tampering | Hash chain is tamper-evident by construction: modifying any Capsule changes its hash, which invalidates every subsequent Capsule's `previous_hash` link. | + +## Complementary Controls + +The following PCI DSS requirements are outside the protocol's scope: + +- **Req 1-2** Network security and secure configurations -- infrastructure-level +- **Req 3-4** Cardholder data encryption at rest and in transit -- application/transport layer +- **Req 5** Malware protection -- endpoint security +- **Req 6** Secure development -- organizational SDLC (though Capsule itself is developed with 100% test coverage and strict linting) +- **Req 7-9** Access control, physical security, personnel -- organizational controls + +--- + +[Back to Compliance Overview](./README.md) diff --git a/docs/compliance/soc2.md b/docs/compliance/soc2.md new file mode 100644 index 0000000..a83b71e --- /dev/null +++ b/docs/compliance/soc2.md @@ -0,0 +1,17 @@ +# SOC 2 Trust Services Criteria + +SOC 2 Type II audit mappings for the Security and Availability trust service categories. + +--- + +| Criterion | Title | How Capsule Addresses It | +|---|---|---| +| **CC6.1** | Logical access security | Ed25519 key-based signing; key files restricted to owner (0600 permissions) | +| **CC7.2** | System monitoring | Every AI action produces a Capsule; chain provides complete operational history | +| **CC7.3** | Detection of unauthorized changes | `chain.verify()` detects any modification, deletion, or insertion | +| **CC7.4** | Incident response data | Capsules contain full context (6 sections) for post-incident analysis | +| **CC8.1** | Change management | Each Capsule records what changed (`outcome.side_effects`), who approved it (`authority`), and why (`reasoning`) | + +--- + +[Back to Compliance Overview](./README.md) diff --git a/docs/security.md b/docs/security.md index 3818593..3950e44 100644 --- a/docs/security.md +++ b/docs/security.md @@ -211,7 +211,7 @@ Use this checklist when evaluating Capsule for your organization: ## Related Documentation - [Architecture](./architecture.md) — Technical deep dive on the 6-section model and cryptographic sealing -- [Compliance Mapping](./compliance.md) — NIST SP 800-53, EU AI Act, SOC 2, ISO 27001 +- [Compliance Mapping](./compliance/) — NIST SP 800-53, EU AI Act, SOC 2, ISO 27001, HIPAA, GDPR - [CPS Specification](../spec/) — Protocol rules and golden test vectors - [SECURITY.md](../SECURITY.md) — Vulnerability reporting diff --git a/docs/why-capsules.md b/docs/why-capsules.md index 695842d..a5e9e97 100644 --- a/docs/why-capsules.md +++ b/docs/why-capsules.md @@ -78,5 +78,5 @@ Every Capsule is addressable by its SHA3-256 hash via the `capsule://` URI schem - [Architecture](./architecture.md) — How the protocol works - [Security Evaluation](./security.md) — Cryptographic guarantees -- [Compliance Mapping](./compliance.md) — Regulatory framework alignment +- [Compliance Mapping](./compliance/) — Regulatory framework alignment - [CPS Specification](../spec/) — The full protocol specification diff --git a/reference/python/tests/test_protocol_structure.py b/reference/python/tests/test_protocol_structure.py index 04cdb91..7c2fb3b 100644 --- a/reference/python/tests/test_protocol_structure.py +++ b/reference/python/tests/test_protocol_structure.py @@ -443,7 +443,6 @@ class TestProtocolDocs: "README.md", "architecture.md", "security.md", - "compliance.md", "why-capsules.md", "implementors-guide.md", ] @@ -452,6 +451,32 @@ class TestProtocolDocs: def test_doc_exists(self, filename: str): assert (REPO_ROOT / "docs" / filename).exists(), f"docs/{filename} missing" + def test_compliance_directory_exists(self): + """Compliance is a directory with per-framework mappings.""" + compliance_dir = REPO_ROOT / "docs" / "compliance" + assert compliance_dir.is_dir(), "docs/compliance/ directory missing" + assert (compliance_dir / "README.md").exists(), "docs/compliance/README.md missing" + + REQUIRED_COMPLIANCE_FRAMEWORKS = [ + "nist-sp-800-53.md", + "nist-ai-rmf.md", + "eu-ai-act.md", + "soc2.md", + "iso27001.md", + "hipaa.md", + "gdpr.md", + "pci-dss.md", + "fedramp.md", + "finra.md", + "cmmc.md", + ] + + @pytest.mark.parametrize("filename", REQUIRED_COMPLIANCE_FRAMEWORKS) + def test_compliance_framework_exists(self, filename: str): + assert (REPO_ROOT / "docs" / "compliance" / filename).exists(), ( + f"docs/compliance/{filename} missing" + ) + def test_python_specific_docs_not_in_protocol_docs(self): """API reference and getting-started are Python-specific, not protocol-level.""" protocol_docs = {p.name for p in (REPO_ROOT / "docs").glob("*.md")}