@axiom-lattice/pg-stores 5.1.2 → 5.2.0

package/src/stores/PostgreSQLPlatformAuditStore.ts

@@ -0,0 +1,209 @@
+import type {
+  PlatformAuditAction,
+  PlatformAuditAppendInput,
+  PlatformAuditInitiator,
+  PlatformAuditQuery,
+  PlatformAuditRecord,
+  PlatformAuditSource,
+  PlatformAuditStatus,
+  PlatformAuditStore,
+} from "@axiom-lattice/protocols";
+import type { Pool } from "pg";
+
+const TABLE = "lattice_platform_audit";
+
+interface AuditRow {
+  id: string;
+  initiator_user_id: string | null;
+  initiator_role: string | null;
+  initiator: PlatformAuditInitiator | string;
+  source: string;
+  executor: PlatformAuditRecord["executor"] | string;
+  tenant_id: string | null;
+  action: string;
+  status: string;
+  summary: Record<string, unknown> | string;
+  before: Record<string, unknown> | string | null;
+  after: Record<string, unknown> | string | null;
+  error_code: string | null;
+  duration_ms: number;
+  created_at: Date;
+}
+
+function parseJson<T>(value: T | string): T {
+  return typeof value === "string" ? (JSON.parse(value) as T) : value;
+}
+
+/**
+ * Normalizes an optional timestamp boundary to a canonical UTC ISO string.
+ *
+ * Equivalent inputs (e.g. `2024-01-01T08:00:01+08:00`, date-only values, or
+ * explicit `Z`) all compare as the same instant. Empty or unparseable values
+ * are ignored rather than compared as raw text.
+ */
+function normalizeBoundary(value?: string): string | undefined {
+  if (value === undefined) return undefined;
+  const trimmed = value.trim();
+  if (trimmed === "") return undefined;
+  const parsed = new Date(trimmed);
+  if (Number.isNaN(parsed.getTime())) return undefined;
+  return parsed.toISOString();
+}
+
+/**
+ * Normalizes a pagination value: non-finite values use the fallback, finite
+ * values are truncated to integers, and negatives are clamped to zero.
+ */
+function normalizePagination(
+  value: number | undefined,
+  fallback: number,
+): number {
+  if (value === undefined || !Number.isFinite(value)) return fallback;
+  return Math.max(0, Math.trunc(value));
+}
+
+function mapRow(row: AuditRow): PlatformAuditRecord {
+  return {
+    id: row.id,
+    initiator: parseJson<PlatformAuditInitiator>(row.initiator),
+    source: row.source as PlatformAuditSource,
+    executor: parseJson<PlatformAuditRecord["executor"]>(row.executor),
+    ...(row.tenant_id !== null ? { tenantId: row.tenant_id } : {}),
+    action: row.action as PlatformAuditAction,
+    status: row.status as PlatformAuditStatus,
+    summary: parseJson<Record<string, unknown>>(row.summary),
+    ...(row.before !== null
+      ? { before: parseJson<Record<string, unknown>>(row.before) }
+      : {}),
+    ...(row.after !== null
+      ? { after: parseJson<Record<string, unknown>>(row.after) }
+      : {}),
+    ...(row.error_code !== null ? { errorCode: row.error_code } : {}),
+    durationMs: Number(row.duration_ms),
+    createdAt: row.created_at,
+  };
+}
+
+/**
+ * PostgreSQL implementation of {@link PlatformAuditStore}.
+ *
+ * Persists platform-level audit records in the append-only
+ * `lattice_platform_audit` table. Records are returned newest-first by
+ * `createdAt` descending, then `id` descending.
+ */
+export class PostgreSQLPlatformAuditStore implements PlatformAuditStore {
+  constructor(private readonly options: { pool: Pool }) {}
+
+  private get pool(): Pool {
+    return this.options.pool;
+  }
+
+  /** Appends a record, assigning a fresh id and creation timestamp. */
+  async append(record: PlatformAuditAppendInput): Promise<PlatformAuditRecord> {
+    const initiator = record.initiator;
+    const initiatorUserId =
+      initiator.type === "human" ? initiator.userId : null;
+    const initiatorRole = initiator.type === "human" ? initiator.role : null;
+    const durationMs = Number.isFinite(record.durationMs)
+      ? Math.max(0, Math.round(record.durationMs))
+      : 0;
+
+    const result = await this.pool.query<AuditRow>(
+      `INSERT INTO ${TABLE}
+         (initiator_user_id, initiator_role, initiator, source, executor,
+          tenant_id, action, status, summary, before, after, error_code,
+          duration_ms)
+       VALUES ($1,$2,$3::jsonb,$4,$5::jsonb,$6,$7,$8,$9::jsonb,$10::jsonb,
+               $11::jsonb,$12,$13)
+       RETURNING *`,
+      [
+        initiatorUserId,
+        initiatorRole,
+        JSON.stringify(initiator),
+        record.source,
+        JSON.stringify(record.executor),
+        record.tenantId ?? null,
+        record.action,
+        record.status,
+        JSON.stringify(record.summary),
+        record.before === undefined ? null : JSON.stringify(record.before),
+        record.after === undefined ? null : JSON.stringify(record.after),
+        record.errorCode ?? null,
+        durationMs,
+      ],
+    );
+
+    const row = result.rows[0];
+    if (!row) throw new Error("Platform audit record was not persisted");
+    return mapRow(row);
+  }
+
+  /** Returns a record by id, or null when it does not exist. */
+  async get(id: string): Promise<PlatformAuditRecord | null> {
+    const result = await this.pool.query<AuditRow>(
+      `SELECT * FROM ${TABLE} WHERE id = $1`,
+      [id],
+    );
+    return result.rows[0] ? mapRow(result.rows[0]) : null;
+  }
+
+  /**
+   * Returns matching records newest-first.
+   *
+   * `initiatorUserId` only matches human initiators. `from` is inclusive and
+   * `to` is exclusive after both are normalized to instants; invalid or empty
+   * boundaries are ignored. Records are ordered by `createdAt` descending,
+   * then by `id` descending. Results are paginated with a default limit of 100;
+   * non-finite `offset`/`limit` fall back to defaults, finite values are
+   * truncated to integers, and negatives are clamped to 0.
+   */
+  async query(params: PlatformAuditQuery): Promise<PlatformAuditRecord[]> {
+    const clauses: string[] = [];
+    const values: unknown[] = [];
+
+    if (params.initiatorUserId !== undefined) {
+      values.push(params.initiatorUserId);
+      clauses.push(`initiator_user_id = $${values.length}`);
+    }
+    if (params.source !== undefined) {
+      values.push(params.source);
+      clauses.push(`source = $${values.length}`);
+    }
+    if (params.tenantId !== undefined) {
+      values.push(params.tenantId);
+      clauses.push(`tenant_id = $${values.length}`);
+    }
+    if (params.action !== undefined) {
+      values.push(params.action);
+      clauses.push(`action = $${values.length}`);
+    }
+    if (params.status !== undefined) {
+      values.push(params.status);
+      clauses.push(`status = $${values.length}`);
+    }
+    const from = normalizeBoundary(params.from);
+    if (from !== undefined) {
+      values.push(from);
+      clauses.push(`created_at >= $${values.length}`);
+    }
+    const to = normalizeBoundary(params.to);
+    if (to !== undefined) {
+      values.push(to);
+      clauses.push(`created_at < $${values.length}`);
+    }
+
+    const limit = normalizePagination(params.limit, 100);
+    const offset = normalizePagination(params.offset, 0);
+    values.push(limit, offset);
+
+    const where = clauses.length > 0 ? ` WHERE ${clauses.join(" AND ")}` : "";
+    const { rows } = await this.pool.query<AuditRow>(
+      `SELECT * FROM ${TABLE}${where}
+       ORDER BY created_at DESC, id DESC
+       LIMIT $${values.length - 1} OFFSET $${values.length}`,
+      values,
+    );
+
+    return rows.map(mapRow);
+  }
+}

package/src/stores/PostgreSQLUserTenantLinkStore.ts

@@ -1,6 +1,7 @@
 import { Pool } from "pg";
 import type { PoolConfig } from "pg";
 import {
+  assertNotPlatformTenant,
   UserTenantLinkStore,
   UserTenantLink,
   CreateUserTenantLinkRequest,
@@ -132,6 +133,7 @@ export class PostgreSQLUserTenantLinkStore implements UserTenantLinkStore {
   }
 
   async createLink(data: CreateUserTenantLinkRequest): Promise<UserTenantLink> {
+    assertNotPlatformTenant(data.tenantId);
     await this.ensureInitialized();
     
     const now = new Date();