Agent-readable docs index: /llms.txt. Full docs in one file: /llms-full.txt. Download /docs.zip to grep all markdown files locally.

Approval Lifecycle and State Machine

When an AI agent requests an action governed by an APPROVAL_REQUIRED policy rule, Dmint intercepts the call, persists a pending record, and halts execution before the tool is invoked.
Dmint does not block or sleep in a polling loop waiting for approval. The protected function raises ApprovalRequiredError immediately, allowing the host application to notify the operator and proceed with other work.

The 7-State Lifecycle Machine

An approval record transitions through a strictly validated state machine:
┌───────────┐ │ PENDING │ └─────┬─────┘ ┌────────────────┼────────────────┬────────────────┐ │ │ │ │ ▼ ▼ ▼ ▼ ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐ │ APPROVED │ │ REJECTED │ │ CANCELLED │ │ EXPIRED │ └─────┬─────┘ └───────────┘ └───────────┘ └───────────┘ │ ├────────────────┬────────────────┐ ▼ ▼ ▼ ┌───────────┐ ┌───────────┐ ┌────────────────────┐ │ CONSUMED │ │ EXPIRED │ │ POLICY_INVALIDATED │ └───────────┘ └───────────┘ └────────────────────┘

Complete State Definitions

StateTriggerDescriptionTool Execution Allowed?
PENDINGAgent initiates callRequest arguments fingerprinted and written to store.No
APPROVEDHuman signs via UI or CLICryptographic Ed25519 signature generated.Yes (exactly once on retry)
REJECTEDHuman rejects via UI or CLIMarked as rejected with optional audit note.No (fails closed)
CANCELLEDHost application or agent cancelsPending request withdrawn before review.No
EXPIREDSystem clock > expires_atApproval lifetime elapsed (configured via approval_ttl, e.g. 5 minutes).No (DMT_APPROVAL_EXPIRED)
POLICY_INVALIDATEDpolicy.json modifiedPolicy digest changed, invalidating unconsumed approvals.No (DMT_APPROVAL_POLICY_INVALID)
CONSUMEDHost retries approved requestAtomically marked consumed as tool executes.No (subsequent retries fail)

The End-to-End Retry Protocol

Dmint enforces non-blocking, asynchronous retry semantics:
1. Agent Calls Tool ──► Dmint halts call ──► Returns DMT_APPROVAL_REQUIRED (with req_id, apr_id) │ 2. Reviewer Inspects Request ▼ (Dashboard / CLI) ──────► dmint approve <apr_id> ──► Signs Ed25519 assertion (Executes NOTHING) │ 3. Host Retries Call ──────► Dmint Verifier ▼ ├── Checks Ed25519 Signature ├── Verifies Exact Argument Fingerprint ├── Checks TTL & Policy Digest └── Atomically transitions state: APPROVED ──► CONSUMED │ 4. Protected Tool ◄─────────────────────────────────┘ Executes ONCE

Cryptographic Assertion Format

When approved, LocalApprovalAuthority generates an Ed25519 digital signature over the canonical assertion envelope:
Approval Assertion Envelope
{ "algorithm": "Ed25519", "credential_version": "dmint/approval-assertion/v2", "payload": { "approval_id": "apr_01j7v0q9k3...", "approver_id": "alice@company.com", "approver_kind": "HUMAN", "audience": "dmint/dashboard/v1", "created_at": "2026-10-16T01:00:00Z", "deployment_epoch": "prod-2026", "expires_at": "2026-10-16T01:05:00Z", "issuer": "dmint-authority", "nonce": "n_4x8L0mK...", "policy_digest": "sha256:a1b2c3d4...", "request_fingerprint": "3b1a8f9024c...", "request_id": "req_8v7G9q...", "schema_version": "dmint/approval-record/v2" }, "signature": "base64:3f9a..." }

Security Invariants in the Assertion

  • request_fingerprint: Binds the signature to the exact RFC 8785 canonical arguments.
  • policy_digest: Binds the signature to the active policy epoch.
  • deployment_epoch: Prevents cross-cluster or rollback approval replay.
  • expires_at: Caps validity to a short window (configured via approval_ttl, e.g. 5 minutes).

Single-Use Replay Protection

Approvals are single-use tokens. Once executed, the record is permanently marked CONSUMED:

Concurrency Guarantees

  • PostgreSQL: Dmint uses SELECT ... FOR UPDATE row-level locks inside a serialized transaction. If 10 concurrent workers receive the same approved assertion and retry simultaneously, exactly one worker acquires the row lock, marks it CONSUMED, and runs the tool. The other 9 workers fail closed with DMT_APPROVAL_CONCURRENT_CONSUME or DMT_APPROVAL_CONSUMED.
  • SQLite: Dmint uses immediate transactions with PRAGMA busy_timeout = 5000 and thread-safe connection pooling to guarantee atomic serialization.

Row-Level Integrity Protection (HMAC)

To detect out-of-band database tampering (e.g., an unauthorized user editing SQLite with a hex editor or direct SQL to flip PENDING to APPROVED), every record in the approval store includes an HMAC-SHA256 signature: Domain: b"dmint/approval-record-integrity/v2\x00"
If any database row has been altered without knowledge of the 0600-protected integrity key, Dmint refuses to load or evaluate the row, failing closed with DMT_APPROVAL_CORRUPT.

Key Management & Split-Trust Model

How are signing keys managed, and why can't a compromised agent forge an approval?
Dmint operates on a split-trust model:
  • The Human Approver holds the Ed25519 Private Key (private.key). This file lives strictly on the reviewer's laptop or inside the isolated dmint-dashboard service with strict 0600 POSIX permissions. It is never mounted into or accessible by the agent.
  • The Enforcement Gateway holds only the Ed25519 Public Key configured in trusted_issuers.
# 1. Generate the authority keys (Ed25519 private key + HMAC storage key) dmint init-keys # 2. Export the public key to configure the gateway dmint export-public-key --format json
When an agent retries an execution, the gateway verifies the Ed25519 signature against its configured trusted_issuers. Because the agent has no access to private.key, it cannot forge signatures, and replaying old signatures fails because approvals are single-use (CONSUMED).

Next Steps