@cqrs-ddd/pipeline-audit 0.5.0

package/dist/sinks/postgres.sink.js

@@ -0,0 +1,132 @@
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+import { toPostgresJson } from '@cqrs-ddd/pipeline';
+import { stringifyAuditValue } from '../helpers/json.js';
+/** Allows `table` or `schema.table` made of unquoted SQL identifiers only. */
+const SAFE_IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)?$/;
+function assertSafeTable(table) {
+    if (!SAFE_IDENTIFIER.test(table)) {
+        throw new Error(`Invalid audit table name "${table}". ` +
+            'Use an unquoted identifier like "audit_log" or "schema.audit_log".');
+    }
+    return table;
+}
+/**
+ * SQL to create the audit table. Run once in a migration.
+ *
+ * A row whose `outcome` is `'pending'` is an operation that started and has no
+ * final record: `duration_ms` and `completed_at` stay null. An old pending row
+ * marks an attempt interrupted by a process stop, whose outcome is unknown:
+ *
+ * ```sql
+ * SELECT * FROM audit_log
+ * WHERE outcome = 'pending' AND occurred_at < now() - interval '1 hour';
+ * ```
+ *
+ * @param table - Table name (validated). Default `'audit_log'`.
+ */
+export function createAuditTableSql(table = 'audit_log') {
+    const name = assertSafeTable(table);
+    return `CREATE TABLE IF NOT EXISTS ${name} (
+  id              UUID        PRIMARY KEY,
+  correlation_id  TEXT        NOT NULL,
+  action          TEXT        NOT NULL,
+  severity        TEXT        NOT NULL,
+  outcome         TEXT        NOT NULL,
+  actor           JSONB,
+  request_kind    TEXT        NOT NULL,
+  request_name    TEXT        NOT NULL,
+  handler_name    TEXT        NOT NULL,
+  payload         JSONB,
+  response        JSONB,
+  error           JSONB,
+  duration_ms     DOUBLE PRECISION,
+  metadata        JSONB,
+  occurred_at     TIMESTAMPTZ NOT NULL,
+  completed_at    TIMESTAMPTZ
+);`;
+}
+/**
+ * {@link AuditSink} backed by **Postgres** (`pg`) — a drop-in replacement for
+ * the console sink. {@link begin} inserts a pending row when an operation
+ * starts, and {@link write} completes it under the same id (or inserts it, when
+ * no pending row exists), so an operation interrupted by a process stop stays
+ * visible as `'pending'`.
+ *
+ * Create the table once with {@link createAuditTableSql}. The table name is
+ * validated as a plain SQL identifier (it is interpolated, not parameterized);
+ * all record values are passed as bound parameters. A NUL character or a lone
+ * surrogate, which `jsonb` rejects, is stored as U+FFFD (see
+ * `toPostgresJson`), so one such character cannot lose the whole record.
+ *
+ * @example
+ * ```ts
+ * import { Pool } from 'pg';
+ * const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+ * await pool.query(createAuditTableSql());
+ * const sink = new PostgresAuditSink(pool);
+ * ```
+ */
+export class PostgresAuditSink {
+    db;
+    beginSql;
+    writeSql;
+    constructor(db, options = {}) {
+        this.db = db;
+        const table = assertSafeTable(options.table ?? 'audit_log');
+        const columns = `(id, correlation_id, action, severity, outcome, actor, request_kind,
+       request_name, handler_name, payload, response, error, duration_ms,
+       metadata, occurred_at, completed_at)`;
+        this.beginSql = `INSERT INTO ${table} ${columns}
+      VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15, NULL)`;
+        this.writeSql = `INSERT INTO ${table} ${columns}
+      VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15, now())
+      ON CONFLICT (id) DO UPDATE SET
+        outcome = EXCLUDED.outcome,
+        actor = EXCLUDED.actor,
+        payload = EXCLUDED.payload,
+        response = EXCLUDED.response,
+        error = EXCLUDED.error,
+        duration_ms = EXCLUDED.duration_ms,
+        metadata = EXCLUDED.metadata,
+        completed_at = EXCLUDED.completed_at`;
+    }
+    /** Inserts the pending row of an operation about to run. */
+    async begin(record) {
+        await this.db.query(this.beginSql, this.values(record));
+    }
+    /**
+     * Inserts the final row, or completes the pending row that {@link begin}
+     * inserted under the same id.
+     */
+    async write(record) {
+        await this.db.query(this.writeSql, this.values(record));
+    }
+    values(record) {
+        const json = (value) => toPostgresJson(stringifyAuditValue(value));
+        const metadata = record.metadata || record.tenantId
+            ? {
+                ...(record.metadata ?? {}),
+                ...(record.tenantId ? { tenantId: record.tenantId } : {}),
+            }
+            : null;
+        const final = record.outcome === 'pending' ? undefined : record;
+        return [
+            record.id,
+            record.correlationId,
+            record.action,
+            record.severity,
+            record.outcome,
+            record.actor ? json(record.actor) : null,
+            record.requestKind,
+            record.requestName,
+            record.handlerName,
+            record.payload === undefined ? null : json(record.payload),
+            final?.response === undefined ? null : json(final.response),
+            final?.error ? json(final.error) : null,
+            final?.durationMs ?? null,
+            metadata ? json(metadata) : null,
+            record.timestamp,
+        ];
+    }
+}
+//# sourceMappingURL=postgres.sink.js.map

package/dist/sinks/postgres.sink.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"postgres.sink.js","sourceRoot":"","sources":["../../src/sinks/postgres.sink.ts"],"names":[],"mappings":"AAAA,sEAAsE;AAEtE,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAyBzD,8EAA8E;AAC9E,MAAM,eAAe,GAAG,qDAAqD,CAAC;AAE9E,SAAS,eAAe,CAAC,KAAa;IACpC,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACjC,MAAM,IAAI,KAAK,CACb,6BAA6B,KAAK,KAAK;YACrC,oEAAoE,CACvE,CAAC;IACJ,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAK,GAAG,WAAW;IACrD,MAAM,IAAI,GAAG,eAAe,CAAC,KAAK,CAAC,CAAC;IACpC,OAAO,8BAA8B,IAAI;;;;;;;;;;;;;;;;;GAiBxC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,OAAO,iBAAiB;IAKT,EAAE;IAJJ,QAAQ,CAAS;IACjB,QAAQ,CAAS;IAElC,YACmB,EAAyB,EAC1C,OAAO,GAA6B,EAAE;kBADrB,EAAE;QAGnB,MAAM,KAAK,GAAG,eAAe,CAAC,OAAO,CAAC,KAAK,IAAI,WAAW,CAAC,CAAC;QAC5D,MAAM,OAAO,GAAG;;4CAEwB,CAAC;QACzC,IAAI,CAAC,QAAQ,GAAG,eAAe,KAAK,IAAI,OAAO;sFACmC,CAAC;QACnF,IAAI,CAAC,QAAQ,GAAG,eAAe,KAAK,IAAI,OAAO;;;;;;;;;;6CAUN,CAAC;IAC5C,CAAC;IAED,4DAA4D;IAC5D,KAAK,CAAC,KAAK,CAAC,MAAwB;QAClC,MAAM,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;IAC1D,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,KAAK,CAAC,MAAmB;QAC7B,MAAM,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;IAC1D,CAAC;IAEO,MAAM,CAAC,MAAsC;QACnD,MAAM,IAAI,GAAG,CAAC,KAAc,EAAE,EAAE,CAAC,cAAc,CAAC,mBAAmB,CAAC,KAAK,CAAC,CAAC,CAAC;QAC5E,MAAM,QAAQ,GACZ,MAAM,CAAC,QAAQ,IAAI,MAAM,CAAC,QAAQ;YAChC,CAAC,CAAC;gBACE,GAAG,CAAC,MAAM,CAAC,QAAQ,IAAI,EAAE,CAAC;gBAC1B,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aAC1D;YACH,CAAC,CAAC,IAAI,CAAC;QACX,MAAM,KAAK,GAAG,MAAM,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC;QAEhE,OAAO;YACL,MAAM,CAAC,EAAE;YACT,MAAM,CAAC,aAAa;YACpB,MAAM,CAAC,MAAM;YACb,MAAM,CAAC,QAAQ;YACf,MAAM,CAAC,OAAO;YACd,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI;YACxC,MAAM,CAAC,WAAW;YAClB,MAAM,CAAC,WAAW;YAClB,MAAM,CAAC,WAAW;YAClB,MAAM,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC;YAC1D,KAAK,EAAE,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC;YAC3D,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI;YACvC,KAAK,EAAE,UAAU,IAAI,IAAI;YACzB,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI;YAChC,MAAM,CAAC,SAAS;SACjB,CAAC;IACJ,CAAC;CACF"}

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@cqrs-ddd/pipeline-audit",
+  "version": "0.5.0",
+  "description": "Audit records for @cqrs-ddd/pipeline: who did what, in which tenant, with redacted payloads, to a log or PostgreSQL sink",
+  "author": "Aristotelis",
+  "license": "SEE LICENSE IN LICENSE",
+  "type": "module",
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "keywords": [
+    "pipeline",
+    "cqrs",
+    "audit",
+    "audit-trail",
+    "audit-log",
+    "compliance",
+    "security",
+    "redaction",
+    "behavior"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aristoteliss/ddd-cqrs.git",
+    "directory": "packages/pipeline-audit"
+  },
+  "homepage": "https://aristoteliss.github.io/ddd-cqrs/packages/pipeline-audit/",
+  "bugs": {
+    "url": "https://github.com/aristoteliss/ddd-cqrs/issues"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "LICENSE",
+    "COMMERCIAL_LICENSE.txt"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@cqrs-ddd/pipeline": "^0.5.0"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^5.0.3",
+    "vitest": "^5.0.3",
+    "@cqrs-ddd/pipeline": "0.5.0"
+  },
+  "dependencies": {
+    "@cqrs-ddd/safe-stringify": "^0.5.0",
+    "@cqrs-ddd/uuidv7": "^0.5.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "build:watch": "tsc -p tsconfig.build.json --watch",
+    "clean": "rm -rf dist tsconfig.tsbuildinfo",
+    "rebuild": "pnpm run clean && pnpm run build",
+    "lint": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}