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.

AGLedger records accountability metadata in your infrastructure. Your data stays where it is, your traffic goes where it went, and a record reaches another organization only when its share flag is set. Topology, sizing, and the air-gapped install are on the install 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 does not collect product usage information.

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 under keys that signed key statements link to a key you pinned, 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 export carries the signing keys and the signed key statements that admit them: a genesis for the install’s first key, a succession signed by the old and new key at each rotation, a closure at each retirement. The one external input is a pin, the SHA-256 of a vault key’s SPKI (sha256:<hex>), which the installer prints and the operator hands the auditor out of band. The same keys are served unauthenticated at GET /v1/verification-keys and GET /.well-known/agledger-vault-keys.json: anchored keys only, retired ones included with their signed windows, each with its statements, plus anchoredFrom, the serving process’s own pin, to compare against yours. A key document is only as trustworthy as whatever served it, which is why the pin and not the document decides trust. 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.

The verifier is deliberately small, so that trusting it is not the same as trusting the Server: @agledger/verify-core has a single runtime dependency, a CBOR codec. A pin goes in as --trust-anchor sha256:<hex>, and the verifier walks the key statements from it, so a chain re-signed wholesale under a key written into the database, or shipped inside the export, fails with CHAIN_SIGNING_KEY_UNANCHORED. Each run reports a verdict: trusted (clean, every signing key anchored to the pin), unanchored (clean, no pin given), or failed. A run without a pin passes flagged as not anchored and never as trusted. Where a key came from is not whether it is trusted: --keys supplies keys from elsewhere and --require-supplied-keys refuses the export’s own, but keys fetched from the Server come from the same database an attacker would write to, and only the pin anchors them. Exit codes separate verified (0, with the verdict saying whether it was anchored), verification failed (1), and could-not-verify (2, malformed or missing input including a mistyped pin), so an inconclusive run never reads as a pass.

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 held outside the database, and the chain’s trust starts there. 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 (§13). The install script generates the keypair locally, on your machine, and prints its pin. At boot the key is read from an environment variable or a file, or fetched from AWS SSM Parameter Store (SecureString) or HashiCorp Vault KV v2; it can instead stay in AWS KMS (VAULT_SIGNING_KEY_KMS_ARN), where the private half never leaves KMS.

The key registry holds public keys only, and is append-only in the same way the chain is. DELETE and TRUNCATE are refused by trigger, and the single UPDATE the trigger permits is the active-to-retired transition: key material, algorithm, and activation instant are immutable once written. A registry row alone is trusted for nothing. A key counts only when a signed key statement (genesis, succession, or closure, kept in an append-only table of its own) links it to a key a process holds outside the database, so a key row written with database access alone is absent from the published keys and every entry it signs breaks as unanchored. Retired keys stay published with the activation and retirement instants their statements sign, and the offline verifier checks each entry’s write time against the validity window of the key that signed it.

Zero-downtime rotation

Key loss does not invalidate history. Verification uses the public keys and the key statements that sign them, not the private key in the environment. Losing the private key stops new signing; it does not retroactively break the existing chain. A replacement that nothing links to that history registers only when the operator pins the history it vouches for in VAULT_TRUST_ANCHORS; it starts under a fresh genesis, and auditors take its pin. 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 (§15).

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). Only asymmetric algorithms are accepted: HS* and none are excluded, with per-issuer overrides available on the trusted issuer. The HMAC secret behind key storage rotates without downtime through a previous-secret window. The provenance of an OIDC validation (the key thumbprint and the instant it was validated) is recorded into the signed chain alongside the record it authorized. 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 addressed to the receiving Server (its instance id, then method, path, RFC 8785-canonical body hash, timestamp, nonce), so a message signed for one peer does not verify at another; 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. Supply chain and release integrity

Every release is built and signed in CI; nothing is published by hand. Each artifact traces back to the commit and the workflow that produced it, checkable with stock tooling and no AGLedger account.

Signing is keyless. GitHub OIDC to Fulcio to the public Rekor transparency log, so the signing identity is the workflow that built the artifact rather than a key a person holds. Image provenance is generated by the isolated slsa-github-generator reusable workflow, which signs in a build the release job itself cannot reach.

Publication is gated. VEX-aware Trivy scanning at CRITICAL and HIGH on both architectures, boot gates on both architectures, and a FIPS-mode boot gate all pass before an image publishes.

CI actions are SHA-pinned, with one deliberate exception: the SLSA builder workflow is tag-pinned, because its verifier resolves the trusted builder by tag.

Verification is yours to run. The deployment repository’s SECURITY.md carries the exact commands per artifact: cosign for image and chart signatures, the attestation checks worth asserting, and slsa-verifier for provenance. The installers verify signatures when cosign is present; set AGLEDGER_REQUIRE_VERIFY=true and a run that cannot verify refuses to install. Marketplace and ECR mirrors are checked by digest equality against the authoritative image.

Runtime image. Red Hat UBI 10 minimal with Node 24, built from a digest-pinned build stage and running as a non-root user. Node’s permission model grants the application filesystem read and nothing else: writes, child processes, native addons, the inspector, WASI, and worker threads are all denied. Dependency updates run continuously (Dependabot) and Semgrep SAST runs before each release.

12. Threat model

Explicitly out of scope

13. 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 Personal Data in the standard deployment; no international transfers when sharing is off; encrypted mode enables cryptographic erasure (§3).

14. 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.

The EU AI Act mapping reaches into the engine: it ships the Act’s risk-tier taxonomy (Article 5, Annex III, Article 50) as first-class record vocabulary, so the tier a system claims is recorded inside the signed payload rather than tracked beside it.

SOC 2: not a certification - AGLedger is self-hosted software, not a service organization, so your deployment runs under your existing certifications.

15. Algorithm agility and post-quantum readiness

16. Continuity and releases

17. Incident response and coordinated vulnerability disclosure

Detected tampering

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.

AGLedger Coordinated Vulnerability Disclosure Policy

Version: 1.6 Effective Date: June 4, 2026 Last Updated: September 15, 2026 Contact: security@agledger.ai

This is the canonical coordinated vulnerability disclosure ("CVD") policy for the AGLedger software product (the self-hosted Licensed Software, SDKs, CLI, MCP server, container images, Helm charts, and release artifacts). It is the policy referenced by the SECURITY.md and security.txt files distributed with the software and published at agledger.ai/security, and by Software License Agreement § 6.6.

AGLedger's public online resources (the website, the documentation, and the registries from which the software is distributed) are governed by the Acceptable Use Policy, which sets out in § 6 how to report a vulnerability in those resources and provides that good-faith research conducted in compliance with that section does not breach the AUP. The safe harbor, good-faith conditions, disclosure timeline, and recognition terms in this policy apply to research on the software product.

1. Scope

In scope:

• The AGLedger Licensed Software (server) and its container images, Helm charts, air-gap bundles, and GitHub Release artifacts.
• The public AGLedger packages published on npm and PyPI.
• The cryptographic chain, signing/verification, federation, gate, and webhook (Notify) surfaces of the product.
• The integrity of our software supply chain (image signatures, build provenance, SBOM).

Out of scope:

• Findings that require a compromised host, a malicious privileged database administrator, or physical access already assumed in our threat model.
• Self-inflicted misconfiguration of a customer's own deployment (e.g., exposing the database, disabling TLS).
• Vulnerabilities in third-party dependencies that are already publicly disclosed and for which we have shipped, or are within the Support Terms window of shipping, a fix.
• Volumetric denial-of-service, social engineering of AGLedger staff, and findings against software versions outside the Supported Version window stated in the Support Terms. These may be reported but are triaged best-effort.

2. How to report

Email security@agledger.ai, or report privately through GitHub private vulnerability reporting on any public agledger-ai repository. If your report contains sensitive detail, say so in your first email without including the detail, and we will agree an encrypted channel with you before you send it. We do not currently publish a PGP key.

Please include:

1. The affected component and version (and image digest, if applicable).
2. A description of the vulnerability and its impact.
3. Reproduction steps or proof-of-concept (minimal; see §3).
4. Any suggested remediation.
5. Whether you intend to disclose publicly, and on what timeline.

We aim to acknowledge receipt promptly and to provide an initial assessment as soon as practicable.

3. Safe harbor for good-faith research

If you make a good-faith effort to comply with this policy during your research, AGLedger will:

• consider your research authorized under the Computer Fraud and Abuse Act and analogous laws, and will not pursue or support legal action against you for it;
• work with you to understand and resolve the issue promptly; and
• recognize your contribution (with your permission) once the issue is resolved.

Good-faith research means you:

(a) report promptly and do not exploit the vulnerability beyond the minimum proof-of-concept necessary to demonstrate it; (b) do not access, modify, exfiltrate, or destroy data that is not your own, beyond minimal proof-of-concept evidence; (c) do not degrade, disrupt, or impair the availability of any system or any other party's deployment; (d) test only against your own deployment or systems you are authorized to test, and never against another customer's deployment; (e) give us a reasonable opportunity to remediate before any public disclosure (see §5); and (f) comply with all applicable law.

This safe harbor is a statement of how AGLedger will treat good-faith research; it does not authorize action against third parties and does not waive any third party's rights.

4. Our handling process

1. Triage: confirm, reproduce, and assign a severity (CVSS-aligned).
2. Remediate: develop and test a Security Fix. Remediation targets for licensed customers are in the Support Terms; they are targets, not guarantees, and are made to customers, not to reporters.
3. Distribute: release the fix as signed artifacts through the public distribution channels, without authentication or entitlement checks. The contractual commitment to provide Security Fixes is made to Enterprise Edition Licensees under License Agreement §§ 6.2 and 6.4.
4. Notify: inform affected customers and, where the law requires (including the EU Cyber Resilience Act reporting cadence for actively exploited vulnerabilities and severe incidents), notify the competent authorities (the CSIRT-coordinator and ENISA) within the required 24-hour / 72-hour / 14-day windows.
5. Disclose: publish a security advisory and credit the reporter (with permission).

5. Coordinated disclosure timeline

We follow a 90-day coordinated disclosure window by default: we aim to release a fix and advisory within 90 days of a validated report, and we ask that you not disclose publicly before the earlier of (a) a fix being available or (b) 90 days, whichever comes first. For vulnerabilities under active exploitation, we will move faster and coordinate an accelerated timeline with you. We are happy to coordinate CVE assignment and joint disclosure.

6. Recognition

With your permission, we will acknowledge your contribution in the security advisory. AGLedger does not currently operate a paid bug-bounty program; this is a coordinated-disclosure (not a bounty) policy.

7. Changes

We may update this policy by posting a revised version with an updated effective date at agledger.ai/security. Material changes will be noted in the change log below.