aegis-latent-core

Aegis Latent Core

AI Governance and Cryptographic Evidence Gateway

Aegis Latent Core commits signed, hash-linked evidence of every governed AI call — before the response reaches the caller — and issues a portable proof that a third party verifies without trusting the gateway, us, or you.

Every load-bearing claim in this file carries a locator and a stated boundary; the gates that enforce that discipline run in CI.

Current release: v5.0.1 — the latest published release (the checked-out source is v5.0.2, an Apache-2.0 source target that is not published), published 2026-09-24 on every surface (PyPI aegis-latent-core 5.0.1 followed on 2026-09-26), read back the same day (Release Status §1.0a). The Sigstore-signed tag passes gitsign verify-tag; the GitHub Release carries 31 assets and all 15 files listed in its SHA256SUMS re-hash to their digests; PyPI aegis-latent-sdk 5.0.1 and npm aegis-latent-sdk 5.0.1 are byte-identical to the release assets of the same name; and the GHCR gateway and dashboard images pass cosign verify and their build-provenance attestations verify, each against the exact publishing workflow identity. The gateway distribution aegis-latent-core reached PyPI at 5.0.1 on 2026-09-26 (run 36224961909 of publish_pypi_gateway.yml, read back 2026-09-29, Release Status §1.0b); pip install aegis-latent-core resolves to 5.0.1, and its wheel and sdist match the release assets byte for byte. The GHCR images and the Release assets remain available. The previous release, v5.0.0, was published 2026-09-16 on the same surfaces (§1.0). There is no 4.2.0; the number was skipped.

First published version with the gateway on PyPI: v4.1.2, read back on 2026-09-04 — signed annotated tag, GitHub Release with 31 assets, PyPI aegis-latent-core 4.1.2, PyPI aegis-latent-sdk 4.1.2, npm aegis-latent-sdk 4.1.2, and GHCR gateway and dashboard images. 4.1.2 is the first version installable from PyPI as aegis-latent-core; before it the gateway came from source or GHCR only. The npm version list skips 4.1.1, whose publish step failed. A v4.1.0 release object also exists but was created outside the pipeline and carries no assets; ignore it. The two 4.1.2 PyPI gateway artifacts are byte-different from the release assets of the same name — same content, different build host — so SHA256SUMS does not cover those downloads; the 5.0.1 PyPI gateway artifacts match it. See Release Status for provenance and readback.

---

The problem

Your AI decisions are logged to a database your administrators can edit. When someone asks what the model was told six months ago, you answer from records the interested party could have changed.

In a regulated industry that is not a paperwork problem — it is an existential one. The regulator, the court and the auditor each ask the same question, and "our logs are probably fine" is not an answer they accept:

1. A record the interested party could have altered is not evidence — it only reads as evidence until someone with a reason to doubt it asks one question.
2. You already owe someone a record you can stand behind — EU AI Act Art. 12, HIPAA audit controls, SEC 17a-4's audit-trail alternative, MiFID II. Those are your obligations; this software is an input to them, never a discharge of them.
3. The fix has to be checkable by someone who distrusts you, or it is the same problem wearing better clothes.

The Aegis solution

• Append-only, tamper-evident MMR. Every record is a leaf in a Merkle Mountain Range. A portable inclusion proof (O(log n), no zero-knowledge claim) lets a third party verify a disclosed record against a root they obtained independently. verify_integrity() detects tampering on read; tampering is detected, not prevented — see the boundaries below.
• Cryptographic sealing. Each record is hashed into a chain link and signed — HMAC by default, Ed25519 (RFC 8032) or ML-DSA-65 (FIPS 204) where configured, with an HSM path in the enterprise server. Optional per-subject shredding (AES-256-GCM key destruction) erases plaintext from a ciphertext holder's view without changing the MMR root or previously issued proofs.
• Zero-trust verification. Proofs verify offline: a 313-line pure-Python verifier, a TypeScript twin with the same semantics, and zero network calls. No trust in the gateway, the vendor, or the operator who discloses the record — only in a root you obtained through a channel the discloser does not control.
• Regulatory inputs. MiFID II Art. 16(6)/16(7) and MiFIR Art. 25(1) record-keeping framing (durable, ordered-within-process records; no orders — RTS 24 — and no clock traceability — RTS 25); EU AI Act Art. 12 logging inputs (commit-before-response, tamper detection, verifiable inclusion); HIPAA Safe-Harbor-style pattern redaction; ISO/IEC 27037-style extracts. These are technical inputs, not compliance. No certification exists, none is in progress, and whether any obligation is met is a determination for you and your assessor (CLM-039 is LEGAL-REVIEW-REQUIRED).

→ Prove it yourself — twelve lines of Python, no call to our servers, three cases of which two must fail.

pip install aegis-latent-sdk aegis-latent-core   # verifier + gateway, both 5.0.1 on PyPI
python tools/sales/prove_it/prove_it.py --demo   # accepts one record, rejects two forgeries
python -m examples.demo                          # gateway + mock upstream, tamper detected

Both commands run from a checkout of this repository; what each one shows and does not show.

---

Architecture at a glance

 caller ──────────►  Aegis gateway  ──────────────────────────►  upstream provider
                        │  admission: auth · scope · bounds
                        │  WAF · rate limiting · session checks
                        │
                        │  (policy passed) forward
                        │  ◄─────────────── response ─────────
                        │
                        │  redact → hash → sign → WAL append + fsync → MMR leaf
                        │  (refused requests: the refusal is committed to the
                        │   same signed chain before the error returns)
                        │
 caller ◄──────────  response + X-Aegis-Evidence-Status
                        + X-Aegis-Request-ID + X-Aegis-MMR-* proof headers

Non-streaming. The evidence record is committed before the response is observable by the caller.

Streaming. Sanitized events are emitted incrementally through a bounded, byte-accounted queue while evidence status reads pending-terminal. One exact-byte terminal summary is committed, and only then is the terminal marker emitted. If that commit fails, the marker is withheld.

Fail-closed. No signer, no distributed limiter, or a ledger that fails to replay means no service — rather than quietly serving unevidenced traffic.

Details: Architecture · Failure Semantics

---

Real-world benchmarks

Real measurements from the retained 2026-09-24 artifact (evidence/benchmarks/benchmarks_5.0.1_2026-09-24.json), taken against real backends — a real WAL fsync per commit — on one shared, unpinned four-CPU x86_64 container (Linux, CPython 3.11.15). Reproduce with scripts/run_benchmarks_5.0.1.py --json.

Verified metrics

Measured suite (dated records; counts move as tests are added — run pytest -q on the commit you evaluate): 7,444 passed / 39 skipped / 0 failed (pytest -n auto -q) and 7,449 passed / 34 skipped / 0 failed (CI's exact serial Forensic command), both 2026-09-24 on the checked-out 5.0.1 tree. Statement coverage: 91.30% (2026-09-24; 91.25% on a later same-day run). The floor CI enforces is 65% (--cov-fail-under=65, .github/workflows/ci.yml); the 90% figure was a one-off mission floor, met at 90.07% on 2026-09-21 (REG-D36) and not enforced.

None of this is a capacity claim. Offered load is not accepted throughput. The absolute latencies are properties of one shared container; what transfers is the shape — per-commit cost stopped growing with chain length — not the numbers. Re-run the harnesses in your own environment before planning against any of them.

Evidence Index · Benchmark Method · Benchmark Record

---

Quickstart

Three steps, copy-pasteable. Honest channel note first: pip install aegis-latent-core installs 5.0.1 (read back 2026-09-29, CLM-113); at 5.0.0 the gateway was never on PyPI (UC-047, kept as history). You can also use this repository, the GHCR image ghcr.io/juanlunaia/aegis-latent-core:5.0.1, or the wheel attached to the v5.0.1 GitHub Release.

Step 1 — get the source:

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 .

Step 2 — run it (isolated local evaluation, against a mock upstream on 127.0.0.1:9999):

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:9999
aegis

Development mode disables the controls that make records meaningful — it is for reading the API, not for evaluating security. For a hardened single node see Deployment Profiles; to run one on Azure with a generated kit, see the Azure Quickstart. Container alternative: docker compose up --build (evaluation profile, bound to 127.0.0.1).

Step 3 — make a governed call and read the evidence headers:

curl -sS http://127.0.0.1:8080/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -H 'x-session-id: demo-session' \
  -d '{"messages":[{"role":"user","content":"Hello, Aegis."}]}'

curl -sS -D - -o /dev/null http://127.0.0.1:8080/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -H 'x-session-id: demo-session' \
  -d '{"messages":[{"role":"user","content":"Hello, Aegis."}]}' \
  | grep -i '^x-aegis'

Expect X-Aegis-Evidence-Status, X-Aegis-Request-ID and the X-Aegis-MMR-* proof headers; X-Aegis-Proof-Status is sent on streaming responses only (pending-terminal).

More: Developer Quickstart · Usage Examples

---

Verification

A third party verifies a log entry without trusting the Aegis server — offline, from the exported bundle, against a key and root obtained out of band:

pip install "aegis-latent-sdk[verify]"
aegis-sdk verify export.zip --public-key operator-ed25519.pub.pem

Exit 0 only when nothing failed and the manifest signature verified against a key you supplied. Exit 3 (INCOMPLETE) means the digests are internally consistent but the signature was not checked. The same check in library form:

from aegis_sdk.proof import InclusionProof, verify_inclusion_hash

proof = InclusionProof.from_mapping(record["mmr_proof"])
verify_inclusion_hash(record["mmr_leaf_hash"], proof, trusted_root)

Three cases, and two of them must fail:

The third case is the one to understand first: a root supplied by the same gateway that produced the proof establishes internal consistency and nothing more (CLM-044). Getting the root by a path the discloser does not control is your design problem, and no software solves it for you. A passing verification establishes inclusion under the root you supplied — not that the response was correct, not who produced the record, and not that nothing was omitted. Full worked transcript with the failing cases: docs/PROVE_IT.md

Verify what you downloaded

Release assets carry a digest, and checking one needs no checkout and no cooperation from this project:

curl -fsSL -O https://github.com/juanlunaia/aegis-latent-core/releases/download/v5.0.1/SHA256SUMS
# then, for each artifact you downloaded:
curl -fsSL -O https://github.com/juanlunaia/aegis-latent-core/releases/download/v5.0.1/<artifact-name>
sha256sum -c SHA256SUMS --ignore-missing

Two things that snippet does not establish. It shows the bytes match the manifest; it does not show who built them — an OCI signature (cosign verify) and a build attestation (gh attestation verify) are separate checks against separate infrastructure. And it covers the release assets only: the PyPI wheels for aegis-latent-core are rebuilt from the same source on a different build host, so their bytes differ from the release assets of the same name and SHA256SUMS does not cover them (see docs/RELEASE_STATUS.md).

python scripts/verify_release_readback.py --tag v5.0.1 --verify-assets automates the whole readback — the GitHub Release, the SHA256SUMS sweep, the PyPI and npm versions, and the GHCR manifest digests — and prints NOT_EXECUTED, with the reason, for anything it could not check from where it ran. This block is emitted by that same tool, so the documented commands cannot drift from it.

---

Compliance & security

• JCS determinism. Forensic exports are canonicalized with JSON Canonicalization Scheme (RFC 8785): a manifest.json over DAG-CBOR, content-addressed with CIDv1, plus a technical PDF and an embedded VERIFY.sh. Non-finite numbers are rejected fail-closed rather than silently normalized.
• Domain-separated hashing. New chains record leaves under the aegis-mmr-inclusion-v2 scheme — RFC 6962-style domain separation, so a leaf payload cannot hash to an interior node (CLM-064). Existing v1 chains keep verifying unchanged; a scheme mismatch faults instead of replaying to a different root.
• Audit inputs. Every claim in this repository carries an evidence locator and a stated boundary; the Claims Matrix, the Defect Registry, SBOMs, signed tags and signed images exist to serve an audit — they are inputs to audits, never a certification: no SOC 2, no ISO 27001, no HIPAA attestation, no FedRAMP, and none in progress.
• Boundaries, stated once: tampering is detected, not prevented — an operator with filesystem access can alter records. No universal PII removal; redaction protects the record, not your provider. No output validation — the gateway records what the model returned, it does not check whether it was true (UC-068). No cross-replica global ordering. No guaranteed prompt-injection prevention.

SECURITY.md · Threat Model · Compliance Mapping · Boundaries

---

Support the project

Aegis Latent Core is developed by one maintainer. A donation is voluntary: it buys no licence, support, feature or influence, and it is not tax-deductible. The source is licensed under Apache-2.0 for every use, commercial or not (COMMERCIAL.md).

---

Links

• ROADMAP.md — what is built, what is not, and the ticket ledger behind it.
• REGISTRY.md — master defect and debt registry: every finding, its state and its evidence file.
• UNSUPPORTED_CLAIMS.md — the register of what this software does not claim, and the phrases CI rejects.
• RELEASE_STATUS.md — per-surface publication state and readback commands (single source of truth).
• CLAIMS_MATRIX.md · docs/BOUNDARIES.md · docs/INDEX.md

---

_{Copyright © 2026 Juan Luna. Licensed under the Apache License, Version 2.0 from 5.0.2 (releases up to 5.0.1 keep the AGPLv3-or-commercial terms they were published under; see docs/legal/LICENSE_TRANSITION_5.0.2.md). Full documentation index: docs/INDEX.md}