@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

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

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

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

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

Storing an override

import { approveOverride } from "@parmanasystems/core";

const override = await approveOverride({
  execution_fingerprint:
    attestation.execution_fingerprint,
  approved_by:   "[e-mail]",
  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 - audit persistence requirements
• Server Package - governance server with built-in audit-db integration