Release v0.1.7

README.md

@@ -1,11 +1,15 @@
 # GovOPlaN Audit
 
-`govoplan-audit` owns audit API route contributions during the GovOPlaN module
+`govoplan-audit` owns audit API route contributions and audit administration
-split.
+WebUI sections during the GovOPlaN module split.
 
 This repository owns the live `audit_log` table, audit API route
-contributions, and the target boundary for future audit sink/export capability
+contributions, the `@govoplan/audit-webui` package, and the target boundary
-work.
+for future audit sink/export capability work.
+
+The WebUI package contributes the `system-audit` and `tenant-audit` admin
+sections through the shared `admin.sections` UI capability. The admin shell
+does not render audit panels unless this module is installed and enabled.
 
 It also owns the audit command/event separation and production delivery
 foundation:

package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@govoplan/audit-webui",
+  "version": "0.1.7",
+  "private": true,
+  "type": "module",
+  "main": "webui/src/index.ts",
+  "module": "webui/src/index.ts",
+  "types": "webui/src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./webui/src/index.ts",
+      "import": "./webui/src/index.ts"
+    }
+  },
+  "files": [
+    "webui/src",
+    "README.md",
+    "LICENSE"
+  ],
+  "peerDependencies": {
+    "@govoplan/core-webui": "^0.1.7",
+    "lucide-react": "^1.23.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "react-router-dom": "^7.1.1"
+  },
+  "peerDependenciesMeta": {
+    "@govoplan/core-webui": {
+      "optional": true
+    }
+  }
+}

pyproject.toml

@@ -4,13 +4,13 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "govoplan-audit"
-version = "0.1.6"
+version = "0.1.7"
 description = "GovOPlaN audit platform module."
 readme = "README.md"
 requires-python = ">=3.12"
 authors = [{ name = "GovOPlaN" }]
 dependencies = [
-  "govoplan-core>=0.1.6",
+  "govoplan-core>=0.1.7",
 ]
 
 [tool.setuptools.packages.find]

src/govoplan_audit/backend/manifest.py

@@ -8,7 +8,7 @@ from govoplan_core.core.access import (
     CAPABILITY_AUTH_PRINCIPAL_RESOLVER,
 )
 from govoplan_core.core.module_guards import drop_table_retirement_provider, persistent_table_uninstall_guard
-from govoplan_core.core.modules import MigrationSpec, ModuleContext, ModuleManifest
+from govoplan_core.core.modules import FrontendModule, MigrationSpec, ModuleContext, ModuleManifest
 from govoplan_core.db.base import Base
 
 
@@ -36,9 +36,13 @@ def _audit_retention(context: ModuleContext):
 manifest = ModuleManifest(
     id="audit",
     name="Audit",
-    version="0.1.6",
+    version="0.1.7",
     required_capabilities=(CAPABILITY_AUTH_PRINCIPAL_RESOLVER, CAPABILITY_AUTH_PERMISSION_EVALUATOR),
     route_factory=_route_factory,
+    frontend=FrontendModule(
+        module_id="audit",
+        package_name="@govoplan/audit-webui",
+    ),
     migration_spec=MigrationSpec(
         module_id="audit",
         metadata=Base.metadata,

webui/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@govoplan/audit-webui",
+  "version": "0.1.7",
+  "private": true,
+  "type": "module",
+  "main": "src/index.ts",
+  "module": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts"
+    }
+  },
+  "peerDependencies": {
+    "@govoplan/core-webui": "^0.1.7",
+    "lucide-react": "^1.23.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "react-router-dom": "^7.1.1"
+  },
+  "peerDependenciesMeta": {
+    "@govoplan/core-webui": {
+      "optional": true
+    }
+  }
+}

webui/src/api/audit.ts

@@ -0,0 +1,74 @@
+import { apiFetch, type ApiSettings, type DeltaDeletedItem } from "@govoplan/core-webui";
+
+export type AuditAdminItem = {
+  id: string;
+  scope: "tenant" | "system";
+  tenant_id?: string | null;
+  actor_email?: string | null;
+  action: string;
+  object_type?: string | null;
+  object_id?: string | null;
+  details: Record<string, unknown>;
+  created_at: string;
+};
+
+export type AuditSortBy = "time" | "actor" | "action" | "object" | "tenant";
+
+export type AuditQueryOptions = {
+  tenantId?: string | null;
+  allTenants?: boolean;
+  scope?: "tenant" | "system";
+  limit?: number;
+  offset?: number;
+  page?: number;
+  pageSize?: number;
+  cursor?: string | null;
+  sortBy?: AuditSortBy;
+  sortDirection?: "asc" | "desc";
+  filters?: Partial<Record<AuditSortBy, string>>;
+};
+
+export type AuditAdminListResponse = {
+  items: AuditAdminItem[];
+  total: number;
+  page: number;
+  page_size: number;
+  pages: number;
+  cursor?: string | null;
+  next_cursor?: string | null;
+};
+
+export type AuditAdminDeltaResponse = AuditAdminListResponse & {
+  deleted: DeltaDeletedItem[];
+  watermark?: string | null;
+  has_more: boolean;
+  full: boolean;
+};
+
+function auditQuery(options: AuditQueryOptions & { since?: string | null } = {}): string {
+  const params = new URLSearchParams();
+  if (options.tenantId) params.set("tenant_id", options.tenantId);
+  if (options.allTenants) params.set("all_tenants", "true");
+  if (options.scope) params.set("scope", options.scope);
+  if (options.limit) params.set("limit", String(options.limit));
+  if (options.offset) params.set("offset", String(options.offset));
+  if (options.page) params.set("page", String(options.page));
+  if (options.pageSize) params.set("page_size", String(options.pageSize));
+  if (options.cursor) params.set("cursor", options.cursor);
+  if (options.sortBy) params.set("sort_by", options.sortBy);
+  if (options.sortDirection) params.set("sort_direction", options.sortDirection);
+  if (options.since) params.set("since", options.since);
+  for (const [column, value] of Object.entries(options.filters ?? {})) {
+    if (value?.trim()) params.set(`filter_${column}`, value);
+  }
+  const suffix = params.toString();
+  return suffix ? `?${suffix}` : "";
+}
+
+export function fetchAdminAudit(settings: ApiSettings, options: AuditQueryOptions = {}): Promise<AuditAdminListResponse> {
+  return apiFetch(settings, `/api/v1/admin/audit${auditQuery(options)}`);
+}
+
+export function fetchAdminAuditDelta(settings: ApiSettings, options: AuditQueryOptions & { since?: string | null } = {}): Promise<AuditAdminDeltaResponse> {
+  return apiFetch(settings, `/api/v1/admin/audit/delta${auditQuery(options)}`);
+}

webui/src/features/audit/AdminAuditPanel.tsx

@@ -0,0 +1,200 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { Search } from "lucide-react";
+import {
+  AdminIconButton,
+  AdminPageLayout,
+  adminErrorMessage,
+  Button,
+  DataGrid,
+  Dialog,
+  formatAdminDateTime as formatDateTime,
+  mergeDeltaRows,
+  useDeltaWatermarks,
+  type ApiSettings,
+  type AuthInfo,
+  type DataGridColumn,
+  type DataGridQueryState
+} from "@govoplan/core-webui";
+import { fetchAdminAudit, fetchAdminAuditDelta, type AuditAdminItem, type AuditSortBy } from "../../api/audit";
+
+type Props = {
+  settings: ApiSettings;
+  auth: AuthInfo;
+  systemMode?: boolean;
+};
+
+const DEFAULT_QUERY: DataGridQueryState = {
+  sort: { columnId: "time", direction: "desc" },
+  filters: {}
+};
+
+export default function AdminAuditPanel({ settings, auth, systemMode = false }: Props) {
+  const [items, setItems] = useState<AuditAdminItem[]>([]);
+  const itemsRef = useRef<AuditAdminItem[]>([]);
+  const pageItemsRef = useRef<Record<string, AuditAdminItem[]>>({});
+  const pageCursorsRef = useRef<Record<number, string | null>>({ 1: null });
+  const { getDeltaWatermark, setDeltaWatermark, resetDeltaWatermark } = useDeltaWatermarks();
+  const [total, setTotal] = useState(0);
+  const [page, setPage] = useState(1);
+  const [pageSize, setPageSize] = useState(10);
+  const [query, setQuery] = useState<DataGridQueryState>(DEFAULT_QUERY);
+  const [selected, setSelected] = useState<AuditAdminItem | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState("");
+  const [reloadToken, setReloadToken] = useState(0);
+  const tenantId = (auth.active_tenant ?? auth.tenant).id;
+
+  const load = useCallback(async () => {
+    setLoading(true);
+    setError("");
+    try {
+      const sortColumn = query.sort?.columnId;
+      const sortBy = sortColumn && ["time", "actor", "action", "object", "tenant"].includes(sortColumn)
+        ? sortColumn as AuditSortBy
+        : "time";
+      const sortDirection = query.sort?.direction ?? "desc";
+      const filters = query.filters;
+      const pageCursor = page === 1 ? null : pageCursorsRef.current[page];
+      const deltaMode = page === 1 || pageCursor !== undefined;
+      const requestOptions = {
+        scope: systemMode ? "system" as const : "tenant" as const,
+        page,
+        pageSize,
+        cursor: pageCursor,
+        sortBy,
+        sortDirection,
+        filters
+      };
+      const deltaKey = `audit:${systemMode ? "system" : "tenant"}:${tenantId}:${pageSize}:${page}:${pageCursor ?? "root"}:${JSON.stringify({ sortBy, sortDirection, filters })}`;
+      const response = deltaMode
+        ? await fetchAdminAuditDelta(settings, { ...requestOptions, since: getDeltaWatermark(deltaKey) })
+        : await fetchAdminAudit(settings, requestOptions);
+      const baseItems = pageItemsRef.current[deltaKey] ?? [];
+      const nextItems = "full" in response && !response.full
+        ? mergeDeltaRows(baseItems, response.items, response.deleted, (item) => item.id, { sort: compareAuditEvents(sortBy, sortDirection) }).slice(0, pageSize)
+        : response.items;
+      pageItemsRef.current[deltaKey] = nextItems;
+      itemsRef.current = nextItems;
+      setItems(nextItems);
+      setTotal(response.total);
+      if (!deltaMode && response.page !== page) setPage(response.page);
+      if (response.cursor !== undefined) pageCursorsRef.current[page] = response.cursor ?? null;
+      if (response.next_cursor !== undefined) {
+        if (response.next_cursor) pageCursorsRef.current[page + 1] = response.next_cursor;
+        else delete pageCursorsRef.current[page + 1];
+      }
+      if ("full" in response && !response.full && page === 1 && (response.items.length > 0 || response.deleted.length > 0)) {
+        pageCursorsRef.current = { 1: null };
+      }
+      if ("watermark" in response) setDeltaWatermark(deltaKey, response.watermark);
+      if (!deltaMode) resetDeltaWatermark(deltaKey);
+    } catch (err) {
+      setError(adminErrorMessage(err));
+    } finally {
+      setLoading(false);
+    }
+  }, [settings.accessToken, settings.apiBaseUrl, settings.apiKey, systemMode, tenantId, page, pageSize, query, reloadToken, getDeltaWatermark, setDeltaWatermark, resetDeltaWatermark]);
+
+  useEffect(() => {
+    itemsRef.current = [];
+    pageItemsRef.current = {};
+    pageCursorsRef.current = { 1: null };
+    resetDeltaWatermark();
+  }, [settings.accessToken, settings.apiBaseUrl, settings.apiKey, systemMode, tenantId, pageSize, query, resetDeltaWatermark]);
+
+  useEffect(() => { void load(); }, [load]);
+
+  const handleQueryChange = useCallback((next: DataGridQueryState) => {
+    setQuery((current) => {
+      if (JSON.stringify(current) === JSON.stringify(next)) return current;
+      setPage(1);
+      return next;
+    });
+  }, []);
+
+  const columns = useMemo<DataGridColumn<AuditAdminItem>[]>(() => [
+    { id: "time", header: "Time", width: 190, minWidth: 150, maxWidth: 260, resizable: true, sticky: "start", sortable: true, filterable: true, filterType: "date", value: (row) => row.created_at, render: (row) => formatDateTime(row.created_at) },
+    { id: "actor", header: "Actor", width: 220, minWidth: 170, maxWidth: 360, resizable: true, sortable: true, filterable: true, value: (row) => row.actor_email || "System" },
+    { id: "action", header: "Action", width: 250, minWidth: 170, maxWidth: 420, resizable: true, sortable: true, filterable: true, value: (row) => row.action },
+    { id: "object", header: "Object", width: 300, minWidth: 180, maxWidth: 640, resizable: true, fill: true, sortable: true, filterable: true, value: (row) => `${row.object_type || "-"} ${row.object_id || ""}`.trim() },
+    ...(systemMode ? [{ id: "tenant", header: "Tenant context", width: 190, minWidth: 150, maxWidth: 300, resizable: true, sortable: true, filterable: true, value: (row: AuditAdminItem) => row.tenant_id || "-" }] : []),
+    { id: "actions", header: "Actions", width: 70, sticky: "end", resizable: false, align: "right", render: (row) => <div className="admin-icon-actions"><AdminIconButton label="Inspect audit event" icon={<Search />} onClick={() => setSelected(row)} /></div> }
+  ], [systemMode]);
+
+  const firstShown = total === 0 ? 0 : (page - 1) * pageSize + 1;
+  const lastShown = Math.min(total, page * pageSize);
+  const pageDescription = systemMode
+    ? `System-level administrative history, showing ${firstShown}-${lastShown} of ${total}.`
+    : `Tenant-level administrative history for the active tenant, showing ${firstShown}-${lastShown} of ${total}.`;
+
+  return (
+    <>
+      <AdminPageLayout
+        title={systemMode ? "System audit" : "Tenant audit"}
+        description={pageDescription}
+        loading={loading}
+        error={error}
+        actions={<Button onClick={() => setReloadToken((value) => value + 1)} disabled={loading}>Reload</Button>}>
+        <div className="admin-table-surface">
+          <DataGrid
+            id={systemMode ? "admin-system-audit-v6" : "admin-tenant-audit-v6"}
+            rows={items}
+            columns={columns}
+            initialFit="container"
+            getRowKey={(row) => row.id}
+            emptyText="No administrative audit records found."
+            className="admin-audit-grid"
+            initialSort={{ columnId: "time", direction: "desc" }}
+            pagination={{
+              mode: "server",
+              page,
+              pageSize,
+              totalRows: total,
+              pageSizeOptions: [10, 25, 50, 100, 250],
+              disabled: loading,
+              onPageChange: setPage,
+              onPageSizeChange: (next) => { setPageSize(next); setPage(1); }
+            }}
+            onQueryChange={handleQueryChange}
+          />
+        </div>
+      </AdminPageLayout>
+      <Dialog open={Boolean(selected)} title="Audit event details" onClose={() => setSelected(null)} className="admin-dialog admin-dialog-wide" footer={<Button onClick={() => setSelected(null)}>Close</Button>}>
+        {selected && (
+          <>
+            <dl className="admin-details-grid">
+              <div><dt>Scope</dt><dd>{selected.scope}</dd></div>
+              <div><dt>Action</dt><dd>{selected.action}</dd></div>
+              <div><dt>Actor</dt><dd>{selected.actor_email || "System"}</dd></div>
+              <div><dt>Object</dt><dd>{selected.object_type || "-"} {selected.object_id || ""}</dd></div>
+              <div><dt>Tenant context</dt><dd>{selected.tenant_id || "-"}</dd></div>
+              <div><dt>Time</dt><dd>{formatDateTime(selected.created_at)}</dd></div>
+            </dl>
+            <pre className="admin-json-preview">{JSON.stringify(selected.details, null, 2)}</pre>
+          </>
+        )}
+      </Dialog>
+    </>
+  );
+}
+
+function compareAuditEvents(sortBy: AuditSortBy, sortDirection: "asc" | "desc"): (left: AuditAdminItem, right: AuditAdminItem) => number {
+  return (left, right) => {
+    const primary = compareAuditValues(auditSortValue(left, sortBy), auditSortValue(right, sortBy));
+    const directed = sortDirection === "asc" ? primary : -primary;
+    return directed || right.id.localeCompare(left.id);
+  };
+}
+
+function auditSortValue(item: AuditAdminItem, sortBy: AuditSortBy): string | number {
+  if (sortBy === "time") return new Date(item.created_at).getTime();
+  if (sortBy === "actor") return item.actor_email || "System";
+  if (sortBy === "action") return item.action;
+  if (sortBy === "object") return `${item.object_type || ""} ${item.object_id || ""}`;
+  return item.tenant_id || "";
+}
+
+function compareAuditValues(left: string | number, right: string | number): number {
+  if (typeof left === "number" && typeof right === "number") return left - right;
+  return String(left).localeCompare(String(right));
+}

webui/src/index.ts

@@ -0,0 +1,5 @@
+export { default } from "./module";
+export * from "./module";
+export * from "./api/audit";
+export { default as AdminAuditPanel } from "./features/audit/AdminAuditPanel";
+export type { PlatformWebModule } from "@govoplan/core-webui";

webui/src/module.ts

@@ -0,0 +1,45 @@
+import { createElement, lazy } from "react";
+import { type AdminSectionsUiCapability, type PlatformWebModule } from "@govoplan/core-webui";
+
+const AdminAuditPanel = lazy(() => import("./features/audit/AdminAuditPanel"));
+
+const auditAdminSections: AdminSectionsUiCapability = {
+  sections: [
+    {
+      id: "system-audit",
+      label: "Audit",
+      group: "SYSTEM",
+      order: 90,
+      allOf: ["system:audit:read"],
+      render: ({ settings, auth }) => createElement(AdminAuditPanel, {
+        settings,
+        auth,
+        systemMode: true
+      })
+    },
+    {
+      id: "tenant-audit",
+      label: "Audit",
+      group: "TENANT",
+      order: 100,
+      allOf: ["audit:read"],
+      render: ({ settings, auth }) => createElement(AdminAuditPanel, {
+        settings,
+        auth,
+        systemMode: false
+      })
+    }
+  ]
+};
+
+export const auditModule: PlatformWebModule = {
+  id: "audit",
+  label: "Audit",
+  version: "0.1.6",
+  dependencies: ["access", "admin"],
+  uiCapabilities: {
+    "admin.sections": auditAdminSections
+  }
+};
+
+export default auditModule;