stemedb/applications/aphoria/docs/guides/policy-audit-trails.md

Guide: Policy Audit Trails — "Who Approved This?"

Target Audience: Compliance Officers, Security Auditors, Engineering Managers Prerequisite: Federating Truth

---

The Problem: The Compliance Nightmare

It's audit season. The auditor asks:

"Show me evidence that your TLS configuration was approved by someone with authority."

You dig through Slack, Jira, and Confluence. You find a thread from 2024 where someone said "LGTM." The auditor is not impressed.

What you need is:

1. What was approved (the exact policy)
2. Who approved it (cryptographic proof)
3. When it was approved (timestamp)
4. Where it's enforced (which projects)

Aphoria's policy source tracking gives you all four.

---

How Policy Provenance Works

When you import a Trust Pack, Aphoria stores metadata for every assertion:

Field	Description	Example
pack_name	Human-readable policy name	"Acme Security Standard"
pack_version	Semver version	"2.1.0"
issuer_hex	First 8 chars of signer's public key	"a1b2c3d4"

This metadata appears in every conflict report, creating an unbroken chain from violation → policy → approver.

---

Step 1: Establish Policy Authority

Your Security team creates the authoritative policy in a dedicated repo.

cd security-policies/

# Initialize persistent storage
aphoria init

# Define policies through bless commands
aphoria bless "code://*/tls/cert_verification" enabled true \
  --reason "SOC2 CC6.1: Encrypt data in transit"

aphoria bless "code://*/secrets/api_key" storage "vault" \
  --reason "SOC2 CC6.7: Secrets must use approved vault"

aphoria bless "code://*/logging/pii" masked true \
  --reason "GDPR Art.32: PII must not appear in logs"

Step 2: Export with Versioning

Export the policy with a meaningful version that maps to your compliance cycle.

# Version matches your security policy document
aphoria export \
  --name "Acme SOC2 Controls v2.1" \
  --output acme-soc2-v2.1.pack

The .pack file contains:

• All assertions (the "what")
• Ed25519 signature (the "who" — cryptographic proof)
• Timestamp (the "when")

Step 3: Distribute to Projects

Host the pack and configure projects to use it:

# Every project's aphoria.toml
policies = ["https://security.internal/policies/acme-soc2-v2.1.pack"]

Step 4: The Audit Trail in Action

When a developer violates policy, the report shows full provenance:

┌─────────────────────────────────────────────────────────────────┐
│ BLOCK   code://go/payments/tls/cert_verification                │
├─────────────────────────────────────────────────────────────────┤
│ Location:   src/client.go:45                                    │
│ Your Code:  tls.InsecureSkipVerify = true                       │
│ Policy:     enabled = true                                      │
│                                                                 │
│ Source:     Acme SOC2 Controls v2.1 (a1b2c3d4)                 │
│ Reason:     SOC2 CC6.1: Encrypt data in transit                 │
└─────────────────────────────────────────────────────────────────┘

The auditor can now verify:

• What: TLS verification must be enabled
• Who: Key a1b2c3d4 (maps to Security Team's signing key)
• When: Pack creation timestamp in the file
• Where: This specific project imported the policy

---

Generating Compliance Reports

Export scan results as JSON for your compliance dashboard:

aphoria scan . --mode persistent --format json > compliance-scan.json

Extract policy sources for your audit evidence:

cat compliance-scan.json | jq '
  .findings[] |
  select(.verdict == "BLOCK" or .verdict == "FLAG") |
  {
    violation: .claim.concept_path,
    policy: .conflicting_sources[0].policy_source.pack_name,
    version: .conflicting_sources[0].policy_source.pack_version,
    approver: .conflicting_sources[0].policy_source.issuer_hex
  }
'

Output:

{
  "violation": "code://go/payments/tls/cert_verification",
  "policy": "Acme SOC2 Controls v2.1",
  "version": "2.1.0",
  "approver": "a1b2c3d4"
}

---

Mapping Issuer Keys to People

The issuer_hex is derived from an Ed25519 public key. Map these to real identities in your key registry:

# key-registry.yaml (maintained by Security team)
keys:
  a1b2c3d4:
    owner: "security-team@acme.com"
    name: "Security Team Signing Key"
    created: "2025-01-15"

  e5f6g7h8:
    owner: "platform-team@acme.com"
    name: "Platform Team Signing Key"
    created: "2025-03-20"

Now the auditor sees:

"Violation blocked by Acme SOC2 Controls v2.1, approved by Security Team (key a1b2c3d4)"

---

Version History for Compliance

Keep old pack versions for historical audits:

policies/
├── acme-soc2-v1.0.pack    # 2024 Q1-Q2
├── acme-soc2-v1.1.pack    # 2024 Q3-Q4
├── acme-soc2-v2.0.pack    # 2025 Q1
└── acme-soc2-v2.1.pack    # Current

If an auditor asks "What policies were in effect on March 15, 2025?", you can point to the specific pack version and its contents.

---

Summary

Audit Question	Aphoria Answer
"Who approved this policy?"	issuer_hex → Key Registry → Owner
"When was it approved?"	Pack file timestamp
"What exactly was approved?"	Assertions in the pack
"Is it still enforced?"	Current aphoria.toml policies list
"Which projects comply?"	Scan results across repos

Next: See how multiple teams can publish non-conflicting policies in Multi-Team Policy Governance.