AegisSystem Architecture Overview

ELI5

AEGIS is the bouncer at a vault: it lets people prove they belong inside without ever handing over their ID card. Five specialist crew members handle the proof-making, checking, logging, and cross-referencing so the vault operator never learns who visited or what they touched.

Technical Deep Dive

AEGIS stands for Authenticated Evidence Guard with Integrated Security. The entry point is AegisSystem in src/lib.rs, which aggregates five owned subsystems:

All five fields are pub, making the struct transparent to callers. Errors flow through AegisErrorType, a five-variant enum (ProofError, VerificationFailed, AccessDenied, CommitmentError, AuditError).

Class Diagram

classDiagram
    class AegisSystem {
        +zk_engine: ZKEngine
        +verifier: Verifier
        +access_control: AccessControl
        +audit_trail: AuditTrail
        +consistency_proofs: HashMap
        +verify_access(user_commitment, doc_commitment, proof) Result~bool~
        +check_permission(user_id, doc_id, action) Result~bool~
        +audit_access(user_id, doc_id, action) void
        +stats() AegisStats
    }
    class AegisStats {
        +total_proofs: usize
        +verified_count: usize
        +audit_entries: usize
        +consistency_proofs: usize
    }
    class AegisErrorType {
        ProofError(String)
        VerificationFailed(String)
        AccessDenied(String)
        CommitmentError(String)
        AuditError(String)
    }
    AegisSystem --> AegisStats : "stats()"
    AegisSystem --> AegisErrorType : returns

Request Flow

flowchart LR
    caller([Caller]) --> va[verify_access]
    caller --> cp[check_permission]
    caller --> aa[audit_access]
    va --> verifier[Verifier.verify_zk_proof]
    cp --> ac[AccessControl.check_permission]
    aa --> at[AuditTrail.record_access]
    verifier --> result((Result bool))
    ac --> result

The three primary methods delegate immediately to the owned subsystem — AegisSystem is a facade, not a policy engine itself.

AegisStats

stats() aggregates counts from all five subsystems into a Clone + Debug struct. consistency_proofs counts the entries in the HashMap field, not the entries verified by ConsistencyProofManager.

Key Terms

• AegisSystem → Top-level facade owning all five AEGIS subsystems; defined in src/lib.rs
• AegisErrorType → Five-variant enum encoding AEGIS-specific failures
• AegisStats → Snapshot of proof, verification, audit, and consistency counts
• zero-trust → Every request is re-verified regardless of prior session state
• VEST chain → External audit chain that ConsistencyProof anchors to (referenced via vest_chain_ref)

Q&A

Q: verify_access takes both user_commitment and doc_commitment — what happens if either slice is empty? A: Verifier::verify_zk_proof checks user_commitment.is_empty() || doc_commitment.is_empty() and returns Ok(false), not an error. The VerificationFailed variant is reserved for lower-level failures, so an empty commitment silently returns false.

Q: check_permission converts the action: &str into a Permission enum — what does it return for an unrecognised action string? A: AccessControl::check_permission returns Err(format!("Unknown action: {}", action)), which AegisSystem::check_permission propagates as Result<bool, AegisErrorType> — but note the return type in lib.rs wraps this as AegisErrorType::AccessDenied only if the inner call errors.

Q: Can two AccessEntry rows exist for the same (user_id, doc_id) pair with different permissions? A: Yes. grant_permission appends without deduplication. get_permissions returns all valid matching entries as a Vec<Permission>, so multi-grant is by design.

Examples

A caller authorising a read:

let mut sys = AegisSystem::new();
sys.access_control.grant_permission("u1", "doc42", Permission::Read).unwrap();
let allowed = sys.check_permission("u1", "doc42", "read").unwrap(); // true
sys.audit_access("u1", "doc42", "read");
let stats = sys.stats();
assert_eq!(stats.audit_entries, 1);