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:

```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`