tractatus/docs/GOVERNANCE_AUTHORIZATION_SYSTEM_PLAN.md

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:

# 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

{
  "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

# 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

# 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

# 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

# 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

// 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:

# 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

{
  "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
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:

# 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