jordan/stemedb
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
cde30b9213
stemedb/applications/aphoria/docs/guides/authoritative-state-per-project.md
jordan b3e8a9a058 feat: Multi-application expansion with chaos testing and community UI 
Major additions:
- Community Next.js app (port 18187) for browsing claims with API docs
- stemedb-chaos crate: Fault injection, chaos testing, CRDT properties
- Latent ingestion system: Reddit/FDA ingesters with ADK-Go agents
- Disputed claims handling: Manual review workflows and validation
- Aphoria security scanner: New extractors (SQL injection, command
  injection, weak crypto, TLS version), policy-based ignores, UAT reports
- Docker infrastructure: Dockerfile, docker-compose.yml for full stack
- VulnBank demo: Intentionally vulnerable multi-language test corpus

SDK & API enhancements:
- Source registry handlers for tracking data provenance
- Metrics endpoint
- Skeptic filtering improvements

Code quality:
- Split 14 large files (>500 lines) into focused modules
- All files now under 500-line limit per project guidelines

Documentation:
- Chaos testing guide, circuit breakers, observability docs
- Phase 7 UAT documentation updates
- Martin Kleppmann technical writer agent

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-02-04 01:24:14 -07:00

2.7 KiB
Raw Blame History

How-To: Declare Authoritative State Per Project

Aphoria allows organizations to define their own authoritative "truth." This means you can say: "At Acme Corp, this is how we do Auth," and Aphoria will enforce it across all your projects.

The Mechanism: Trust Packs

You don't edit the engine; you publish a Trust Pack.

1. Define Your "Truth" (The Acme Auth Policy)

You want to enforce that all authentication must happen via gRPC to auth.acme.internal.

A. Create a Policy Repo Create a repository (e.g., acme-policies) to hold your assertions.

B. Author the Assertion You can create assertions using the Aphoria CLI or by writing a policy definition file (planned feature, currently we use aphoria ack to "bless" patterns or manual ingestion).

Conceptual Workflow (Future aphoria policy author):

# policy/auth.toml
[[assertion]]
subject = "code://acme/auth/mechanism"
predicate = "protocol"
object = "grpc"
source_class = "Regulatory" # It's a hard rule for your company
confidence = 1.0
description = "All auth must use gRPC to auth.acme.internal"

Current Workflow (using ack to bootstrap): Scan a "Golden Repo" that does it right.

$ aphoria scan ./golden-auth-service
# Aphoria sees: code://go/auth/protocol = grpc
# You confirm:
$ aphoria ack "code://go/auth/protocol" --reason "This is the Acme Standard"

C. Export the Trust Pack Export your "acknowledged truth" as a portable pack.

$ aphoria policy export --name "Acme Auth Standard" --output acme-auth.pack

2. Distribute the Truth

Host the pack where your developers can reach it (S3, Artifactory, internal Git). https://internal.acme.com/policies/acme-auth.pack

3. Enforce the Truth (The Consumer)

In every project's aphoria.toml:

[policies]
# Subscribe to the company standard
auth = "https://internal.acme.com/policies/acme-auth.pack"

4. The Result

When Developer Bob tries to implement Auth using REST / HTTP:

  1. Extractor sees: code://go/auth/protocol = http
  2. Aphoria loads acme-auth.pack.
  3. Conflict Detected:
    • Code Claim: http
    • Authority (Acme Pack): grpc (Tier 0 Regulatory for this org)
  4. Verdict: BLOCK.
    • Report: "Conflict: Auth protocol must be gRPC (Source: Acme Auth Standard)"

Why this is easy

  1. No Code Changes: You didn't write a regex or a linter rule to "ban HTTP." You just asserted "Truth is gRPC." The engine handled the conflict logic.
  2. Inheritance: You can stack packs. [Global Security] + [Team Backend] + [Project Specifics].
  3. Dynamic Updates: When you update the pack (e.g., "gRPC or GraphQL are okay"), everyone's next scan picks up the new truth automatically. No plugin updates required.