stemedb/applications/aphoria/docs/architecture/enterprise-validation.md

Enterprise Scenario Validation

Validation of: Policy Alias solution for enterprise security policy enforcement Date: 2026-02-04

---

The Enterprise Requirement

A large organization needs to:

1. Centralize security standards in a Trust Pack managed by the security team
2. Distribute the Trust Pack to 50+ development teams
3. Enforce violations at CI/CD time without per-team configuration
4. Audit compliance across all projects

Critical constraint: Dev teams cannot modify security policies. They import a signed Trust Pack.

---

Scenario Walkthrough

Step 1: Security Team Creates Standard

Golden Repo: security-standards/

cd security-standards

# Security team uses a logical hierarchy
aphoria bless \
  --subject "code://standards/tls/cert_verification" \
  --predicate "enabled" \
  --value true \
  --reason "RFC 5246 compliance - TLS certificate verification required"

Intent: "All code, regardless of language or project, must have TLS verification enabled."

Resulting Assertion:

Assertion {
    subject: "code://standards/tls/cert_verification",
    predicate: "enabled",
    object: ObjectValue::Boolean(true),
    source_class: SourceClass::Expert,  // Tier 3
    confidence: 1.0,
    // ...
}

---

Step 2: Add Policy Aliases

Security team knows dev teams use Rust, Go, and Python. Add aliases:

aphoria policy export security-standards-v1.0.pack

aphoria policy add-alias \
  --pack security-standards-v1.0.pack \
  --policy-path "code://standards/tls/cert_verification" \
  --target "code://rust/*/tls/cert_verification" \
  --target "code://go/*/tls/cert_verification" \
  --target "code://python/*/tls/cert_verification"

Trust Pack Contents:

TrustPack {
    header: PackHeader {
        name: "Acme Security Standards",
        version: "1.0.0",
        issuer_id: [0xab, 0xcd, ...],  // Security team's public key
        timestamp: 1738713600,
    },
    assertions: vec![
        Assertion {
            subject: "code://standards/tls/cert_verification",
            predicate: "enabled",
            object: ObjectValue::Boolean(true),
            source_class: SourceClass::Expert,
            // ...
        }
    ],
    aliases: vec![],
    policy_aliases: vec![
        PolicyAlias {
            policy_path: "code://standards/tls/cert_verification",
            target_patterns: vec![
                "code://rust/*/tls/cert_verification",
                "code://go/*/tls/cert_verification",
                "code://python/*/tls/cert_verification",
            ],
        }
    ],
    signature: [0x12, 0x34, ...],  // Ed25519 signature
}

---

Step 3: Distribute Trust Pack

Security team publishes the pack:

# Upload to internal artifact server
aws s3 cp security-standards-v1.0.pack \
  s3://acme-policies/security-standards-v1.0.pack --acl public-read

# Or add to internal policy registry
curl -X POST https://policy-registry.acme.com/packs \
  --data-binary @security-standards-v1.0.pack

---

Step 4: Dev Team Imports Policy

Dev Team Repo: backend-api/ (Rust service)

File: aphoria.toml

[policies]
sources = [
    "https://acme-policies.s3.amazonaws.com/security-standards-v1.0.pack"
]

Dev team runs:

aphoria scan --mode persistent

What happens:

1. Aphoria downloads security-standards-v1.0.pack
2. Verifies Ed25519 signature (ensures integrity)
3. Loads assertions and policy aliases into scan context

---

Step 5: Extractor Finds Violation

File: backend-api/src/main.rs

// Developer disabled cert verification for local testing
// and forgot to re-enable it
let client = reqwest::Client::builder()
    .danger_accept_invalid_certs(true)  // ❌ VIOLATION
    .build()?;

Rust Extractor Output:

Observation {
    concept_path: "code://rust/backend-api/tls/cert_verification",
    predicate: "enabled",
    value: ObjectValue::Boolean(false),
    file: "src/main.rs",
    line: 42,
    matched_text: "danger_accept_invalid_certs(true)",
    confidence: 0.95,
    description: "TLS certificate verification disabled",
}

---

Step 6: Conflict Detection

Scan Flow:

// scan.rs:210
let index = ConceptIndex::build(&corpus);

// local.rs:273
let auth_assertions = index.lookup_with_policy_aliases(
    "code://rust/backend-api/tls/cert_verification",  // Claim path
    "enabled",                                         // Predicate
    &policy_aliases,                                   // From Trust Pack
);

Matching Algorithm:

1. Try tail-path match:

   Claim:  "code://rust/backend-api/tls/cert_verification"
   Key:    "backend-api/tls::enabled"
   
   Policy: "code://standards/tls/cert_verification"
   Key:    "tls/cert_verification::enabled"
   
   ❌ NO MATCH (different tail segments)
   

2. Try policy alias:

   Pattern: "code://rust/*/tls/cert_verification"
   Claim:   "code://rust/backend-api/tls/cert_verification"
   
   Match segments:
     "code" == "code" ✅
     "rust" == "rust" ✅
     "*"    == "backend-api" ✅ (wildcard)
     "tls"  == "tls" ✅
     "cert_verification" == "cert_verification" ✅
   
   ✅ MATCH
   

3. Lookup using policy path:

   Lookup: "code://standards/tls/cert_verification::enabled"
   Key:    "tls/cert_verification::enabled"
   
   ✅ FOUND: Assertion with object = Boolean(true)
   

4. Compare values:

   Authoritative: true
   Code:          false
   
   ❌ CONFLICT
   

---

Step 7: Report Generation

Console Output:

┌─────────────────────────────────────────────────────────────────────┐
│ Aphoria Security Scan Report                                       │
├─────────────────────────────────────────────────────────────────────┤
│ Project: backend-api                                                │
│ Scan ID: scan-1738713600                                            │
│ Files:   42                                                         │
│ Claims:  127                                                        │
├─────────────────────────────────────────────────────────────────────┤
│ 🚫 BLOCK (1)                                                        │
├─────────────────────────────────────────────────────────────────────┤
│ src/main.rs:42                                                      │
│ code://rust/backend-api/tls/cert_verification                       │
│                                                                     │
│ Code asserts: enabled = false (confidence: 0.95)                   │
│ Authority:    enabled = true  (confidence: 1.00)                   │
│                                                                     │
│ Source: Acme Security Standards v1.0.0 (abcd1234)                  │
│ Policy: code://standards/tls/cert_verification                     │
│ Tier:   Expert (Internal Policy)                                   │
│                                                                     │
│ Matched via policy alias:                                          │
│   Pattern: code://rust/*/tls/cert_verification                     │
│                                                                     │
│ Conflict Score: 0.92 (Expert tier authority mismatch)              │
│ Verdict: BLOCK                                                      │
│                                                                     │
│ Recommendation:                                                     │
│   Remove danger_accept_invalid_certs(true) to comply with          │
│   RFC 5246 and internal security policy.                           │
└─────────────────────────────────────────────────────────────────────┘

Exit code: 1

CI/CD Pipeline:

# .github/workflows/ci.yml
- name: Security Scan
  run: |
    aphoria scan --mode persistent --exit-code
    # Fails if BLOCK verdict found    

Result: Build fails, developer must fix violation before merge.

---

Validation Checklist

Functional Requirements

• Security team can create policy with logical hierarchy (code://standards/*)
• Policy is signed and cryptographically verified
• Dev team imports policy with zero configuration (just URL in config)
• Rust extractor output (code://rust/backend-api/*) matches policy
• Conflict is detected and reported
• Report shows policy provenance (pack name, version, issuer)
• CI/CD build fails on BLOCK verdict

Security Requirements

• Trust Pack signature verification prevents tampering
• Dev team cannot modify policy (read-only import)
• Policy path is distinct from code path (clear separation)
• Alias mapping is explicit (auditable)

Usability Requirements

• Security team workflow is straightforward (3 commands)
• Dev team workflow is minimal (1 config line + scan)
• Error messages clearly identify policy source
• Pattern matching is intuitive (glob wildcards)

Performance Requirements

• Scan time increase < 5% (O(P*A) with small P and A)
• Memory overhead < 10 KB per Trust Pack
• Policy download is cached (no repeated fetches)

---

Edge Cases

Case 1: Multiple Aliases Match

Scenario: Two aliases both match the same code path.

PolicyAlias {
    policy_path: "code://standards/tls/cert_verification",
    target_patterns: vec!["code://rust/*/tls/cert_verification"],
}

PolicyAlias {
    policy_path: "code://internal/tls/verification",
    target_patterns: vec!["code://rust/backend-api/tls/cert_verification"],
}

Resolution: First match wins (aliases processed in order).

Implication: Security team should order aliases from most specific to least specific.

---

Case 2: Alias Pattern Has Typo

Scenario: Security team writes code://rust/*/tsl/cert_verification (typo: tsl not tls).

Result: Pattern never matches, no conflicts detected.

Mitigation: Validation at Trust Pack creation time (warn if pattern doesn't match any known extractors).

Future Enhancement: aphoria policy validate command to test aliases against sample code.

---

Case 3: New Language Added

Scenario: Dev team starts using Kotlin, but Trust Pack only has aliases for Rust/Go/Python.

Result: Kotlin code doesn't match, no conflicts detected.

Solution: Security team adds new alias:

aphoria policy add-alias \
  --pack security-standards-v1.1.pack \
  --policy-path "code://standards/tls/cert_verification" \
  --target "code://kotlin/*/tls/cert_verification"

Dev teams update aphoria.toml to v1.1.

Alternative: Use broader wildcard:

target_patterns: vec!["code://*/*/tls/cert_verification"]
// Matches ANY language, ANY project

---

Case 4: Policy Hierarchy Refactor

Scenario: Security team changes from code://standards/* to code://policy/security/*.

Impact: Existing aliases become invalid.

Solution: Update policy_path in Trust Pack, re-sign, publish as new version.

Mitigation: Use semantic versioning (breaking change = major version bump).

---

Comparison: Without Policy Aliases

Current Behavior (No Aliases)

Security team creates:

subject: "code://standards/tls/cert_verification"
predicate: "enabled"
object: true

Extractor produces:

concept_path: "code://rust/backend-api/tls/cert_verification"
predicate: "enabled"
object: false

Tail-path matching:

Policy key: "tls/cert_verification::enabled"
           (from "standards/tls/cert_verification")

Code key:   "backend-api/tls::enabled"
           (from "rust/backend-api/tls/cert_verification")

❌ KEYS DON'T MATCH (wrong segments extracted)

Result: No conflict detected. Developer ships insecure code. ❌

---

With Policy Aliases

Same inputs, but alias added:

PolicyAlias {
    policy_path: "code://standards/tls/cert_verification",
    target_patterns: vec!["code://rust/*/tls/cert_verification"],
}

Matching:

1. Tail-path fails (same as before)
2. Alias matches (rust/backend-api matches rust/*)
3. Lookup using code://standards/tls/cert_verification
4. Conflict detected ✅

Result: Build fails, developer fixes code before merge. ✅

---

Real-World Adoption Path

Phase 1: Pilot (Week 1-2)

• Security team creates Trust Pack with 5 critical policies
• 2-3 dev teams import and scan
• Collect feedback on alias patterns

Success Metric: All critical violations detected, 0 false positives.

Phase 2: Expansion (Week 3-4)

• Add 20 more policies (OWASP Top 10 coverage)
• Roll out to 10 more teams
• Add aliases for new languages as needed

Success Metric: 50+ dev teams importing pack, CI/CD integration stable.

Phase 3: Enforcement (Month 2)

• Make policy import mandatory in CI/CD
• Require approval for policy exceptions (aphoria ack)
• Audit compliance across all projects

Success Metric: 0 production incidents related to covered policies.

---

Conclusion

Enterprise Scenario: ✅ SOLVED

The policy alias system enables:

1. Security teams to use logical hierarchies
2. Dev teams to import policies without configuration
3. Cross-language enforcement via glob patterns
4. Cryptographic verification for trust

Key Insight: The gap wasn't in the tail-path algorithm itself - it's a design win for RFC/code matching. The gap was in enterprise policy hierarchies not aligning with extractor conventions. Policy aliases bridge that gap explicitly and auditably.

Next Step: Implement Phase 1 of the implementation plan and validate with a real enterprise security team.

---

This architecture decision is validated. Proceed with implementation.