Enforce before execution. Verify before settlement.
AEGIS is a security and economic-control layer for high-risk AI-agent tool calls — combining atomic budget enforcement, replay-safe authorization, deterministic receipts, SHA-256 action references, Ed25519 signatures, and an isolated atomic L3 settlement layer.
pip install aegis-core-lortuarte-sdkAutonomous AI agents can initiate payments, purchases, trades, API actions, and other irreversible tool calls concurrently.
A policy decision made too far away from execution can leave room for:
AI AGENT
│
▼
TOOL INTENT
│
┌────────┼────────┐
│ │ │
▼ ▼ ▼
CALL #1 CALL #2 CALL #N
│ │ │
└────────┼────────┘
│
▼
CONCURRENT STATE RACE
│
┌─────────┴─────────┐
│ │
▼ ▼
DUPLICATE EXECUTION OVERSPEND
AEGIS moves the authorization boundary directly in front of tool execution.
AI AGENT
│
▼
TOOL INTENT
│
▼
┌─────────────────────┐
│ 🛡️ AEGIS │
│ AUTHORIZATION GATE │
└──────────┬──────────┘
│
┌─────┴─────┐
│ │
▼ ▼
execution_permitted: True execution_permitted: False
│ │
▼ ▼
EXECUTE TOOL 🛑 BLOCK
The protected tool executes only when
receipt["execution_permitted"] is True.
AEGIS Core 3.4.0 focuses on the economic and authorization boundary between an autonomous agent and a high-risk external action.
Concurrent mutations of the process-local ledger are serialized by a lock.
An exact replay of the same authorization returns the historical receipt without consuming the budget again.
Reuse of the same transaction identity with conflicting economic data is denied.
tool_call_id participates in the authorization identity used to derive the signed action reference.
Changing the tool-call identity changes the resulting action_ref.
AEGIS produces deterministic authorization payloads protected by:
Deterministic Payload
│
▼
SHA-256
│
▼
Ed25519
│
▼
Signed Authorization Receipt
Changing signed authorization data invalidates cryptographic verification.
Internal authorization failures deny execution.
An explicitly configured invalid Ed25519 private key aborts startup rather than silently replacing the configured cryptographic identity.
Economic state uses Python Decimal rather than binary floating-point arithmetic.
AEGIS Core 3.4.0 supports monetary amounts with up to 6 decimal places.
- Minimum supported positive amount:
$0.000001 $0.001micropayments are supported- Amounts with more than 6 decimal places fail closed
- L3 settlement stores value as integer monetary units at a scale of
1,000,000units per USD
An isolated settlement layer consumes signed AEGIS authorizations and performs atomic buyer → seller balance transitions using SQLite transactions.
pip install aegis-core-lortuarte-sdkRequirements:
Python >= 3.8
cryptography
cryptography is installed automatically by the package.
from decimal import Decimal
from aegis import AegisLocalPolicyGate
gate = AegisLocalPolicyGate()
agent_id = "agent-demo-001"
gate.ledger_data[agent_id] = Decimal("10.00")
receipt = gate.evaluar_gasto(
agent_did=agent_id,
operation="stripe_charge",
tool_call_id="payment-001",
amount_usd="3.00",
)
if receipt["execution_permitted"] is True:
print("AUTHORIZED")
# Execute the protected tool here.
else:
print("BLOCKED")
print(receipt)Expected authorization:
AUTHORIZED
Economic transition:
$10.00
│
│ request $3.00
▼
ALLOW
│
▼
$7.00
Assume the remaining budget is:
$7.00
The agent attempts:
$20.00
AEGIS evaluates the action before external execution:
$7.00 AVAILABLE
│
│ REQUEST $20.00
▼
┌─────────────┐
│ DENY │
└──────┬──────┘
│
▼
budget_exhausted
│
▼
🛑 TOOL BLOCKED
Integration pattern:
receipt = gate.evaluar_gasto(
agent_did=agent_id,
operation="stripe_charge",
tool_call_id="payment-002",
amount_usd="20.00",
)
if receipt["execution_permitted"] is True:
result = execute_payment()
else:
result = "BLOCKED"The integration layer remains responsible for ensuring the external tool is invoked only when receipt["execution_permitted"] is True.
AEGIS identifies an authorization using the agent and tool-call identity.
First request:
tool_call_id: payment-001
amount: $3.00
│
▼
ALLOW
│
├── budget decreases once
├── cached: False
├── execution_permitted: True
└── signed receipt created
Exact replay:
tool_call_id: payment-001
amount: $3.00
│
▼
HISTORICAL RECEIPT
│
├── same action_ref
├── cached: True
├── execution_permitted: False
└── NO second debit
policy_decision describes the signed historical authorization. External tools must execute only when execution_permitted is True. Exact replays retain the historical receipt but receive no new process-local execution grant.
Conflicting replay:
SAME TRANSACTION ID
│
├── original amount: $1.00
└── new amount: $100.00
│
▼
DENY
│
▼
idempotency_conflict
Validated:
Exact replay does not double-debit PASS
Same ID + different amount blocked PASS
Same ID + different operation blocked PASS
100 same-ID concurrent retries grant one execution PASS
AEGIS signs deterministic authorization semantics rather than an unstructured success flag.
POLICY EVALUATION
│
▼
DETERMINISTIC PAYLOAD
│
├── agent_did
├── operation
├── amount
├── decision
└── tool-call binding
│
▼
SHA-256
│
▼
Ed25519
│
▼
SIGNED POLICY RECEIPT
│
▼
action_ref
Example receipt:
{
"agent_did": "agent-demo-001",
"operation": "stripe_charge",
"amount_usd": "3.00",
"policy_decision": "allow",
"policy_attenuations": [],
"policy_signature": "ed25519:...",
"action_ref": "...",
"cached": False,
"execution_permitted": True
}action_ref is represented as the 64-character hexadecimal encoding of a 32-byte SHA-256 digest.
SHA-256 digest 32 bytes
│
▼
action_ref 64 hexadecimal characters
Original signed authorization:
ORIGINAL PAYLOAD
│
├── SHA-256
│
└── Ed25519
│
▼
VALID ✓
Modify signed data:
MODIFIED PAYLOAD
│
├── different digest
│
└── original signature
│
▼
INVALID ✗
Validated:
Signature verification PASS
Tampered authorization rejected PASS
AEGIS is designed to prefer denial over silent authorization when the protected authorization path fails.
INTERNAL FAILURE
│
▼
🛑 DENY
│
▼
TOOL MUST NOT EXECUTE
Validated forced cryptographic failure:
BALANCE BEFORE: 10.00
DECISION: deny
BALANCE AFTER: 10.00
BALANCE PRESERVED: True
FAIL-CLOSED: True
ROLLBACK: PASS
Configured invalid-key behavior:
CONSTRUCTOR EXCEPTION: ValueError
GATE CREATED: False
FAIL-CLOSED STARTUP: True
EMERGENCY RECOVERY: False
SECURITY MODEL: INVALID KEY REJECTED
RESULT: PASS
This prevents an invalid configured cryptographic identity from being silently replaced at startup.
AEGIS was exercised against a focused matrix of economic failure scenarios.
| Scenario | Result |
|---|---|
| Exact replay does not double-debit | ✅ PASS |
| Same ID + different amount blocked | ✅ PASS |
| Same ID + different operation blocked | ✅ PASS |
| Signature failure preserves balance | ✅ PASS |
| Over-budget request blocked without mutation | ✅ PASS |
| Exact-balance authorization | ✅ PASS |
| Zero / negative / non-numeric fail closed | ✅ PASS |
| Excess monetary precision rejected | ✅ PASS |
| DENY does not execute tool | ✅ PASS |
| Signed authorization verifies | ✅ PASS |
| Tampered receipt rejected | ✅ PASS |
tool_call_id changes action_ref |
✅ PASS |
TOTAL TESTS: 12
PASS: 12
FAIL: 0
FINAL RESULT: PASS
A 1,000-request adversarial contention test was executed against a budget capable of funding only one request.
Configuration:
REQUESTS: 1,000
WORKERS: 100
INITIAL BALANCE: $10.00
AMOUNT EACH: $10.00
Result:
$10 AVAILABLE
│
1,000 COMPETING REQUESTS
│
▼
AEGIS LOCK
│
┌──────┴──────┐
│ │
▼ ▼
1 × ALLOW 999 × DENY
│
▼
$10 AUTHORIZED
│
▼
FINAL BALANCE $0
Measured result:
| Property | Result |
|---|---|
| Allow | 1 |
| Deny | 999 |
| Authorized total | $10.00 |
| Final balance | $0.00 |
| Overspend | NO |
| Result | PASS |
This demonstrates concurrent budget protection inside the current process-local execution model.
It does not demonstrate cross-process or distributed consensus.
AEGIS includes an isolated L3 settlement layer that consumes a signed authorization before mutating settlement balances.
AI AGENT
│
▼
AEGIS AUTHORIZATION
│
SHA-256 + Ed25519
│
▼
SIGNED POLICY RECEIPT
│
▼
┌──────────────────────┐
│ L3 VERIFICATION │
│ │
│ ✓ decision = allow │
│ ✓ payload rebuilt │
│ ✓ action_ref │
│ ✓ Ed25519 signature │
└──────────┬───────────┘
│
▼
BEGIN IMMEDIATE
│
┌─────┴─────┐
│ │
▼ ▼
DEBIT BUYER CREDIT SELLER
│ │
└─────┬─────┘
│
▼
SETTLEMENT RECORD
│
▼
COMMIT
If settlement fails after the transaction begins:
FAILURE
│
▼
ROLLBACK
│
▼
BALANCES PRESERVED
Validated L3 security matrix:
| L3 Property | Result |
|---|---|
| Signed settlement | ✅ PASS |
| Conservation of value | ✅ PASS |
| Exact replay idempotent | ✅ PASS |
| Tampered seller blocked | ✅ PASS |
| Tampered amount blocked | ✅ PASS |
| Atomic rollback | ✅ PASS |
| Concurrent limited-budget settlement | ✅ PASS |
Concurrent L3 test:
REQUESTS: 100
SETTLED: 1
DENIED: 99
TOTAL: 7
PASS: 7
FAIL: 0
FINAL RESULT: PASS
Performance is reported by execution layer.
AEGIS does not use a single latency number to represent different workloads.
The following results were measured locally during the current validation run using time.perf_counter_ns().
They are local process measurements and must not be interpreted as Internet or hosted API round-trip latency.
Isolates local:
lock
+
Decimal comparison
+
Decimal subtraction
+
quantization
| Metric | Measured |
|---|---|
| Minimum | 0.400 µs |
| Median | 0.500 µs |
| P95 | 1.000 µs |
| P99 | 1.300 µs |
MEDIAN = 0.000500 ms
| Metric | Measured |
|---|---|
| Minimum | 2.200 µs |
| Median | 2.400 µs |
| P95 | 4.900 µs |
| P99 | 7.700 µs |
MEDIAN = 0.002400 ms
Includes the complete local authorization path measured by the benchmark:
validation
│
▼
lock
│
▼
idempotency
│
▼
budget decision
│
▼
deterministic payload
│
▼
SHA-256
│
▼
Ed25519
│
▼
receipt
| Metric | Measured |
|---|---|
| Minimum | 45.200 µs |
| Median | 47.900 µs |
| Mean | 57.363 µs |
| P95 | 81.600 µs |
| P99 | 153.900 µs |
MEDIAN = 0.047900 ms
Signed receipt verification + SQLite transactional settlement using :memory:.
| Metric | Measured |
|---|---|
| Minimum | 133.400 µs |
| Median | 146.550 µs |
| P95 | 245.900 µs |
| P99 | 393.200 µs |
MEDIAN = 0.146550 ms
Signed receipt verification + local file-backed SQLite transaction.
| Metric | Measured |
|---|---|
| Minimum | 486.600 µs |
| Median | 969.200 µs |
| Mean | 1.022 ms |
| P95 | 1.621 ms |
| P99 | 2.188 ms |
MEDIAN = 0.969200 ms
File-backed SQLite results include the local persistence path, but should not be interpreted as guaranteed physical-disk latency for every operation because SQLite and the operating system may cache I/O.
| Layer | Median | P95 | P99 |
|---|---|---|---|
| ⚡ Economic decision primitive | 0.500 µs | 1.000 µs | 1.300 µs |
| 🔁 Idempotency cache hit | 2.400 µs | 4.900 µs | 7.700 µs |
| 🔐 Full signed authorization | 47.900 µs | 81.600 µs | 153.900 µs |
🏦 L3 SQLite :memory: |
146.550 µs | 245.900 µs | 393.200 µs |
| 💾 L3 local file-backed SQLite | 969.200 µs | 1.621 ms | 2.188 ms |
SIGNED / DECISION: 95.80×
FILE L3 / MEMORY L3: 6.61×
L3 MEMORY / SIGNED: 3.06×
A previous single latency number can hide which work is actually being measured.
AEGIS therefore reports the layers independently:
0.500 µs
DECISION PRIMITIVE
│
▼
2.400 µs
IDEMPOTENCY CACHE HIT
│
▼
47.900 µs
FULL SIGNED AUTHORIZATION
│
▼
146.550 µs
L3 SQLITE :MEMORY:
│
▼
969.200 µs
LOCAL FILE-BACKED SQLITE
These numbers answer different questions.
AEGIS therefore does not present 0.005 ms as a full L3 or end-to-end settlement latency claim.
The current evidence supports low-microsecond local hot paths and a sub-millisecond median for the tested local signed and SQLite settlement paths described above.
The final evidence benchmark also isolates common measurement contamination.
Measured write to os.devnull:
NO-PRINT MEDIAN: 0.200 µs
PRINT MEDIAN: 2.400 µs
ADDED MEDIAN COST: 2.200 µs
REQUESTED SLEEP: 1.000 ms
OBSERVED MEDIAN: 1.696 ms
P95: 1.941 ms
P99: 2.251 ms
Therefore intentional sleeps and console/debug work are kept conceptually separate from engine latency claims.
The current benchmark does not measure:
✗ Client → Internet → Render → client HTTP round-trip
✗ Multi-process coordination
✗ Multi-worker shared-state coordination
✗ Multi-node distributed consensus
✗ Remote Redis coordination
✗ Remote PostgreSQL coordination
✗ Stripe settlement latency
✗ Blockchain settlement latency
No number for those layers is inferred from the local benchmark.
LOCAL ENGINE PERFORMANCE
≠
NETWORK ROUND-TRIP
≠
DISTRIBUTED CONSENSUS
≠
EXTERNAL FINANCIAL SETTLEMENT
AEGIS Core 3.4.0 has received a public external source-level evaluation and benchmark in kube-coder issue #573.
The external project-side evaluator inspected the published artifacts and source, verified package hashes, reviewed package behavior, and benchmarked the relevant local execution paths.
| Path | Median | p95 | p99 |
|---|---|---|---|
| Process-local signed gate | 0.0582 ms | 0.1042 ms | 0.1260 ms |
| File-backed settlement, end-to-end | 1.1349 ms | 3.2434 ms | 4.6677 ms |
The evaluator described the package as real/readable and did not identify malicious package behavior. The fit decision, however, was not to adopt AEGIS as the dependency for kube-coder Phase 4.
The reasons were architectural and are important:
- kube-coder's LLM-turn cost is not fully known before the call, while AEGIS 3.4.0 expects a supplied amount before authorization;
- kube-coder needs shared durable budget state across agent processes, while the AEGIS local gate is process-local;
- Ed25519 receipts solve a trust-boundary problem that does not exist when policy and enforcement live inside the same trusted process;
- kube-coder already has an in-process refusal point, so a network-latency race is not the relevant failure mode there.
The same review then recorded AEGIS patterns worth carrying into kube-coder's own Phase 4 design:
- durable allow/deny decision receipts;
- idempotency with conflict detection;
- integer monetary units rather than binary float;
- evaluate → record → mutate commit ordering;
- fail-closed behavior on internal faults;
- attenuated policy outcomes for soft-cap/hard-cap behavior.
Evidence classification:
- External source review: YES
- External benchmark: YES
- External fit assessment: YES
- Design influence: YES
- kube-coder adoption: NO
- kube-coder integration: NO
- Production validation: NO
- Institutional endorsement: NO
Full evidence record: EXTERNAL_EVALUATION_KUBE_CODER.md
Primary public sources:
- External evaluation and benchmark
- Phase 4 design notes derived from AEGIS scoping
- AEGIS author correction and scope clarification
A retry/disconnect failure mode reported by Iraitz / LortuArte was credited in the merged upstream PayMCP PR #52, “Return the paid result on retry instead of running the tool twice.”
The upstream PR documents that a paid tool could execute, the client could disconnect before receiving the result, and a retry could execute the underlying tool again. For tools with side effects, the external action could therefore happen twice even though there was one payment.
PayMCP's merged fix stores and replays the paid result instead of automatically re-executing the consequential tool path.
Evidence classification:
- Externally credited engineering finding: YES
- Upstream fix merged: YES
- Independent confirmation that retry ambiguity can cause duplicate consequential execution: YES
- AEGIS dependency used by PayMCP: NO
- AEGIS integration/adoption by PayMCP: NO
- Production validation or endorsement of AEGIS: NO
This is published as external engineering impact and problem validation, not as an AEGIS adoption claim.
Full evidence record: EXTERNAL_ENGINEERING_IMPACT_PAYMCP.md
Current focused evidence:
┌───────────────────────────────────────────────┐
│ AEGIS SECURITY │
├───────────────────────────────────────────────┤
│ Cryptographic rollback PASS │
│ Idempotency conflict PASS │
│ tool_call_id binding PASS │
│ Invalid configured key PASS │
│ Fail-closed startup PASS │
│ Ed25519 verification PASS │
│ Tamper detection PASS │
│ DENY → tool not executed PASS │
│ Decimal boundary handling PASS │
│ Financial-loss matrix 12/12 PASS │
│ 1,000-request double-spend PASS │
│ L3 settlement matrix 7/7 PASS │
└───────────────────────────────────────────────┘
This evidence is intended to be reproducible from the repository rather than accepted as a marketing claim.
Core integration:
python test_integration.pyEnforcement:
python test_enforcement.pyConcurrent budget protection:
python test_concurrency.pyCryptographic rollback:
python test_signature_failure_rollback.pyIdempotency conflict:
python test_idempotency_conflict.pyTool-call cryptographic binding:
python test_tool_call_binding.pyConfigured-key fail-closed behavior:
python test_key_failure_behavior.pyFinancial-loss adversarial matrix:
python test_financial_loss_matrix.py1,000-request double-spend test:
python test_double_spend_1000.pyL3 settlement security:
python test_l3_settlement.pyFinal layered performance evidence:
python benchmark_final_evidence.pyExpected high-level security status:
CORE SECURITY PASS
FINANCIAL MATRIX 12/12 PASS
DOUBLE-SPEND PASS
L3 SECURITY 7/7 PASS
PERFORMANCE EVIDENCE COMPLETE
AI AGENT
│
▼
TOOL INTENT
│
▼
┌──────────────────────┐
│ 🛡️ AEGIS CORE │
│ │
│ Monetary Validation │
│ Idempotency │
│ Atomic Lock │
│ Budget Enforcement │
└──────────┬───────────┘
│
┌──────┴──────┐
│ │
▼ ▼
ALLOW DENY
│ │
│ └──────────► 🛑 BLOCK
▼
DETERMINISTIC PAYLOAD
│
▼
SHA-256
│
▼
Ed25519
│
▼
SIGNED AUTHORIZATION
│
┌─────────┴─────────┐
│ │
▼ ▼
PROTECTED TOOL L3 SETTLEMENT
│
▼
VERIFY AUTHORIZATION
│
▼
BEGIN IMMEDIATE
│
┌────────┴────────┐
│ │
▼ ▼
DEBIT CREDIT
│ │
└────────┬────────┘
│
▼
COMMIT
The authorization core and settlement layer are intentionally separated.
That separation makes it possible to benchmark, test, and reason about each boundary independently.
AEGIS currently demonstrates these properties:
Authorization is produced before the integration invokes the protected external tool.
A lock protects local ledger mutation from concurrent access inside the current process.
Exact replay does not consume budget twice.
Conflicting reuse of transaction identity is denied.
Security-relevant authorization data is deterministically serialized before hashing and signing.
SHA-256 and Ed25519 allow downstream verification of authorization integrity.
Failures in protected authorization and settlement paths preserve economic state when the tested transaction must fail.
The isolated L3 layer performs transactional buyer → seller mutation and records settlement atomically under the tested SQLite model.
AEGIS Core 3.4.0 is Beta software.
✓ Process-local authorization
✓ Process-local locking
✓ Decimal monetary accounting
✓ Replay-safe idempotency
✓ Idempotency conflict detection
✓ Deterministic authorization receipts
✓ SHA-256 action references
✓ Ed25519 signatures
✓ tool_call_id cryptographic binding
✓ Fail-closed authorization behavior
✓ Invalid configured-key rejection
✓ Economic rollback
✓ Concurrent local budget enforcement
✓ One process-local execution grant across 100 same-ID concurrent retries
✓ Atomic SQLite L3 settlement
✓ L3 replay protection
✓ L3 tamper rejection
✗ Cross-process atomicity
✗ Shared state across multiple workers
✗ Multi-node consensus
✗ Distributed ledger coordination
✗ Redis-backed distributed locking
✗ PostgreSQL-backed distributed settlement
✗ Byzantine fault tolerance
✗ Blockchain finality
✗ Stripe settlement guarantees
✗ Internet-scale production readiness
✗ Exactly-once external side effects
✗ Crash recovery after external dispatch
✗ Automatic reserve / commit / release reconciliation
These are separate production/distributed-system concerns and should not be inferred from the current local evidence.
Agent
│
▼
AEGIS Core
│
├── authorization
├── budget control
├── idempotency
├── SHA-256
└── Ed25519
│
▼
Signed Receipt
│
▼
Local Atomic L3 Settlement
MULTIPLE AGENTS
│
▼
DISTRIBUTED AEGIS
│
┌───────────┼───────────┐
│ │ │
▼ ▼ ▼
Shared State Coordination Persistence
│ │ │
└───────────┼───────────┘
│
▼
DISTRIBUTED SETTLEMENT
The distributed architecture is a direction, not a claim about the current implementation.
AEGIS is not an LLM reasoning guardrail.
It operates at the execution boundary:
AGENT REASONING
│
▼
TOOL INTENT
│
▼
🛡️ AEGIS
│
┌───────────┼───────────┐
│ │ │
▼ ▼ ▼
BUDGET IDEMPOTENCY CRYPTOGRAPHY
│ │ │
└───────────┼───────────┘
│
▼
execution_permitted True / False
│
┌─────┴─────┐
│ │
▼ ▼
TOOL EXECUTION L3
SETTLEMENT
The goal is narrow: make economically sensitive agent actions explicitly authorized, cryptographically verifiable, and testable before irreversible execution.
| Evidence class | Status |
|---|---|
| Local focused tests | ✅ PASS |
| Local adversarial/concurrency tests | ✅ PASS |
| Reproducible local benchmark suite | ✅ Documented |
| Independent external source review | ✅ Completed |
| Independent external benchmark | ✅ Completed |
| External design influence | ✅ Documented |
| Externally credited engineering finding | ✅ PayMCP PR #52 merged |
| External product integration | ❌ Not yet |
| External production validation | ❌ Not yet |
| Distributed/multiprocess guarantees | ❌ Not claimed |
The external evidence is intentionally separated from local author-run evidence. See EXTERNAL_EVALUATION_KUBE_CODER.md.
| Distribution | aegis-core-lortuarte-sdk |
| Version | 3.4.0 |
| Python | >=3.8 |
| Status | Beta |
| License | MIT |
Install:
pip install aegis-core-lortuarte-sdkMIT License.