Approval Service

The Approval Service implements the Human-in-the-Loop (HITL) approval system for AEGIS. It manages approval requests created by the orchestration engine at mandatory checkpoints, records reviewer decisions, handles escalation for timed-out requests, and writes HMAC-signed entries to the append-only audit trail.

Overview

All regulatory filings produced by AEGIS agents must be reviewed and approved by a human before submission. The approval service provides the backend for this workflow:

1. The orchestration engine detects a HITL checkpoint (e.g., pre_filing, good_cause_review)
2. It creates an approval request via this service, including a snapshot of the current execution state
3. The approval sits in pending status until a reviewer decides (approve, reject, or modify)
4. Once decided, the orchestration engine can resume execution

The service also implements time-based escalation: if a pending approval exceeds the configured timeout (default 24 hours), it can be reassigned to a fallback reviewer.

Every action (creation, decision, escalation) is recorded in the HMAC-signed, append-only audit trail.

Port & Language

Key Endpoints

Architecture

Module Breakdown

src/approval/
├── main.py         # FastAPI app, all endpoint definitions
├── config.py       # Settings from environment variables
├── schemas.py      # Pydantic request/response models
├── repository.py   # PostgreSQL CRUD for approval_requests table
├── audit.py        # HMAC-signed audit trail writer
└── seed_filings.py # Demo filing data seeder

Approval Lifecycle

Created (pending)
    │
    ├── Reviewer approves  → status: "approved"
    ├── Reviewer rejects   → status: "rejected"
    ├── Reviewer modifies  → status: "modified" (modified_output stored in snapshot)
    │
    └── Timeout exceeded   → Escalated (reassigned to fallback reviewer, stays "pending")

Approval Request Fields

Each approval request stores:

Decision Types

Reviewer Assignment Strategies

Escalation Logic

The /approvals/escalate endpoint finds all pending approvals whose created_at timestamp exceeds the configured timeout:

SELECT * FROM approval_requests
WHERE status = 'pending'
  AND created_at < NOW() - INTERVAL '1 second' * $1

If a fallback_reviewer_id is provided, timed-out approvals are reassigned to that reviewer. Each escalation is recorded in the audit trail.

Audit Trail (audit.py)

Every approval action writes a signed entry to the audit_logs table:

1. Payload construction: The event data dict is JSON-serialized with sorted keys
2. HMAC signing: A SHA-256 HMAC signature is computed using the HMAC_SIGNING_KEY
3. Insert: The entry is inserted into audit_logs with the signature

signature = hmac.new(
    settings.HMAC_SIGNING_KEY.encode(),
    json.dumps(event_data, sort_keys=True).encode(),
    hashlib.sha256,
).hexdigest()

The audit_logs table has database triggers that prevent UPDATE and DELETE operations, ensuring the trail is truly append-only.

Audit event types:

Dependencies

Python Packages

Infrastructure Dependencies

Configuration

Running Locally

cd services/approval-service
poetry install
poetry run uvicorn approval.main:app --reload --port 8004

Requires PostgreSQL to be running with the approval_requests and audit_logs tables created (handled by infrastructure/docker/postgres/init.sql).