tractatus/docs/DOCUMENT_SECURITY_GOVERNANCE.md

# Document Security Governance Controls

**Date:** 2025-10-08
**Created in response to:** Accidental public deployment of sensitive documentation
**Status:** IMPLEMENTED

---

## Incident Summary

**What happened:**
- Security Audit Report, Koha Stripe Setup Guide, and Koha Production Deployment Guide were imported and deployed to production
- These documents contained sensitive information (credentials, vulnerabilities, payment setup, infrastructure details)
- Documents were marked `public: true` and `audience: 'technical'`
- No security validation occurred before deployment

**Root cause:**
- No distinction between `audience` (who it's FOR) and `visibility` (who can ACCESS it)
- Framework components (BoundaryEnforcer, MetacognitiveVerifier) didn't have rules for document security
- Import script lacked security classification logic

---

## Solution Architecture

### 1. Document Visibility Model

**NEW: Three-tier visibility system**

```javascript
visibility: 'public'        // Accessible via public API
visibility: 'internal'      // Only accessible to authenticated users
visibility: 'confidential'  // Restricted access, high sensitivity
```

**Separate from audience:**
```javascript
audience: 'technical'  // WHO it's written for
visibility: 'internal' // WHO can access it
```

**Example:**
- API documentation: `audience: 'technical'`, `visibility: 'public'` ✅
- Security audit: `audience: 'technical'`, `visibility: 'confidential'` ✅
- Deployment guide: `audience: 'technical'`, `visibility: 'internal'` ✅

### 2. Security Classification Metadata

**NEW: Automatic content analysis**

```javascript
security_classification: {
  contains_credentials: boolean,
  contains_financial_info: boolean,
  contains_vulnerability_info: boolean,
  contains_infrastructure_details: boolean,
  requires_authentication: boolean
}
```

**Automated keyword detection:**
- Credentials: password, api_key, secret, token, mongodb_uri, stripe_secret
- Financial: stripe, payment, pricing, revenue, cost, billing
- Vulnerabilities: security audit, vulnerability, exploit, cve-
- Infrastructure: deployment, server, ssh, production environment, database credentials

### 3. Pre-Import Security Validation

**NEW: validate-document-security.js**

**Blocks import if:**
- Document contains credentials AND visibility is 'public' → ❌ BLOCKED
- Document contains vulnerabilities AND visibility is 'public' → ❌ BLOCKED

**Warns if:**
- Document contains financial info AND visibility is 'public' → ⚠️ WARNING
- Document contains infrastructure details AND visibility is 'public' → ⚠️ WARNING

**Example output:**
```bash
$ node scripts/validate-document-security.js "Security Audit Report" docs/SECURITY_AUDIT_REPORT.md

🔒 Security Validation: Security Audit Report
────────────────────────────────────────────────────────────

ISSUES:
  ❌ BLOCKED: Document contains credentials but is marked public
  ❌ BLOCKED: Document contains vulnerability information but is marked public

WARNINGS:
  ⚠️  WARNING: Document contains infrastructure details but is marked public
  ⚠️  RECOMMEND: Change visibility from 'public' to 'confidential'

CLASSIFICATION:
  Credentials: true
  Financial Info: false
  Vulnerabilities: true
  Infrastructure: true
  Recommended: confidential

────────────────────────────────────────────────────────────
❌ VALIDATION FAILED
```

### 4. Updated Import Script

**NEW: Automatic security checks in import-technical-docs.js**

```javascript
// Security validation before import
const securityCheck = validateDocumentSecurity(docConfig, content_markdown);

if (!securityCheck.valid) {
  console.log(`  ❌ SECURITY VALIDATION FAILED`);
  errors++;
  continue; // Block import
}

// Store classification with document
const document = await Document.create({
  title: docConfig.title,
  visibility: docConfig.visibility || 'public',
  security_classification: securityCheck.classification,
  // ...
});
```

**Documents now require explicit visibility:**
```javascript
{
  file: 'docs/claude-code-framework-enforcement.md',
  visibility: 'public', // ✅ EXPLICIT
  // ...
}
```

**Sensitive docs removed from import list:**
```javascript
// REMOVED: Security Audit, Koha Stripe Setup, Koha Deployment
// These documents contain sensitive information and should NOT be public
```

### 5. API Filter Updates

**NEW: documents.controller.js filters by visibility**

```javascript
// Build filter - only show public documents (not internal/confidential)
const filter = {
  $or: [
    { visibility: 'public' },
    { public: true, visibility: { $exists: false } } // Legacy support
  ]
};
```

**Public API endpoints:**
- `/api/documents` → Only returns `visibility: 'public'` documents
- `/api/documents?audience=technical` → Only returns `visibility: 'public'` AND `audience: 'technical'`

**Internal documents:** Require authentication (future implementation)

### 6. Framework Instruction

**NEW: inst_012 - Document Security Requirement**

**Classification:**
- Quadrant: SYSTEM
- Persistence: HIGH
- Temporal Scope: PERMANENT
- Verification: MANDATORY

**Text:**
> "NEVER deploy documents marked 'internal' or 'confidential' to public production without explicit human approval. Documents containing credentials, security vulnerabilities, financial information, or infrastructure details MUST NOT be publicly accessible."

**Enforcement:** CrossReferenceValidator should check this before any document deployment

### 7. Pre-Action Check

**NEW: Action type `document-deployment`**

```bash
node scripts/pre-action-check.js document-deployment "Import technical docs to production"
```

**Requirements:**
- BoundaryEnforcer must have been used (security decision)
- CrossReferenceValidator must have checked instructions (inst_012)

---

## Usage Guidelines

### For Developers: Importing Documents

**1. Classify document visibility:**
```javascript
{
  file: 'docs/my-doc.md',
  title: 'My Document',
  audience: 'technical',        // Who it's for
  visibility: 'public',         // Who can access it
  // ...
}
```

**2. Run security validation:**
```bash
node scripts/validate-document-security.js "My Document" docs/my-doc.md
```

**3. If validation passes, add to TECHNICAL_DOCS array:**
```javascript
const TECHNICAL_DOCS = [
  {
    file: 'docs/my-doc.md',
    visibility: 'public', // ✅ REQUIRED
    // ...
  }
];
```

**4. Run import:**
```bash
node scripts/import-technical-docs.js
```

### For Developers: Deploying to Production

**1. Verify no internal/confidential docs in import list:**
```bash
grep -A 5 "visibility:" scripts/import-technical-docs.js
```

**2. Run pre-action check:**
```bash
node scripts/pre-action-check.js document-deployment "Deploy docs to production"
```

**3. Check CrossReferenceValidator against inst_012:**
- Are any documents marked 'internal' or 'confidential'?
- If yes → BLOCKED (requires explicit human approval)
- If no → Proceed

**4. Deploy only after validation passes**

### Content Guidelines

**Mark as `visibility: 'public'` if:**
- General framework documentation
- API reference guides
- Implementation tutorials
- Case studies (anonymized)
- Blog posts

**Mark as `visibility: 'internal'` if:**
- Deployment procedures
- Infrastructure setup guides
- Team processes
- Internal roadmaps
- Non-sensitive financial data

**Mark as `visibility: 'confidential'` if:**
- Security audits or vulnerability reports
- API keys, secrets, credentials
- Payment processor setup (Stripe keys, etc.)
- Database connection strings
- Sensitive financial information
- Production environment details

---

## Framework Integration

### BoundaryEnforcer

**Triggers on:**
- Document import with `visibility: 'internal'` or `visibility: 'confidential'`
- Deployment scripts that include document operations

**Required action:**
- Verify inst_012 (no public deployment of sensitive docs)
- Require human approval if overriding

### CrossReferenceValidator

**Checks:**
- Before document deployment: Scan for conflicts with inst_012
- Before modifying Document model: Verify visibility enforcement

### MetacognitiveVerifier

**Triggers on:**
- Complex document operations (>3 files, multiple visibility levels)
- First-time deployment of new document categories

**Required verification:**
- "What are the security consequences of this deployment?"
- "Are there alternative approaches with lower risk?"
- "What validation steps are needed?"

---

## Testing

### Test Cases

**1. Security Validation - Credentials**
```bash
node scripts/validate-document-security.js "Test Doc" <(echo "stripe_secret_key=sk_live_123")
# Expected: ❌ BLOCKED
```

**2. Security Validation - Vulnerabilities**
```bash
node scripts/validate-document-security.js "Security Audit" <(echo "CVE-2024-1234 vulnerability found")
# Expected: ❌ BLOCKED
```

**3. Import with Security Block**
```bash
# Add doc with credentials and visibility: 'public' to TECHNICAL_DOCS
node scripts/import-technical-docs.js
# Expected: Document blocked, errors++
```

**4. API Visibility Filter**
```bash
curl "https://agenticgovernance.digital/api/documents?audience=technical"
# Expected: Only documents with visibility: 'public'
```

---

## Recovery Procedures

### If Sensitive Document Accidentally Deployed

**1. Immediate removal:**
```bash
ssh production
mongosh tractatus_prod --eval "db.documents.deleteOne({slug: 'sensitive-doc-slug'})"
```

**2. Verify removal:**
```bash
curl "https://agenticgovernance.digital/api/documents?limit=100" | jq '.documents[].title'
```

**3. Update import script:**
```javascript
// Remove document from TECHNICAL_DOCS array
// OR change visibility to 'internal' or 'confidential'
```

**4. Document incident:**
- Add to instruction-history.json notes
- Update this governance document
- Review security classification keywords

---

## Maintenance

### Quarterly Review

**Check:**
- Security classification keywords still comprehensive?
- Any new document categories requiring governance?
- Framework components detecting document security issues?

### After Security Incidents

**Update:**
- Add new keywords to SECURITY_KEYWORDS
- Review inst_012 for additional requirements
- Enhance validation logic if needed

---

## References

- Document Model: `src/models/Document.model.js`
- Security Validation: `scripts/validate-document-security.js`
- Import Script: `scripts/import-technical-docs.js`
- Documents Controller: `src/controllers/documents.controller.js`
- Instruction: `.claude/instruction-history.json` (inst_012)
- Pre-Action Check: `scripts/pre-action-check.js`

---

**Last Updated:** 2025-10-08
**Next Review:** 2026-01-08