@crombolo/server 0.10.0 → 0.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crombolo/server",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "The crombolo HTTP server: routing, configuration, media stores and background jobs.",
   "license": "MIT",
   "author": "Crombolo",
@@ -28,16 +28,16 @@
     "access": "public"
   },
   "dependencies": {
-    "@crombolo/api-management": "0.10.0",
-    "@crombolo/assistant": "0.10.0",
-    "@crombolo/auth": "0.10.0",
-    "@crombolo/backoffice-host": "0.10.0",
-    "@crombolo/contracts": "0.10.0",
-    "@crombolo/core": "0.10.0",
-    "@crombolo/data": "0.10.0",
-    "@crombolo/render": "0.10.0",
-    "@crombolo/schema": "0.10.0",
-    "@crombolo/transfer": "0.10.0",
+    "@crombolo/api-management": "0.11.0",
+    "@crombolo/assistant": "0.11.0",
+    "@crombolo/auth": "0.11.0",
+    "@crombolo/backoffice-host": "0.11.0",
+    "@crombolo/contracts": "0.11.0",
+    "@crombolo/core": "0.11.0",
+    "@crombolo/data": "0.11.0",
+    "@crombolo/render": "0.11.0",
+    "@crombolo/schema": "0.11.0",
+    "@crombolo/transfer": "0.11.0",
     "@logtape/logtape": "^2.3.8"
   }
 }

package/src/adapters/audit.ts

@@ -0,0 +1,186 @@
+/**
+ * The audit log's ports: where the router writes, what an item's Info tab reads,
+ * and the Settings dashboard's endpoint. docs/audit-log.md.
+ */
+import type { AuditHistoryPort, AuditSink } from '@crombolo/api-management'
+import {
+  AUDIT_CATEGORIES,
+  type AuditCategory,
+  type AuditEntry,
+  type AuditEntryInput,
+  AuditLog,
+  type Db,
+} from '@crombolo/data'
+import { logger } from '../logging.ts'
+
+const log = logger('Audit')
+
+/** The oldest moment the log still keeps, or undefined when it keeps everything. */
+export function auditRetainedSince(retentionDays: number, now = new Date()): Date | undefined {
+  return retentionDays > 0 ? new Date(now.getTime() - retentionDays * 86_400_000) : undefined
+}
+
+/**
+ * Writes an entry without ever failing what it records: the change has already
+ * been made by the time it is written, so a failure here is logged, not raised.
+ */
+export async function recordAudit(
+  db: Db,
+  entries: AuditEntryInput | readonly AuditEntryInput[],
+): Promise<void> {
+  try {
+    await new AuditLog(db).record(entries)
+  } catch (error) {
+    log.error('Could not write to the audit log: {error}', { error })
+  }
+}
+
+export function createAuditSink(db: Db): AuditSink {
+  const audit = new AuditLog(db)
+  return {
+    async describe(entityType, key) {
+      try {
+        return await audit.describe(entityType, key)
+      } catch (error) {
+        log.warning('Could not name {entityType} {key} for the audit log: {error}', {
+          entityType,
+          key,
+          error,
+        })
+        return { entityType, entityKey: key, entityName: null }
+      }
+    },
+    record: (entries) =>
+      recordAudit(
+        db,
+        entries.map((entry) => ({ ...entry, source: 'request' as const })),
+      ),
+  }
+}
+
+export function createAuditHistory(db: Db, retentionDays: number): AuditHistoryPort {
+  const audit = new AuditLog(db)
+  let started: Date | undefined
+  return {
+    async forItem(key) {
+      const { items } = await audit.query({ entityKey: key }, { skip: 0, take: 10_000 })
+      return items
+    },
+    async startedAt() {
+      started ??= await audit.startedAt()
+      return started
+    },
+    retainedSince: () => auditRetainedSince(retentionDays),
+  }
+}
+
+function toResponse(entry: AuditEntry) {
+  return {
+    id: entry.id,
+    occurredAt: entry.occurredAt.toISOString(),
+    category: entry.category,
+    action: entry.action,
+    source: entry.source,
+    user: entry.userKey || entry.userName ? { key: entry.userKey, name: entry.userName } : null,
+    item: entry.entityType
+      ? { type: entry.entityType, key: entry.entityKey, name: entry.entityName }
+      : null,
+    ipAddress: entry.ipAddress,
+    forwardedFor: entry.forwardedFor,
+    detail: entry.detail,
+  }
+}
+
+function dateParam(value: string | null): Date | undefined | null {
+  if (!value) return undefined
+  const parsed = new Date(value)
+  return Number.isNaN(parsed.getTime()) ? null : parsed
+}
+
+const badRequest = (detail: string) =>
+  Response.json({ title: 'Invalid request', status: 400, detail }, { status: 400 })
+
+/**
+ * The Settings dashboard's reads: `GET /` lists entries, newest first, filtered
+ * by user, item, category, action, date and text; `GET /users` names everyone in
+ * the log. Nothing here writes, so an entry cannot be changed through it.
+ */
+export function createAuditHost(db: Db, retentionDays: number) {
+  const audit = new AuditLog(db)
+  return {
+    async handle(request: Request, pathname: string): Promise<Response | undefined> {
+      if (pathname !== '' && pathname !== '/' && pathname !== '/users') return undefined
+      if (request.method !== 'GET')
+        return new Response('Method Not Allowed', { status: 405, headers: { allow: 'GET' } })
+      if (pathname === '/users') return Response.json({ items: await audit.users() })
+
+      const search = new URL(request.url).searchParams
+      const skip = Number(search.get('skip') ?? 0)
+      const take = Number(search.get('take') ?? 50)
+      if (!Number.isInteger(skip) || skip < 0 || !Number.isInteger(take) || take < 1 || take > 500)
+        return badRequest('skip must be 0 or more, and take between 1 and 500.')
+      const category = search.get('category') ?? undefined
+      if (category && !AUDIT_CATEGORIES.includes(category as AuditCategory))
+        return badRequest(`There is no category "${category}".`)
+      const since = dateParam(search.get('since'))
+      const until = dateParam(search.get('until'))
+      if (since === null || until === null) return badRequest('since and until must be dates.')
+      const result = await audit.query(
+        {
+          userKey: search.get('user') ?? undefined,
+          entityKey: search.get('item') ?? undefined,
+          category: category as AuditCategory | undefined,
+          action: search.get('action') ?? undefined,
+          since,
+          until,
+          text: search.get('text') ?? undefined,
+        },
+        { skip, take },
+      )
+      return Response.json({
+        total: result.total,
+        retentionDays,
+        items: result.items.map(toResponse),
+      })
+    },
+  }
+}
+
+const VERB: Record<string, string> = {
+  POST: 'Create',
+  PUT: 'Save',
+  PATCH: 'Save',
+  DELETE: 'Delete',
+}
+
+/** Crombolo's own endpoints that change something, by their first segment. */
+const PLUGIN_AREAS: Record<string, { category: AuditCategory; entityType: string }> = {
+  'schema-import': { category: 'schema', entityType: 'Schema' },
+  git: { category: 'schema', entityType: 'Schema' },
+  seo: { category: 'settings', entityType: 'SeoSettings' },
+  bundles: { category: 'system', entityType: 'Bundle' },
+  forms: { category: 'content', entityType: 'Form' },
+}
+
+const PLUGIN_ACTIONS: Record<string, string> = {
+  'schema-import': 'Import',
+  'git/commit': 'Commit',
+  'bundles/install': 'Install',
+  'bundles/uninstall': 'Uninstall',
+}
+
+/** The entry for a write to `<plugin>/api/<subpath>`: the area it is in, and what it did there. */
+export function pluginAuditPlan(
+  method: string,
+  subpath: string,
+): Pick<AuditEntryInput, 'category' | 'action' | 'entityType' | 'entityKey' | 'detail'> {
+  const [area = '', ...rest] = subpath.split('/')
+  const known = PLUGIN_AREAS[area]
+  return {
+    category: known?.category ?? 'settings',
+    entityType: known?.entityType ?? area,
+    action: PLUGIN_ACTIONS[subpath] ?? VERB[method] ?? method,
+    entityKey: rest.length > 0 ? rest.join('/') : null,
+    detail: `${method} ${subpath}`,
+  }
+}

package/src/adapters/search-index.ts

@@ -0,0 +1,31 @@
+/** The Examine dashboard's port over the search index. docs/search.md. */
+import type { SearchIndexInfo, SearchIndexPort } from '@crombolo/api-management'
+import { type Db, SEARCH_INDEXES, SearchIndex, type SearchIndexDefinition } from '@crombolo/data'
+
+export function createSearchIndexPort(db: Db, onQueued?: () => void): SearchIndexPort {
+  const search = new SearchIndex(db)
+  const info = async (index: SearchIndexDefinition): Promise<SearchIndexInfo> => ({
+    name: index.name,
+    searcherName: index.searcherName,
+    ...(await search.stats(index)),
+  })
+  return {
+    indexes: () => Promise.all(SEARCH_INDEXES.map(info)),
+    async index(name) {
+      const index = SearchIndex.definition(name)
+      return index ? info(index) : undefined
+    },
+    async rebuild(name) {
+      const index = SearchIndex.definition(name)
+      if (!index) return false
+      await search.rebuild(index)
+      onQueued?.()
+      return true
+    },
+    searchers: () => SEARCH_INDEXES.map((index) => index.searcherName),
+    async query(searcherName, term, paging) {
+      const index = SearchIndex.bySearcher(searcherName)
+      return index ? search.query(index, term, paging) : undefined
+    },
+  }
+}

package/src/config.ts

@@ -161,6 +161,8 @@ export interface CromboloConfig {
     keepAllVersionsNewerThanDays: number
     keepLatestVersionPerDayForDays: number
   }
+  /** How many days the audit log keeps an entry; 0 keeps them forever. docs/audit-log.md. */
+  auditRetentionDays: number
   /** Where uploaded media files live; served at `/media/`. */
   mediaDir: string
   /**
@@ -317,6 +319,7 @@ export const DEFAULTS = {
   npmRegistry: 'https://registry.npmjs.org',
   keepAllVersionsNewerThanDays: 7,
   keepLatestVersionPerDayForDays: 90,
+  auditRetentionDays: 365,
   memberRegistrationType: 'Member',
   memberSessionMinutes: 60 * 24 * 14,
   maxFailedPasswordAttempts: 5,
@@ -440,6 +443,10 @@ export function loadConfig(
           DEFAULTS.keepLatestVersionPerDayForDays,
       ),
     },
+    auditRetentionDays: nonNegative(
+      Bun.env.CROMBOLO_AUDIT_RETENTION_DAYS,
+      DEFAULTS.auditRetentionDays,
+    ),
     mediaDir: Bun.env.CROMBOLO_MEDIA_DIR ?? DEFAULTS.mediaDir,
     mediaStore: undefined,
     logsDir: Bun.env.CROMBOLO_LOGS_DIR ?? DEFAULTS.logsDir,
@@ -518,6 +525,12 @@ export function loadConfig(
 }
 
 /** `true`/`false` from the environment; undefined when unset, so a default applies. */
+/** A whole number of at least 0; anything else falls back, rather than ageing the log out by accident. */
+function nonNegative(value: string | undefined, fallback: number): number {
+  const parsed = value === undefined ? Number.NaN : Number(value)
+  return Number.isInteger(parsed) && parsed >= 0 ? parsed : fallback
+}
+
 function envFlag(value: string | undefined): boolean | undefined {
   return value === undefined ? undefined : value !== 'false'
 }
@@ -553,4 +566,4 @@ export function describeDatabase(
   }
 }
 
-export const VERSION = '0.10.0'
+export const VERSION = '0.11.0'

package/src/index.ts

@@ -1,3 +1,4 @@
+export * from './adapters/audit.ts'
 export * from './adapters/blueprints.ts'
 export * from './adapters/bundles.ts'
 export * from './adapters/content.ts'

package/src/jobs.ts

@@ -1,13 +1,21 @@
 /**
  * Background jobs, as Umbraco runs them: scheduled publishing every minute and
- * version cleanup every hour when it is enabled. Each run can also be called directly, which is
+ * version cleanup every hour when it is enabled, plus the search indexer
+ * draining its queue and the audit log ageing out old entries hourly. Each run can also be called directly, which is
  * how tests drive them. On a multi-node Postgres site every node runs them;
- * each schedule is claimed atomically, so it runs once.
+ * each schedule and queued item is claimed atomically, so it runs once.
  */
 
 import type { NodeSchemaState } from '@crombolo/data'
-import { type Db, DocumentRepository, PublishBlockedError } from '@crombolo/data'
+import {
+  AuditLog,
+  type Db,
+  DocumentRepository,
+  PublishBlockedError,
+  SearchIndex,
+} from '@crombolo/data'
 import type { PublishedCache } from '@crombolo/render'
+import { auditRetainedSince, recordAudit } from './adapters/audit.ts'
 import type { WorkflowRunner, WorkflowRunReport } from './form-workflows.ts'
 import { logger } from './logging.ts'
 import type { MediaFileStore } from './media-files.ts'
@@ -33,6 +41,10 @@ export interface JobsOptions {
    */
   formWorkflows?: WorkflowRunner
   formWorkflowsMs?: number
+  /** How often the search indexer looks for queued items; a write here also starts it at once. */
+  searchIndexingMs?: number
+  /** Days the audit log keeps an entry; 0 or absent keeps them forever. */
+  auditRetentionDays?: number
 }
 
 export interface ScheduledRun {
@@ -45,6 +57,12 @@ export interface BackgroundJobs {
   runScheduledPublishing(now?: Date): Promise<ScheduledRun>
   /** Runs the form workflows that are due; a no-op when none are configured. */
   runFormWorkflows(now?: Date): Promise<WorkflowRunReport>
+  /** Indexes every queued item, and returns how many. docs/search.md. */
+  runSearchIndexing(): Promise<number>
+  /** Something was queued here: index it shortly, rather than at the next tick. */
+  kickSearchIndexing(): void
+  /** Deletes audit entries older than the retention period, and returns how many. */
+  runAuditRetention(now?: Date): Promise<number>
   /** Runs whether or not the hourly job is enabled; the policy decides what goes. */
   runVersionCleanup(now?: Date): Promise<{ nodes: number; versionsDeleted: number }>
   start(): void
@@ -60,6 +78,9 @@ export function createBackgroundJobs(options: JobsOptions): BackgroundJobs {
   })
   const timers: Array<ReturnType<typeof setInterval>> = []
   let running = false
+  const search = new SearchIndex(options.db)
+  let indexing: Promise<number> | undefined
+  let kicked: ReturnType<typeof setTimeout> | undefined
 
   async function runScheduledPublishing(now = new Date()): Promise<ScheduledRun> {
     const run: ScheduledRun = { published: [], unpublished: [], failed: [] }
@@ -67,13 +88,20 @@ export function createBackgroundJobs(options: JobsOptions): BackgroundJobs {
       if (!(await documents.claimSchedule(due.id))) continue
       const cultures = due.culture ? [due.culture] : null
       try {
-        if (due.action === 'Release') {
-          await documents.publish(due.key, cultures)
-          run.published.push(due.key)
-        } else {
-          await documents.unpublish(due.key, cultures)
-          run.unpublished.push(due.key)
-        }
+        const release = due.action === 'Release'
+        const changed = release
+          ? await documents.publish(due.key, cultures)
+          : await documents.unpublish(due.key, cultures)
+        ;(release ? run.published : run.unpublished).push(due.key)
+        await recordAudit(options.db, {
+          category: 'content',
+          action: release ? 'Publish' : 'Unpublish',
+          source: 'job',
+          entityType: 'Document',
+          entityKey: due.key,
+          entityName: changed?.variants[0]?.name ?? null,
+          detail: `Scheduled${due.culture ? ` (${due.culture})` : ''}`,
+        })
         options.onDocumentChanged?.(due.key)
       } catch (error) {
         if (!(error instanceof PublishBlockedError)) throw error
@@ -84,6 +112,11 @@ export function createBackgroundJobs(options: JobsOptions): BackgroundJobs {
     return run
   }
 
+  async function runAuditRetention(now = new Date()): Promise<number> {
+    const before = auditRetainedSince(options.auditRetentionDays ?? 0, now)
+    return before ? new AuditLog(options.db).prune(before) : 0
+  }
+
   async function runVersionCleanup(now = new Date()) {
     return documents.cleanupVersions(now, options.versionCleanup)
   }
@@ -99,6 +132,20 @@ export function createBackgroundJobs(options: JobsOptions): BackgroundJobs {
     )
   }
 
+  // Its own guard rather than `guarded`: indexing a big rebuild must not hold up
+  // a scheduled publish, and a kick while it runs joins the run in progress.
+  function runSearchIndexing(): Promise<number> {
+    indexing ??= search.indexAll().finally(() => {
+      indexing = undefined
+    })
+    return indexing
+  }
+
+  const indexQuietly = () =>
+    runSearchIndexing().catch((error: unknown) => {
+      logger('jobs').error('Search indexing failed', { error })
+    })
+
   const guarded = (job: () => Promise<unknown>) => async () => {
     if (running) return
     running = true
@@ -120,18 +167,35 @@ export function createBackgroundJobs(options: JobsOptions): BackgroundJobs {
   return {
     runScheduledPublishing,
     runVersionCleanup,
+    runAuditRetention,
     runFormWorkflows,
+    runSearchIndexing,
+    kickSearchIndexing() {
+      if (timers.length === 0 || kicked) return
+      kicked = setTimeout(() => {
+        kicked = undefined
+        void indexQuietly()
+      }, 250)
+      kicked.unref()
+    },
     start() {
       every(options.scheduledPublishingMs ?? 60_000, runScheduledPublishing)
+      // The queue is shared, so this also picks up what other nodes wrote.
+      const searchTimer = setInterval(indexQuietly, options.searchIndexingMs ?? 5_000)
+      searchTimer.unref()
+      timers.push(searchTimer)
       // More often than the other jobs: somebody waiting on a form notification
       // notices a minute, and a queue row is cheap to look for.
       if (options.formWorkflows) every(options.formWorkflowsMs ?? 15_000, runFormWorkflows)
       if (options.versionCleanup.enabled) every(60 * 60_000, runVersionCleanup)
+      if (options.auditRetentionDays) every(60 * 60_000, runAuditRetention)
       const files = options.mediaFiles
       if (files) every(60 * 60_000, () => files.cleanupExpired())
     },
     stop() {
       for (const timer of timers.splice(0)) clearInterval(timer)
+      if (kicked) clearTimeout(kicked)
+      kicked = undefined
     },
     started() {
       return timers.length > 0

package/src/ports.ts

@@ -35,6 +35,7 @@ import {
 } from '@crombolo/data'
 import type { PublishedCache } from '@crombolo/render'
 import { createNodeLookup } from './access.ts'
+import { createAuditHistory } from './adapters/audit.ts'
 import { createBlueprintPort } from './adapters/blueprints.ts'
 import { createPackagePort } from './adapters/bundles.ts'
 import {
@@ -58,6 +59,7 @@ import {
   type SchemaFiles,
   type SchemaFileWriter,
 } from './adapters/schema-files.ts'
+import { createSearchIndexPort } from './adapters/search-index.ts'
 import { createTemplateFileStore } from './adapters/template-files.ts'
 import { createTemplateQueryPort } from './adapters/template-query.ts'
 import { avatarUrls, createUserPorts } from './adapters/users.ts'
@@ -374,6 +376,8 @@ export interface DepsOptions {
    * tells the other nodes to look; without it they keep the view they imported.
    */
   onViewsChange?: (alias: string) => void | Promise<void>
+  /** Items were queued for the search index; the indexer can start on them now. */
+  onSearchQueued?: () => void
 }
 
 function createTemporaryFilePort(files: MediaFileStore): TemporaryFilePort {
@@ -514,12 +518,14 @@ export function createDeps(options: DepsOptions): ManagementApiDeps {
       stylesheets: deps.stylesheets,
       scripts: deps.scripts,
     })
+    deps.auditHistory = createAuditHistory(options.db, options.config.auditRetentionDays)
     if (options.cache) {
       const cache = options.cache
       deps.templateQuery = createTemplateQueryPort({
         cache,
         types: new ContentTypeRepository(options.db),
       })
+      deps.searchIndex = createSearchIndexPort(options.db, options.onSearchQueued)
       deps.publishedCache = {
         reload: () => cache.invalidate(),
         rebuild: async () => {

package/src/server.ts

@@ -7,7 +7,12 @@
  */
 
 import { join } from 'node:path'
-import { createManagementApiRouter, hasSection, type Principal } from '@crombolo/api-management'
+import {
+  type ClientAddress,
+  createManagementApiRouter,
+  hasSection,
+  type Principal,
+} from '@crombolo/api-management'
 import {
   AuthService,
   AuthStore,
@@ -65,6 +70,7 @@ import {
 import type { SyncReport } from '@crombolo/schema'
 import type { Server } from 'bun'
 import { createNodeLookup, loadAccess } from './access.ts'
+import { createAuditHost, createAuditSink, pluginAuditPlan, recordAudit } from './adapters/audit.ts'
 import { readCreatedBundlePackage, writeCreatedBundlePackage } from './adapters/bundles.ts'
 import { createPublishedContentSource, loadDraftNode } from './adapters/documents.ts'
 import { createSchemaProposals } from './adapters/schema-proposals.ts'
@@ -270,10 +276,30 @@ export async function createServer(config: CromboloConfig = loadConfig()): Promi
   const auth = new AuthService(new AuthStore(db))
   const cookies = { siteName: config.siteName, securePrefix: config.secureCookies }
   const names = cookieNames(cookies)
+  // The socket's peer for each request in flight, which only `Bun.serve` knows;
+  // a request that came some other way (a test, the assistant) has none.
+  const peers = new WeakMap<Request, string>()
+  const clientAddress = (request: Request): ClientAddress => ({
+    ipAddress: peers.get(request) ?? null,
+    forwardedFor: request.headers.get('x-forwarded-for'),
+  })
   const authRoutes = createAuthRoutes({
     backOfficePath: paths.backOfficePath,
     service: auth,
     cookies,
+    onAudit: (event, request) =>
+      recordAudit(db, {
+        category: 'sign-in',
+        action: event.action,
+        source: 'request',
+        userKey: event.user?.key ?? null,
+        userName: event.user?.userName ?? event.login ?? null,
+        entityType: event.user ? 'User' : null,
+        entityKey: event.user?.key ?? null,
+        entityName: event.user?.userName ?? null,
+        detail: event.detail ?? null,
+        ...clientAddress(request),
+      }),
   })
 
   /**
@@ -535,6 +561,7 @@ export async function createServer(config: CromboloConfig = loadConfig()): Promi
         schema,
         mediaFiles,
         email,
+        onSearchQueued: () => jobs.kickSearchIndexing(),
         // This node looks again at once; the others are told to. The write has
         // already landed wherever `componentsDir` points, so there is nothing to
         // distribute — only the fact that it happened.
@@ -557,11 +584,15 @@ export async function createServer(config: CromboloConfig = loadConfig()): Promi
     authenticate,
     nodes: createNodeLookup(db),
     allowLocalLogin: config.allowLocalLogin,
+    audit: createAuditSink(db),
+    clientAddress,
     onNotImplemented: config.development
       ? (operation, request) => notImplemented.record(operation, request)
       : undefined,
     onServerEvent: (event) => {
       events.broadcast('notify', [event])
+      // Saves, deletes and moves all announce themselves; whatever they queued gets indexed now.
+      jobs.kickSearchIndexing()
       // An open preview of the document reloads when it changes.
       if (event.eventSource === 'Umbraco:CMS:Document' && event.eventType !== 'Deleted')
         previewHub.broadcast('refreshed', [event.key])
@@ -606,6 +637,7 @@ export async function createServer(config: CromboloConfig = loadConfig()): Promi
     nodeState: schema.nodeState,
     nodeId: schema.nodeId,
     versionCleanup: config.versionCleanup,
+    auditRetentionDays: config.auditRetentionDays,
     mediaFiles,
     // The workflow queue drains here rather than in the request: a submission is
     // stored first, and an e-mail that cannot be sent yet must not cost it.
@@ -680,6 +712,9 @@ export async function createServer(config: CromboloConfig = loadConfig()): Promi
 
   // Imported only when configured, like the assistant: an unconfigured site has no
   // git route and no credentials anywhere near it.
+  const auditPath = `${paths.pluginPath}/api/audit`
+  const auditHost = createAuditHost(db, config.auditRetentionDays)
+
   const gitPath = `${paths.pluginPath}/api/git`
   const git =
     config.git && servesBackOffice
@@ -714,7 +749,10 @@ export async function createServer(config: CromboloConfig = loadConfig()): Promi
     // there — they are not routes at all, and 404 like any other unknown path.
     if (servesBackOffice) {
       const response = await serveBackOffice(request, url)
-      if (response) return response
+      if (response) {
+        if (response.ok) await auditPluginWrite(request, pathname)
+        return response
+      }
     }
 
     if (pathname.startsWith(`${MEMBER_ROUTE_PREFIX}/`)) {
@@ -749,6 +787,27 @@ export async function createServer(config: CromboloConfig = loadConfig()): Promi
     return renderSite(request, pathname, url.host)
   }
 
+  /**
+   * The audit entry for a successful write to one of Crombolo's own endpoints,
+   * which the contract router does not see. The assistant's are left out: what it
+   * changes goes through the router, and is recorded there. docs/audit-log.md.
+   */
+  async function auditPluginWrite(request: Request, pathname: string): Promise<void> {
+    const prefix = `${paths.pluginPath}/api/`
+    if (request.method === 'GET' || request.method === 'HEAD') return
+    if (!pathname.startsWith(prefix) || pathname.startsWith(`${assistantPath}/`)) return
+    const principal = await authenticate(request)
+    if (!principal) return
+    const plan = pluginAuditPlan(request.method, pathname.slice(prefix.length))
+    await recordAudit(db, {
+      ...plan,
+      source: 'request',
+      userKey: principal.id,
+      userName: principal.name,
+      ...clientAddress(request),
+    })
+  }
+
   /**
    * The backoffice, the Management API and everything that serves an editor.
    *
@@ -1166,6 +1225,16 @@ export async function createServer(config: CromboloConfig = loadConfig()): Promi
     // and no explanation. The findings name documents and the properties that are
     // unfilled: that is the Settings dashboard's material, and the dashboard's own
     // manifest is already `Umb.Condition.SectionAlias` on Settings.
+    // Non-contract, Settings: the audit log dashboard's reads. Settings, as the
+    // dashboard is: it names who signed in from where, and every change made.
+    if (pathname === auditPath || pathname.startsWith(`${auditPath}/`)) {
+      const principal = await authenticate(request)
+      if (!principal) return new Response('Unauthorized', { status: 401 })
+      if (!hasSection(principal, 'settings')) return new Response('Forbidden', { status: 403 })
+      const response = await auditHost.handle(request, pathname.slice(auditPath.length))
+      if (response) return response
+    }
+
     if (pathname === `${paths.pluginPath}/api/change-report`) {
       const principal = await authenticate(request)
       if (!principal) return new Response('Unauthorized', { status: 401 })
@@ -1605,6 +1674,8 @@ export async function createServer(config: CromboloConfig = loadConfig()): Promi
       port: config.port,
       maxRequestBodySize: config.maxRequestBodyBytes,
       fetch: diagnostics.wrap(async (request, bunServer: Server<HubSocketData>) => {
+        const peer = bunServer.requestIP(request)?.address
+        if (peer) peers.set(request, peer)
         const pathname = new URL(request.url).pathname
         if (pathname === hubPath || pathname === previewHubPath) {
           const principal = await authenticate(request)