@parmanasystems/audit-db 1.0.19

package/README.md

@@ -0,0 +1,170 @@
+# @parmanasystems/audit-db
+
+PostgreSQL audit database client for parmanasystems governance decisions, verifications, and security events.
+
+## Overview
+
+`audit-db` provides an `AuditDb` class that persists an immutable audit trail of every governance action. All write methods are **fire-and-forget** — they enqueue a database write and return immediately, so they never block or delay server responses.
+
+The schema lives in PostgreSQL and is managed by the bundled `runMigrations()` function, which is idempotent and safe to run on every server startup.
+
+## Schema
+
+### Tables
+
+| Table | Purpose |
+|-------|---------|
+| `audit_decisions` | One row per `POST /execute` — stores the full `ExecutionAttestation` as JSONB alongside extracted scalar fields for indexed queries. |
+| `audit_verifications` | One row per `POST /verify` — records each check result (`signature_verified`, `runtime_verified`, `schema_compatible`). |
+| `audit_security_events` | Auth failures, replay attempts, malformed requests. Severity: `low \| medium \| high \| critical`. Uses `occurred_at` timestamp column. |
+| `audit_api_access` | Every inbound HTTP request with method, path, status code, response time (`response_time_ms`), user agent, and optional `execution_id`. |
+
+### Views
+
+| View | Purpose |
+|------|---------|
+| `view_decision_timeline` | `audit_decisions` LEFT JOINed to `audit_verifications` — one row per decision, with verification outcome if available. |
+| `view_security_dashboard` | Security events aggregated by `(event_type, severity)` with counts and timestamps. |
+
+## Installation
+
+```bash
+npm install @parmanasystems/audit-db
+```
+
+Requires `pg` (node-postgres) which is listed as a peer dependency.
+
+## Quick start
+
+```typescript
+import { AuditDb } from "@parmanasystems/audit-db";
+
+const db = new AuditDb(process.env.AUDIT_DATABASE_URL!);
+
+// Run migrations once on startup (idempotent)
+await db.migrate();
+
+// Fire-and-forget writes (never await these in the request path)
+db.recordDecision(attestation);
+db.recordVerification(executionId, verificationResult);
+db.recordSecurityEvent({
+  event_type: "auth_failure",
+  severity: "medium",
+  ip_address: req.ip,
+  path: "/execute",
+  method: "POST",
+  user_agent: req.headers["user-agent"],
+});
+db.recordApiAccess({
+  method: "POST",
+  path: "/execute",
+  status_code: 200,
+  response_time_ms: 12,
+  execution_id: attestation.execution_id,
+});
+
+// Async reads
+const stats = await db.getStats();
+const timeline = await db.getDecisionTimeline(100, { policy_id: "claims-approval" });
+const decision = await db.getDecisionById("11111111-...");
+const verifications = await db.getVerificationsByExecution("11111111-...");
+const dashboard = await db.getSecurityDashboard();
+
+await db.disconnect();
+```
+
+## Server integration
+
+When `AUDIT_DATABASE_URL` is set, the parmanasystems server automatically:
+
+1. Runs `db.migrate()` on startup (logs failure, continues running).
+2. Registers an `onResponse` Fastify hook that records every request and emits a security event for 401 responses.
+3. Calls `db.recordDecision()` after each `POST /execute`.
+4. Calls `db.recordVerification()` after each `POST /verify`.
+5. Exposes five read-only audit routes:
+
+| Route | Description |
+|-------|-------------|
+| `GET /audit/decisions` | Decision timeline with optional query filters: `limit`, `offset`, `policy_id`, `decision`, `from`, `to` |
+| `GET /audit/decisions/:executionId` | Single decision with full attestation JSONB |
+| `GET /audit/security` | Security event dashboard, with optional `from`, `to`, `limit` filters |
+| `GET /audit/stats` | Aggregate counts: total decisions, verifications, security events, API calls |
+| `GET /audit/verifications/:executionId` | All verification attempts for an execution, newest first |
+
+## Docker Compose
+
+The included `docker-compose.yml` wires up a `postgres:16-alpine` service and passes `AUDIT_DATABASE_URL` to the server automatically. Set `POSTGRES_PASSWORD` in `.env` before running:
+
+```bash
+cp .env.example .env
+# Edit .env — set POSTGRES_PASSWORD and other values
+docker compose up
+```
+
+## API
+
+### `new AuditDb(connectionString: string)`
+
+Creates a new pool-backed audit client.
+
+### `ping(): Promise<void>`
+
+Sends `SELECT 1` to verify the connection is alive. Used by the server health check.
+
+### `migrate(): Promise<void>`
+
+Runs the schema SQL inside a transaction. Safe to call on every startup — all DDL uses `IF NOT EXISTS` / `CREATE OR REPLACE`.
+
+### `recordDecision(attestation: ExecutionAttestation): void`
+
+Fire-and-forget. Inserts the attestation into `audit_decisions`. Duplicate `execution_id` is silently ignored (`ON CONFLICT DO NOTHING`).
+
+### `recordVerification(executionId: string, result: VerificationResult): void`
+
+Fire-and-forget. Inserts the verification result into `audit_verifications`.
+
+### `recordSecurityEvent(event: SecurityEventInput): void`
+
+Fire-and-forget. Inserts into `audit_security_events`. Required: `event_type`, `severity` (`low | medium | high | critical`). Optional: `ip_address`, `path`, `method`, `user_agent`, `details` (JSONB).
+
+### `recordApiAccess(access: ApiAccessInput): void`
+
+Fire-and-forget. Inserts into `audit_api_access`. Required: `method`, `path`, `status_code`. Optional: `response_time_ms`, `ip_address`, `user_agent`, `execution_id`.
+
+### `getDecisionTimeline(limit?: number, filter?: DecisionFilter): Promise<DecisionTimelineRow[]>`
+
+Queries `view_decision_timeline`. Default limit 100. Optional filter fields: `policy_id`, `decision`, `from_date`, `to_date`.
+
+### `getStats(): Promise<AuditStats>`
+
+Returns seven aggregate counts as strings (PostgreSQL `BIGINT` → TypeScript `string`):
+
+| Field | Description |
+|---|---|
+| `total_decisions` | Total rows in `audit_decisions` |
+| `decisions_today` | Rows where `executed_at >= CURRENT_DATE` |
+| `total_verifications` | Total rows in `audit_verifications` |
+| `valid_verifications` | Verifications where `valid = true` |
+| `invalid_verifications` | Verifications where `valid = false` |
+| `total_security_events` | Total rows in `audit_security_events` |
+| `total_api_calls` | Total rows in `audit_api_access` |
+
+### `getDecisionById(executionId: string): Promise<AuditDecision | null>`
+
+Returns the full decision row including the raw `attestation` JSONB, or `null` if not found.
+
+### `getVerificationsByExecution(executionId: string): Promise<AuditVerification[]>`
+
+Returns all verification attempts for a given `execution_id`, newest first.
+
+### `getSecurityDashboard(): Promise<SecurityDashboardRow[]>`
+
+Returns `view_security_dashboard` rows ordered by `event_count DESC`. Each row includes `event_type`, `severity`, `event_count` (string), `first_occurrence`, and `last_occurrence`.
+
+### `disconnect(): Promise<void>`
+
+Drains the connection pool. Also available as `close()` — both call `pool.end()`.
+
+## License
+
+Apache-2.0

package/dist/index.d.ts

@@ -0,0 +1,124 @@
+import { ExecutionAttestation } from '@parmanasystems/execution';
+export { ExecutionAttestation } from '@parmanasystems/execution';
+import { VerificationResult } from '@parmanasystems/verifier';
+export { VerificationResult } from '@parmanasystems/verifier';
+import { PoolClient } from 'pg';
+
+interface AuditDecision {
+    id: number;
+    execution_id: string;
+    policy_id: string;
+    policy_version: string;
+    schema_version: string;
+    runtime_version: string;
+    runtime_hash: string;
+    decision: string;
+    signals_hash: string;
+    signature: string;
+    attestation: ExecutionAttestation;
+    executed_at: Date;
+    recorded_at: Date;
+}
+interface AuditVerification {
+    id: number;
+    execution_id: string;
+    valid: boolean;
+    signature_verified: boolean;
+    runtime_verified: boolean;
+    schema_compatible: boolean;
+    verified_at: Date;
+}
+type SecurityEventSeverity = "low" | "medium" | "high" | "critical";
+interface SecurityEventInput {
+    event_type: string;
+    severity: SecurityEventSeverity;
+    ip_address?: string;
+    path?: string;
+    method?: string;
+    user_agent?: string;
+    details?: Record<string, unknown>;
+}
+interface AuditSecurityEvent extends SecurityEventInput {
+    id: number;
+    occurred_at: Date;
+}
+interface ApiAccessInput {
+    method: string;
+    path: string;
+    status_code: number;
+    response_time_ms?: number;
+    ip_address?: string;
+    user_agent?: string;
+    execution_id?: string;
+}
+interface AuditApiAccess extends ApiAccessInput {
+    id: number;
+    accessed_at: Date;
+}
+interface DecisionTimelineRow {
+    execution_id: string;
+    policy_id: string;
+    policy_version: string;
+    decision: string;
+    runtime_version: string;
+    runtime_hash: string;
+    executed_at: Date;
+    recorded_at: Date;
+    verification_valid: boolean | null;
+    signature_verified: boolean | null;
+    runtime_verified: boolean | null;
+    schema_compatible: boolean | null;
+    verified_at: Date | null;
+}
+interface SecurityDashboardRow {
+    event_type: string;
+    severity: string;
+    /** pg returns BIGINT as string */
+    event_count: string;
+    last_occurrence: Date;
+    first_occurrence: Date;
+}
+interface DecisionFilter {
+    policy_id?: string;
+    decision?: string;
+    /** ISO date string — inclusive lower bound on executed_at */
+    from_date?: string;
+    /** ISO date string — inclusive upper bound on executed_at */
+    to_date?: string;
+}
+/** All counts returned as strings because pg serialises BIGINT as string. */
+interface AuditStats {
+    total_decisions: string;
+    decisions_today: string;
+    total_verifications: string;
+    valid_verifications: string;
+    invalid_verifications: string;
+    total_security_events: string;
+    total_api_calls: string;
+}
+
+declare class AuditDb {
+    private readonly pool;
+    constructor(connectionString: string);
+    ping(): Promise<void>;
+    disconnect(): Promise<void>;
+    migrate(): Promise<void>;
+    /** Fire-and-forget — never throws, never delays the caller. */
+    recordDecision(attestation: ExecutionAttestation): void;
+    /** Fire-and-forget — never throws, never delays the caller. */
+    recordVerification(executionId: string, result: VerificationResult): void;
+    /** Fire-and-forget — never throws, never delays the caller. */
+    recordSecurityEvent(event: SecurityEventInput): void;
+    /** Fire-and-forget — never throws, never delays the caller. */
+    recordApiAccess(access: ApiAccessInput): void;
+    getDecisionTimeline(limit?: number, filter?: DecisionFilter): Promise<DecisionTimelineRow[]>;
+    getStats(): Promise<AuditStats>;
+    getDecisionById(executionId: string): Promise<AuditDecision | null>;
+    getVerificationsByExecution(executionId: string): Promise<AuditVerification[]>;
+    getSecurityDashboard(): Promise<SecurityDashboardRow[]>;
+    close(): Promise<void>;
+}
+
+declare function runMigrations(client: PoolClient): Promise<void>;
+
+export { type ApiAccessInput, type AuditApiAccess, AuditDb, type AuditDecision, type AuditSecurityEvent, type AuditStats, type AuditVerification, type DecisionFilter, type DecisionTimelineRow, type SecurityDashboardRow, type SecurityEventInput, type SecurityEventSeverity, runMigrations };

package/dist/index.js

@@ -0,0 +1,282 @@
+// src/client.ts
+import { Pool } from "pg";
+
+// src/migrations.ts
+var SCHEMA_SQL = `
+CREATE TABLE IF NOT EXISTS audit_decisions (
+  id              BIGSERIAL    PRIMARY KEY,
+  execution_id    UUID         NOT NULL UNIQUE,
+  policy_id       TEXT         NOT NULL,
+  policy_version  TEXT         NOT NULL,
+  schema_version  TEXT         NOT NULL,
+  runtime_version TEXT         NOT NULL,
+  runtime_hash    TEXT         NOT NULL,
+  decision        TEXT         NOT NULL,
+  signals_hash    TEXT         NOT NULL,
+  signature       TEXT         NOT NULL,
+  attestation     JSONB        NOT NULL,
+  executed_at     TIMESTAMPTZ  NOT NULL,
+  recorded_at     TIMESTAMPTZ  NOT NULL DEFAULT NOW()
+);
+
+CREATE INDEX IF NOT EXISTS idx_audit_decisions_policy_id
+  ON audit_decisions (policy_id);
+CREATE INDEX IF NOT EXISTS idx_audit_decisions_executed_at
+  ON audit_decisions (executed_at DESC);
+CREATE INDEX IF NOT EXISTS idx_audit_decisions_decision
+  ON audit_decisions (decision);
+
+CREATE TABLE IF NOT EXISTS audit_verifications (
+  id                   BIGSERIAL    PRIMARY KEY,
+  execution_id         UUID         NOT NULL,
+  valid                BOOLEAN      NOT NULL,
+  signature_verified   BOOLEAN      NOT NULL,
+  runtime_verified     BOOLEAN      NOT NULL,
+  schema_compatible    BOOLEAN      NOT NULL,
+  verified_at          TIMESTAMPTZ  NOT NULL DEFAULT NOW()
+);
+
+CREATE INDEX IF NOT EXISTS idx_audit_verifications_execution_id
+  ON audit_verifications (execution_id);
+CREATE INDEX IF NOT EXISTS idx_audit_verifications_valid
+  ON audit_verifications (valid);
+CREATE INDEX IF NOT EXISTS idx_audit_verifications_verified_at
+  ON audit_verifications (verified_at DESC);
+
+CREATE TABLE IF NOT EXISTS audit_security_events (
+  id           BIGSERIAL    PRIMARY KEY,
+  event_type   TEXT         NOT NULL,
+  severity     TEXT         NOT NULL CHECK (severity IN ('low','medium','high','critical')),
+  ip_address   TEXT,
+  path         TEXT,
+  method       TEXT,
+  user_agent   TEXT,
+  details      JSONB,
+  occurred_at  TIMESTAMPTZ  NOT NULL DEFAULT NOW()
+);
+
+CREATE INDEX IF NOT EXISTS idx_audit_security_events_event_type
+  ON audit_security_events (event_type);
+CREATE INDEX IF NOT EXISTS idx_audit_security_events_severity
+  ON audit_security_events (severity);
+CREATE INDEX IF NOT EXISTS idx_audit_security_events_occurred_at
+  ON audit_security_events (occurred_at DESC);
+
+CREATE TABLE IF NOT EXISTS audit_api_access (
+  id               BIGSERIAL    PRIMARY KEY,
+  method           TEXT         NOT NULL,
+  path             TEXT         NOT NULL,
+  status_code      INTEGER      NOT NULL,
+  response_time_ms INTEGER,
+  ip_address       TEXT,
+  user_agent       TEXT,
+  execution_id     UUID,
+  accessed_at      TIMESTAMPTZ  NOT NULL DEFAULT NOW()
+);
+
+CREATE INDEX IF NOT EXISTS idx_audit_api_access_path
+  ON audit_api_access (path);
+CREATE INDEX IF NOT EXISTS idx_audit_api_access_status_code
+  ON audit_api_access (status_code);
+CREATE INDEX IF NOT EXISTS idx_audit_api_access_accessed_at
+  ON audit_api_access (accessed_at DESC);
+
+CREATE OR REPLACE VIEW view_decision_timeline AS
+SELECT
+  d.execution_id,
+  d.policy_id,
+  d.policy_version,
+  d.decision,
+  d.runtime_version,
+  d.runtime_hash,
+  d.executed_at,
+  d.recorded_at,
+  v.valid              AS verification_valid,
+  v.signature_verified,
+  v.runtime_verified,
+  v.schema_compatible,
+  v.verified_at
+FROM  audit_decisions d
+LEFT  JOIN audit_verifications v ON d.execution_id = v.execution_id;
+
+CREATE OR REPLACE VIEW view_security_dashboard AS
+SELECT
+  event_type,
+  severity,
+  COUNT(*)         AS event_count,
+  MAX(occurred_at) AS last_occurrence,
+  MIN(occurred_at) AS first_occurrence
+FROM  audit_security_events
+GROUP BY event_type, severity;
+`;
+async function runMigrations(client) {
+  await client.query("BEGIN");
+  try {
+    await client.query(SCHEMA_SQL);
+    await client.query("COMMIT");
+  } catch (err) {
+    await client.query("ROLLBACK");
+    throw err;
+  }
+}
+
+// src/client.ts
+var AuditDb = class {
+  pool;
+  constructor(connectionString) {
+    this.pool = new Pool({ connectionString });
+  }
+  async ping() {
+    await this.pool.query("SELECT 1");
+  }
+  async disconnect() {
+    await this.pool.end();
+  }
+  async migrate() {
+    const client = await this.pool.connect();
+    try {
+      await runMigrations(client);
+    } finally {
+      client.release();
+    }
+  }
+  /** Fire-and-forget — never throws, never delays the caller. */
+  recordDecision(attestation) {
+    this.pool.query(
+      `INSERT INTO audit_decisions
+          (execution_id, decision, execution_state,
+           runtime_hash, signature, attestation, executed_at)
+         VALUES ($1,$2,$3,$4,$5,$6,$7)
+         ON CONFLICT (execution_id) DO NOTHING`,
+      [
+        attestation.execution_id,
+        attestation.decision,
+        attestation.execution_state,
+        attestation.runtime_hash,
+        attestation.signature,
+        JSON.stringify(attestation),
+        (/* @__PURE__ */ new Date()).toISOString()
+      ]
+    ).catch(() => void 0);
+  }
+  /** Fire-and-forget — never throws, never delays the caller. */
+  recordVerification(executionId, result) {
+    this.pool.query(
+      `INSERT INTO audit_verifications
+          (execution_id, valid, signature_verified, runtime_verified, schema_compatible)
+         VALUES ($1,$2,$3,$4,$5)`,
+      [
+        executionId,
+        result.valid,
+        result.checks.signature_verified,
+        result.checks.runtime_verified,
+        result.checks.schema_compatible
+      ]
+    ).catch(() => void 0);
+  }
+  /** Fire-and-forget — never throws, never delays the caller. */
+  recordSecurityEvent(event) {
+    this.pool.query(
+      `INSERT INTO audit_security_events
+          (event_type, severity, ip_address, path, method, user_agent, details)
+         VALUES ($1,$2,$3,$4,$5,$6,$7)`,
+      [
+        event.event_type,
+        event.severity,
+        event.ip_address ?? null,
+        event.path ?? null,
+        event.method ?? null,
+        event.user_agent ?? null,
+        event.details != null ? JSON.stringify(event.details) : null
+      ]
+    ).catch(() => void 0);
+  }
+  /** Fire-and-forget — never throws, never delays the caller. */
+  recordApiAccess(access) {
+    this.pool.query(
+      `INSERT INTO audit_api_access
+          (method, path, status_code, response_time_ms, ip_address, user_agent, execution_id)
+         VALUES ($1,$2,$3,$4,$5,$6,$7)`,
+      [
+        access.method,
+        access.path,
+        access.status_code,
+        access.response_time_ms ?? null,
+        access.ip_address ?? null,
+        access.user_agent ?? null,
+        access.execution_id ?? null
+      ]
+    ).catch(() => void 0);
+  }
+  async getDecisionTimeline(limit = 100, filter) {
+    const conditions = [];
+    const values = [];
+    if (filter?.policy_id) {
+      values.push(filter.policy_id);
+      conditions.push(`policy_id = $${values.length}`);
+    }
+    if (filter?.decision) {
+      values.push(filter.decision);
+      conditions.push(`decision = $${values.length}`);
+    }
+    if (filter?.from_date) {
+      values.push(filter.from_date);
+      conditions.push(`executed_at >= $${values.length}`);
+    }
+    if (filter?.to_date) {
+      values.push(filter.to_date);
+      conditions.push(`executed_at <= $${values.length}`);
+    }
+    values.push(limit);
+    const limitParam = `$${values.length}`;
+    const where = conditions.length ? `WHERE ${conditions.join(" AND ")}` : "";
+    const { rows } = await this.pool.query(
+      `SELECT * FROM view_decision_timeline ${where} ORDER BY executed_at DESC LIMIT ${limitParam}`,
+      values
+    );
+    return rows;
+  }
+  async getStats() {
+    const { rows } = await this.pool.query(`
+      SELECT
+        (SELECT COUNT(*) FROM audit_decisions)::text AS total_decisions,
+        (SELECT COUNT(*) FROM audit_decisions WHERE executed_at >= CURRENT_DATE)::text AS decisions_today,
+        (SELECT COUNT(*) FROM audit_verifications)::text AS total_verifications,
+        (SELECT COUNT(*) FROM audit_verifications WHERE valid = true)::text AS valid_verifications,
+        (SELECT COUNT(*) FROM audit_verifications WHERE valid = false)::text AS invalid_verifications,
+        (SELECT COUNT(*) FROM audit_security_events)::text AS total_security_events,
+        (SELECT COUNT(*) FROM audit_api_access)::text AS total_api_calls
+    `);
+    return rows[0];
+  }
+  async getDecisionById(executionId) {
+    const { rows } = await this.pool.query(
+      `SELECT * FROM audit_decisions WHERE execution_id = $1`,
+      [executionId]
+    );
+    return rows[0] ?? null;
+  }
+  async getVerificationsByExecution(executionId) {
+    const { rows } = await this.pool.query(
+      `SELECT * FROM audit_verifications
+       WHERE execution_id = $1
+       ORDER BY verified_at DESC`,
+      [executionId]
+    );
+    return rows;
+  }
+  async getSecurityDashboard() {
+    const { rows } = await this.pool.query(
+      `SELECT * FROM view_security_dashboard ORDER BY event_count DESC`
+    );
+    return rows;
+  }
+  async close() {
+    await this.pool.end();
+  }
+};
+export {
+  AuditDb,
+  runMigrations
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/client.ts","../src/migrations.ts"],"sourcesContent":["import { Pool } from \"pg\";\nimport type { PoolClient } from \"pg\";\n\nimport type { ExecutionAttestation } from \"@parmanasystems/execution\";\nimport type { VerificationResult } from \"@parmanasystems/verifier\";\n\nimport type {\n  AuditDecision,\n  AuditVerification,\n  SecurityEventInput,\n  ApiAccessInput,\n  DecisionTimelineRow,\n  DecisionFilter,\n  SecurityDashboardRow,\n  AuditStats,\n} from \"./types.js\";\nimport { runMigrations } from \"./migrations.js\";\n\nexport class AuditDb {\n  private readonly pool: InstanceType<typeof Pool>;\n\n  constructor(connectionString: string) {\n    this.pool = new Pool({ connectionString });\n  }\n\n  async ping(): Promise<void> {\n    await this.pool.query(\"SELECT 1\");\n  }\n\n  async disconnect(): Promise<void> {\n    await this.pool.end();\n  }\n\n  async migrate(): Promise<void> {\n    const client: PoolClient = await this.pool.connect();\n    try {\n      await runMigrations(client);\n    } finally {\n      client.release();\n    }\n  }\n\n  /** Fire-and-forget — never throws, never delays the caller. */\n  recordDecision(attestation: ExecutionAttestation): void {\n    this.pool\n      .query(\n        `INSERT INTO audit_decisions\n          (execution_id, decision, execution_state,\n           runtime_hash, signature, attestation, executed_at)\n         VALUES ($1,$2,$3,$4,$5,$6,$7)\n         ON CONFLICT (execution_id) DO NOTHING`,\n        [\n          attestation.execution_id,\n          attestation.decision,\n          attestation.execution_state,\n          attestation.runtime_hash,\n          attestation.signature,\n          JSON.stringify(attestation),\n          new Date().toISOString(),\n        ],\n      )\n      .catch(() => undefined);\n  }\n\n  /** Fire-and-forget — never throws, never delays the caller. */\n  recordVerification(executionId: string, result: VerificationResult): void {\n    this.pool\n      .query(\n        `INSERT INTO audit_verifications\n          (execution_id, valid, signature_verified, runtime_verified, schema_compatible)\n         VALUES ($1,$2,$3,$4,$5)`,\n        [\n          executionId,\n          result.valid,\n          result.checks.signature_verified,\n          result.checks.runtime_verified,\n          result.checks.schema_compatible,\n        ],\n      )\n      .catch(() => undefined);\n  }\n\n  /** Fire-and-forget — never throws, never delays the caller. */\n  recordSecurityEvent(event: SecurityEventInput): void {\n    this.pool\n      .query(\n        `INSERT INTO audit_security_events\n          (event_type, severity, ip_address, path, method, user_agent, details)\n         VALUES ($1,$2,$3,$4,$5,$6,$7)`,\n        [\n          event.event_type,\n          event.severity,\n          event.ip_address ?? null,\n          event.path ?? null,\n          event.method ?? null,\n          event.user_agent ?? null,\n          event.details != null ? JSON.stringify(event.details) : null,\n        ],\n      )\n      .catch(() => undefined);\n  }\n\n  /** Fire-and-forget — never throws, never delays the caller. */\n  recordApiAccess(access: ApiAccessInput): void {\n    this.pool\n      .query(\n        `INSERT INTO audit_api_access\n          (method, path, status_code, response_time_ms, ip_address, user_agent, execution_id)\n         VALUES ($1,$2,$3,$4,$5,$6,$7)`,\n        [\n          access.method,\n          access.path,\n          access.status_code,\n          access.response_time_ms ?? null,\n          access.ip_address ?? null,\n          access.user_agent ?? null,\n          access.execution_id ?? null,\n        ],\n      )\n      .catch(() => undefined);\n  }\n\n  async getDecisionTimeline(limit = 100, filter?: DecisionFilter): Promise<DecisionTimelineRow[]> {\n    const conditions: string[] = [];\n    const values: unknown[] = [];\n\n    if (filter?.policy_id) {\n      values.push(filter.policy_id);\n      conditions.push(`policy_id = $${values.length}`);\n    }\n    if (filter?.decision) {\n      values.push(filter.decision);\n      conditions.push(`decision = $${values.length}`);\n    }\n    if (filter?.from_date) {\n      values.push(filter.from_date);\n      conditions.push(`executed_at >= $${values.length}`);\n    }\n    if (filter?.to_date) {\n      values.push(filter.to_date);\n      conditions.push(`executed_at <= $${values.length}`);\n    }\n\n    values.push(limit);\n    const limitParam = `$${values.length}`;\n    const where = conditions.length ? `WHERE ${conditions.join(\" AND \")}` : \"\";\n\n    const { rows } = await this.pool.query<DecisionTimelineRow>(\n      `SELECT * FROM view_decision_timeline ${where} ORDER BY executed_at DESC LIMIT ${limitParam}`,\n      values,\n    );\n    return rows;\n  }\n\n  async getStats(): Promise<AuditStats> {\n    const { rows } = await this.pool.query<AuditStats>(`\n      SELECT\n        (SELECT COUNT(*) FROM audit_decisions)::text AS total_decisions,\n        (SELECT COUNT(*) FROM audit_decisions WHERE executed_at >= CURRENT_DATE)::text AS decisions_today,\n        (SELECT COUNT(*) FROM audit_verifications)::text AS total_verifications,\n        (SELECT COUNT(*) FROM audit_verifications WHERE valid = true)::text AS valid_verifications,\n        (SELECT COUNT(*) FROM audit_verifications WHERE valid = false)::text AS invalid_verifications,\n        (SELECT COUNT(*) FROM audit_security_events)::text AS total_security_events,\n        (SELECT COUNT(*) FROM audit_api_access)::text AS total_api_calls\n    `);\n    return rows[0]!;\n  }\n\n  async getDecisionById(executionId: string): Promise<AuditDecision | null> {\n    const { rows } = await this.pool.query<AuditDecision>(\n      `SELECT * FROM audit_decisions WHERE execution_id = $1`,\n      [executionId],\n    );\n    return rows[0] ?? null;\n  }\n\n  async getVerificationsByExecution(executionId: string): Promise<AuditVerification[]> {\n    const { rows } = await this.pool.query<AuditVerification>(\n      `SELECT * FROM audit_verifications\n       WHERE execution_id = $1\n       ORDER BY verified_at DESC`,\n      [executionId],\n    );\n    return rows;\n  }\n\n  async getSecurityDashboard(): Promise<SecurityDashboardRow[]> {\n    const { rows } = await this.pool.query<SecurityDashboardRow>(\n      `SELECT * FROM view_security_dashboard ORDER BY event_count DESC`,\n    );\n    return rows;\n  }\n\n  async close(): Promise<void> {\n    await this.pool.end();\n  }\n}","import type { PoolClient } from \"pg\";\n\n// Inlined so the bundle has no runtime fs dependency.\n// The canonical reference lives in schema.sql alongside this file.\nconst SCHEMA_SQL = `\nCREATE TABLE IF NOT EXISTS audit_decisions (\n  id              BIGSERIAL    PRIMARY KEY,\n  execution_id    UUID         NOT NULL UNIQUE,\n  policy_id       TEXT         NOT NULL,\n  policy_version  TEXT         NOT NULL,\n  schema_version  TEXT         NOT NULL,\n  runtime_version TEXT         NOT NULL,\n  runtime_hash    TEXT         NOT NULL,\n  decision        TEXT         NOT NULL,\n  signals_hash    TEXT         NOT NULL,\n  signature       TEXT         NOT NULL,\n  attestation     JSONB        NOT NULL,\n  executed_at     TIMESTAMPTZ  NOT NULL,\n  recorded_at     TIMESTAMPTZ  NOT NULL DEFAULT NOW()\n);\n\nCREATE INDEX IF NOT EXISTS idx_audit_decisions_policy_id\n  ON audit_decisions (policy_id);\nCREATE INDEX IF NOT EXISTS idx_audit_decisions_executed_at\n  ON audit_decisions (executed_at DESC);\nCREATE INDEX IF NOT EXISTS idx_audit_decisions_decision\n  ON audit_decisions (decision);\n\nCREATE TABLE IF NOT EXISTS audit_verifications (\n  id                   BIGSERIAL    PRIMARY KEY,\n  execution_id         UUID         NOT NULL,\n  valid                BOOLEAN      NOT NULL,\n  signature_verified   BOOLEAN      NOT NULL,\n  runtime_verified     BOOLEAN      NOT NULL,\n  schema_compatible    BOOLEAN      NOT NULL,\n  verified_at          TIMESTAMPTZ  NOT NULL DEFAULT NOW()\n);\n\nCREATE INDEX IF NOT EXISTS idx_audit_verifications_execution_id\n  ON audit_verifications (execution_id);\nCREATE INDEX IF NOT EXISTS idx_audit_verifications_valid\n  ON audit_verifications (valid);\nCREATE INDEX IF NOT EXISTS idx_audit_verifications_verified_at\n  ON audit_verifications (verified_at DESC);\n\nCREATE TABLE IF NOT EXISTS audit_security_events (\n  id           BIGSERIAL    PRIMARY KEY,\n  event_type   TEXT         NOT NULL,\n  severity     TEXT         NOT NULL CHECK (severity IN ('low','medium','high','critical')),\n  ip_address   TEXT,\n  path         TEXT,\n  method       TEXT,\n  user_agent   TEXT,\n  details      JSONB,\n  occurred_at  TIMESTAMPTZ  NOT NULL DEFAULT NOW()\n);\n\nCREATE INDEX IF NOT EXISTS idx_audit_security_events_event_type\n  ON audit_security_events (event_type);\nCREATE INDEX IF NOT EXISTS idx_audit_security_events_severity\n  ON audit_security_events (severity);\nCREATE INDEX IF NOT EXISTS idx_audit_security_events_occurred_at\n  ON audit_security_events (occurred_at DESC);\n\nCREATE TABLE IF NOT EXISTS audit_api_access (\n  id               BIGSERIAL    PRIMARY KEY,\n  method           TEXT         NOT NULL,\n  path             TEXT         NOT NULL,\n  status_code      INTEGER      NOT NULL,\n  response_time_ms INTEGER,\n  ip_address       TEXT,\n  user_agent       TEXT,\n  execution_id     UUID,\n  accessed_at      TIMESTAMPTZ  NOT NULL DEFAULT NOW()\n);\n\nCREATE INDEX IF NOT EXISTS idx_audit_api_access_path\n  ON audit_api_access (path);\nCREATE INDEX IF NOT EXISTS idx_audit_api_access_status_code\n  ON audit_api_access (status_code);\nCREATE INDEX IF NOT EXISTS idx_audit_api_access_accessed_at\n  ON audit_api_access (accessed_at DESC);\n\nCREATE OR REPLACE VIEW view_decision_timeline AS\nSELECT\n  d.execution_id,\n  d.policy_id,\n  d.policy_version,\n  d.decision,\n  d.runtime_version,\n  d.runtime_hash,\n  d.executed_at,\n  d.recorded_at,\n  v.valid              AS verification_valid,\n  v.signature_verified,\n  v.runtime_verified,\n  v.schema_compatible,\n  v.verified_at\nFROM  audit_decisions d\nLEFT  JOIN audit_verifications v ON d.execution_id = v.execution_id;\n\nCREATE OR REPLACE VIEW view_security_dashboard AS\nSELECT\n  event_type,\n  severity,\n  COUNT(*)         AS event_count,\n  MAX(occurred_at) AS last_occurrence,\n  MIN(occurred_at) AS first_occurrence\nFROM  audit_security_events\nGROUP BY event_type, severity;\n`;\n\nexport async function runMigrations(client: PoolClient): Promise<void> {\n  await client.query(\"BEGIN\");\n  try {\n    await client.query(SCHEMA_SQL);\n    await client.query(\"COMMIT\");\n  } catch (err) {\n    await client.query(\"ROLLBACK\");\n    throw err;\n  }\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@parmanasystems/audit-db",
+  "version": "1.0.19",
+  "private": false,
+  "type": "module",
+  "description": "PostgreSQL audit database client for parmanasystems governance decisions, verifications, and security events.",
+  "scripts": {
+    "build": "tsup"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "dependencies": {
+    "@parmanasystems/execution": "^1.0.19",
+    "@parmanasystems/verifier": "^1.0.19",
+    "pg": "^8.13.3"
+  },
+  "devDependencies": {
+    "@types/pg": "^8.11.13"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/pavancharak/parmanasystems-core.git"
+  },
+  "homepage": "https://github.com/pavancharak/parmanasystems-core",
+  "bugs": {
+    "url": "https://github.com/pavancharak/parmanasystems-core/issues"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts"
+}