Security Architecture

1. The signed record - what the signature covers

The agent reports with its key; the notary signs what it reported. The agent (or any caller) makes the API call that records a stage of the work. The Server - not the caller - assembles the entry, encodes it, and signs it with the instance vault key. The authority being recorded is the principal’s; the signature is the notary’s.

Because the attribution rides inside the signed payload, an entry cannot be re-pointed at a different principal without invalidating the signature. The protected header carries the actor identity as a CWT private claim ({ key_id, role, owner_id }); any delegation context rides in the in-toto Statement predicate as on_behalf_of. Both are covered by the Ed25519 signature. To the auditor, the claim is exact: the chain proves what was reported, signed, and recorded, and that the attribution has not been altered since.

Agents are not required to hold signing keys. The default path needs no client-side cryptography from the agent: it authenticates and reports, and the notary signs. An optional per-request attestation path (X-Agent-Signature / X-Agent-Signature-Content-Hash), a no-op by default, lets a cert-bound caller co-sign its own request; the co-signature is carried into the envelope as predicate.on_behalf_of.agent_signature and honored only when the caller authenticated with an ephemeral cert (§7).

2. Deployment model and trust boundaries

AGLedger is software you deploy, not a service you send data to. One role: Server. Every install is the same binary. A Server is a sovereign domain: its own database, auth, agents, contracts, signing key, and chain. Federation participation is a per-record / per-contract / global flag, not a deployment mode.

We do: record accountability metadata in your infrastructure. We do not: host your data, proxy your traffic, judge your work, or require outbound connectivity unless a record’s share flag is set. Topology, sizing, and the air-gapped install are on the Deployment page.

3. Data classification and lifecycle

Not stored, not inspected

All data resides in the PostgreSQL instance you provision. No external data stores, no phone-home: AGLedger collects no usage data and operates no service that receives data from your deployment.

Retention and deletion. The customer controls retention as the database operator. The audit vault is append-only by design, which is in deliberate tension with deletion regulations (GDPR Article 17, CCPA): Signed Statements hold accountability metadata, while record criteria and completion evidence live in separate tables that can be archived or purged. In encrypted mode (§4) the server stores only the encrypted evidence envelope and an evidence hash, so destroying the encryption key renders the content irrecoverable while chain integrity is preserved - cryptographic erasure.

4. Cryptographic architecture

5. Audit vault integrity and offline verification

The audit vault is the core primitive: an append-only ledger of every accountability event. Each entry surfaces to customers as a Signed Statement:

Enforcement layers

Offline verification

Verification means one thing in this document: checking the cryptography. Three properties are independently checkable: the signatures are genuine against the instance’s published keys, the hash chain recomputes end to end (a break is located at the exact position it occurs), and the visible payload has not drifted from the signed bytes. A pass does not prove the claim inside a record was true or the work behind it good - the principal renders that verdict at the Gate, and verification confirms the verdict is authentic and untampered like every other entry.

GET /v1/records/{id}/audit-export exports a record’s chain as a self-contained signed bundle for verification on a machine that never talks to AGLedger. The published keys are the only external input, served unauthenticated at GET /v1/verification-keys and GET /.well-known/agledger-vault-keys.json, with active and retired keys both returned so historical chains verify across rotations. The standalone verifier, the CLI, the SDKs, and the MCP server all check the same exported bytes; step-by-step commands are in the offline verification guide.

No AGLedger code is required on the verification path. Every entry is a standard COSE_Sign1 envelope, so a stock COSE library can confirm a chain on its own; our verifier is a convenience, not a dependency. The chain also exports as DSSE envelopes wrapped in Sigstore Bundle format (v0.3, BYO-key), verifiable with cosign in private-infrastructure mode. Where the Transparency Service is enabled, an export can include SCITT Receipts - RFC 9162 Merkle inclusion proofs in COSE, opt-in via ?receipts=true - proving an entry was admitted to the transparency log at a known position, independent of the chain itself.

Because verification needs nothing but the bytes and the published keys, an auditor, a counterparty, a regulator, or a court can confirm a chain years later - with the Server shut down, the license lapsed, or the vendor gone. The proof outlives the vendor.

6. Key management and rotation

The vault signing key is the trust root of the chain. It is supplied as VAULT_SIGNING_KEY - required in production and customer-held: AGLedger LLC never possesses it. The customer protects the private key with their own secrets manager (§12).

Zero-downtime rotation

Key loss does not invalidate history. Verification uses the public key recorded in the database, not the private key in the environment. Losing the private key stops new signing; it does not retroactively break the existing chain. The registry supports unlimited rotations and records an algorithm per key, so a chain spanning two algorithms verifies entry by entry against the key that signed it (§14).

7. Authentication and access control

Two authentication paths, same protocol on the wire. Enterprise installs lead with OIDC-bound ephemeral signing certificates: agents exchange a JWT from the customer’s own identity provider (Auth0, Okta, Azure AD, Keycloak, GCP WIF, K8s service-account tokens) for a short-lived AGLedger cert via POST /v1/auth/oidc/cert - 10 minutes by default, configurable per issuer up to one hour - and present it as the Bearer credential. No agent holds a long-lived key; blast radius on credential compromise is minutes.

Long-lived API keys remain fully supported for development, the quickstart, and single-operator installs. Keys are never stored in plaintext - the server computes HMAC-SHA256 and looks up the hash. Both credential types produce the same chain envelope, and the actor identity each carries is named inside the signed payload (§1). Trust anchors are configured per-org via POST /v1/admin/trusted-issuers - one row per IdP per purpose with an applies_to discriminator (agent / principal / admin / any); JWKS endpoints are auto-discovered via OIDC well-known. See the Authentication guide.

8. Federation and privacy boundary

Across organizations, federation is peer-to-peer signed-message transport over TLS. Each Server signs every request with its own per-instance Ed25519 key over a domain-separated sign input (method, path, RFC 8785-canonical body hash, timestamp, nonce); there is no shared key and no central coordinator.

Each Server remains sovereign: it records the signed bytes a peer sent, verifies them against the peer’s published key, and never holds the peer’s underlying business data. Transport mechanics live on the Federation page.

9. Application security

10. Infrastructure hardening

11. Threat model

Explicitly out of scope

12. Privacy, data protection, and shared responsibility

AGLedger is self-hosted software: in the typical deployment, AGLedger LLC is neither a data processor nor a data controller. Residency follows the customer’s database placement, license validation is an offline Ed25519 check, and no AGLedger LLC system sits in the data path. Zero sub-processors for customer data in the standard deployment; no international transfers when sharing is off; encrypted mode enables cryptographic erasure (§3).

13. Compliance mapping

AGLedger captures signed records, delegation chains, and cross-org evidence transport regardless of regulation; downstream, these map to the obligations below. Detailed crosswalks live on the dedicated pages.

SOC 2: not a certification - AGLedger is self-hosted software, not a service organization, so your deployment runs under your existing certifications. Enterprise customers can review the source code and request a SOC 2 alignment report mapping AGLedger’s controls to the Trust Services Criteria (internal readiness assessment completed March 2026).

14. Algorithm agility and post-quantum readiness

15. Continuity and releases

16. Incident response