> ## Documentation Index
> Fetch the complete documentation index at: https://docs.manthan.systems/llms.txt
> Use this file to discover all available pages before exploring further.

# @parmanasystems/audit-db

> PostgreSQL-backed audit storage for authority verification outcomes

Structured audit storage for governance attestations, overrides, security events, and API access logs. Backed by PostgreSQL with automatic schema migrations.

## Install

```bash theme={null}
npm install @parmanasystems/audit-db
```

## Key exports

| Export               | Description                                         |
| -------------------- | --------------------------------------------------- |
| `AuditDb`            | Main client class for all audit operations          |
| `runMigrations`      | Run schema migrations against a PostgreSQL database |
| `AuditDecision`      | Type - a stored authority verification outcome      |
| `AuditOverride`      | Type - a stored human override                      |
| `AuditVerification`  | Type - a stored verification result                 |
| `AuditSecurityEvent` | Type - a stored security event                      |

## Setup

```typescript theme={null}
import { AuditDb, runMigrations } from "@parmanasystems/audit-db";

// Run once at startup or in a migration script
await runMigrations(process.env.DATABASE_URL!);

const db = new AuditDb(process.env.DATABASE_URL!);
```

## Storing a decision

```typescript theme={null}
await db.recordDecision({
  executionId:           attestation.executionId,
  policyId:              attestation.policyId,
  policyVersion:         attestation.policyVersion,
  decision_action:       attestation.decision.action,
  decision_reason:       attestation.decision.reason,
  requires_override:     attestation.decision.requires_override,
  execution_state:       attestation.execution_state,
  execution_fingerprint: attestation.execution_fingerprint,
  signature:             attestation.signature,
});
```

## Querying decisions

```typescript theme={null}
const decisions = await db.getDecisions({
  policyId: "loan-approval",
  from:     new Date("2024-01-01"),
  to:       new Date("2024-12-31"),
});
```

## Storing an override

```typescript theme={null}
import { approveOverride } from "@parmanasystems/core";

const override = await approveOverride({
  execution_fingerprint:
    attestation.execution_fingerprint,
  approved_by:   "user@example.com",
  approver_role: "risk-manager",
  reason:        "Manually reviewed and approved.",
});

await db.recordOverride(override);
```

## Database schema

The audit database maintains five tables:

| Table                   | Contents                                                     |
| ----------------------- | ------------------------------------------------------------ |
| `audit_decisions`       | Every authority verification outcome with attestation fields |
| `audit_overrides`       | Human overrides with approver identity and signature         |
| `audit_verifications`   | Verification results for stored attestations                 |
| `audit_security_events` | Security events and anomaly detections                       |
| `audit_api_access`      | API access log for all governance requests                   |

## See also

* [Production Checklist](/guides/production-checklist) - audit persistence requirements
* [Server Package](/packages/server) - governance server with built-in audit-db integration