jordan 41c676a78e feat: Aphoria enterprise features + ontology SDK + file length compliance

Enterprise Features:
- Hosted mode with remote sync for team pattern aggregation
- Community sharing with privacy-preserving anonymization
- LLM-based semantic claim extraction with Gemini integration
- Pattern learning with promotion to declarative extractors
- High-entropy secrets extractor with configurable thresholds
- Auth bypass and insecure cookies extractors

Module Refactoring:
- Split oversized files to comply with 500-line limit
- Config split: types/core.rs, types/extractors.rs, types/hosted.rs, etc.
- Handlers split: scan.rs, policy.rs, report.rs modules
- Extractors split: declarative/, high_entropy_secrets/, insecure_cookies/
- Learning split: store modules with metrics and persistence

SDK & Ontology:
- stemedb-ontology SDK with fluent builders and StemeDB client
- Pharma domain extractors for FDA Orange Book data
- Consumer health UAT test infrastructure

Code Quality:
- Fixed clippy warnings (needless_borrows_for_generic_args)
- Added KVStore trait imports where needed
- Fixed utoipa path re-exports for OpenAPI docs

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

2026-02-05 12:55:29 -07:00

4.6 KiB

Raw Blame History

Configure Aphoria Hosted Mode

When to use: Setting up Aphoria for team-wide observation aggregation via a central StemeDB server.

Prerequisites

Aphoria installed (cargo install --path applications/aphoria)
A running StemeDB server (for the team)
Network access to the server

Quick Start

# aphoria.toml
[hosted]
url = "https://episteme.acme.corp"

That's it. Observations now sync automatically on every scan.

Architecture

┌──────────────┐  ┌──────────────┐  ┌──────────────┐
│ Developer A  │  │ Developer B  │  │ Developer C  │
│ aphoria scan │  │ aphoria scan │  │ aphoria scan │
└──────┬───────┘  └──────┬───────┘  └──────┬───────┘
       │                 │                 │
       └─────────────────┼─────────────────┘
                         ▼
              ┌─────────────────────┐
              │ Team StemeDB Server │
              │ POST /v1/aphoria/   │
              │      observations   │
              └─────────────────────┘

Configuration Options

Minimal (recommended for most teams)

[project]
name = "billing-service"

[hosted]
url = "https://episteme.acme.corp"

Full Configuration

[project]
name = "billing-service"

[hosted]
url = "https://episteme.acme.corp"    # Required: enables hosted mode
project_id = "billing-api"             # Optional: defaults to [project.name]
team_id = "platform-team"              # Optional: for multi-team servers
sync_mode = "remote-only"              # "remote-only" | "local-and-remote"
offline_fallback = "skip"              # "skip" | "fail" | "queue"
api_key_env = "APHORIA_API_KEY"        # Env var containing auth token
max_retries = 3                        # Retry attempts on failure
retry_delay_ms = 1000                  # Delay between retries

Sync Modes

Mode	Description	When to Use
`remote-only`	Only push to server, no local storage	Single source of truth (default)
`local-and-remote`	Store locally AND push to server	Need local history for debugging

Offline Handling

Mode	Behavior	When to Use
`skip`	Warn and continue scan	Don't block developers (default)
`fail`	Abort scan with error	CI/CD where sync is mandatory
`queue`	Queue for later (not implemented)	Future offline support

Authentication

If your server requires authentication:

# Set the API key
export APHORIA_API_KEY="your-secret-token"

[hosted]
url = "https://episteme.acme.corp"
api_key_env = "APHORIA_API_KEY"  # Reads from this env var

The client sends Authorization: Bearer <token> header.

CI/CD Integration

GitHub Actions

- name: Aphoria Scan
  env:
    APHORIA_API_KEY: ${{ secrets.APHORIA_API_KEY }}
  run: aphoria scan --staged --exit-code

Pre-commit Hook

#!/bin/sh
# .git/hooks/pre-commit
aphoria scan --staged --exit-code

With hosted mode configured, observations sync automatically.

Verifying Setup

# Check config is loaded
aphoria status

# Test with verbose output
RUST_LOG=aphoria=debug aphoria scan --persist --sync

# Expected log: "Pushed N observations to hosted server"

Server Setup

Start a StemeDB server:

# Local testing
cargo run -p stemedb-api -- --bind 127.0.0.1:18180

# Production (with persistence)
stemedb-api --bind 0.0.0.0:18180 --data-dir /var/lib/stemedb

The server exposes POST /v1/aphoria/observations for receiving observations.

Troubleshooting

"Hosted sync failed, continuing"

Server is unreachable. Check:

URL is correct
Server is running
Network/firewall allows connection

"Failed to sync to hosted server" (error)

You have offline_fallback = "fail". Either:

Fix the connection issue
Change to offline_fallback = "skip" temporarily

Observations not appearing on server

Check:

url is set in [hosted] section
Scan finds novel claims (no authority conflicts)
Server logs show incoming requests

Aphoria Roadmap - Phase 4E details
ai-lookup: Aphoria Config - Config reference
API Endpoints Guide - Adding new endpoints

4.6 KiB Raw Blame History