🔒 Security Architecture Implementation

This PR adds comprehensive security features to the Dossier system, including integrity verification, cryptographic signatures, risk assessment, and MCP server integration.

📊 Summary

10 commits | 13 files changed | ~2,300 lines added

Phase 1: Core Security Implementation ✅

Security schema fields and validation
Signing and verification tools
Security-enhanced templates and examples
Protocol and documentation updates

Phase 2: MCP Integration ✅

MCP security verification tool
Security resources for LLM understanding
Security-first execution flow

🎯 Key Features

1. Multi-Layer Security Model

Layer 1: Integrity Verification (REQUIRED)

SHA256 checksums for all dossiers
Automatic tamper detection
BLOCKS execution if checksum fails

Layer 2: Cryptographic Signatures (OPTIONAL)

minisign-based signatures
Trust levels: VERIFIED, SIGNED_UNKNOWN, UNSIGNED, INVALID
Decentralized trust model (like Docker Hub)

Layer 3: Risk Assessment (REQUIRED)

Risk levels: low, medium, high, critical
Specific risk factors (modifies_files, requires_credentials, etc.)
Detailed destructive operations documentation
Automatic approval requests for high-risk operations

Layer 4: MCP Verification (AUTOMATIC)

verify_dossier tool for automated checks
ALLOW/WARN/BLOCK recommendations
Security-first execution flow

📝 Changes by Category

Schema Updates

dossier-schema.json: +90 lines
- checksum (REQUIRED) - SHA256 integrity
- signature (OPTIONAL) - minisign authenticity
- risk_level (REQUIRED) - risk classification
- risk_factors (OPTIONAL) - specific risks
- requires_approval (REQUIRED) - approval flag
- destructive_operations (OPTIONAL) - dangerous actions

Security Tools

tools/sign-dossier.js: +230 lines
- Calculate SHA256 checksums
- Sign with minisign
- Embed in frontmatter
- Dry-run mode, help, key management
tools/verify-dossier.js: +330 lines
- Verify integrity (checksum)
- Verify authenticity (signature)
- Check trusted keys
- Risk assessment
- ALLOW/WARN/BLOCK recommendations
- Beautiful CLI + JSON output

Templates & Examples

templates/dossier-template.md: +84 lines
- Security fields in frontmatter
- Embedded LLM execution guide
- Security documentation
examples/: +108 lines across 4 files
- deploy-to-aws.md: risk=high, cloud operations
- migrate-schema.md: risk=critical, database operations
- setup-react-library.md: risk=medium, file modifications
- train-ml-model.md: risk=medium, resource intensive

Documentation

SECURITY_ARCHITECTURE.md: +814 lines (NEW)
- Complete security design
- Implementation plan (3 phases)
- Risk classification guidelines
- Trust model explanation
- FAQ and best practices
PROTOCOL.md: +156 lines
- Security Verification Protocol (4 steps)
- Risk-based approval matrix
- Execution monitoring guidelines
- Verification tools documentation
KEYS.txt: +133 lines (NEW)
- Official public key documentation
- Trust model explanation
- Community key guidelines
- Revocation procedures
README.md: +79 lines
- Security & Trust section
- Integrity verification
- Cryptographic signatures
- Risk assessment overview
- Trust model

MCP Server Integration

mcp-server/SPECIFICATION.md: +223 lines
- verify_dossier tool specification
- dossier://security resource
- dossier://keys resource
- Security-first execution flow
- 3 detailed verification examples
mcp-server/README.md: +77 lines
- Security features overview
- Automatic verification example
- Trust model explanation
- Updated roadmap

🔐 Security Flow

Before Execution:

1. 🔒 Verify checksum (integrity)
   ❌ Mismatch → BLOCK execution

2. 🔐 Verify signature (authenticity) if present
   ✅ Verified + trusted → Proceed
   ⚠️  Unsigned/unknown → Warn user
   ❌ Invalid → BLOCK execution

3. ⚠️  Assess risk level
   High/Critical → Request approval

4. ✅ Execute if approved

MCP Integration:

// LLM calls verify_dossier tool
const verification = await verify_dossier({ path: "dossier.md" });

if (verification.recommendation === "BLOCK") {
  // DO NOT EXECUTE
  return;
}

if (verification.recommendation === "WARN") {
  // Show warning, request approval
  const approved = await askUser("Proceed? (y/N)");
  if (!approved) return;
}

// ALLOW - proceed with execution
executeDossier();

🎯 Design Decisions

Why minisign?

✅ Purpose-built for software artifacts
✅ Lightweight (~100KB vs GPG ~20MB)
✅ Simple trust model
✅ No infrastructure required
✅ Battle-tested (OpenBSD, Homebrew)

Why Decentralized Trust?

✅ Like Docker Hub - anyone can sign
✅ Users choose which keys to trust
✅ No central authority required
✅ Community-friendly

Why Optional Signatures?

✅ Integrity always checked (checksums)
✅ Warnings for unsigned dossiers
✅ Flexibility for development
✅ Path to gradual adoption

📚 Documentation

All aspects fully documented:

✅ SECURITY_ARCHITECTURE.md - Complete design
✅ PROTOCOL.md - Execution protocol
✅ KEYS.txt - Trust model
✅ README.md - Overview
✅ Tools - Help text and examples
✅ MCP Spec - Integration details

🧪 Testing

Tools tested:

✅ sign-dossier.js - Creates valid checksums and signatures
✅ verify-dossier.js - Verifies integrity and authenticity
✅ Exit codes: 0=ALLOW, 2=WARN, 1=BLOCK

Examples validated:

✅ All 4 examples have valid security metadata
✅ Risk levels appropriately assigned
✅ Destructive operations documented

🚀 Impact

For Users:

✅ Know dossiers haven’t been tampered with
✅ Verify authenticity before execution
✅ Understand risks before running
✅ Control trust relationships

For LLMs:

✅ Automatic security verification (MCP)
✅ Clear execution guidance
✅ Risk-aware execution
✅ Structured approval flow

For Authors:

✅ Sign dossiers to build trust
✅ Document risks clearly
✅ Flexible trust model

📋 Checklist

Implements SECURITY_ARCHITECTURE.md design
Follows PROTOCOL.md v1.0
Compatible with dossier-schema v1.0.0
Ready for Phase 3: MCP implementation

📸 Example Output

$ node tools/verify-dossier.js examples/devops/deploy-to-aws.md

🔍 Dossier Verification Report
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
File: examples/devops/deploy-to-aws.md
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📊 INTEGRITY CHECK (Checksum)
   ✅ Status: VALID
   Checksum matches - content has not been tampered with

🔐 AUTHENTICITY CHECK (Signature)
   ⚠️  Status: UNSIGNED
   No signature found - authenticity cannot be verified

⚠️  RISK ASSESSMENT
   🟠 Risk Level: HIGH
   Risk Factors:
     • modifies_cloud_resources
     • requires_credentials
     • network_access
   Destructive Operations:
     • Creates/updates AWS infrastructure
     • Modifies IAM roles
   Requires Approval: YES

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
⚠️  RECOMMENDATION: WARN
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

⚠️  WARNING: This dossier should be reviewed before execution.
Reasons:
  • Dossier is not signed (cannot verify author)
  • High risk level: high

Only execute if you trust the source!

Ready for review and merge! 🚀

Rendered from docs/contributing/pr-guide.md in the repository. Edit it there.