Aegis Latent Core

AI governance and evidence gateway for multi-provider LLM applications.

Aegis Latent Core is an OpenAI-compatible gateway that applies request policy, WAF, egress, rate-limit, and session controls before forwarding traffic to an upstream model provider. For governed traffic, it builds a canonical evidence record, signs the record, commits it to a durable write-ahead log, and exposes the evidence status to the caller. Optional response enrichment runs behind a bounded queue and is never a substitute for the authoritative evidence commit.

Product boundary: Aegis is an AI Governance and Evidence Gateway. It is not an LLM, a universal WAF, a compliance certification, a legal-admissibility ruling, a production SLO, or a replacement for network, identity, privacy, retention, or incident-response controls.

Last verified: 2026-08-25 UTC Release baseline: published v3.1.0 Merged-source baseline: 2050a310ec295afc61d033ff842c9a535a4f3105 (PR #112; fourteen version anchors synchronized at 4.0.0)

Baselines and claim scope

The immutable public release baseline is v3.1.0. Commit 2050a310ec295afc61d033ff842c9a535a4f3105 is the merged v4 source baseline; its source release contract reports all fourteen version anchors synchronized at 4.0.0. Streaming SSE with bounded pending-terminal evidence, native Anthropic POST /v1/messages, the Python and TypeScript SDKs, portable MMR proofs, the forensic dashboard and ZIP export, the auxiliary RustWal stream segment, and the SSE benchmark are merged-source capabilities; they are not attributed to the v3.1.0 tag.

The merged source remains unreleased and unpublished. At the 2026-08-25 audit there was no v4.0.0 tag, GitHub Release, PyPI publication, or npm publication. Release evidence and source implementation evidence must be evaluated separately. The release-readiness checker evaluates source contracts only: it does not prove a tag, GitHub environment approval, signer trust path, registry policy, artifact attestation, multi-architecture runtime, or external acceptance.

Who should evaluate Aegis

Aegis is intended for platform, application-security, and AI-engineering teams operating more than one model provider or requiring provider-independent evidence for governed AI traffic. The initial commercial focus is B2B SaaS, fintech, and regulated enterprise platform teams that need private deployment and verifiable evidence but are not asking this repository to become a universal authorization or certification product.

The relevant buyer committee typically includes the CISO or AppSec owner, platform engineering, AI/ML engineering, compliance or legal, procurement, and an executive sponsor. The recommended proof sequence is local evaluation → evidence replay → controlled pilot → security review → procurement package → production rollout.

The problem Aegis addresses

Standard access logs can show that an API call occurred. They do not, by themselves, establish the exact governed request and response hashes, the policy path, the evidence commit boundary, the signing scheme, the chain predecessor, or whether the request was rejected before or after the evidence boundary. Aegis makes those transitions explicit and verifiable under declared deployment controls.

Request and evidence lifecycle

sequenceDiagram
    participant C as Client
    participant A as Aegis Gateway
    participant W as Policy/WAF/Egress
    participant U as Upstream Model
    participant L as Signed WAL
    participant Q as Bounded Enrichment

    C->>A: Authenticated OpenAI-compatible or Anthropic request
    A->>W: Size, canonicalization, WAF, session, rate-limit
    W-->>C: Fail-closed response + durable error evidence when rejected
    W->>U: Forward only after admission
    U-->>A: Complete response or bounded SSE events
    A->>L: Non-stream: hash, sign, append, flush, fsync
    L-->>A: Non-stream durable evidence status
    A->>Q: Optional bounded response analysis
    A-->>C: Non-stream response + portable MMR proof headers
    A-->>C: Stream events through bounded queue
    A->>L: Stream terminal summary, sign, append, flush, fsync
    L-->>A: Terminal commit complete
    A-->>C: Protocol terminal marker

The strict lifecycle is:

1. Authenticate the caller and assign a request identifier.
2. Enforce request-size bounds and canonicalize the request representation.
3. Apply WAF, session-behavior, egress, and rate-limit controls.
4. Reject on a required-control failure instead of silently weakening the security path.
5. Forward to the configured upstream provider.
6. For non-streaming calls, capture the response, compute canonical hashes, sign the evidence, append to the WAL, flush, and fsync before returning it.
7. For SSE calls, relay sanitized logical events through a byte-accounted bounded queue. Incrementally hash the exact emitted bytes; on termination, commit one signed terminal summary before emitting the protocol terminal marker. The initial streaming header is therefore X-Aegis-Evidence-Status: pending-terminal, not durable.
8. Run optional response enrichment through a bounded worker path after the authoritative record exists.

Core contract

Quickstart for local evaluation

The local path is for development, tests, and evidence replay. It is not a production deployment profile.

git clone https://github.com/JuanLunaIA/aegis-latent-core.git
cd aegis-latent-core
python3 -m venv .venv
. .venv/bin/activate
python -m pip install --require-hashes -r requirements.lock
python -m pip install --no-deps -e .
python -m compileall -q aegis aegis_server
pytest -q

For a minimal source-checkout gateway, use the declared aegis console entry point with a local or mocked upstream:

export AEGIS_SECURITY_ENFORCEMENT_MODE=development
export AEGIS_DEBUG_MODE=true
export AEGIS_AUTH_DISABLED=true
export AEGIS_BACKEND_URL='http://127.0.0.1:9001/v1'
export AEGIS_WAL_PATH='/tmp/aegis-evaluation.wal.jsonl'
aegis

development is the only accepted non-strict mode in the current settings model; the older permissive value and uvicorn aegis.main:app command are stale. Never put provider keys, bearer tokens, signing secrets, WAL records, or customer payloads into source control.

Merged-source SDKs

The merged-source Python distribution in sdk/python is a drop-in integration that subclasses the official OpenAI and Anthropic clients. Existing request/response model types and sync/async resource APIs are preserved while Aegis tenant, session, and bearer-auth headers are injected at construction. The native Anthropic /v1/messages ingress requires AEGIS_PROVIDER=anthropic; it preserves the Anthropic Messages response shape instead of translating it to OpenAI objects.

The edge-compatible merged-source TypeScript package in sdk/typescript verifies aegis-mmr-inclusion-v1 proofs with Web Crypto and supplies provider-native wrappers and constructor options rather than re-declaring provider payloads. The official OpenAI and Anthropic packages are peer dependencies, so their native resources, request parameters, response models, streaming iterators, retries and error types remain authoritative. Both SDKs consume the same frozen proof vectors under sdk/shared/.

The unreleased Python SDK candidate also includes privacy-minimized LangChain and LlamaIndex callback adapters. Publication workflows are disabled unless external trusted-publisher, environment, signed-tag, and repository-variable prerequisites are configured. See docs/DEVELOPER_INTEGRATIONS_GUIDE.md.

from aegis_sdk.openai import OpenAI

client = OpenAI(
    aegis_api_key="gateway-token",
    gateway_url="https://aegis.internal",
    tenant_id="tenant-42",
)
response = client.chat.completions.create(
    model="gpt-4.1-mini",
    messages=[{"role": "user", "content": "hello"}],
)

Proof verification is opt-in because callers must obtain the trusted MMR root through an independently approved channel. Enabling verification while trusting the root from the same untrusted response would detect corruption but would not provide an independent trust anchor.

Merged-source forensic audit dashboard

The merged-source dashboard is a read-only Next.js 16 and React 19 interface. It renders only authenticated gateway data: overview health, a filterable retained-window ledger, canonical JCS and DAG-CBOR node projections with CIDv1 identifiers, an interactive MMR verifier with a local Web Crypto sandbox, live Prometheus-derived metrics, and a bounded forensic export workflow. It contains no fallback sample data.

cd sdk/typescript && npm ci && npm run build
cd ../../dashboard && npm ci
export AEGIS_PRIMARY_BASE_URL='https://aegis.internal'
export AEGIS_DASHBOARD_API_KEY='retrieve-from-your-secret-manager'
npm run dev

AEGIS_DASHBOARD_API_KEY is server-only and is never serialized into browser bundles. The export endpoint requires the audit:export scope when per-key scopes are configured. Each bounded ZIP contains an RFC 8785 JCS manifest.json, canonical DAG-CBOR ledger_slice.cbor identified by CIDv1, merkle_proof.json, audit_certificate.pdf, and VERIFY.sh. The certificate is a technical integrity report, not a certification or legal-admissibility conclusion.

Strict deployment path

Strict mode is the intended production posture. It requires authentication, durable evidence, strong signing, bounded request bodies, a distributed rate-limit backend, durable storage, and the configured kernel controls. Use a secret manager and mount the WAL on a durable, owner-readable path.

export AEGIS_SECURITY_ENFORCEMENT_MODE=strict
export AEGIS_API_KEYS='replace-with-a-secret-manager-reference'
export AEGIS_SIGNING_KEY='at-least-32-bytes-of-secret-material'
export AEGIS_RATE_LIMIT_BACKEND=redis
export AEGIS_REDIS_URL='rediss://redis.internal:6380/0'
export AEGIS_REQUIRE_DISTRIBUTED_LIMITER=true
export AEGIS_REQUIRE_DURABLE_EVIDENCE=true
export AEGIS_REQUIRE_LSM=true
export AEGIS_REQUIRE_SECCOMP=true
export AEGIS_MAX_REQUEST_BODY_BYTES=1048576
export AEGIS_BACKEND_URL='https://llm.internal.example/v1'
export AEGIS_WAL_PATH='/var/lib/aegis/aegis.wal.jsonl'

For zero-restart HMAC rotation, configure an owner-readable keyring path instead of relying on a single process-start secret:

export AEGIS_SIGNER_PROVIDER=hmac
export AEGIS_HMAC_KEYRING_PATH='/var/lib/aegis/secrets/hmac-keyring.json'
export AEGIS_HMAC_KEYRING_RELOAD_INTERVAL_S=1

The keyring protocol, overlap window, expiry, rollback, and three-replica acceptance criteria are in docs/operations/KEY_ROTATION_RUNBOOK.md. A keyring path is not a secret manager; the deployment must still establish custody, access control, atomic delivery, backup, destruction, and auditability.

Evidence and signing model

The local ledger is an append-only JSONL WAL with an in-memory bounded chain and optional archived segments. Each record contains request and response hashes, chain linkage, a Merkle root, signature metadata, and the request identifier. The WAL is flushed and synchronized before the durable response path completes.

Supported signing choices are deployment-dependent:

Aegis does not fabricate ML-DSA signatures when the native backend is unavailable. It reports the backend as unavailable and requires an explicit real fallback policy. A timing result with p > 0.05 would mean only that statistically significant leakage was not detected under the named experiment; it would not prove constant-time execution.

Backpressure and failure semantics

Durable evidence is a hot-path invariant. Under storage or fsync stall, the request path may block or reject according to the configured bounds; it must not silently drop authoritative evidence. The enrichment queue may reject optional work, but a queue policy cannot turn a governed accepted response into an unrecorded response.

The deterministic fault-injection harness is:

PYTHONPATH=. .venv/bin/python tools/benchmarks/run_backpressure_stall.py \
  --duration-s 0.25 --offered-rps 10000 --fsync-delay-ms 2 --max-workers 64 \
  --output evidence/backpressure_stall_report.json

The retained v3.1.0 run offered 10,000 requests at 10,000 RPS with a 2 ms injected fsync delay. It recorded 10,000 durable commits, zero failures, zero missing IDs, zero duplicate IDs, and valid chain integrity. The observed p99 commit latency was 1,189.89 ms. This is a bounded fault-injection result with substantial queueing. It is not a production capacity or SLO claim. See docs/operations/BACKPRESSURE_RUNBOOK.md.

WAF and ingress boundary

The local corpus currently covers 15 executable malicious cases and 8 benign cases. The v3.1.0 candidate run recorded zero observed bypasses and zero benign false positives for that pinned corpus. Because the corpus is small, its confidence interval is wide; the result is a regression signal, not universal detection coverage.

The application harness does not execute HTTP/2 fragmentation, pseudo-header ordering, continuation-boundary differentials, compressed-body parser differences, or ingress-specific normalization. nuclei-templates/waf-bypass is not treated as executed unless a pinned revision runs against an authorized disposable local target and produces a retained artifact. See docs/security/WAF_TESTING.md.

Observability and operations

Governed responses expose X-Aegis-Request-ID, X-Aegis-Session-ID, X-Aegis-Evidence-Status, X-Aegis-Analysis-Status, and, after a non-streaming durable commit, the X-Aegis-MMR-Format, X-Aegis-MMR-Leaf, X-Aegis-MMR-Proof, and X-Aegis-MMR-Root proof headers. Streaming responses expose a Link to /v1/audit/proofs/{request_id} and remain pending-terminal until the authenticated terminal lookup succeeds. Authoritative records are in the evidence store.

Operators should alert on evidence-commit failures, WAL synchronization failures, rate-limit backend failures, queue saturation, circuit opening, upstream error spikes, keyring reload failures, missing key overlap, signer unavailability, Seccomp/LSM startup rejection, and integrity-verification failure. Preserve WAL segments and reports read-only during incident handling. Roll back to the prior signed/image-digest release when a kill criterion is met.

In the merged-source baseline, when the PyO3 extension is available, each terminal streaming record is also appended once to an auxiliary CRC32-framed, memory-mapped RustWal segment at <AEGIS_WAL_PATH>.stream.rwal inside the same executor call that performs the authoritative JSONL ledger commit. The native segment is bounded to 256 MiB. If its append fails after the JSONL commit, Aegis increments aegis_native_stream_wal_errors_total, logs the degradation, disables the auxiliary segment for the process and preserves the client-visible terminal marker because the JSONL chain remains the replay authority. Streaming telemetry also exposes duration histograms, token counters and bounded-category redaction counters without payload labels.

Deployment topologies

Cross-replica global audit ordering and multi-region HA are not claimed by the current release. Use the scaling guide and roadmap as the authoritative boundary.

Benchmark interpretation

The repository separates dispatch microbenchmarks, client-visible proxy overhead, upstream-inclusive latency, WAL durability throughput, WAF corpus metrics, and native crypto timing. Each measurement must identify workload, hardware, warmup, sample count, percentile method, raw artifact, and boundary.

The previously published 2.70 µs result is a background-dispatch microbenchmark, not end-to-end gateway latency. Per-worker throughput is constrained by the interpreter, event-loop scheduling, upstream behavior, storage, and deployment topology. No README claim of “zero latency,” “zero overhead,” “10k RPS capacity,” or “1B RPM” is authorized without a new artifact that satisfies the claim matrix.

The merged-source Phase 2 in-process streaming harness is benchmarks/bench_streaming_sse.py. Its retained working-tree measurement is evidence/commercial_phase2_streaming_benchmark.json. It exercises 1,000 deterministic SSE events per round and reports first-byte latency, transformation throughput, queue high-water marks and tracemalloc peak memory. It excludes network and durable-WAL latency and therefore is not an end-to-end capacity result.

See docs/benchmarks/README.md, docs/BENCHMARKS.md, and docs/performance/SCALING_GUIDE.md.

Security and supply-chain posture

The release process produces a lockfile, SBOM, dependency/advisory results, provenance envelope, release-gate record, repository manifest, asset hashes, and rollback instructions. The security policy is in SECURITY.md; the public claim controls are in docs/CLAIMS_MATRIX.md. Vulnerability reports should use the private reporting path described in SECURITY.md, not public issue comments.

The repository does not claim SOC 2, HIPAA, FedRAMP, EU AI Act conformity, GDPR compliance, FIPS 140 validation, or court admissibility by itself. It provides code and evidence paths that an organization may evaluate as part of a broader control system and independent assessment. Framework references are contribution mappings, not certifications or legal conclusions.

Commercial path

The commercial model is intentionally staged:

Pricing hypotheses, cost-to-serve assumptions, procurement blockers, and buyer questions are in docs/COMMERCIAL_STRATEGY_US.md and docs/BUYER_GUIDE_US.md. The repository does not fabricate customer logos, testimonials, adoption numbers, support coverage, or ROI guarantees.

Repository map

Documentation index

Non-goals and residual risk

Application-layer controls do not replace network segmentation, firewall policy, Kubernetes NetworkPolicy, cloud IAM, a secret manager, immutable backup, disaster-recovery testing, or an incident-response program. Strict startup checks prove configured prerequisites at initialization; they do not prove that an external provider, filesystem, kernel, signer, or network remains healthy indefinitely. HMAC-SHA256 is classical and symmetric; long-lived or quantum-sensitive evidence requires a reviewed migration or hybrid architecture. ML-DSA availability is not equivalent to constant-time proof, FIPS 140 validation, or certification.

A release is blocked when a governed accepted response lacks durable evidence in the declared test scope, a chain fails verification, a critical WAF corpus case bypasses, a valid key rotation loses or invalidates a record, a timing experiment exposes leakage, a supply-chain gate fails, or public documentation overstates the evidence. See docs/SECURITY_ASSURANCE_ROADMAP.md for the external-assurance path.

License

The repository is licensed under the terms in LICENSE and COMMERCIAL.md. Commercial use cases, AGPL obligations, exemptions, future-version rights, and contractual terms require the applicable license text and legal review; this README is not legal advice.

Current release

The latest published release is v3.1.0. Commit 2050a310ec295afc61d033ff842c9a535a4f3105 is the merged v4.0.0 source baseline with fourteen synchronized 4.0.0 version anchors, but it remains unpublished source: no v4 tag, GitHub Release, PyPI package, or npm package is claimed. No OCI publication, WORM status, SLSA level, legal admissibility, or production-readiness claim is made. The ML-DSA verify timing claim remains blocked because the retained experiment returned p=0.0; a source merge or published release is not evidence that every deployment prerequisite or external assurance requirement has been satisfied.

External reference boundaries

The documentation uses NIST AI RMF, NIST CSF, NIST FIPS 204, W3C WCAG 2.2, CISA Secure by Design, IETF HTTP/2 and other primary sources as reference frameworks. These sources define terminology or review lenses. They do not certify Aegis or replace customer-specific legal, security, privacy or accessibility review.

Related documents

• docs/DEVELOPER_QUICKSTART.md
• docs/DEVELOPER_INTEGRATIONS_GUIDE.md
• docs/PLATFORM_OPERATOR_GUIDE.md
• docs/architecture/ARCHITECTURE.md
• docs/FAQ_TECHNICAL.md
• docs/FAQ_SECURITY.md
• docs/FAQ_PROCUREMENT.md
• docs/compliance/COMPLIANCE_MAPPING.md