Security Architecture
Version 1.0 — April 2026 — Classification: Public
Contact: security@agledger.ai
AGLedger is accountability infrastructure for automated operations. It records mandates, receipts, and verdicts in a tamper-evident audit trail — deployed in your infrastructure, under your control.
This document describes the security architecture of the AGLedger platform for security teams, compliance officers, and procurement decision-makers evaluating AGLedger for enterprise deployment.
Self-hosted by design. AGLedger runs in your VPC. No data leaves your infrastructure unless you explicitly enable federation.
Cryptographically signed audit trail. Every state change is recorded in an append-only, hash-chained, Ed25519-signed vault. Tampering is mathematically detectable.
Zero content inspection. AGLedger records accountability metadata (who committed what, who delivered, who accepted). It never inspects, stores, or processes your business data, prompts, or model outputs.
Algorithm-agile. All cryptographic operations record their algorithm identifiers, enabling future migration to post-quantum algorithms without data loss or chain breaks.
Standards-based. HMAC-SHA256, RFC 9421 HTTP Message Signatures, Ed25519 + SHA-256, RFC 8785 JSON Canonicalization, RFC 9457 Problem Details.
1. Deployment model and trust boundaries
AGLedger is software you deploy, not a service you send data to.
| Mode | Description | Network |
|---|---|---|
| Standalone | Full engine, no federation. All data local. | None. Zero outbound connections. |
| Gateway | Standalone + federation client. Connects to one Hub. | Outbound HTTPS to Hub only. |
| Hub | Gateway + federation coordinator for other Gateways. | Inbound from Gateways; optional outbound to peered Hubs. |
We do: Record accountability metadata in your infrastructure. We do not: Host your data, proxy your traffic, or require any outbound connectivity in Standalone mode.
2. Data classification
| Category | Storage | Sensitivity |
|---|---|---|
| Accountability metadata | PostgreSQL (your DB) | Business-sensitive |
| Audit trail | PostgreSQL (your DB) | Integrity-critical |
| API credentials | PostgreSQL (your DB) | Secret |
| Webhook secrets | PostgreSQL (your DB) | Secret |
What AGLedger does not store
Model prompts, completions, or training data
Business document content (AGLedger validates structure, not value)
PII beyond what customers include in mandate metadata (customer-controlled)
Payment card data or banking credentials
All data resides in the PostgreSQL instance you provision. No external data stores, no telemetry, no phone-home.
3. Data lifecycle
AGLedger does not impose data retention policies — the customer controls retention as the database operator.
The audit vault is cryptographically append-only by design. This creates a deliberate tension with deletion regulations (GDPR Article 17, CCPA). AGLedger’s position: vault entries contain accountability metadata — not business data. Mandate criteria and receipt evidence are stored in separate tables that can be archived or purged.
In encrypted mode, the server stores only the encrypted envelope and an evidence hash. Destroying the encryption key renders content irrecoverable while preserving vault chain integrity — cryptographic erasure.
4. Cryptographic architecture
| Layer | Standard | Purpose |
|---|---|---|
| Customer-facing | HMAC-SHA256 / Argon2id | Webhook auth, API keys, password hashing |
| Instance-to-instance | RFC 9421 + Ed25519 | Federation authentication |
| Data-at-rest | SHA-256 + Ed25519 / AES-256-GCM | Audit vault tamper evidence, secret storage |
| Client-side | AES-256-GCM / GCM-SIV | Encrypted mandate evidence (server-blind) |
| Federation | X25519 + AES-256-GCM (HKDF) | Criteria relay with forward secrecy |
| Canonicalization | RFC 8785 (JCS) | Deterministic serialization before hashing |
Named standards only. Every algorithm maps to an RFC, NIST publication, or IETF draft. No bespoke constructions.
Independent keys. Ed25519 (signing) and X25519 (encryption) keys are generated independently — never derived from each other.
Algorithm identifiers recorded. Every artifact includes alg fields, enabling algorithm migration without breaking verification.
Domain-separated key derivation. HKDF-SHA256 with purpose-specific labels ensures cryptographic independence.
5. Audit vault integrity
The audit vault is AGLedger’s core security primitive — a cryptographically signed, append-only ledger of every accountability event.
| Tampering | Mechanism | Detection |
|---|---|---|
| Insertion | Hash chain breaks previous_hash link | LINK_BROKEN |
| Deletion | Sequential chain_position gap | POSITION_GAP |
| Modification | Recomputed hash mismatch | HASH_MISMATCH |
| Forgery | Ed25519 signature fails against registered key | SIGNATURE_INVALID |
Enforcement layers
Database: REVOKE UPDATE, DELETE on audit_vault table. Database trigger rejects any modification attempt.
Application: Vault writes occur inside the same transaction as the state change — the entry exists if and only if the state change committed.
Cryptographic: SHA-256 hash chain with Ed25519 signatures provides tamper evidence independent of database access controls.
Operational: Signed checkpoints every 6 hours. Optional external anchoring to S3-compatible storage with COMPLIANCE mode object lock.
6. Authentication and access control
API keys are the primary authentication mechanism. Keys are never stored in plaintext — server computes HMAC-SHA256 and looks up the resulting hash.
| Role | Capabilities | Typical user |
|---|---|---|
| Platform | System administration, enterprise provisioning, vault management | AGLedger operator |
| Enterprise | Configuration, oversight, compliance exports, key management | Enterprise customer |
| Agent | Mandate lifecycle operations scoped to authorized actions | AI agent, RPA bot, service |
Each API key carries a scope list. Anti-escalation prevents creating keys with broader scopes than the creating key.
All queries filter by enterprise_id — cross-tenant data access is not possible through the API.
Optional: OIDC SSO, per-key IP allowlisting, Argon2id portal passwords (NIST SP 800-63B).
7. Federation and privacy boundary
What crosses federation boundaries
Node ID + public keys
Agent IDs
Mandate ID, contract type
State transitions (state, timestamp, signature)
Verification outcome (PASS/FAIL)
Settlement Signal (SETTLE/HOLD/RELEASE)
Reputation scores
Criteria commitment (SHA-256 hash, not content)
What never crosses
Mandate criteria (actual acceptance terms)
Receipt evidence (work product)
Audit vault entries
Prompts, context, or business logic
API keys or auth credentials
Webhook URLs or delivery payloads
Every Hub is a witness, not a custodian. It observes state transitions and aggregates reputation. It never holds the underlying business data.
8. Application security
Schema-first validation
Every endpoint declares request and response JSON Schemas enforced by the framework. Unknown fields rejected. No implicit type coercion. 1 MiB global request limit, 65 KiB mandate limit, 20-level JSON depth cap.
SQL injection prevention
All queries use parameterized SQL with positional parameters. Sort and filter columns validated against explicit whitelists.
SSRF protection
8-layer defense: private IP ranges, loopback, cloud metadata endpoints, alternative IP encodings, DNS re-resolution (TOCTOU), hostname suffixes, embedded credentials, HTTPS-only.
Expression engine sandboxing
jsep AST parser (not eval). 50 AST nodes, depth 10, 1,000 operations max. No access to global scope, prototype chain, or Node.js APIs.
Rate limiting
Tiered by trust level: 200/min (sandbox), 500/min (standard), 1,000/min (trusted). PostgreSQL-backed for multi-replica consistency.
9. Infrastructure hardening
Container security
Distroless base image (no shell)
Non-root user (UID 65534)
Read-only filesystem + tmpfs for /tmp
512 MiB memory, 1.0 CPU limits
Liveness + readiness health probes
File-based secrets injection
Database hardening
Three PostgreSQL roles (app, monitor, DDL)
REVOKE UPDATE, DELETE on audit_vault
sslmode=verify-full required in production
Advisory-locked, checksummed migrations
Node.js 24 LTS, pinned dependencies
10. Threat model
| Threat | Controls |
|---|---|
| Audit trail tampering | Hash chain + Ed25519 signatures + DB triggers + external checkpoints |
| Cross-tenant access | All queries filter by enterprise_id; scoped API keys; principal enforcement |
| API key compromise | HMAC-hashed storage; IP allowlisting; expiration; scope limits blast radius |
| Webhook SSRF | 8-layer validation including DNS re-resolution; HTTPS-only |
| Federation MITM | TLS + RFC 9421 Ed25519 signatures; per-request signing on critical operations |
| Signing key compromise | Key registry supports immediate rotation; external anchors verify pre-compromise entries |
| Denial of service | Tiered rate limiting; size caps; depth limits; handler timeouts |
Explicitly out of scope
Compromised principals. If the entity creating mandates is malicious, AGLedger faithfully records their mandates. We record accountability, not intent.
Content-level threats. AGLedger validates structure, not business content.
Infrastructure compromise. OS, network, and physical security are the customer’s responsibility.
11. Compliance mapping
Detailed mappings for each framework are available on their dedicated pages:
12. Privacy and data protection
AGLedger is self-hosted software. In the typical deployment, AGLedger LLC is neither a data processor nor a data controller. We provide software that the customer operates in their own infrastructure.
GDPR: Data minimization by design. Encrypted mode enables cryptographic erasure (Article 17). No international transfers in Standalone mode.
CCPA: No sale or sharing of personal information. No access to customer data in self-hosted model.
Sub-processors: Zero sub-processors for customer data in standard deployment.
13. Shared responsibility model
AGLedger provides
Application security (validation, SSRF, SQLi prevention)
Cryptographic integrity (hash chain, signatures, agility)
Access control (RBAC, scoping, rate limiting)
Secret handling (HMAC, AES-256-GCM, log redaction)
Container hardening (distroless, non-root, read-only)
Database role separation (three-role model)
Customer provides
Infrastructure security (network, OS, physical)
Database encryption at rest
TLS certificate management
Signing key protection (secrets manager)
Backup and disaster recovery
Monitoring, alerting, and SIEM integration
14. Business continuity
As self-hosted software, RPO and RTO depend on the customer’s infrastructure and backup strategy. AGLedger provides the tooling.
The audit vault’s hash chain is self-verifying. After restoring from any backup, run the vault integrity endpoint to confirm chain continuity.
Signing key loss does not invalidate historical entries — verification uses the public key stored in the database, not the private key from the environment.
Provided tooling: backup.sh, restore.sh, support-bundle.sh, and health probes for orchestrator-level recovery.
15. Security assurance
| Assessment | Status |
|---|---|
| SOC 2 readiness assessment | Completed March 2026 — 19 findings, code-level controls rated Strong to Excellent |
| SOC 2 Type II audit | Planned |
| Penetration testing | Planned for pre-GA |
| Vulnerability management | Active — 7-day release target for critical/high severity |
Vulnerability disclosure: security@agledger.ai
16. Release and update process
Semantic versioning. Checksummed, advisory-locked, transactional database migrations.
Breaking changes: 90-day advance notice with migration guides.
Security patches distributed as new versions. Customers notified via advisory with CVE references.
Security fixes are always free — regardless of support contract status.
17. Algorithm agility and post-quantum readiness
All algorithms are current NIST-approved. NIST finalized post-quantum standards in August 2024 (ML-KEM / FIPS 203, ML-DSA / FIPS 204, SLH-DSA / FIPS 205).
Algorithm identifiers on all artifacts — verification reads these fields rather than assuming a fixed algorithm.
Signing key registry — supports unlimited rotation. A new ML-DSA key can coexist alongside Ed25519.
No re-signing required — new entries use the new algorithm; old entries remain valid. The chain is continuous.
COSE_Sign1 alignment planned — future vault envelope aligned with RFC 9052, the standard chosen by IETF SCITT.
Hybrid (classical + PQC) signatures expected 2027–2028. AGLedger’s architecture requires no customer action today.
18. Incident response
Vulnerabilities: security@agledger.ai
Acknowledgment within 24 hours. Assessment within 72 hours.
Critical/high severity patch within 7 days.
If vault integrity verification detects tampering, the failure is logged with full context (chain position, expected vs. actual hash, signing key ID). Failed entries are flagged but never modified — the evidence of tampering is itself part of the audit record.
Read the announcement blog post for a summary of key highlights.
Version 1.0 — April 2026
AGLedger is a product of AGLedger LLC. This document describes the security architecture of AGLedger software. It is not a guarantee of security and should be evaluated alongside your organization’s specific risk assessment.
Contact: security@agledger.ai