quantumpipes · bradleygauthier · Mar 9, 2026 · Mar 9, 2026 · Mar 9, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -11,6 +11,33 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ---
 
+## [1.3.0] - 2026-03-09
+
+CLI verifier and epoch-based key rotation system.
+
+### Added
+
+- **`capsule` CLI** -- command-line tool for verification, inspection, and key management. Installed as a console script via `pip install qp-capsule`. Zero new dependencies (stdlib `argparse` + existing `pynacl`).
+  - `capsule verify <source>` -- verify chain integrity from JSON files (`chain.json`) or SQLite databases (`--db`). Three verification levels: `--structural` (default, sequence + previous_hash linkage), `--full` (+ SHA3-256 recomputation), `--signatures` (+ Ed25519 verification via keyring). Output modes: colored terminal (default), `--json` (machine-readable for policy engines and CI), `--quiet` (exit code only: 0=pass, 1=fail, 2=error).
+  - `capsule inspect` -- show a capsule's full 6-section content with seal metadata. Lookup by `--seq` or `--id` from JSON files or SQLite databases.
+  - `capsule keys info` -- display keyring metadata, epoch history, and capsule counts per epoch.
+  - `capsule keys rotate` -- generate new Ed25519 key pair, retire current key, update keyring. No downtime.
+  - `capsule keys export-public` -- export current public key for third-party verification.
+  - `capsule hash <file>` -- compute SHA3-256 of any file.
+- **Epoch-based key rotation** (`keyring.py`) -- automated key lifecycle management aligned with NIST SP 800-57. Keyring stored at `~/.quantumpipes/keyring.json` with atomic writes for crash safety. Supports backward-compatible verification across key rotations via fingerprint lookup. Seamless migration from existing single-key installations (auto-creates epoch 0 on first encounter).
+- **Epoch-aware signature verification** -- `Seal(keyring=kr)` uses the capsule's `signed_by` fingerprint to look up the correct epoch's public key from the keyring. Capsules signed with old keys continue to verify after rotation.
+- **`KeyringError` exception** -- dedicated exception for keyring operations (load, save, rotate, lookup).
+- **100+ new tests** -- keyring creation, migration, rotation, lookup, registration, export, atomic writes, edge cases. CLI verification (structural/full/signatures), inspection, key management, hash utility, ANSI color support, cross-rotation verification, seal+keyring integration. 100% code coverage maintained.
+
+### Security
+
+- Key rotation follows NIST SP 800-57 lifecycle: Generation, Active, Retired, Destroyed. Private keys are securely replaced on rotation (old key overwritten with new). Public keys are retained in the keyring for backward-compatible verification.
+- Keyring writes are atomic (temp file + `os.replace`) to prevent corruption on crash.
+- New `qp_key_XXXX` fingerprint format with backward-compatible lookup of legacy 16-char hex fingerprints.
+- `Seal.verify()` resolves the verification key from the keyring when available, falling back to the local key. No manual key management during verification.
+
+---
+
 ## [1.2.0] - 2026-03-08
 
 Protocol-first restructure, TypeScript implementation, finalized URI scheme, full CapsuleType conformance, Security Considerations in spec, cryptographic chain verification, and 11-framework compliance directory.
@@ -111,6 +138,7 @@ Initial public release of the Capsule Protocol Specification (CPS) v1.0 referenc
 
 ---
 
+[1.3.0]: https://github.com/quantumpipes/capsule/releases/tag/v1.3.0
 [1.2.0]: https://github.com/quantumpipes/capsule/releases/tag/v1.2.0
 [1.1.0]: https://github.com/quantumpipes/capsule/releases/tag/v1.1.0
 [1.0.0]: https://github.com/quantumpipes/capsule/releases/tag/v1.0.0
diff --git a/README.md b/README.md
@@ -168,7 +168,7 @@ See more examples in [`examples/`](./examples/).
 
 | Language | Status | Install | Source |
 |---|---|---|---|
-| **Python** | v1.1.0 (stable) | `pip install qp-capsule` | [`reference/python/`](./reference/python/) |
+| **Python** | v1.3.0 (stable) | `pip install qp-capsule` | [`reference/python/`](./reference/python/) |
 | **TypeScript** | v0.0.1 (conformant, 16/16 fixtures) | `npm install @quantumpipes/capsule` | [`reference/typescript/`](./reference/typescript/) |
 | Go | Separate repo (planned) | — | [quantumpipes/capsule-go](https://github.com/quantumpipes/capsule-go) |
 | Rust | Separate repo (planned) | — | [quantumpipes/capsule-rust](https://github.com/quantumpipes/capsule-rust) |
@@ -197,6 +197,22 @@ seal.seal(capsule)
 assert seal.verify(capsule)
 ```
 
+### CLI
+
+The Python package includes a CLI for verification, inspection, and key management:
+
+```bash
+capsule verify chain.json                      # Structural verification
+capsule verify --full --db capsules.db         # + SHA3-256 recomputation
+capsule verify --signatures --json chain.json  # + Ed25519, JSON output
+capsule inspect --db capsules.db --seq 47      # Full 6-section display
+capsule keys info                              # Epoch history
+capsule keys rotate                            # Rotate to new key (no downtime)
+capsule hash document.pdf                      # SHA3-256 of any file
+```
+
+Exit codes: `0` = pass, `1` = fail, `2` = error. Designed for CI/CD gates: `capsule verify --quiet && deploy`.
+
 See the [Python reference documentation](./reference/python/) for the full guide.
 
 ### Quick Start (TypeScript)
@@ -260,6 +276,7 @@ See the [compliance overview](./docs/compliance/) for FIPS algorithm details and
 | [Compliance Mapping](./docs/compliance/) | Regulators, GRC |
 | [Why Capsules](./docs/why-capsules.md) | Decision-Makers, Architects |
 | [Implementor's Guide](./docs/implementors-guide.md) | SDK Authors |
+| [CLI Reference](./docs/architecture.md#cli) | DevOps, Auditors |
 
 ---
 

diff --git a/docs/architecture.md b/docs/architecture.md
@@ -1,7 +1,7 @@
 ---
 title: "Capsule Architecture"
 description: "Complete technical architecture of Capsule: the 6-section record model, cryptographic sealing, hash chain integrity, and storage backends."
-date_modified: "2026-03-07"
+date_modified: "2026-03-09"
 ai_context: |
   Full architecture of the Capsule system. Covers the 6-section Capsule model
   (Trigger, Context, Reasoning, Authority, Execution, Outcome), two-tier
@@ -207,18 +207,58 @@ If any step fails, `seal.verify()` returns `False`.
 
 ### Key Management
 
-<!-- VERIFIED: reference/python/src/qp_capsule/seal.py:122-159, 161-222 -->
+<!-- VERIFIED: reference/python/src/qp_capsule/seal.py:129-172 -->
+<!-- VERIFIED: reference/python/src/qp_capsule/keyring.py:82-213 -->
 
-| Key | Location | Permissions | Generated |
+| File | Location | Permissions | Purpose |
 |---|---|---|---|
-| Ed25519 private key | `~/.quantumpipes/key` | `0600` (owner only) | On first `seal()` call |
-| ML-DSA-65 secret key | `~/.quantumpipes/key.ml` | `0600` (owner only) | On first PQ `seal()` call |
-| ML-DSA-65 public key | `~/.quantumpipes/key.ml.pub` | `0644` (world-readable) | On first PQ `seal()` call |
+| Ed25519 private key | `~/.quantumpipes/key` | `0600` | Signing (active epoch only) |
+| Keyring | `~/.quantumpipes/keyring.json` | `0600` | Epoch history and public keys |
+| ML-DSA-65 secret key | `~/.quantumpipes/key.ml` | `0600` | Post-quantum signing |
+| ML-DSA-65 public key | `~/.quantumpipes/key.ml.pub` | `0644` | Post-quantum verification |
 
 Override the key directory with the `QUANTUMPIPES_DATA_DIR` environment variable or by passing `key_path` to the `Seal` constructor.
 
 Keys are generated using cryptographically secure random sources. File creation uses `umask(0o077)` to prevent race conditions between creation and permission setting.
 
+### Key Rotation and Epochs
+
+<!-- VERIFIED: reference/python/src/qp_capsule/keyring.py:226-271 -->
+
+Keys are managed through *epochs*. Each epoch tracks a single Ed25519 key pair with a lifecycle aligned to NIST SP 800-57:
+
+| Lifecycle Phase | Implementation |
+|---|---|
+| Generation | `capsule keys rotate` or auto-generate on first `seal()` |
+| Active | Current epoch, used for new capsules |
+| Retired | Old epoch, public key retained for verification only |
+| Destroyed | Private key securely overwritten on rotation |
+
+The keyring (`keyring.json`) stores the epoch history:
+
+```json
+{
+  "version": 1,
+  "active_epoch": 1,
+  "epochs": [
+    { "epoch": 0, "algorithm": "ed25519", "fingerprint": "qp_key_a7f3", "status": "retired" },
+    { "epoch": 1, "algorithm": "ed25519", "fingerprint": "qp_key_8b1d", "status": "active" }
+  ]
+}
+```
+
+**Rotation protocol:**
+
+1. Generate new Ed25519 key pair
+2. Set current epoch's status to `retired` with `rotated_at` timestamp
+3. Add new epoch with status `active`
+4. Write new private key (securely replaces old)
+5. Save keyring atomically (temp file + `os.replace`)
+
+**Backward-compatible verification:** `Seal.verify()` uses the capsule's `signed_by` fingerprint to look up the correct epoch's public key from the keyring. Capsules signed with old keys verify after rotation without manual key management.
+
+**Migration:** The first time the `Seal` or CLI encounters an existing key file without a keyring, it creates `keyring.json` with epoch 0 for the existing key. No manual migration required.
+
 ---
 
 ## Hash Chain
@@ -374,6 +414,52 @@ Capsules can form parent-child hierarchies: `WORKFLOW` (parent) -> `AGENT` (chil
 
 ---
 
+## CLI
+
+<!-- VERIFIED: reference/python/src/qp_capsule/cli.py:1-617 -->
+
+The `capsule` CLI provides command-line verification, inspection, and key management. It is installed automatically with the Python package and has zero additional dependencies.
+
+```bash
+pip install qp-capsule
+```
+
+### Verification
+
+```bash
+capsule verify chain.json                     # Structural (sequence + previous_hash)
+capsule verify --full chain.json              # + recompute SHA3-256 from content
+capsule verify --signatures --db capsules.db  # + Ed25519 via keyring
+capsule verify --json chain.json              # Machine-readable for policy engines
+capsule verify --quiet chain.json && deploy   # CI/CD gate (exit code only)
+```
+
+Exit codes: 0 = pass, 1 = fail, 2 = error.
+
+### Inspection
+
+```bash
+capsule inspect --db capsules.db --seq 47     # Full 6-section display for capsule #47
+capsule inspect --db capsules.db --id <uuid>  # Look up by ID
+capsule inspect capsule.json                  # From exported JSON
+```
+
+### Key Management
+
+```bash
+capsule keys info                             # Epoch history and active key
+capsule keys rotate                           # Rotate to new epoch (no downtime)
+capsule keys export-public                    # Export for third-party verification
+```
+
+### Utility
+
+```bash
+capsule hash document.pdf                     # SHA3-256 of any file
+```
+
+---
+
 ## Related Documentation
 
 - [Why Capsules](./why-capsules.md) — The case for cryptographic AI memory

diff --git a/docs/implementors-guide.md b/docs/implementors-guide.md
@@ -187,6 +187,58 @@ Validate against [`conformance/uri-fixtures.json`](../conformance/uri-fixtures.j
 
 ---
 
+## Step 9: Key Management (Recommended)
+
+Implementations SHOULD support epoch-based key rotation per [CPS Section 8](../spec/README.md#8-key-management-recommendations).
+
+### Keyring
+
+Maintain a keyring that maps fingerprints to public keys across rotation epochs. The Python reference uses `~/.quantumpipes/keyring.json`:
+
+```json
+{
+  "version": 1,
+  "active_epoch": 1,
+  "epochs": [
+    { "epoch": 0, "algorithm": "ed25519", "public_key_hex": "...", "fingerprint": "qp_key_a7f3", "status": "retired" },
+    { "epoch": 1, "algorithm": "ed25519", "public_key_hex": "...", "fingerprint": "qp_key_8b1d", "status": "active" }
+  ]
+}
+```
+
+### Epoch-Aware Verification
+
+When verifying a sealed Capsule:
+
+```
+1. Read capsule.signed_by fingerprint
+2. Look up fingerprint in keyring → find epoch → get public_key_hex
+3. Verify Ed25519 signature with the resolved key
+4. If fingerprint not found, fall back to the local active key
+```
+
+This enables verification of Capsules signed across key rotations without manual key management.
+
+### Rotation Protocol
+
+```
+1. Generate new Ed25519 key pair
+2. Set current epoch status to "retired" with rotated_at timestamp
+3. Add new epoch with status "active"
+4. Securely overwrite old private key with new
+5. Save keyring atomically (temp file + rename)
+```
+
+### Migration
+
+On first use, if a key file exists but no keyring file, create the keyring with epoch 0 for the existing key. No user intervention required.
+
+### Fingerprints
+
+The Python reference uses `qp_key_XXXX` (first 4 hex characters of the public key). Implementations MAY use different formats but MUST ensure fingerprints are unique within a keyring. Legacy capsules may use a 16-character hex prefix as `signed_by`; the lookup function should match both formats.
+
+---
+
 ## Registering Your Implementation
 
 Once conformant, submit a PR to add your implementation to `reference/<language>/` and update the implementation matrix in [`reference/README.md`](../reference/README.md). See [CONTRIBUTING.md](../CONTRIBUTING.md) for details.
@@ -197,6 +249,6 @@ Once conformant, submit a PR to add your implementation to `reference/<language>
 
 - [CPS v1.0 Specification](../spec/) — The normative protocol spec
 - [Conformance Suite](../conformance/) — Golden test vectors
-- [Python Reference](../reference/python/) — Python implementation (conformant, 506 tests, 100% coverage)
+- [Python Reference](../reference/python/) — Python implementation (conformant, 668 tests, 100% coverage)
 - [TypeScript Reference](../reference/typescript/) — TypeScript implementation (conformant, 101 tests, 100% coverage)
 - [URI Scheme](../spec/uri-scheme.md) — Content-addressable references
diff --git a/docs/security.md b/docs/security.md
@@ -1,7 +1,7 @@
 ---
 title: "Security Evaluation Guide"
 description: "Security evaluation guide for CISOs and security teams assessing Capsule for organizational adoption. Covers cryptographic architecture, key management, tamper evidence, attack surface, and deployment."
-date_modified: "2026-03-07"
+date_modified: "2026-03-09"
 classification: "Public"
 ai_context: |
   CISO-targeted security evaluation of the Capsule package. Covers two-tier
@@ -15,7 +15,7 @@ ai_context: |
 
 **For CISOs and Security Teams Evaluating Capsule**
 
-*Capsule v1.0.0 — March 2026*
+*Capsule v1.3.0 — March 2026*
 *Classification: Public*
 
 ---
@@ -93,12 +93,27 @@ Ed25519 is always required. ML-DSA-65 is additive, never a replacement. If one a
 
 ### Key Rotation
 
-Key rotation is currently a manual process:
+<!-- VERIFIED: reference/python/src/qp_capsule/keyring.py:226-271 -->
 
-1. Stop the application
-2. Move existing keys to backup
-3. Restart the application (new keys auto-generated)
-4. Previous Capsules remain verifiable using `seal.verify_with_key(capsule, old_public_key_hex)`
+Key rotation is automated through the epoch-based keyring system, aligned with NIST SP 800-57:
+
+```bash
+capsule keys rotate    # Generate new key, retire current, update keyring. No downtime.
+```
+
+Rotation protocol:
+
+1. Generate new Ed25519 key pair using cryptographically secure random
+2. Set current epoch's status to `retired` with timestamp
+3. Add new epoch as `active`
+4. Write new private key to disk (securely replaces old)
+5. Save keyring atomically (temp file + `os.replace`)
+
+**Backward compatibility:** After rotation, Capsules signed with previous keys continue to verify. The keyring retains all retired epochs' public keys. `Seal.verify()` uses the capsule's `signed_by` fingerprint to look up the correct epoch's public key automatically.
+
+**Migration:** Existing installations without a keyring file are migrated seamlessly. On first use, the Seal or CLI creates `keyring.json` with epoch 0 for the existing key. No manual intervention required.
+
+**Automated rotation:** Schedule `capsule keys rotate` via cron for periodic rotation (e.g., every 90 days).
 
 > **Note:** HSM integration is planned for a future release. File-based key storage is appropriate for development and single-tenant deployments. For multi-tenant production deployments, ensure key directories have appropriate OS-level access controls.
 
@@ -203,7 +218,7 @@ Use this checklist when evaluating Capsule for your organization:
 | Multi-tenant isolation | Yes | PostgreSQL backend with `tenant_id` scoping |
 | Test coverage | Yes | 100% line coverage enforced in CI (`fail_under = 100`) |
 | Warning-free | Yes | `filterwarnings = ["error"]` with zero exemptions |
-| Key rotation support | Partial | Manual rotation; `verify_with_key()` for old keys; HSM planned |
+| Key rotation support | Yes | Automated via `capsule keys rotate`; epoch-based keyring with backward-compatible verification; HSM planned |
 | FIPS 140-2/3 validated module | No | Uses FIPS-approved algorithms via PyNaCl/libsodium; module itself is not FIPS-validated |
 
 ---
@@ -217,4 +232,4 @@ Use this checklist when evaluating Capsule for your organization:
 
 ---
 
-*Capsule v1.0.0 — Quantum Pipes Technologies, LLC*
+*Capsule v1.3.0 — Quantum Pipes Technologies, LLC*