# Governance Authorization System - Architecture Plan **Classification**: INTERNAL **Date**: November 2, 2025 **Status**: Planning Phase **Security Level**: Not for public distribution ## Executive Summary This document outlines the architecture for a scalable authorization system to protect the integrity of the Tractatus Governance Framework. The current system can be bypassed via scripts - this is intentional for legitimate operations but requires proper authorization controls. **Core Principle**: Authorization complexity scales with organizational complexity. ## Problem Statement ### Current State The governance framework protects instruction-history.json via PreToolUse hooks, preventing direct modifications through Claude Code's Edit/Write tools. However, as demonstrated in session 2025-11-02: ```bash # This bypasses the governance hook cat > .claude/instruction-history.json << 'EOF' { "modified": "content" } EOF ``` **Why This Exists**: Legitimate rule updates must be possible (e.g., adding security rules). The hook protects against *accidental* violations, not *authorized* changes. **The Gap**: No authorization mechanism distinguishes legitimate from malicious bypasses. ### Security Requirements 1. **Authenticity**: Verify the actor is authorized to modify rules 2. **Authorization**: Verify the actor has permission for *this specific change* 3. **Audit Trail**: Record who approved what, when, and why 4. **Non-Repudiation**: Cryptographic proof of approval 5. **Scalability**: Single developer → multinational organization 6. **Least Privilege**: Minimum necessary access for each role ## Proposed Architecture ### 1. Vault Integration **Purpose**: Secure credential and token storage **Technology Options**: - HashiCorp Vault (enterprise-grade) - AWS Secrets Manager (cloud-native) - Azure Key Vault (Microsoft ecosystem) - Self-hosted vault (tractatus-integrated) **Vault Structure**: ``` vault/ ├── credentials/ │ ├── developers/ │ │ ├── developer1/ │ │ │ ├── totp_secret │ │ │ ├── pgp_public_key │ │ │ └── authorization_level │ │ └── developer2/... │ ├── approvers/ │ │ ├── team_leads/... │ │ ├── department_heads/... │ │ └── executives/... ├── tokens/ │ ├── active/ │ │ └── token_abc123_expiry_timestamp │ └── revoked/ │ └── audit_trail └── policies/ ├── rule_modification_requirements.json └── approval_chains.json ``` ### 2. Authorization Tiers **Tier 0: Single Developer (2FA)** - Scenario: Personal projects, small startups - Requirement: Time-based OTP (TOTP) or hardware key (YubiKey) - Approval: Self-approval with 2FA verification - Example: Family-history project current state **Tier 1: Small Team (Team Lead Approval)** - Scenario: 2-10 developers - Requirement: Developer requests, team lead approves - Approval: Team lead signs with PGP key - Example: Startup with tech lead **Tier 2: Department (Management Approval)** - Scenario: 10-50 developers across departments - Requirement: Team lead requests, department head approves - Approval: Department head + compliance review - Example: Mid-size company **Tier 3: Enterprise (Multi-Level Approval)** - Scenario: 50-500 developers - Requirement: Department → VP → CTO approval chain - Approval: Digital signatures at each level - Example: Large corporation **Tier 4: Multinational (Board/Compliance Approval)** - Scenario: 500+ developers across countries - Requirement: Regional compliance → Corporate compliance → Legal → Board - Approval: Complex approval matrix based on rule category - Example: Global enterprise with regulatory requirements ### 3. Rule Security Classification **Current State**: All rules treated equally **Proposed**: Tag each rule with security classification ```json { "id": "inst_fh_sec_001", "title": "Client-Side Storage Prohibition", "securityClassification": "INTERNAL", "modificationRequiresApproval": "TIER_1", "publicDisclosure": "SUMMARY_ONLY", "rationale": "Full implementation details could expose attack surface" } ``` **Classification Levels**: 1. **PUBLIC**: Safe for public documentation - General principles (e.g., "Multi-tenant isolation required") - No implementation details - Broad security goals 2. **INTERNAL**: Company employees only - Implementation patterns - Technology choices - Non-sensitive technical details 3. **CONFIDENTIAL**: Need-to-know basis - Specific security controls - Vulnerability mitigations - Integration details 4. **RESTRICTED**: Executive/Compliance only - Vault integration details - Cryptographic key management - Incident response procedures 5. **SECRET**:極秘 (Highest classification) - Master keys - Emergency override procedures - Security vulnerability details before patches ### 4. Authorization Workflow #### Scenario: Developer Needs to Add Security Rule **Step 1: Request Initiation** ```bash # Developer runs authorization request tool ./scripts/governance/request-rule-modification.sh \ --action add \ --rule-id inst_fh_sec_014 \ --justification "Add XSS prevention rule per security audit" \ --urgency normal # Output: # Request ID: REQ-2025-11-02-001 # Required Approval: TIER_1 (Team Lead) # Token will be generated upon approval ``` **Step 2: Approval Chain** ```bash # Team lead reviews request ./scripts/governance/review-request.sh --request-id REQ-2025-11-02-001 # Shows: # - Proposed rule changes (diff) # - Justification # - Risk assessment # - Related rules affected # Team lead approves with PGP signature ./scripts/governance/approve-request.sh \ --request-id REQ-2025-11-02-001 \ --pgp-sign \ --comments "Approved - aligns with security policy" ``` **Step 3: Token Generation** ```bash # System generates time-limited authorization token # Token stored in vault with: # - Request ID # - Approver signature # - Expiry timestamp (e.g., 1 hour) # - Allowed operation (add rule inst_fh_sec_014 only) # Developer receives token # Token: GOVAUTH_REQ2025110201_EXP20251102T1200_SIG_abc123def456 ``` **Step 4: Authorized Modification** ```bash # Developer uses token to modify rules ./scripts/governance/add-rule-authorized.sh \ --token GOVAUTH_REQ2025110201_EXP20251102T1200_SIG_abc123def456 \ --rule-file new-rule-inst_fh_sec_014.json # Script validates: # 1. Token signature (PGP verify) # 2. Token not expired # 3. Token not revoked # 4. Operation matches token scope # 5. Vault confirms token validity # If valid, modifies instruction-history.json # Logs to GovernanceAuditLog with approval chain ``` **Step 5: Audit Trail** ```javascript // GovernanceAuditLog entry { sessionId: "session-2025-11-02-xyz", timestamp: "2025-11-02T11:45:00Z", service: "AuthorizedRuleModification", operation: "add_rule", ruleId: "inst_fh_sec_014", requestId: "REQ-2025-11-02-001", requester: "developer@company.com", approvers: [ { name: "teamlead@company.com", role: "TIER_1_APPROVER", signature: "PGP_SIGNATURE_HASH", timestamp: "2025-11-02T11:30:00Z" } ], tokenUsed: "GOVAUTH_REQ2025110201_...", justification: "Add XSS prevention rule per security audit", evidence: { beforeHash: "sha256_of_instruction_history_before", afterHash: "sha256_of_instruction_history_after", diff: "git diff output" } } ``` ### 5. Emergency Override System **Purpose**: Critical security fixes when normal approval chain too slow **Requirements**: - Break-glass mechanism - Multi-signature required (2 of 3 executives) - Automatic incident report - Post-incident review mandatory **Process**: ```bash # Emergency override request ./scripts/governance/emergency-override.sh \ --severity CRITICAL \ --vulnerability CVE-2025-XXXXX \ --justification "Zero-day exploit in production" \ --rule-id inst_fh_sec_015 # Requires 2 of 3 executive signatures within 15 minutes # If approved, generates 15-minute token # Automatically creates incident report # Schedules post-incident review meeting ``` ### 6. Approval Chain Configuration **File**: `.claude/governance/approval-chains.json` ```json { "organizationTier": "TIER_1", "approvalChains": { "ruleModification": { "add": { "securityClassification": { "PUBLIC": ["SELF_2FA"], "INTERNAL": ["TEAM_LEAD"], "CONFIDENTIAL": ["TEAM_LEAD", "DEPARTMENT_HEAD"], "RESTRICTED": ["DEPARTMENT_HEAD", "CTO", "COMPLIANCE"], "SECRET": ["CTO", "COMPLIANCE", "CEO", "LEGAL"] } }, "modify": { "securityClassification": { "PUBLIC": ["TEAM_LEAD"], "INTERNAL": ["TEAM_LEAD", "DEPARTMENT_HEAD"], "CONFIDENTIAL": ["DEPARTMENT_HEAD", "CTO"], "RESTRICTED": ["CTO", "COMPLIANCE", "LEGAL"], "SECRET": ["BOARD_APPROVAL"] } }, "delete": { "securityClassification": { "PUBLIC": ["TEAM_LEAD", "COMPLIANCE"], "INTERNAL": ["DEPARTMENT_HEAD", "COMPLIANCE"], "CONFIDENTIAL": ["CTO", "COMPLIANCE"], "RESTRICTED": ["CTO", "COMPLIANCE", "LEGAL"], "SECRET": ["BOARD_APPROVAL", "LEGAL"] } } }, "emergencyOverride": { "required": ["EXECUTIVE_1", "EXECUTIVE_2"], "outOf": 3, "timeWindow": "15_MINUTES", "postIncidentReview": "MANDATORY" } }, "approvers": { "TEAM_LEAD": ["teamlead@company.com"], "DEPARTMENT_HEAD": ["depthead@company.com"], "CTO": ["cto@company.com"], "COMPLIANCE": ["compliance@company.com"], "LEGAL": ["legal@company.com"], "CEO": ["ceo@company.com"], "EXECUTIVE_1": ["exec1@company.com"], "EXECUTIVE_2": ["exec2@company.com"], "EXECUTIVE_3": ["exec3@company.com"] }, "vault": { "provider": "hashicorp", "endpoint": "https://vault.company.internal:8200", "authMethod": "ldap", "tokenTTL": "1h", "maxTokenUses": 1 } } ``` ### 7. Documentation Security Tiers **Problem**: Some documentation should never be public **Solution**: Multi-tier documentation system **Directory Structure**: ``` docs/ ├── public/ # Safe for GitHub, website │ ├── README.md │ ├── GETTING_STARTED.md │ └── governance/ │ └── PRINCIPLES.md # Broad principles only ├── internal/ # Company employees only │ ├── IMPLEMENTATION.md │ ├── ARCHITECTURE.md │ └── governance/ │ └── RULE_CATALOG.md ├── confidential/ # Need-to-know (not in git) │ ├── VAULT_INTEGRATION.md │ ├── APPROVAL_WORKFLOWS.md │ └── governance/ │ └── SECURITY_CONTROLS.md └── restricted/ # Executive/Compliance (vault-stored) ├── EMERGENCY_PROCEDURES.md ├── INCIDENT_RESPONSE.md └── governance/ └── MASTER_KEY_MANAGEMENT.md ``` **Git Configuration**: ```gitignore # .gitignore docs/confidential/ docs/restricted/ .claude/governance/approval-chains.json # Contains real emails/roles .claude/governance/vault-config.json ``` **Vault Storage**: Confidential and Restricted docs stored in vault, retrieved only by authorized users ### 8. Implementation Phases #### Phase 1: Foundation (Weeks 1-2) - [ ] Design vault schema - [ ] Create authorization token system - [ ] Implement PGP signature verification - [ ] Add securityClassification field to schema v3.0 - [ ] Create approval-chains.json template #### Phase 2: Core Authorization (Weeks 3-4) - [ ] Implement request-rule-modification.sh - [ ] Implement review-request.sh - [ ] Implement approve-request.sh - [ ] Implement add-rule-authorized.sh - [ ] Integrate with GovernanceAuditLog #### Phase 3: Vault Integration (Weeks 5-6) - [ ] Set up HashiCorp Vault (or alternative) - [ ] Configure LDAP/OAuth integration - [ ] Implement token generation/validation - [ ] Create vault CLI wrapper scripts - [ ] Migrate existing credentials to vault #### Phase 4: Multi-Tier Support (Weeks 7-8) - [ ] Implement approval chain engine - [ ] Support TIER_0 through TIER_4 - [ ] Add emergency override system - [ ] Create admin dashboard for approval management - [ ] Testing across all tiers #### Phase 5: Documentation Security (Weeks 9-10) - [ ] Categorize existing documentation - [ ] Move confidential docs to vault - [ ] Create public-safe versions of sensitive docs - [ ] Implement documentation access controls - [ ] Update platform-admin hub to respect classification ### 9. Technology Stack **Vault**: HashiCorp Vault - Industry standard - Excellent API - Dynamic secrets support - Audit logging built-in **Signatures**: GnuPG (PGP) - Cryptographic non-repudiation - Widely adopted - Offline signing support - Air-gap capable for highest security **2FA**: TOTP (Time-based OTP) - Standards-based (RFC 6238) - Works offline - Compatible with Google Authenticator, Authy, etc. - No phone/SMS dependency **Audit**: MongoDB GovernanceAuditLog - Already in use - Supports complex queries - Immutable append-only with proper configuration - Easy integration with existing framework **Token Format**: JWT (JSON Web Tokens) - Self-contained - Cryptographically signed - Expiry built-in - Industry standard ### 10. Security Considerations **Attack Vectors to Mitigate**: 1. **Token Theft**: - Mitigation: Short TTL (1 hour), single-use tokens 2. **Replay Attacks**: - Mitigation: Nonce in token, vault tracks used tokens 3. **Man-in-Middle**: - Mitigation: TLS for vault communication, PGP signatures 4. **Insider Threat**: - Mitigation: Multi-party approval, audit trails, least privilege 5. **Compromised Approver**: - Mitigation: Multi-signature for sensitive operations 6. **Social Engineering**: - Mitigation: Out-of-band verification for high-risk changes 7. **Script Injection**: - Mitigation: Validate all inputs, sanitize rule content 8. **Vault Compromise**: - Mitigation: Hardware security module (HSM) for master keys **Defense in Depth**: - Multiple approval levels - Cryptographic signatures - Audit logging - Time-limited tokens - Single-use tokens - Anomaly detection - Incident response procedures ### 11. Public Documentation Guidelines **What to Include in Public Docs**: - ✅ General governance principles - ✅ Rule categories and purposes - ✅ Benefits of framework - ✅ How to get started - ✅ Example rules (non-sensitive) **What to EXCLUDE from Public Docs**: - ❌ Vault integration details - ❌ Authorization token formats - ❌ Approval chain specifics - ❌ Emergency override procedures - ❌ Specific security controls - ❌ Cryptographic key details - ❌ Script bypass techniques **Public Documentation Template**: ```markdown # Governance Framework Authorization The Tractatus Framework includes enterprise-grade authorization controls for rule modifications. The system scales from individual developers to multinational organizations. ## Key Features - **Multi-tier approval**: Configurable approval chains - **Cryptographic verification**: Non-repudiation of approvals - **Audit trails**: Complete record of all changes - **Vault integration**: Secure credential storage ## Getting Started Contact your system administrator to configure authorization for your organization. For implementation details, see internal documentation. ``` ### 12. Migration Path for Existing Projects **Current State**: No authorization (bypass via scripts possible) **Target State**: Full vault-based authorization **Migration Steps**: 1. **Phase 0: Audit** (Week 1) - Identify all scripts that modify instruction-history.json - Document current access patterns - Assess organization tier (TIER_0 through TIER_4) 2. **Phase 1: Soft Enforcement** (Weeks 2-3) - Add authorization checks to scripts (warn, don't block) - Educate developers on new process - Set up vault infrastructure 3. **Phase 2: Hard Enforcement** (Week 4) - Convert warnings to errors - Require authorization tokens - Grandfather existing rules 4. **Phase 3: Full Compliance** (Week 5+) - All modifications require authorization - Regular audit reviews - Continuous monitoring ### 13. Metrics and Monitoring **Key Metrics**: - Authorization request response time - Approval chain completion rate - Token expiry without use (indicates friction) - Emergency override frequency - Audit log coverage **Alerts**: - Unauthorized modification attempt - Token reuse detected - Approval chain timeout - Emergency override used - Vault connectivity issues **Dashboard Widgets** (for platform-admin hub): - Pending authorization requests - Recent rule modifications - Approval chain health - Security classification distribution - Token usage patterns ## Recommendations ### For Family-History Project (Current) **Recommended Tier**: TIER_0 (Single Developer with 2FA) **Immediate Actions**: 1. Set up TOTP for John G Stroh 2. Create simple 2FA wrapper for rule modification scripts 3. Add securityClassification field to existing rules 4. Move to TIER_1 if additional developers join ### For Platform-Admin Hub **Recommended Features**: 1. Authorization request dashboard 2. Pending approvals view 3. Audit trail visualization 4. Documentation classification viewer ### For Tractatus Framework **Enhancements Needed**: 1. Add securityClassification to schema v3.0 2. Create authorization subsystem 3. Vault integration module 4. Public documentation sanitization tools ## Conclusion This authorization system provides: - **Scalability**: Single developer → multinational org - **Security**: Multiple layers of protection - **Auditability**: Complete non-repudiable trail - **Flexibility**: Configurable approval chains - **Compliance**: Meets enterprise requirements The system maintains the balance between: - **Accessibility**: Legitimate changes possible - **Security**: Unauthorized changes prevented - **Usability**: Not overly burdensome - **Transparency**: Public disclosure carefully managed **Next Steps**: Begin Phase 1 implementation with vault setup and token system. --- **Classification**: INTERNAL **Author**: Claude (Anthropic) under direction of John G Stroh **Review Required**: Before any public disclosure **Related Documents**: - `docs/GOVERNANCE_FRAMEWORK.md` (public version) - `docs/SCHEMA_V3_SPECIFICATION.md` - `.claude/instruction-history.json`