@ultimat3/admin 1.0.0

package/src/ai-panes.ts

@@ -0,0 +1,139 @@
+// Opt-in AI panes. Every pane is off until named in `enable`, and every pane declares the
+// scope it needs — an anomaly pane that can read job metrics cannot also read rows, and the
+// NL-query pane is bounded to the read-only DB tool. Nothing here runs without a runner.
+
+import type { Gateway } from '@ultimat3/ai';
+import { ADMIN_READ } from './permissions';
+import type { AdminJobSummary } from './registry';
+
+/** What a pane is allowed to look at. Checked by the caller against the actor's grants. */
+export type AiPaneScope = 'jobs:read' | 'metrics:read' | 'db:read-only';
+
+export interface AiPaneRequest {
+  readonly system: string;
+  readonly user: string;
+  readonly scopes: readonly AiPaneScope[];
+}
+
+/**
+ * The narrow slice of an AI gateway a pane uses. `Gateway` from @ultimat3/ai is adapted to
+ * it by the host app, so a pane cannot reach a tool the app did not hand it.
+ */
+export interface AiRunner {
+  complete(request: AiPaneRequest): Promise<string>;
+}
+
+export type GatewayAdapter = (gateway: Gateway) => AiRunner;
+
+export interface AiPaneFacts {
+  readonly jobs: readonly AdminJobSummary[];
+  /** Queue depth per queue name, as the jobs panel already reports it. */
+  readonly queueDepth: Readonly<Record<string, number>>;
+  /** Failures per queue over the pane's window. */
+  readonly failures: Readonly<Record<string, number>>;
+  /** The operator's question, for the NL-query pane. Empty for the others. */
+  readonly question: string;
+}
+
+export interface AiPane {
+  readonly key: string;
+  readonly titleKey: string;
+  readonly descriptionKey: string;
+  readonly scopes: readonly AiPaneScope[];
+  /** Admin permissions the viewer needs on top of the scope. */
+  readonly permissions: readonly string[];
+  readonly enabled: boolean;
+  request(facts: AiPaneFacts): AiPaneRequest;
+}
+
+const facts = (input: AiPaneFacts): string =>
+  JSON.stringify(
+    {
+      queueDepth: input.queueDepth,
+      failures: input.failures,
+      jobs: input.jobs.map((job) => ({ name: job.name, queue: job.queue ?? 'default' })),
+    },
+    null,
+    2,
+  );
+
+const anomalyPane: AiPane = {
+  key: 'anomaly',
+  titleKey: 'admin.ai.anomaly.title',
+  descriptionKey: 'admin.ai.anomaly.description',
+  scopes: ['jobs:read', 'metrics:read'],
+  permissions: [ADMIN_READ],
+  enabled: false,
+  request(input): AiPaneRequest {
+    return {
+      system:
+        'You review background-job metrics. Report only deviations you can point at a number for. No advice.',
+      user: `Queue and failure counts:\n${facts(input)}\n\nList anomalies as: queue, metric, observed, expected.`,
+      scopes: ['jobs:read', 'metrics:read'],
+    };
+  },
+};
+
+const nlQueryPane: AiPane = {
+  key: 'nl-query',
+  titleKey: 'admin.ai.nl-query.title',
+  descriptionKey: 'admin.ai.nl-query.description',
+  // The DB tool this pane targets is the read-only one behind the /_x DB panel.
+  scopes: ['db:read-only'],
+  permissions: [ADMIN_READ],
+  enabled: false,
+  request(input): AiPaneRequest {
+    return {
+      system:
+        'You write one read-only Postgres SELECT. No DML, no DDL, no CTE that writes. Return SQL only.',
+      user: input.question,
+      scopes: ['db:read-only'],
+    };
+  },
+};
+
+const forecastPane: AiPane = {
+  key: 'backlog-forecast',
+  titleKey: 'admin.ai.forecast.title',
+  descriptionKey: 'admin.ai.forecast.description',
+  scopes: ['jobs:read', 'metrics:read'],
+  permissions: [ADMIN_READ],
+  enabled: false,
+  request(input): AiPaneRequest {
+    return {
+      system:
+        'You forecast queue drain time from depth and throughput. State the assumption behind each number.',
+      user: `Current state:\n${facts(input)}\n\nFor each queue: minutes to drain, and the throughput you assumed.`,
+      scopes: ['jobs:read', 'metrics:read'],
+    };
+  },
+};
+
+export const AI_PANES: readonly AiPane[] = [anomalyPane, nlQueryPane, forecastPane];
+
+export interface AiPanesOptions {
+  /** Pane keys to switch on. Anything not listed stays off. */
+  readonly enable?: readonly string[];
+  readonly runner?: AiRunner;
+}
+
+/** The pane list for the admin shell: same shape whether AI is on or off. */
+export function aiPanes(opts: AiPanesOptions = {}): readonly AiPane[] {
+  const enable = new Set(opts.enable ?? []);
+  return AI_PANES.map((pane) => ({ ...pane, enabled: enable.has(pane.key) }));
+}
+
+export type AiPaneResult =
+  | { readonly ok: true; readonly text: string }
+  | { readonly ok: false; readonly reason: string };
+
+/** A disabled pane, or a missing runner, is a refusal — never a silent no-op. */
+export async function runAiPane(
+  pane: AiPane,
+  input: AiPaneFacts,
+  runner: AiRunner | undefined,
+): Promise<AiPaneResult> {
+  if (!pane.enabled) return { ok: false, reason: 'admin.ai.disabled' };
+  if (runner === undefined) return { ok: false, reason: 'admin.ai.no-runner' };
+  return { ok: true, text: await runner.complete(pane.request(input)) };
+}

package/src/audit.ts

@@ -0,0 +1,183 @@
+// Append-only audit log: actor, operation, entity, before/after diff, requestId, timestamp.
+// If it isn't logged, it didn't happen — so denied and failed attempts are logged too, and
+// there is deliberately no update or delete on this interface.
+
+import type { AdminActor, AdminDecision } from './authz';
+import type { AdminRow } from './registry';
+
+export const REDACTED = '[redacted]';
+
+export interface AuditFieldDiff {
+  readonly field: string;
+  readonly before: unknown;
+  readonly after: unknown;
+}
+
+export type AuditOutcome = 'allowed' | 'denied' | 'failed';
+
+export interface AuditEntry {
+  readonly id: string;
+  /** ISO-8601 UTC. Stored UTC, formatted per viewer zone at the edge. */
+  readonly at: string;
+  readonly requestId: string;
+  readonly actor: { readonly id: string; readonly roles: readonly string[] };
+  /** `list` | `create` | `update` | `delete`, or an action name. */
+  readonly operation: string;
+  readonly kind: 'operation' | 'action';
+  readonly entity: string;
+  readonly entityId: string | null;
+  readonly permission: string;
+  readonly outcome: AuditOutcome;
+  /** i18n key or policy rule name explaining the outcome. */
+  readonly reason: string;
+  readonly diff: readonly AuditFieldDiff[];
+}
+
+export interface AuditDraft {
+  readonly requestId: string;
+  readonly actor: AdminActor;
+  readonly operation: string;
+  readonly kind: 'operation' | 'action';
+  readonly entity: string;
+  readonly entityId?: string | null;
+  readonly permission: string;
+  readonly outcome: AuditOutcome;
+  readonly reason: string;
+  readonly diff?: readonly AuditFieldDiff[];
+}
+
+/** Where entries go beyond memory: a table, stdout as JSON lines, an OTel log. */
+export interface AuditSink {
+  write(entry: AuditEntry): Promise<void> | void;
+}
+
+export interface AuditLog {
+  append(draft: AuditDraft): Promise<AuditEntry>;
+  /** Newest first. A copy — the log cannot be mutated through what it hands out. */
+  entries(query?: {
+    readonly entity?: string;
+    readonly actorId?: string;
+    readonly limit?: number;
+  }): readonly AuditEntry[];
+}
+
+export interface AuditLogOptions {
+  readonly sinks?: readonly AuditSink[];
+  /** Injected so tests get deterministic timestamps and ids. */
+  readonly now?: () => Date;
+  readonly nextId?: () => string;
+  /** Ring size. The memory log is a dev/inspection buffer, not the system of record. */
+  readonly capacity?: number;
+}
+
+export function auditEntry(draft: AuditDraft, id: string, at: Date): AuditEntry {
+  return {
+    id,
+    at: at.toISOString(),
+    requestId: draft.requestId,
+    actor: { id: draft.actor.id, roles: draft.actor.roles ?? [] },
+    operation: draft.operation,
+    kind: draft.kind,
+    entity: draft.entity,
+    entityId: draft.entityId ?? null,
+    permission: draft.permission,
+    outcome: draft.outcome,
+    reason: draft.reason,
+    diff: draft.diff ?? [],
+  };
+}
+
+export function memoryAuditLog(opts: AuditLogOptions = {}): AuditLog {
+  const now = opts.now ?? ((): Date => new Date());
+  const nextId = opts.nextId ?? ((): string => crypto.randomUUID());
+  const capacity = opts.capacity ?? 1000;
+  const sinks = opts.sinks ?? [];
+  const log: AuditEntry[] = [];
+
+  return {
+    async append(draft: AuditDraft): Promise<AuditEntry> {
+      // Timestamp first: the entry is stamped when it happened, not when the id generator
+      // got around to it.
+      const at = now();
+      const entry = auditEntry(draft, nextId(), at);
+      log.push(entry);
+      if (log.length > capacity) log.splice(0, log.length - capacity);
+      for (const sink of sinks) await sink.write(entry);
+      return entry;
+    },
+    entries(query = {}): readonly AuditEntry[] {
+      const filtered = log.filter(
+        (entry) =>
+          (query.entity === undefined || entry.entity === query.entity) &&
+          (query.actorId === undefined || entry.actor.id === query.actorId),
+      );
+      const newestFirst = [...filtered].reverse();
+      return query.limit === undefined ? newestFirst : newestFirst.slice(0, query.limit);
+    },
+  };
+}
+
+const same = (a: unknown, b: unknown): boolean => {
+  if (a === b) return true;
+  if (a instanceof Date && b instanceof Date) return a.getTime() === b.getTime();
+  if (a === null || b === null || a === undefined || b === undefined) return false;
+  if (typeof a === 'object' && typeof b === 'object') {
+    return JSON.stringify(a) === JSON.stringify(b);
+  }
+  return false;
+};
+
+/**
+ * Shallow field-by-field diff of the row before and after a mutation. Only changed fields
+ * appear — a diff nobody can read is a diff nobody reads. Sensitive fields are recorded as
+ * having changed, with their values replaced.
+ */
+export function diffRows(
+  before: AdminRow | null,
+  after: AdminRow | null,
+  opts: { readonly redact?: readonly string[] } = {},
+): readonly AuditFieldDiff[] {
+  const redact = new Set(opts.redact ?? []);
+  const names = new Set([...Object.keys(before ?? {}), ...Object.keys(after ?? {})]);
+  const out: AuditFieldDiff[] = [];
+
+  for (const field of [...names].sort()) {
+    const from = before === null ? undefined : before[field];
+    const to = after === null ? undefined : after[field];
+    if (same(from, to)) continue;
+    out.push(
+      redact.has(field)
+        ? {
+            field,
+            before: from === undefined ? undefined : REDACTED,
+            after: to === undefined ? undefined : REDACTED,
+          }
+        : { field, before: from, after: to },
+    );
+  }
+  return out;
+}
+
+/** The draft for a denied attempt. Denials are the entries an auditor actually wants. */
+export function deniedDraft(input: {
+  readonly requestId: string;
+  readonly actor: AdminActor;
+  readonly operation: string;
+  readonly kind: 'operation' | 'action';
+  readonly entity: string;
+  readonly entityId?: string | null;
+  readonly decision: AdminDecision;
+}): AuditDraft {
+  return {
+    requestId: input.requestId,
+    actor: input.actor,
+    operation: input.operation,
+    kind: input.kind,
+    entity: input.entity,
+    entityId: input.entityId ?? null,
+    permission: input.decision.permission,
+    outcome: 'denied',
+    reason: input.decision.reason,
+    diff: [],
+  };
+}

package/src/authz.ts

@@ -0,0 +1,129 @@
+// ONE authz seam for the whole admin. Every surface — the rendered button, the HTTP call
+// behind it, the MCP tool, the nav item, the search result — asks this interface and nobody
+// re-implements the question. That is the invariant the admin exists to keep: the UI cannot
+// show what the call would refuse.
+//
+// The interface is structural on purpose: `policyAuthz()` in policy-bridge.ts adapts
+// @ultimat3/policy into it, a host app can supply its own, and tests can supply a stub —
+// but there is still exactly one decision per request.
+
+import { ADMIN_PERMISSION_SPEC, type AdminPermission } from './permissions';
+
+export interface AdminActor {
+  readonly id: string;
+  readonly roles?: readonly string[];
+  /** BCP-47. Drives every `t()` call and every `Intl` format in the admin. */
+  readonly locale?: string;
+  /** IANA zone. The admin refuses to render a timestamp without one. */
+  readonly timeZone?: string;
+}
+
+/** What a decision is about: an entity row, an action's input, or nothing (a page). */
+export interface AdminSubject {
+  readonly entity?: string;
+  readonly id?: string;
+  readonly input?: unknown;
+}
+
+export interface AdminDecision {
+  readonly allowed: boolean;
+  readonly permission: string;
+  /** An i18n key or a policy rule name — never a sentence. Rendered by the caller. */
+  readonly reason: string;
+  /** Rule-by-rule trace, shown verbatim in the `/_x` policy panel. */
+  readonly trace: readonly string[];
+}
+
+export interface AdminAuthzQuery {
+  readonly permission: string;
+  readonly actor: AdminActor;
+  readonly subject?: AdminSubject;
+}
+
+export interface AdminAuthz {
+  decide(query: AdminAuthzQuery): AdminDecision;
+}
+
+export function allowed(
+  permission: string,
+  reason: string,
+  trace: readonly string[] = [],
+): AdminDecision {
+  return { allowed: true, permission, reason, trace };
+}
+
+export function denied(
+  permission: string,
+  reason: string,
+  trace: readonly string[] = [],
+): AdminDecision {
+  return { allowed: false, permission, reason, trace };
+}
+
+/** Every permission must hold. The first denial wins, and carries its own reason. */
+export function decideAll(
+  authz: AdminAuthz,
+  permissions: readonly string[],
+  actor: AdminActor,
+  subject?: AdminSubject,
+): AdminDecision {
+  const trace: string[] = [];
+  for (const permission of permissions) {
+    const decision = authz.decide(
+      subject === undefined ? { permission, actor } : { permission, actor, subject },
+    );
+    trace.push(`${permission}: ${decision.allowed ? 'allow' : 'deny'} (${decision.reason})`);
+    if (!decision.allowed)
+      return denied(permission, decision.reason, [...trace, ...decision.trace]);
+  }
+  const last = permissions[permissions.length - 1] ?? '';
+  return allowed(last, 'admin.policy.all-granted', trace);
+}
+
+export function isAllowed(
+  authz: AdminAuthz,
+  permissions: readonly string[],
+  actor: AdminActor,
+  subject?: AdminSubject,
+): boolean {
+  return decideAll(authz, permissions, actor, subject).allowed;
+}
+
+const impliedBy = (permission: string): readonly string[] => {
+  // Widened: `permission` is any string at runtime, so the lookup really can miss.
+  const spec: { readonly implies: readonly string[] } | undefined =
+    ADMIN_PERMISSION_SPEC[permission as AdminPermission];
+  return spec?.implies ?? [];
+};
+
+/** Transitive closure of the admin permission implications (`destroy` ⇒ `write` ⇒ `read`). */
+export function expandPermissions(granted: readonly string[]): readonly string[] {
+  const out = new Set<string>();
+  const walk = (permission: string): void => {
+    if (out.has(permission)) return;
+    out.add(permission);
+    for (const next of impliedBy(permission)) walk(next);
+  };
+  for (const permission of granted) walk(permission);
+  return [...out].sort();
+}
+
+/**
+ * A grant-list authz for tests, seeds, and `x dev --actor`. Production always goes through
+ * `policyAuthz()` so the app's real rules (ownership, org scoping) are the ones evaluated.
+ */
+export function staticAuthz(granted: readonly string[]): AdminAuthz {
+  const set = new Set(expandPermissions(granted));
+  return {
+    decide({ permission }): AdminDecision {
+      return set.has(permission)
+        ? allowed(permission, 'admin.policy.granted', [`static: ${permission} in grant list`])
+        : denied(permission, 'admin.policy.not-granted', [
+            `static: ${permission} not in [${[...set].join(', ')}]`,
+          ]);
+    },
+  };
+}
+
+/** No actor, no grants. The default for an unauthenticated request. */
+export const anonymousAuthz: AdminAuthz = staticAuthz([]);