@cosmicdrift/kumiko-samples 0.378.0 → 0.379.0

package/packages/bundled-features/src/audit/handlers/audit-events.ts

@@ -0,0 +1,153 @@
+// Query building and row mapping shared by every audit read handler, so the own-tenant
+// and the all-tenants variants cannot drift apart. The tenant condition is the only part
+// that differs per handler and is passed in.
+//
+// Event payloads hold PII as subject-KMS ciphertext; it is replaced by
+// REDACTED_PII_PLACEHOLDER before returning (payload and metadata), since the API leak guard refuses ciphertext.
+
+import { selectMany, type TenantDb, type WhereObject } from "@cosmicdrift/kumiko-framework/db";
+import { eventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
+import * as z from "zod";
+import { redactPiiCiphertext } from "../../shared/index.ts";
+
+const MAX_LIMIT = 100;
+
+// At most 18 digits keeps the id inside bigint, so an oversized cursor or id is a 422, not a 500.
+const CURSOR_PATTERN = /^\d{1,18}$/;
+
+export const auditListPayloadShape = {
+  cursor: z.string().regex(CURSOR_PATTERN, "cursor must be a positive integer").optional(),
+  before: z.string().regex(CURSOR_PATTERN, "cursor must be a positive integer").optional(),
+  search: z.string().trim().optional(),
+  limit: z.number().int().min(1).max(MAX_LIMIT).default(50),
+  aggregateType: z.string().optional(),
+  aggregateId: z.uuid().optional(),
+  eventType: z.string().optional(),
+  userId: z.string().optional(),
+  sort: z.enum(["createdAt", "type"]).optional(),
+  sortDirection: z.enum(["asc", "desc"]).optional(),
+  from: z.iso.datetime().optional(),
+  to: z.iso.datetime().optional(),
+} as const;
+
+export const auditEventIdSchema = z
+  .string()
+  .regex(/^[1-9]\d{0,17}$/, "id must be a positive integer");
+
+export const AUDIT_DATE_RANGE_CHECK = {
+  isValid: (v: { from?: string | undefined; to?: string | undefined }): boolean =>
+    !v.from || !v.to || v.from <= v.to,
+  params: {
+    message: "`from` must be less than or equal to `to`",
+    path: ["from"],
+  },
+};
+
+function buildDateRange(
+  from: string | undefined,
+  to: string | undefined,
+): { gte?: unknown; lte?: unknown } | null {
+  if (!from && !to) return null;
+  const range: { gte?: unknown; lte?: unknown } = {};
+  if (from) range.gte = Temporal.Instant.from(from);
+  if (to) range.lte = Temporal.Instant.from(to);
+  return range;
+}
+
+function escapeLikePattern(value: string): string {
+  return value.replace(/[\\%_]/g, (m) => `\\${m}`);
+}
+
+export type AuditListFilters = {
+  aggregateType?: string | undefined;
+  aggregateId?: string | undefined;
+  eventType?: string | undefined;
+  search?: string | undefined;
+  userId?: string | undefined;
+  from?: string | undefined;
+  to?: string | undefined;
+  cursor?: string | undefined;
+  before?: string | undefined;
+};
+
+/** `tenantCondition` is a tenant id, or an operator object for reads across tenants. */
+export function buildAuditWhere(
+  tenantCondition: unknown,
+  p: AuditListFilters,
+  direction: "asc" | "desc",
+): WhereObject {
+  const where: WhereObject = { tenantId: tenantCondition };
+  if (p.aggregateType) where["aggregateType"] = p.aggregateType;
+  if (p.aggregateId) where["aggregateId"] = p.aggregateId;
+  if (p.eventType) where["type"] = p.eventType;
+  else if (p.search) where["type"] = { like: `%${escapeLikePattern(p.search)}%` };
+  if (p.userId) where["createdBy"] = p.userId;
+  const range = buildDateRange(p.from, p.to);
+  if (range) where["createdAt"] = range;
+  const cursor = p.cursor ?? p.before;
+  // The cursor is an event id, so it only walks pages in id order: ascending
+  // pages continue past it, descending pages stop before it.
+  if (cursor) where["id"] = direction === "asc" ? { gt: BigInt(cursor) } : { lt: BigInt(cursor) };
+  return where;
+}
+
+type AuditEventRow = {
+  id: bigint;
+  tenantId: string;
+  aggregateId: string;
+  aggregateType: string;
+  version: number;
+  type: string;
+  payload: Record<string, unknown>;
+  metadata: Record<string, unknown>;
+  createdAt: unknown;
+  createdBy: string;
+};
+
+export function serializeAuditEvent(r: AuditEventRow) {
+  return {
+    id: String(r.id),
+    tenantId: r.tenantId,
+    aggregateId: r.aggregateId,
+    aggregateType: r.aggregateType,
+    version: r.version,
+    type: r.type,
+    payload: redactPiiCiphertext(r.payload),
+    metadata: redactPiiCiphertext(r.metadata),
+    createdAt: r.createdAt,
+    createdBy: r.createdBy,
+  };
+}
+
+export async function loadAuditEvent(db: TenantDb, where: WhereObject) {
+  const rows = await selectMany<AuditEventRow>(db, eventsTable, where, { limit: 1 });
+  const row = rows[0];
+  return row === undefined ? null : serializeAuditEvent(row);
+}
+
+export async function listAuditEvents(
+  db: TenantDb,
+  where: WhereObject,
+  p: { limit: number; sort?: "createdAt" | "type" | undefined },
+  direction: "asc" | "desc",
+) {
+  const rows = await selectMany<AuditEventRow>(db, eventsTable, where, {
+    // The id cursor only resumes an id-ordered listing. created_at comes from the
+    // transaction start and can run against insert order, so ordering by it would let
+    // a page boundary skip rows; only the type sort leaves id order (and is one page).
+    orderBy:
+      p.sort === "type"
+        ? [
+            { col: "type", direction },
+            { col: "id", direction },
+          ]
+        : [{ col: "id", direction }],
+    limit: p.limit,
+  });
+  const serialised = rows.map(serializeAuditEvent);
+  const last = serialised[serialised.length - 1];
+  // An id cursor cannot resume a type-ordered listing, so that sort is one page.
+  const nextId = serialised.length === p.limit && last && p.sort !== "type" ? last.id : null;
+  return { rows: serialised, nextCursor: nextId, nextBefore: nextId };
+}

package/packages/bundled-features/src/audit/handlers/audit-system-db.ts

@@ -0,0 +1,13 @@
+import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
+
+export function requireAuditSystemDb<TSystemDb>(
+  systemDb: TSystemDb | undefined,
+  handlerQn: string,
+): TSystemDb {
+  if (!systemDb) {
+    throw new InternalError({
+      message: `${handlerQn} requires ctx.systemDb — is r.systemScope() still set on the audit feature?`,
+    });
+  }
+  return systemDb;
+}

package/packages/bundled-features/src/audit/handlers/details-all-tenants.query.ts

@@ -0,0 +1,26 @@
+// One audit event of any tenant by its event-store id, for the all-tenants log's detail screen.
+
+import { access, defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import * as z from "zod";
+import { auditEventIdSchema, loadAuditEvent } from "./audit-events.ts";
+import { requireAuditSystemDb } from "./audit-system-db.ts";
+import { allTenantsCondition, assertMayReadAllTenants } from "./resolve-audit-tenant.ts";
+
+export const detailsAllTenantsQuery = defineQueryHandler({
+  name: "details-all-tenants",
+  description:
+    "Returns one audit-trail event of any tenant by its event-store id, with full payload, metadata and tenantId; SystemAdmin only, system-tenant events are not included.",
+  schema: z.object({ id: auditEventIdSchema }),
+  access: { roles: access.systemAdmin },
+  handler: async (query, ctx) => {
+    assertMayReadAllTenants(query.user);
+    const db = requireAuditSystemDb(
+      ctx.systemDb,
+      "audit:query:details-all-tenants",
+    ).acknowledgeCrossTenant("SystemAdmin reads one audit event of any tenant");
+    return loadAuditEvent(db, {
+      tenantId: allTenantsCondition(undefined),
+      id: BigInt(query.payload.id),
+    });
+  },
+});

package/packages/bundled-features/src/audit/handlers/details.query.ts

@@ -3,12 +3,11 @@
 // can only read events in their own tenant; a SystemAdmin can pass scope
 // "system" to read app-instance system events (e.g. app.started).
 
-import { selectMany } from "@cosmicdrift/kumiko-framework/db";
 import { access, defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
-import { eventsTable } from "@cosmicdrift/kumiko-framework/event-store";
 import * as z from "zod";
-import { redactPiiCiphertext } from "../../shared/index.ts";
-import { AUDIT_SCOPE_VALUES } from "../constants.ts";
+import { AUDIT_SCOPE_VALUES } from "../web/constants.ts";
+import { auditEventIdSchema, loadAuditEvent } from "./audit-events.ts";
+import { requireAuditSystemDb } from "./audit-system-db.ts";
 import { resolveAuditScopeFilter } from "./resolve-audit-tenant.ts";
 
 export const detailsQuery = defineQueryHandler({
@@ -16,46 +15,19 @@ export const detailsQuery = defineQueryHandler({
   description:
     'Returns one audit-trail event of the caller\'s tenant by its event-store id, with full payload and metadata; use it to inspect the exact change behind a row of the audit log list. A SystemAdmin can set scope "system" to read an app-instance system event (e.g. app.started).',
   schema: z.object({
-    id: z.string().regex(/^[1-9]\d*$/, "id must be a positive integer"),
+    id: auditEventIdSchema,
     scope: z.enum(AUDIT_SCOPE_VALUES).optional(),
   }),
   access: { roles: access.admin },
   handler: async (query, ctx) => {
     const scopeFilter = resolveAuditScopeFilter(query.user, query.payload.scope);
-    const rows = await selectMany<{
-      id: bigint;
-      aggregateId: string;
-      aggregateType: string;
-      version: number;
-      type: string;
-      payload: Record<string, unknown>;
-      metadata: Record<string, unknown>;
-      createdAt: unknown;
-      createdBy: string;
-    }>(
-      ctx.db,
-      eventsTable,
-      {
-        tenantId: scopeFilter.tenantId,
-        ...(scopeFilter.aggregateType !== undefined && {
-          aggregateType: scopeFilter.aggregateType,
-        }),
-        id: BigInt(query.payload.id),
-      },
-      { limit: 1 },
+    const db = requireAuditSystemDb(ctx.systemDb, "audit:query:details").assertTenantMatch(
+      query.user.tenantId,
     );
-    const row = rows[0];
-    if (row === undefined) return null;
-    return {
-      id: String(row.id),
-      aggregateId: row.aggregateId,
-      aggregateType: row.aggregateType,
-      version: row.version,
-      type: row.type,
-      payload: redactPiiCiphertext(row.payload),
-      metadata: row.metadata,
-      createdAt: row.createdAt,
-      createdBy: row.createdBy,
-    };
+    return loadAuditEvent(db, {
+      tenantId: scopeFilter.tenantId,
+      ...(scopeFilter.aggregateType !== undefined && { aggregateType: scopeFilter.aggregateType }),
+      id: BigInt(query.payload.id),
+    });
   },
 });

package/packages/bundled-features/src/audit/handlers/list-all-tenants.query.ts

@@ -0,0 +1,47 @@
+// SystemAdmin view of the audit trail across every tenant (the system tenant excluded, see
+// allTenantsCondition). Rows carry their tenantId so the screen can label the tenant.
+
+import { access, defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import * as z from "zod";
+import {
+  AUDIT_DATE_RANGE_CHECK,
+  auditListPayloadShape,
+  buildAuditWhere,
+  listAuditEvents,
+} from "./audit-events.ts";
+import { requireAuditSystemDb } from "./audit-system-db.ts";
+import { allTenantsCondition, assertMayReadAllTenants } from "./resolve-audit-tenant.ts";
+
+const MAX_TENANT_FILTER_IDS = 100;
+
+// The reference facet on the tenant column sends exactly this shape.
+const tenantIdFiltersSchema = z
+  .array(
+    z.strictObject({
+      field: z.literal("tenantId"),
+      op: z.literal("in"),
+      value: z.array(z.uuid()).max(MAX_TENANT_FILTER_IDS),
+    }),
+  )
+  .max(1);
+
+export const listAllTenantsQuery = defineQueryHandler({
+  name: "list-all-tenants",
+  description:
+    "Lists audit-trail events of every tenant newest-first with cursor paging, each row carrying its tenantId; filterable by tenant, aggregate type, aggregate id, event type, actor and time range. SystemAdmin only; events of the system tenant are not included.",
+  schema: z
+    .object({ ...auditListPayloadShape, filters: tenantIdFiltersSchema.optional() })
+    .refine(AUDIT_DATE_RANGE_CHECK.isValid, AUDIT_DATE_RANGE_CHECK.params),
+  access: { roles: access.systemAdmin },
+  handler: async (query, ctx) => {
+    assertMayReadAllTenants(query.user);
+    const p = query.payload;
+    const direction = p.sortDirection ?? "desc";
+    const where = buildAuditWhere(allTenantsCondition(p.filters?.[0]?.value), p, direction);
+    const db = requireAuditSystemDb(
+      ctx.systemDb,
+      "audit:query:list-all-tenants",
+    ).acknowledgeCrossTenant("SystemAdmin reads the audit trail of every tenant");
+    return listAuditEvents(db, where, p, direction);
+  },
+});

package/packages/bundled-features/src/audit/handlers/list.query.ts

@@ -7,91 +7,27 @@
 // surface any audit UI needs; tenant-isolated at the WHERE level so cross-
 // tenant peeking is structurally impossible for non-SystemAdmin callers.
 // A SystemAdmin can pass scope "system" to read the app-instance system events
-// (e.g. app.started); no other cross-tenant read exists.
-//
-// Event payloads hold PII as subject-KMS ciphertext; it is replaced by
-// REDACTED_PII_PLACEHOLDER before returning, since the API leak guard refuses ciphertext.
+// (e.g. app.started); list-all-tenants is the one other cross-tenant read.
 
-import { selectMany, type WhereObject } from "@cosmicdrift/kumiko-framework/db";
 import { access, defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
-import { eventsTable } from "@cosmicdrift/kumiko-framework/event-store";
-import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import * as z from "zod";
-import { redactPiiCiphertext } from "../../shared/index.ts";
-import { AUDIT_SCOPE_VALUES } from "../constants.ts";
+import { AUDIT_SCOPE_VALUES } from "../web/constants.ts";
+import {
+  AUDIT_DATE_RANGE_CHECK,
+  auditListPayloadShape,
+  buildAuditWhere,
+  listAuditEvents,
+} from "./audit-events.ts";
+import { requireAuditSystemDb } from "./audit-system-db.ts";
 import { resolveAuditScopeFilter } from "./resolve-audit-tenant.ts";
 
-const MAX_LIMIT = 100;
-
-function buildDateRange(
-  from: string | undefined,
-  to: string | undefined,
-): { gte?: unknown; lte?: unknown } | null {
-  if (!from && !to) return null;
-  const range: { gte?: unknown; lte?: unknown } = {};
-  if (from) range.gte = Temporal.Instant.from(from);
-  if (to) range.lte = Temporal.Instant.from(to);
-  return range;
-}
-
-function escapeLikePattern(value: string): string {
-  return value.replace(/[\\%_]/g, (m) => `\\${m}`);
-}
-
-function buildAuditWhere(
-  tenantId: string,
-  p: {
-    aggregateType?: string;
-    aggregateId?: string;
-    eventType?: string;
-    search?: string;
-    userId?: string;
-    from?: string;
-    to?: string;
-    cursor?: string;
-    before?: string;
-  },
-  direction: "asc" | "desc",
-): WhereObject {
-  const where: WhereObject = { tenantId };
-  if (p.aggregateType) where["aggregateType"] = p.aggregateType;
-  if (p.aggregateId) where["aggregateId"] = p.aggregateId;
-  if (p.eventType) where["type"] = p.eventType;
-  else if (p.search) where["type"] = { like: `%${escapeLikePattern(p.search)}%` };
-  if (p.userId) where["createdBy"] = p.userId;
-  const range = buildDateRange(p.from, p.to);
-  if (range) where["createdAt"] = range;
-  const cursor = p.cursor ?? p.before;
-  // The cursor is an event id, so it only walks pages in id order: ascending
-  // pages continue past it, descending pages stop before it.
-  if (cursor) where["id"] = direction === "asc" ? { gt: BigInt(cursor) } : { lt: BigInt(cursor) };
-  return where;
-}
-
 export const listQuery = defineQueryHandler({
   name: "list",
   description:
     'Lists the tenant\'s audit-trail events newest-first with cursor paging, filterable by aggregate type, aggregate id, event type, actor and time range; use it to answer who changed what and when. A SystemAdmin can set scope "system" to read the app-instance system events (e.g. app.started) instead of the own tenant.',
   schema: z
-    .object({
-      cursor: z.string().regex(/^\d+$/, "cursor must be a positive integer").optional(),
-      before: z.string().regex(/^\d+$/, "cursor must be a positive integer").optional(),
-      search: z.string().trim().optional(),
-      limit: z.number().int().min(1).max(MAX_LIMIT).default(50),
-      aggregateType: z.string().optional(),
-      aggregateId: z.uuid().optional(),
-      eventType: z.string().optional(),
-      userId: z.string().optional(),
-      sort: z.enum(["createdAt", "type"]).optional(),
-      sortDirection: z.enum(["asc", "desc"]).optional(),
-      from: z.iso.datetime().optional(),
-      to: z.iso.datetime().optional(),
-      scope: z.enum(AUDIT_SCOPE_VALUES).optional(),
-    })
-    .refine((v) => !v.from || !v.to || v.from <= v.to, {
-      message: "`from` must be less than or equal to `to`",
-      path: ["from"],
-    }),
+    .object({ ...auditListPayloadShape, scope: z.enum(AUDIT_SCOPE_VALUES).optional() })
+    .refine(AUDIT_DATE_RANGE_CHECK.isValid, AUDIT_DATE_RANGE_CHECK.params),
   access: { roles: access.admin },
   handler: async (query, ctx) => {
     const p = query.payload;
@@ -99,55 +35,12 @@ export const listQuery = defineQueryHandler({
     const direction = p.sortDirection ?? "desc";
     const where = buildAuditWhere(
       scopeFilter.tenantId,
-      {
-        ...p,
-        aggregateType: scopeFilter.aggregateType ?? p.aggregateType,
-      },
+      { ...p, aggregateType: scopeFilter.aggregateType ?? p.aggregateType },
       direction,
     );
-
-    const rows = await selectMany<{
-      id: bigint;
-      aggregateId: string;
-      aggregateType: string;
-      version: number;
-      type: string;
-      payload: Record<string, unknown>;
-      metadata: Record<string, unknown>;
-      createdAt: unknown;
-      createdBy: string;
-    }>(ctx.db, eventsTable, where, {
-      // The id cursor only resumes an id-ordered listing. created_at comes from the
-      // transaction start and can run against insert order, so ordering by it would let
-      // a page boundary skip rows; only the type sort leaves id order (and is one page).
-      orderBy:
-        p.sort === "type"
-          ? [
-              { col: "type", direction },
-              { col: "id", direction },
-            ]
-          : [{ col: "id", direction }],
-      limit: p.limit,
-    });
-
-    const serialised = rows.map((r) => ({
-      id: String(r.id),
-      aggregateId: r.aggregateId,
-      aggregateType: r.aggregateType,
-      version: r.version,
-      type: r.type,
-      payload: redactPiiCiphertext(r.payload),
-      metadata: r.metadata,
-      createdAt: r.createdAt,
-      createdBy: r.createdBy,
-    }));
-    const last = serialised[serialised.length - 1];
-    // An id cursor cannot resume a type-ordered listing, so that sort is one page.
-    const nextId = serialised.length === p.limit && last && p.sort !== "type" ? last.id : null;
-    return {
-      rows: serialised,
-      nextCursor: nextId,
-      nextBefore: nextId,
-    };
+    const db = requireAuditSystemDb(ctx.systemDb, "audit:query:list").assertTenantMatch(
+      query.user.tenantId,
+    );
+    return listAuditEvents(db, where, p, direction);
   },
 });

package/packages/bundled-features/src/audit/handlers/resolve-audit-tenant.ts

@@ -2,10 +2,17 @@ import { mayOverrideTenant, type SessionUser } from "@cosmicdrift/kumiko-framewo
 import { AccessDeniedError, FrameworkReasons } from "@cosmicdrift/kumiko-framework/errors";
 import { APP_INSTANCE_STREAM_TYPE } from "@cosmicdrift/kumiko-framework/event-store";
 import { SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-types/identifiers";
-import { type AuditScope, AuditScopes } from "../constants.ts";
+import { type AuditScope, AuditScopes } from "../web/constants.ts";
 
 export type AuditScopeFilter = { readonly tenantId: string; readonly aggregateType?: string };
 
+function denySystemAdminOnlyRead(): never {
+  throw new AccessDeniedError({
+    i18nKey: "audit.errors.systemScopeRequiresSystemAdmin",
+    details: { reason: FrameworkReasons.tenantOverrideRequiresSystemAdmin },
+  });
+}
+
 // The system tenant also holds personal streams of other features (session
 // revocations, exports, ...); only app-instance streams are released.
 export function resolveAuditScopeFilter(
@@ -13,11 +20,18 @@ export function resolveAuditScopeFilter(
   scope: AuditScope | undefined,
 ): AuditScopeFilter {
   if (scope !== AuditScopes.system) return { tenantId: user.tenantId };
-  if (!mayOverrideTenant(user)) {
-    throw new AccessDeniedError({
-      i18nKey: "audit.errors.systemScopeRequiresSystemAdmin",
-      details: { reason: FrameworkReasons.tenantOverrideRequiresSystemAdmin },
-    });
-  }
+  if (!mayOverrideTenant(user)) denySystemAdminOnlyRead();
   return { tenantId: SYSTEM_TENANT_ID, aggregateType: APP_INSTANCE_STREAM_TYPE };
 }
+
+export function assertMayReadAllTenants(user: SessionUser): void {
+  if (!mayOverrideTenant(user)) denySystemAdminOnlyRead();
+}
+
+// The where condition for reads across tenants. The system tenant is always excluded: it holds
+// personal streams of other features, and a where object cannot express "only app-instance
+// streams of that one tenant" next to "every other tenant".
+export function allTenantsCondition(requestedTenantIds: readonly string[] | undefined): unknown {
+  if (requestedTenantIds === undefined) return { ne: SYSTEM_TENANT_ID };
+  return { in: requestedTenantIds.filter((id) => id !== SYSTEM_TENANT_ID) };
+}

package/packages/bundled-features/src/audit/index.ts

@@ -1,3 +1,3 @@
-export { AUDIT_FEATURE, AuditQueries } from "./constants.ts";
 export { createEscapeHatchAuditSink, ESCAPE_HATCH_USED_EVENT } from "./escape-hatch-audit-sink.ts";
 export { createAuditFeature } from "./feature.ts";
+export { AUDIT_FEATURE, AuditQueries } from "./web/constants.ts";

package/packages/bundled-features/src/audit/run-escape-hatch-retention.ts

@@ -20,14 +20,14 @@ import { pruneEvents } from "@cosmicdrift/kumiko-framework/pipeline";
 import { getTemporal } from "@cosmicdrift/kumiko-framework/time";
 import { resolveProfileForTenant } from "../compliance-profiles/index.ts";
 import { createConfigAccessor } from "../config/index.ts";
-import {
-  DEFAULT_ESCAPE_HATCH_RETENTION_DAYS,
-  ESCAPE_HATCH_RETENTION_DAYS_KEY,
-} from "./constants.ts";
 import {
   ESCAPE_HATCH_USE_AGGREGATE_TYPE,
   escapeHatchUsedSchema,
 } from "./escape-hatch-audit-sink.ts";
+import {
+  DEFAULT_ESCAPE_HATCH_RETENTION_DAYS,
+  ESCAPE_HATCH_RETENTION_DAYS_KEY,
+} from "./web/constants.ts";
 
 // pruneEvents opens its own transaction, so a runner that cannot begin one (a tx handle) is rejected instead of nested.
 export function isDbConnection(runner: DbRunner): runner is DbConnection {

package/packages/bundled-features/src/audit/screens.ts

@@ -0,0 +1,82 @@
+// Columns, labels and layout shared by the tenant audit log and its all-tenants variant, so the
+// two screen pairs cannot drift apart. The all-tenants variant only adds the tenant.
+
+import { i18nKey } from "@cosmicdrift/kumiko-framework/engine";
+import type { EditLayout, ListColumnSpec } from "@cosmicdrift/kumiko-framework/ui-types";
+
+const TENANT_REFERENCE = { refEntity: "tenant:tenant", refLabelField: "name" } as const;
+const ACTOR_REFERENCE = { refEntity: "user:user", refLabelField: "displayName" } as const;
+
+const WHEN_COLUMN = {
+  field: "createdAt",
+  label: i18nKey("audit.log.col.when"),
+  renderer: { format: "timestamp" },
+} as const satisfies ListColumnSpec;
+const TENANT_COLUMN = {
+  field: "tenantId",
+  label: i18nKey("audit.log.col.tenant"),
+  ...TENANT_REFERENCE,
+} as const satisfies ListColumnSpec;
+const TYPE_COLUMN = { field: "type", label: i18nKey("audit.log.col.type") } as const;
+const ACTOR_COLUMN = {
+  field: "createdBy",
+  label: i18nKey("audit.log.col.actor"),
+  ...ACTOR_REFERENCE,
+} as const satisfies ListColumnSpec;
+
+export const AUDIT_LOG_COLUMNS = [WHEN_COLUMN, TYPE_COLUMN, ACTOR_COLUMN] as const;
+export const AUDIT_LOG_ALL_TENANTS_COLUMNS = [
+  WHEN_COLUMN,
+  TENANT_COLUMN,
+  TYPE_COLUMN,
+  ACTOR_COLUMN,
+] as const;
+
+export const AUDIT_LOG_DATE_RANGE_FACET = {
+  type: "dateRange",
+  field: "createdAt",
+  label: i18nKey("audit.log.col.when"),
+  params: { from: "from", to: "to" },
+} as const;
+
+export const AUDIT_LOG_TENANT_FACET = {
+  type: "reference",
+  field: "tenantId",
+  label: i18nKey("audit.log.col.tenant"),
+  entity: TENANT_REFERENCE.refEntity,
+  labelField: TENANT_REFERENCE.refLabelField,
+} as const;
+
+export const AUDIT_LOG_DETAIL_FIELD_LABELS = {
+  type: i18nKey("audit.log.col.type"),
+  createdAt: i18nKey("audit.log.col.when"),
+  aggregateType: i18nKey("audit.log.col.aggregateType"),
+  aggregateId: i18nKey("audit.log.col.aggregateId"),
+  createdBy: i18nKey("audit.log.col.actor"),
+  id: i18nKey("audit.log.detail.field.id"),
+  payload: i18nKey("audit.log.detail.payload"),
+  metadata: i18nKey("audit.log.detail.metadata"),
+} as const;
+
+export function auditLogDetailLayout(options: { readonly withTenant: boolean }): EditLayout {
+  return {
+    sections: [
+      {
+        fields: [
+          "type",
+          { field: "createdAt", renderer: { format: "timestamp" } },
+          ...(options.withTenant ? [{ field: "tenantId", ...TENANT_REFERENCE }] : []),
+          "aggregateType",
+          "aggregateId",
+          { field: "createdBy", ...ACTOR_REFERENCE },
+          "id",
+        ],
+      },
+      // No section `title` here (fw#2312 label-dedup fix): each section
+      // holds exactly one field, so a title would repeat the field's own
+      // label (rendered by RenderField as the Field's heading) verbatim.
+      { fields: [{ field: "payload", renderer: { format: "json" } }] },
+      { fields: [{ field: "metadata", renderer: { format: "json" } }] },
+    ],
+  };
+}

package/packages/bundled-features/src/audit/web/client-plugin.tsx

@@ -1,8 +1,7 @@
-// @runtime client
 import { mergeTranslations, type TranslationsByLocale } from "@cosmicdrift/kumiko-renderer";
 import type { ClientFeatureDefinition } from "@cosmicdrift/kumiko-renderer/web";
-import { AUDIT_FEATURE } from "../constants.ts";
-import { defaultTranslations } from "./i18n.ts";
+import { AUDIT_FEATURE } from "./constants.ts";
+import { defaultTranslations } from "./default-translations.ts";
 
 export type AuditClientOptions = {
   readonly translations?: TranslationsByLocale;

package/packages/bundled-features/src/audit/{constants.ts → web/constants.ts}

@@ -1,4 +1,3 @@
-// @runtime client
 // Qualified handler names + screen ids — shared by server feature and web client.
 export const AUDIT_FEATURE = "audit" as const;
 
@@ -17,6 +16,8 @@ export const SYSTEM_ACTOR_IDS: ReadonlySet<string> = new Set([
 export const AuditQueries = {
   list: "audit:query:list",
   details: "audit:query:details",
+  listAllTenants: "audit:query:list-all-tenants",
+  detailsAllTenants: "audit:query:details-all-tenants",
 } as const;
 
 /** Read scope of the audit queries: the caller's own tenant (default) or the system tenant (SystemAdmin only). */
@@ -30,6 +31,15 @@ export const AUDIT_LOG_SCREEN_ID = "audit-log" as const;
 /** Single-event detail screen, breadcrumb-linked to the audit-log list. */
 export const AUDIT_LOG_DETAIL_SCREEN_ID = "audit-log-detail" as const;
 
+/** SystemAdmin audit log across every tenant. Nav: `audit:nav:audit-log-all-tenants`. */
+export const AUDIT_LOG_ALL_TENANTS_SCREEN_ID = "audit-log-all-tenants" as const;
+
+/** Single-event detail screen of the all-tenants log. */
+export const AUDIT_LOG_ALL_TENANTS_DETAIL_SCREEN_ID = "audit-log-all-tenants-detail" as const;
+
+/** Nav entry of the all-tenants log (short id; QN `audit:nav:audit-log-all-tenants`). */
+export const AUDIT_LOG_ALL_TENANTS_NAV_ID = "audit-log-all-tenants" as const;
+
 /**
  * Config key (system scope) for how long `escapeHatchUse` audit events are kept. Only a fallback
  * for apps without compliance-profiles; with it mounted, the tenant profile's `auditLog.retention`