stemedb/applications/aphoria/docs/guides/federating-truth.md

Guide: Federating Truth — Enterprise Scale Policy

Target Audience: Security Engineers, Platform Teams Prerequisite: The First Scan

---

Introduction

Getting one developer to fix a TLS bug is good. Preventing 500 developers from ever introducing it is better.

In a large organization, "Truth" isn't just what the RFCs say. It's also what You (the Security or Platform team) say.

• "We only use gRPC for internal APIs."
• "MD5 is allowed for file integrity, but banned for passwords."
• "All S3 buckets must block public access."

Aphoria lets you package these rules into Trust Packs and distribute them automatically.

---

1. The "Golden Repo" Strategy

Instead of writing config files from scratch, find a repo that already follows your rules. Use it as the seed for your policy.

Let's say auth-service-v2 implements authentication correctly.

cd auth-service-v2
aphoria scan .

You might see some "conflicts" that are actually correct for your org.

• Aphoria says: "BLOCK: JWT expiry is 30 days (RFC recommends 15min)"
• You know: "Actually, for our mobile app refresh tokens, 30 days is the policy."

Acknowledge it to define your truth:

$ aphoria ack "code://go/auth/jwt/expiry" --reason "Mobile refresh tokens valid for 30d per Security Policy v4.2"

2. Exporting the Trust Pack

Now you have a local database full of acknowledgments that represent your organization's specific deviations from the standard RFCs.

Export this as a portable Trust Pack:

$ aphoria policy export --name "Acme Mobile Security" --output acme-mobile.pack

This file (acme-mobile.pack) contains:

1. Your assertions ("30d expiry is OK")
2. Your digital signature (proving YOU authorized it)
3. Metadata (version, timestamp)

3. Distributing the Policy

Host the pack anywhere your developers can reach (S3, Artifactory, internal GitHub).

https://internal.acme.com/policies/acme-mobile.pack

4. Enforcing the Policy

Now, configure every new mobile project to "inherit" this truth.

Create a standard aphoria.toml for your org:

# aphoria.toml
[policies]
security = "https://internal.acme.com/policies/acme-mobile.pack"

5. The Developer Experience

When a developer on mobile-wallet-app runs a scan:

1. Aphoria downloads acme-mobile.pack.
2. It sees the developer set JWT expiry to 30 days.
3. Conflict Check:
   • Code Claim: "30 days"
   • RFC Authority: "15 mins" (Conflict!)
   • Trust Pack Authority: "30 days" (Match!)
4. Verdict: PASS.

The developer sees:

  PASS     code://go/auth/jwt/expiry
         Allowed by Policy: Acme Mobile Security (signed by @sec-team)

6. Updating the Truth

Next year, you change the policy to 14 days.

1. Update the Golden Repo.
2. Run aphoria ack with the new value.
3. aphoria policy export.
4. Upload the new pack.

Instantly, every project in the company will start failing the scan if they are still on 30 days. You didn't have to send an email. You didn't have to open 500 Jira tickets. You changed the definition of Truth, and the network adapted.

Summary

Traditional Linter	Aphoria Federated Policy
Copy-paste .eslintrc everywhere	Subscribe to a URL
Rules drift out of sync	Policies update dynamically
"Why is this an error?"	"Allowed/Blocked by [Policy Name]"
Security team is a bottleneck	Security team publishes Truth

Next: See how this applies to specialized domains in Preventing Drift in AAA Games.