@crombolo/api-management 0.10.0 → 0.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crombolo/api-management",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Umbraco-compatible Management API handlers for crombolo.",
   "license": "MIT",
   "author": "Crombolo",
@@ -28,7 +28,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@crombolo/core": "0.10.0",
-    "@crombolo/contracts": "0.10.0"
+    "@crombolo/core": "0.11.0",
+    "@crombolo/contracts": "0.11.0"
   }
 }

package/src/audit.ts

@@ -0,0 +1,430 @@
+/**
+ * What each backoffice change writes to the audit log. Derived from the
+ * operation's name, as server events are, with the exceptions listed; every
+ * contract operation that changes something is either mapped here or listed as
+ * not a change, and a test holds that to the whole contract. docs/audit-log.md.
+ */
+export type AuditCategory =
+  | 'content'
+  | 'media'
+  | 'member'
+  | 'schema'
+  | 'settings'
+  | 'user'
+  | 'permission'
+  | 'sign-in'
+  | 'system'
+
+export interface AuditPlan {
+  category: AuditCategory
+  entityType: string
+  action: string
+  /** Where the item's key is: a path parameter, the created resource, or the request body. */
+  key: 'param' | 'generated' | 'none' | ((body: unknown) => string[])
+  /** Other items the change names in its body, listed in the entry's detail: a group's users. */
+  related?: { entityType: string; label: string; keys: (body: unknown) => string[] }
+}
+
+/** One entry the router is about to write, before the item is named. */
+export interface AuditDraft {
+  category: AuditCategory
+  action: string
+  entityType: string
+  entityKey: string | null
+  detail?: string | null
+}
+
+export interface AuditRecord extends AuditDraft {
+  entityName: string | null
+  userKey: string | null
+  userName: string | null
+  ipAddress: string | null
+  forwardedFor: string | null
+}
+
+/** Where the router writes. The server adapts the data layer's `AuditLog` to this. */
+export interface AuditSink {
+  /** Names an item, re-keying it when it belongs to another (a version to its page). */
+  describe(
+    entityType: string,
+    key: string,
+  ): Promise<{ entityType: string; entityKey: string; entityName: string | null }>
+  record(entries: AuditRecord[]): Promise<void>
+}
+
+/** Writes that change nothing anyone would answer for: checks, previews, a user's own UI state. */
+export const NOT_AUDITED = new Set([
+  'DeletePreview',
+  'DeleteTemporaryFileById',
+  'DeleteUserDataById',
+  'PostDocumentTypeAvailableCompositions',
+  'PostDynamicRootQuery',
+  'PostHealthCheckGroupByNameCheck',
+  'PostInstallValidateDatabase',
+  'PostMediaTypeAvailableCompositions',
+  'PostMemberTypeAvailableCompositions',
+  'PostSecurityForgotPassword',
+  'PostSecurityForgotPasswordVerify',
+  'PostTemplateQueryExecute',
+  'PostTemporaryFile',
+  'PostUpgradeAuthorize',
+  'PostUserData',
+  'PostUserInviteVerify',
+  'PutUserData',
+])
+
+const ids = (field: string) => (body: unknown) => {
+  const list = (body as Record<string, unknown> | null)?.[field]
+  return Array.isArray(list)
+    ? list.map((item) => (item as { id?: unknown })?.id).filter((id) => typeof id === 'string')
+    : []
+}
+
+const listed = (body: unknown) =>
+  Array.isArray(body)
+    ? body.map((item) => (item as { id?: unknown })?.id).filter((id) => typeof id === 'string')
+    : []
+
+const GROUPS = { entityType: 'UserGroup', label: 'Groups', keys: ids('userGroupIds') }
+const USERS = { entityType: 'User', label: 'Users', keys: listed }
+
+const reference = (field: string) => (body: unknown) => {
+  const id = ((body as Record<string, unknown> | null)?.[field] as { id?: unknown } | null)?.id
+  return typeof id === 'string' ? [id] : []
+}
+
+const EXCEPTIONS: Record<string, AuditPlan> = {
+  DeleteUser: { category: 'user', entityType: 'User', action: 'Delete', key: ids('userIds') },
+  PostUserDisable: { category: 'user', entityType: 'User', action: 'Disable', key: ids('userIds') },
+  PostUserEnable: { category: 'user', entityType: 'User', action: 'Enable', key: ids('userIds') },
+  PostUserUnlock: { category: 'user', entityType: 'User', action: 'Unlock', key: ids('userIds') },
+  PostUserInvite: { category: 'user', entityType: 'User', action: 'Invite', key: 'generated' },
+  PostUserInviteResend: {
+    category: 'user',
+    entityType: 'User',
+    action: 'ResendInvite',
+    key: reference('user'),
+  },
+  PostUserInviteCreatePassword: {
+    category: 'user',
+    entityType: 'User',
+    action: 'AcceptInvite',
+    key: reference('user'),
+  },
+  PostSecurityForgotPasswordReset: {
+    category: 'user',
+    entityType: 'User',
+    action: 'ResetPasswordByLink',
+    key: reference('user'),
+  },
+  PostUserSetUserGroups: {
+    category: 'permission',
+    entityType: 'User',
+    action: 'SetUserGroups',
+    key: ids('userIds'),
+    related: GROUPS,
+  },
+  PostUser: {
+    category: 'user',
+    entityType: 'User',
+    action: 'Create',
+    key: 'generated',
+    related: GROUPS,
+  },
+  PutUserById: {
+    category: 'user',
+    entityType: 'User',
+    action: 'Save',
+    key: 'param',
+    related: GROUPS,
+  },
+  PostUserGroupByIdUsers: {
+    category: 'permission',
+    entityType: 'UserGroup',
+    action: 'AddUsers',
+    key: 'param',
+    related: USERS,
+  },
+  DeleteUserGroupByIdUsers: {
+    category: 'permission',
+    entityType: 'UserGroup',
+    action: 'RemoveUsers',
+    key: 'param',
+    related: USERS,
+  },
+  DeleteUserGroup: {
+    category: 'permission',
+    entityType: 'UserGroup',
+    action: 'Delete',
+    key: ids('userGroupIds'),
+  },
+  PutDocumentSort: {
+    category: 'content',
+    entityType: 'Document',
+    action: 'Sort',
+    key: reference('parent'),
+  },
+  PutMediaSort: {
+    category: 'media',
+    entityType: 'Media',
+    action: 'Sort',
+    key: reference('parent'),
+  },
+  PutDocumentRootSortChildren: {
+    category: 'content',
+    entityType: 'Document',
+    action: 'Sort',
+    key: 'none',
+  },
+  PutMediaRootSortChildren: { category: 'media', entityType: 'Media', action: 'Sort', key: 'none' },
+  PutUserCurrentProfile: {
+    category: 'user',
+    entityType: 'User',
+    action: 'SaveProfile',
+    key: 'none',
+  },
+  PostUserCurrentChangePassword: {
+    category: 'user',
+    entityType: 'User',
+    action: 'ChangePassword',
+    key: 'none',
+  },
+  PostUserCurrentAvatar: { category: 'user', entityType: 'User', action: 'SetAvatar', key: 'none' },
+  DeleteUserCurrentAvatar: {
+    category: 'user',
+    entityType: 'User',
+    action: 'RemoveAvatar',
+    key: 'none',
+  },
+  PostUserCurrent2faByProviderName: {
+    category: 'user',
+    entityType: 'User',
+    action: 'EnableTwoFactor',
+    key: 'none',
+  },
+  DeleteUserCurrent2faByProviderName: {
+    category: 'user',
+    entityType: 'User',
+    action: 'DisableTwoFactor',
+    key: 'none',
+  },
+  PostInstallSetup: { category: 'system', entityType: 'Install', action: 'Install', key: 'none' },
+  PostPublishedCacheRebuild: {
+    category: 'system',
+    entityType: 'PublishedCache',
+    action: 'Rebuild',
+    key: 'none',
+  },
+  PostPublishedCacheReload: {
+    category: 'system',
+    entityType: 'PublishedCache',
+    action: 'Reload',
+    key: 'none',
+  },
+  PostModelsBuilderBuild: {
+    category: 'system',
+    entityType: 'ModelsBuilder',
+    action: 'Build',
+    key: 'none',
+  },
+  PostTelemetryLevel: {
+    category: 'settings',
+    entityType: 'Telemetry',
+    action: 'Save',
+    key: 'none',
+  },
+  PutProfilingStatus: {
+    category: 'settings',
+    entityType: 'Profiling',
+    action: 'Save',
+    key: 'none',
+  },
+  PostRedirectManagementStatus: {
+    category: 'settings',
+    entityType: 'RedirectManagement',
+    action: 'SetStatus',
+    key: 'none',
+  },
+  PostHealthCheckExecuteAction: {
+    category: 'system',
+    entityType: 'HealthCheck',
+    action: 'Execute',
+    key: 'none',
+  },
+  PostIndexerByIndexNameRebuild: {
+    category: 'system',
+    entityType: 'Index',
+    action: 'Rebuild',
+    key: 'param',
+  },
+  PostDocumentCreateAndPublish: {
+    category: 'content',
+    entityType: 'Document',
+    action: 'CreateAndPublish',
+    key: 'generated',
+  },
+  PostElementCreateAndPublish: {
+    category: 'content',
+    entityType: 'Element',
+    action: 'CreateAndPublish',
+    key: 'generated',
+  },
+  PostDocumentBlueprintFromDocument: {
+    category: 'content',
+    entityType: 'DocumentBlueprint',
+    action: 'Create',
+    key: 'generated',
+  },
+  PostDictionaryImport: {
+    category: 'settings',
+    entityType: 'DictionaryItem',
+    action: 'Import',
+    key: 'generated',
+  },
+}
+
+/** Operation-name entity prefixes, longest first so `DocumentType` wins over `Document`. */
+const ENTITIES: Array<[string, AuditCategory]> = [
+  ['DocumentBlueprint', 'content'],
+  ['DocumentVersion', 'content'],
+  ['DocumentType', 'schema'],
+  ['Document', 'content'],
+  ['ElementVersion', 'content'],
+  ['Element', 'content'],
+  ['MediaType', 'schema'],
+  ['Media', 'media'],
+  ['MemberGroup', 'member'],
+  ['MemberType', 'schema'],
+  ['Member', 'member'],
+  ['DataType', 'schema'],
+  ['Template', 'schema'],
+  ['PartialView', 'schema'],
+  ['Script', 'schema'],
+  ['Stylesheet', 'schema'],
+  ['Language', 'settings'],
+  ['Dictionary', 'settings'],
+  ['LogViewerSavedSearch', 'settings'],
+  ['RedirectManagement', 'settings'],
+  ['PackageCreated', 'settings'],
+  ['Package', 'system'],
+  ['Webhook', 'settings'],
+  ['UserGroup', 'permission'],
+  ['User', 'user'],
+]
+
+const ENTITY_TYPE: Record<string, string> = {
+  Dictionary: 'DictionaryItem',
+  PackageCreated: 'Package',
+  RedirectManagement: 'Redirect',
+}
+
+/** The part after the item's key, to the action it names; anything else is named as it reads. */
+const SUFFIX_ACTION: Record<string, string> = {
+  Move: 'Move',
+  MoveToRecycleBin: 'Trash',
+  Copy: 'Copy',
+  Publish: 'Publish',
+  Unpublish: 'Unpublish',
+  UpdateAndPublish: 'SaveAndPublish',
+  PublishWithDescendants: 'PublishWithDescendants',
+  SortChildren: 'Sort',
+  Domains: 'AssignDomains',
+  Notifications: 'SetNotifications',
+  Restore: 'Restore',
+  Rollback: 'Rollback',
+  PreventCleanup: 'PreventCleanup',
+  Import: 'Import',
+  Rename: 'Rename',
+  Template: 'CreateTemplate',
+  ChangePassword: 'ChangePassword',
+  ResetPassword: 'ResetPassword',
+  RunMigration: 'RunMigration',
+  Patch: 'Save',
+}
+
+const KEY_SEGMENT = /^By(Id|Path|IsoCode|Name|IndexName)/
+
+const plans = new Map<string, AuditPlan | null>()
+
+/** The audit entry an operation writes when it succeeds, or undefined for one that changes nothing. */
+export function auditPlanFor(operationId: string): AuditPlan | undefined {
+  if (plans.has(operationId)) return plans.get(operationId) ?? undefined
+  const plan = derive(operationId)
+  plans.set(operationId, plan ?? null)
+  return plan
+}
+
+function derive(operationId: string): AuditPlan | undefined {
+  if (NOT_AUDITED.has(operationId) || /Validate$/.test(operationId)) return undefined
+  const exception = EXCEPTIONS[operationId]
+  if (exception) return exception
+  const verb = /^(Post|Put|Delete|Patch)(.+)$/.exec(operationId)
+  if (!verb) return undefined
+  const method = verb[1] as string
+  let rest = verb[2] as string
+  const recycleBin = rest.startsWith('RecycleBin')
+  if (recycleBin) rest = rest.slice('RecycleBin'.length)
+  const found = ENTITIES.find(([name]) => rest.startsWith(name))
+  if (!found) return undefined
+  const [entity, category] = found
+  let after = rest.slice(entity.length)
+  let entityType = ENTITY_TYPE[entity] ?? entity
+  if (after.startsWith('Folder')) {
+    entityType = `${entityType}Folder`
+    after = after.slice('Folder'.length)
+  }
+  const keyed = KEY_SEGMENT.exec(after)
+  if (keyed) after = after.slice(keyed[0].length)
+
+  if (recycleBin && method === 'Delete' && !keyed)
+    return { category, entityType, action: 'EmptyRecycleBin', key: 'none' }
+  if (after === '') {
+    const action = method === 'Post' ? 'Create' : method === 'Delete' ? 'Delete' : 'Save'
+    return { category, entityType, action, key: keyed ? 'param' : 'generated' }
+  }
+  return {
+    category: after === 'PublicAccess' ? 'permission' : category,
+    entityType,
+    action: actionFor(method, after),
+    key: keyed ? 'param' : 'none',
+  }
+}
+
+function actionFor(method: string, after: string): string {
+  const mapped = SUFFIX_ACTION[after]
+  if (mapped) return mapped
+  const add = method === 'Delete' ? 'Remove' : method === 'Post' ? 'Add' : 'Set'
+  if (after === 'PublicAccess') return `${add}PublicAccess`
+  if (after === 'Avatar') return `${add}Avatar`
+  if (after.startsWith('ClientCredentials')) return `${add}ClientCredentials`
+  if (after.startsWith('2fa')) return 'DisableTwoFactor'
+  return `${method}${after}`
+}
+
+/** Whether the router must read the request body for this operation's keys before the handler does. */
+export function auditReadsBody(plan: AuditPlan): boolean {
+  return typeof plan.key === 'function' || plan.related !== undefined
+}
+
+/** Whether the item must be named before the handler runs, because it will be gone after. */
+export function auditNamesFirst(plan: AuditPlan): boolean {
+  return plan.action === 'Delete' || plan.action === 'Trash'
+}
+
+/** The entries for a successful operation, keyed but not yet named. */
+export function auditDrafts(
+  plan: AuditPlan,
+  params: Readonly<Record<string, string>>,
+  response: Response,
+  body: unknown,
+): AuditDraft[] {
+  const base = { category: plan.category, action: plan.action, entityType: plan.entityType }
+  if (typeof plan.key === 'function')
+    return plan.key(body).map((key) => ({ ...base, entityKey: key }))
+  if (plan.key === 'none') return [{ ...base, entityKey: null }]
+  const key =
+    plan.key === 'generated'
+      ? response.headers.get('umb-generated-resource')
+      : (params.id ?? params.path ?? params.isoCode ?? params.name ?? params.indexName)
+  return [{ ...base, entityKey: key ?? null }]
+}

package/src/handlers/audit-log.ts

@@ -0,0 +1,131 @@
+/**
+ * An item's audit log, for the Info tab of pages, media, elements and
+ * blueprints. It answers from the audit log; for the time before the log
+ * began, the item's versions stand in, as they did before there was one.
+ * docs/audit-log.md.
+ */
+import type { DocumentVersionSummary } from '@crombolo/core'
+import { invalidSkipTake, problemResponse } from '@crombolo/core'
+import type { AuditHistoryPort } from '../ports.ts'
+import type { ManagementApiRouter, RequestContext } from '../router.ts'
+import { paging } from './content-type.ts'
+
+interface VersionSource {
+  versions(key: string): Promise<DocumentVersionSummary[]>
+  systemUserKey(): Promise<string | null>
+}
+
+const VERSION_TYPE = {
+  save: 'Save',
+  publish: 'Publish',
+  rollback: 'RollBack',
+  migrate: 'System',
+} as const
+
+/** The Info tab's names for what an entry records; anything else is `Custom`, with the action as its comment. */
+const ACTION_TYPE: Record<string, string> = {
+  Create: 'New',
+  CreateAndPublish: 'Publish',
+  Save: 'Save',
+  Publish: 'Publish',
+  SaveAndPublish: 'Publish',
+  PublishWithDescendants: 'Publish',
+  Unpublish: 'Unpublish',
+  Move: 'Move',
+  Trash: 'Move',
+  Restore: 'Move',
+  Copy: 'Copy',
+  Sort: 'Sort',
+  Delete: 'Delete',
+  AssignDomains: 'AssignDomain',
+  SetPublicAccess: 'PublicAccess',
+  AddPublicAccess: 'PublicAccess',
+  RemovePublicAccess: 'PublicAccess',
+  SetNotifications: 'Notify',
+  Rollback: 'RollBack',
+  PreventCleanup: 'ContentVersionPreventCleanup',
+}
+
+const COMMENT: Record<string, string> = {
+  Trash: 'Moved to the recycle bin',
+  Restore: 'Restored from the recycle bin',
+  PublishWithDescendants: 'Published with its descendants',
+}
+
+interface Line {
+  user: string | null
+  timestamp: Date
+  logType: string
+  comment: string | null
+}
+
+/** The log for one item, paged and filtered as the contract asks. */
+export async function auditLogResponse(
+  ctx: RequestContext,
+  source: VersionSource,
+  history: AuditHistoryPort | undefined,
+): Promise<Response> {
+  const page = paging(ctx)
+  if (!page) return problemResponse(invalidSkipTake())
+  const key = ctx.params.id as string
+  const since = ctx.url.searchParams.get('sinceDate')
+  const sinceTime = since ? Date.parse(since) : Number.NaN
+  const fallbackUser = await source.systemUserKey()
+
+  const started = await history?.startedAt()
+  const retained = history?.retainedSince()
+  const lines: Line[] = (await source.versions(key))
+    .filter((v) => !started || v.versionDate < started)
+    .filter((v) => !retained || v.versionDate >= retained)
+    .map((v) => ({
+      user: v.userKey,
+      timestamp: v.versionDate,
+      logType: VERSION_TYPE[v.kind ?? 'save'],
+      comment: null,
+    }))
+  for (const entry of (await history?.forItem(key)) ?? [])
+    lines.push({
+      user: entry.userKey,
+      timestamp: entry.occurredAt,
+      logType: ACTION_TYPE[entry.action] ?? 'Custom',
+      comment: COMMENT[entry.action] ?? (ACTION_TYPE[entry.action] ? entry.detail : entry.action),
+    })
+
+  let shown = Number.isNaN(sinceTime)
+    ? lines
+    : lines.filter((l) => l.timestamp.getTime() >= sinceTime)
+  shown = shown.sort((a, b) => b.timestamp.getTime() - a.timestamp.getTime())
+  if (ctx.url.searchParams.get('orderDirection') === 'Ascending') shown = shown.reverse()
+  return Response.json({
+    total: shown.length,
+    items: shown.slice(page.skip, page.skip + page.take).map((line) => ({
+      user: { id: line.user ?? fallbackUser },
+      timestamp: line.timestamp.toISOString(),
+      logType: line.logType,
+      comment: line.comment,
+      parameters: null,
+    })),
+  })
+}
+
+export function registerAuditLogHandlers(
+  router: ManagementApiRouter,
+  sources: {
+    documents?: VersionSource
+    media?: VersionSource
+    elements?: VersionSource
+    blueprints?: VersionSource
+  },
+  history: AuditHistoryPort | undefined,
+): void {
+  const { documents, media, elements, blueprints } = sources
+  if (documents)
+    router.handle('GetDocumentByIdAuditLog', (ctx) => auditLogResponse(ctx, documents, history))
+  if (media) router.handle('GetMediaByIdAuditLog', (ctx) => auditLogResponse(ctx, media, history))
+  if (elements)
+    router.handle('GetElementByIdAuditLog', (ctx) => auditLogResponse(ctx, elements, history))
+  if (blueprints)
+    router.handle('GetDocumentBlueprintByIdAuditLog', (ctx) =>
+      auditLogResponse(ctx, blueprints, history),
+    )
+}

package/src/handlers/document-blueprint.ts

@@ -7,7 +7,7 @@ import { invalidSkipTake, notFound, problemDetails, problemResponse } from '@cro
 import type { BlueprintPort, PortFailure } from '../ports-content.ts'
 import type { ManagementApiRouter, RequestContext } from '../router.ts'
 import { created, paging, registerFolderHandlers } from './content-type.ts'
-import { auditLogResponse, readBody, toDocumentResponse, toSaveDocument } from './document.ts'
+import { readBody, toDocumentResponse, toSaveDocument } from './document.ts'
 
 const API = '/umbraco/management/api/v1'
 
@@ -126,8 +126,6 @@ export function registerDocumentBlueprintHandlers(
     return new Response(null, { status: 200 })
   })
 
-  router.handle('GetDocumentBlueprintByIdAuditLog', (ctx) => auditLogResponse(ctx, port))
-
   router.handle('GetDocumentTypeByIdBlueprint', async (ctx) => {
     const page = paging(ctx)
     if (!page) return problemResponse(invalidSkipTake())

package/src/handlers/document.ts

@@ -7,11 +7,12 @@ import type {
   DocumentTreeItem,
   DocumentValidationError,
   DocumentValue,
-  DocumentVersionSummary,
 } from '@crombolo/core'
 import {
+  DocumentPermissions,
   invalidSkipTake,
   notFound,
+  permissionsForPath,
   problemDetails,
   problemResponse,
   ROOT_ACCESS,
@@ -24,6 +25,7 @@ import {
   type TreeSource,
   visibleChildren,
   visibleRoot,
+  visibleSearch,
   visibleSiblings,
 } from './start-node-trees.ts'
 
@@ -385,11 +387,28 @@ export function registerDocumentHandlers(
     const page = paging(ctx)
     if (!page) return problemResponse(invalidSkipTake())
     const query = ctx.url.searchParams.get('query') ?? ''
-    const result = await port.search(query, {
-      ...page,
-      trashed: ctx.url.searchParams.get('trashed') === 'true',
-      parentKey: ctx.url.searchParams.get('parentId'),
-    })
+    const groups = ctx.principal?.groups ?? []
+    // Browse is checked per item only when some group could withhold it somewhere.
+    const browsesEverything =
+      !ctx.principal ||
+      groups.some(
+        (group) =>
+          group.defaults.includes(DocumentPermissions.Read) &&
+          [...group.granular.values()].every((verbs) => verbs.includes(DocumentPermissions.Read)),
+      )
+    const result = await visibleSearch(
+      documentStart(ctx),
+      browsesEverything
+        ? undefined
+        : (chain) => permissionsForPath(groups, chain).has(DocumentPermissions.Read),
+      (paging) =>
+        port.search(query, {
+          ...paging,
+          trashed: ctx.url.searchParams.get('trashed') === 'true',
+          parentKey: ctx.url.searchParams.get('parentId'),
+        }),
+      page,
+    )
     return Response.json({ total: result.total, items: result.items.map(toDocumentItemResponse) })
   })
 
@@ -849,7 +868,6 @@ export function registerDocumentHandlers(
   })
 
   /** The page's history, from its versions: who saved, published or rolled back, and when. */
-  router.handle('GetDocumentByIdAuditLog', (ctx) => auditLogResponse(ctx, port))
 
   router.handle('GetDocumentVersion', async (ctx) => {
     const documentId = ctx.url.searchParams.get('documentId')
@@ -922,40 +940,3 @@ export function registerDocumentHandlers(
     })
   })
 }
-
-const AUDIT_TYPE = {
-  save: 'Save',
-  publish: 'Publish',
-  rollback: 'RollBack',
-  migrate: 'System',
-} as const
-
-/** An audit log built from an item's versions, paged and filtered as the contract asks. */
-export async function auditLogResponse(
-  ctx: RequestContext,
-  port: {
-    versions(key: string): Promise<DocumentVersionSummary[]>
-    systemUserKey(): Promise<string | null>
-  },
-): Promise<Response> {
-  const page = paging(ctx)
-  if (!page) return problemResponse(invalidSkipTake())
-  const since = ctx.url.searchParams.get('sinceDate')
-  const sinceTime = since ? Date.parse(since) : Number.NaN
-  let versions = await port.versions(ctx.params.id as string)
-  if (!Number.isNaN(sinceTime))
-    versions = versions.filter((v) => v.versionDate.getTime() >= sinceTime)
-  if (ctx.url.searchParams.get('orderDirection') === 'Ascending') versions = versions.reverse()
-  const fallbackUser = await port.systemUserKey()
-  const window = versions.slice(page.skip, page.skip + page.take)
-  return Response.json({
-    total: versions.length,
-    items: window.map((version) => ({
-      user: { id: version.userKey ?? fallbackUser },
-      timestamp: version.versionDate.toISOString(),
-      logType: AUDIT_TYPE[version.kind ?? 'save'],
-      comment: null,
-      parameters: null,
-    })),
-  })
-}

package/src/handlers/element.ts

@@ -17,7 +17,7 @@ import { invalidSkipTake, notFound, problemDetails, problemResponse } from '@cro
 import type { ElementPort, PortFailure, ReferencePort } from '../ports-content.ts'
 import type { ManagementApiRouter, RequestContext } from '../router.ts'
 import { created, paging, registerFolderHandlers } from './content-type.ts'
-import { auditLogResponse, failureResponse, readBody, toSaveDocument } from './document.ts'
+import { failureResponse, readBody, toSaveDocument } from './document.ts'
 
 const API = '/umbraco/management/api/v1'
 
@@ -444,7 +444,6 @@ export function registerElementHandlers(
     })
 
   // ── history ───────────────────────────────────────────────────────────────
-  handle('GetElementByIdAuditLog', (ctx) => auditLogResponse(ctx, port))
 
   handle('GetElementVersion', async (ctx) => {
     const elementId = ctx.url.searchParams.get('elementId')

package/src/handlers/media.ts

@@ -13,8 +13,8 @@ import {
 import type { MediaPort, PortFailure } from '../ports-content.ts'
 import type { ManagementApiRouter, RequestContext } from '../router.ts'
 import { created, paging } from './content-type.ts'
-import { auditLogResponse, readBody, toSaveDocument, validationProblem } from './document.ts'
-import { visibleChildren, visibleRoot, visibleSiblings } from './start-node-trees.ts'
+import { readBody, toSaveDocument, validationProblem } from './document.ts'
+import { visibleChildren, visibleRoot, visibleSearch, visibleSiblings } from './start-node-trees.ts'
 
 const API = '/umbraco/management/api/v1'
 
@@ -251,8 +251,6 @@ export function registerMediaHandlers(router: ManagementApiRouter, port: MediaPo
   router.handle('PutMediaByIdSortChildren', (ctx) => sortByField(ctx, ctx.params.id as string))
   router.handle('PutMediaRootSortChildren', (ctx) => sortByField(ctx, null))
 
-  router.handle('GetMediaByIdAuditLog', (ctx) => auditLogResponse(ctx, port))
-
   /** Thumbnail and crop URLs in the query vocabulary the media route understands. */
   router.handle('GetImagingResizeUrls', async (ctx) => {
     const params = new URLSearchParams()
@@ -341,11 +339,17 @@ export function registerMediaHandlers(router: ManagementApiRouter, port: MediaPo
     const page = paging(ctx)
     if (!page) return problemResponse(invalidSkipTake())
     const parentId = ctx.url.searchParams.get('parentId')
-    const result = await port.search(ctx.url.searchParams.get('query') ?? '', {
-      trashed: ctx.url.searchParams.get('trashed') === 'true',
-      parentKey: parentId,
-      ...page,
-    })
+    const result = await visibleSearch(
+      mediaStart(ctx),
+      undefined,
+      (paging) =>
+        port.search(ctx.url.searchParams.get('query') ?? '', {
+          trashed: ctx.url.searchParams.get('trashed') === 'true',
+          parentKey: parentId,
+          ...paging,
+        }),
+      page,
+    )
     return Response.json({ total: result.total, items: result.items.map(toMediaItem) })
   })
 

package/src/handlers/search-index.ts

@@ -0,0 +1,96 @@
+/**
+ * The Examine dashboard: the indexes, their health, rebuilding one, and searching
+ * one directly. An index with items still waiting reports itself rebuilding, which
+ * is what makes the dashboard poll until they are done. docs/search.md.
+ */
+import { invalidSkipTake, problemDetails, problemResponse } from '@crombolo/core'
+import type { SearchIndexInfo, SearchIndexPort } from '../ports.ts'
+import type { ManagementApiRouter } from '../router.ts'
+import { paging } from './content-type.ts'
+
+const waiting = (n: number) => `${n} ${n === 1 ? 'item is' : 'items are'} waiting to be indexed`
+
+function toIndexResponse(index: SearchIndexInfo) {
+  return {
+    name: index.name,
+    healthStatus:
+      index.pending > 0
+        ? { status: 'Rebuilding', message: waiting(index.pending) }
+        : { status: 'Healthy', message: null },
+    canRebuild: true,
+    searcherName: index.searcherName,
+    documentCount: index.documentCount,
+    fieldCount: index.fieldCount,
+    providerProperties: null,
+    uniqueKeyFieldName: '__Key',
+  }
+}
+
+const indexNotFound = (name: string) =>
+  problemResponse(
+    problemDetails({
+      title: 'Index Not Found',
+      detail: `No index found with name = ${name}`,
+      status: 400,
+    }),
+  )
+
+export function registerSearchIndexHandlers(
+  router: ManagementApiRouter,
+  port: SearchIndexPort,
+): void {
+  router.handle('GetIndexer', async (ctx) => {
+    const page = paging(ctx)
+    if (!page) return problemResponse(invalidSkipTake())
+    const indexes = await port.indexes()
+    return Response.json({
+      total: indexes.length,
+      items: indexes.slice(page.skip, page.skip + page.take).map(toIndexResponse),
+    })
+  })
+
+  router.handle('GetIndexerByIndexName', async ({ params }) => {
+    const name = params.indexName as string
+    const index = await port.index(name)
+    return index ? Response.json(toIndexResponse(index)) : indexNotFound(name)
+  })
+
+  router.handle('PostIndexerByIndexNameRebuild', async ({ params }) => {
+    const name = params.indexName as string
+    return (await port.rebuild(name)) ? new Response(null, { status: 200 }) : indexNotFound(name)
+  })
+
+  router.handle('GetSearcher', (ctx) => {
+    const page = paging(ctx)
+    if (!page) return problemResponse(invalidSkipTake())
+    const names = port.searchers()
+    return Response.json({
+      total: names.length,
+      items: names.slice(page.skip, page.skip + page.take).map((name) => ({ name })),
+    })
+  })
+
+  router.handle('GetSearcherBySearcherNameQuery', async (ctx) => {
+    const page = paging(ctx)
+    if (!page) return problemResponse(invalidSkipTake())
+    const name = ctx.params.searcherName as string
+    const result = await port.query(name, ctx.url.searchParams.get('term') ?? '', page)
+    if (!result)
+      return problemResponse(
+        problemDetails({
+          title: 'Searcher Not Found',
+          detail: `No searcher found with name = ${name}`,
+          status: 404,
+        }),
+      )
+    return Response.json({
+      total: result.total,
+      items: result.items.map((hit) => ({
+        id: hit.key,
+        score: hit.score,
+        fieldCount: hit.fields.length,
+        fields: hit.fields,
+      })),
+    })
+  })
+}

package/src/handlers/start-node-trees.ts

@@ -82,3 +82,29 @@ export async function visibleSiblings(
   const visible = await onTheWay(start, source, window.items)
   return { items: visible.items, totalBefore: 0, totalAfter: 0 }
 }
+
+/** How far a filtered search looks before paging: past it, an editor refines the query. */
+const SEARCH_WINDOW = 1_000
+
+/**
+ * A page of search results as a user may see them: under a start node, and
+ * passing `allowed` (Browse, for documents). Unrestricted access pages in the
+ * database; otherwise a window of the best matches is filtered, then paged.
+ */
+export async function visibleSearch(
+  start: StartNodes,
+  allowed: ((chain: readonly string[]) => boolean) | undefined,
+  search: (paging: SkipTake) => Promise<Page<DocumentTreeItem>>,
+  paging: SkipTake,
+): Promise<Page<DocumentTreeItem>> {
+  if (start.root && !allowed) return search(paging)
+  const window = await search({ skip: 0, take: SEARCH_WINDOW })
+  const visible = window.items.filter((item) => {
+    const chain = chainOf(item)
+    return hasPathAccess(start, chain, item.isTrashed) && (allowed?.(chain) ?? true)
+  })
+  return {
+    total: visible.length,
+    items: visible.slice(paging.skip, paging.skip + paging.take),
+  }
+}

package/src/index.ts

@@ -1,3 +1,4 @@
+export * from './audit.ts'
 export * from './authorization.ts'
 export * from './handlers/content-type.ts'
 export * from './handlers/package.ts'

package/src/ports.ts

@@ -111,6 +111,54 @@ export interface PublishedCachePort {
   isRebuilding(): boolean
 }
 
+/** An index as the Examine dashboard lists it. */
+export interface SearchIndexInfo {
+  name: string
+  searcherName: string
+  documentCount: number
+  fieldCount: number
+  /** Items waiting to be indexed; while any are, the index reports itself rebuilding. */
+  pending: number
+}
+
+/** An item's entries in the audit log, for its Info tab. docs/audit-log.md. */
+export interface AuditHistoryPort {
+  forItem(
+    key: string,
+  ): Promise<
+    Array<{ userKey: string | null; occurredAt: Date; action: string; detail: string | null }>
+  >
+  /** When the log began; an item's versions from before then stand in for its entries. */
+  startedAt(): Promise<Date | undefined>
+  /** Entries older than this have been aged out, and versions standing in for them are too. */
+  retainedSince(): Date | undefined
+}
+
+/** The backoffice search index behind the Examine dashboard. docs/search.md. */
+export interface SearchIndexPort {
+  indexes(): Promise<SearchIndexInfo[]>
+  index(name: string): Promise<SearchIndexInfo | undefined>
+  /** False when there is no index by that name. */
+  rebuild(name: string): Promise<boolean>
+  searchers(): string[]
+  /** Undefined when there is no searcher by that name. */
+  query(
+    searcherName: string,
+    term: string,
+    paging: { skip: number; take: number },
+  ): Promise<
+    | {
+        total: number
+        items: Array<{
+          key: string
+          score: number
+          fields: Array<{ name: string; values: string[] }>
+        }>
+      }
+    | undefined
+  >
+}
+
 /** Embed markup for a URL, from its oEmbed provider. */
 export interface OEmbedPort {
   markup(
@@ -213,6 +261,8 @@ export interface ManagementApiDeps {
   logViewer?: LogViewerPort
   modelsBuilder?: ModelsBuilderPort
   publishedCache?: PublishedCachePort
+  searchIndex?: SearchIndexPort
+  auditHistory?: AuditHistoryPort
   /** The template editor's query builder. */
   templateQuery?: TemplateQueryPort
   memberGroups?: MemberGroupPort

package/src/router.ts

@@ -14,6 +14,15 @@ import {
   type StartNodes,
   unauthorized,
 } from '@crombolo/core'
+import {
+  type AuditPlan,
+  type AuditRecord,
+  type AuditSink,
+  auditDrafts,
+  auditNamesFirst,
+  auditPlanFor,
+  auditReadsBody,
+} from './audit.ts'
 import { authorize, LOCAL_LOGIN_OPERATIONS, type NodeLookup } from './authorization.ts'
 import { type ServerEvent, serverEventFor } from './server-events.ts'
 
@@ -75,8 +84,24 @@ export interface RouterOptions {
   nodes?: NodeLookup
   /** Whether users may sign in with a password, which opens the password-reset endpoints to everyone. */
   allowLocalLogin?: boolean
+  /** Where every successful change is recorded. docs/audit-log.md. */
+  audit?: AuditSink
+  /** Where a request came from, for its audit entry. */
+  clientAddress?: (request: Request) => ClientAddress
+}
+
+export interface ClientAddress {
+  /** The peer that connected: a proxy, when there is one. */
+  ipAddress: string | null
+  /** What a proxy said the client was; anyone can send it, so it is kept apart. */
+  forwardedFor: string | null
 }
 
+const forwardedOnly = (request: Request): ClientAddress => ({
+  ipAddress: null,
+  forwardedFor: request.headers.get('x-forwarded-for'),
+})
+
 export type OperationHandler = (ctx: RequestContext) => Response | Promise<Response>
 
 interface CompiledRoute {
@@ -95,6 +120,8 @@ export class ManagementApiRouter {
   readonly #onServerEvent: RouterOptions['onServerEvent']
   readonly #nodes: NodeLookup | undefined
   readonly #allowLocalLogin: boolean
+  readonly #audit: AuditSink | undefined
+  readonly #clientAddress: (request: Request) => ClientAddress
 
   constructor(options: RouterOptions = {}) {
     const operations = options.operations ?? listOperations(loadSpec())
@@ -104,6 +131,8 @@ export class ManagementApiRouter {
     this.#onServerEvent = options.onServerEvent
     this.#nodes = options.nodes
     this.#allowLocalLogin = options.allowLocalLogin ?? true
+    this.#audit = options.audit
+    this.#clientAddress = options.clientAddress ?? forwardedOnly
     for (const operation of operations) {
       const segments = operation.path.split('/').filter((s) => s.length > 0)
       const paramNames = segments.map((s) =>
@@ -201,9 +230,13 @@ export class ManagementApiRouter {
 
     const handler = this.#handlers.get(operation.operationId)
     if (!handler) this.#onNotImplemented?.(operation, request)
+    const plan = handler && this.#audit ? auditPlanFor(operation.operationId) : undefined
+    const audit = plan ? await this.#beforeAudit(plan, params, request) : undefined
     const response = handler
       ? await handler({ request, url, params, operation, notifications, principal })
       : problemResponse(notImplemented(operation.operationId))
+    if (plan && audit && response.status >= 200 && response.status < 300)
+      await this.#recordAudit(plan, audit, params, request, response, principal)
     if (handler && this.#onServerEvent) {
       const event = serverEventFor(operation, params, response)
       if (event) this.#onServerEvent(event)
@@ -213,4 +246,76 @@ export class ManagementApiRouter {
     headers.set('cache-control', 'no-store')
     return new Response(response.body, { status: response.status, headers })
   }
+
+  /** Reads what the entry needs before the handler consumes the body or removes the item. */
+  async #beforeAudit(
+    plan: AuditPlan,
+    params: Readonly<Record<string, string>>,
+    request: Request,
+  ): Promise<AuditState> {
+    const body = auditReadsBody(plan)
+      ? await request
+          .clone()
+          .json()
+          .catch(() => undefined)
+      : undefined
+    const named = new Map<string, Subject>()
+    if (auditNamesFirst(plan) && this.#audit)
+      for (const draft of auditDrafts(plan, params, new Response(), body))
+        if (draft.entityKey)
+          named.set(draft.entityKey, await this.#audit.describe(draft.entityType, draft.entityKey))
+    return { body, named }
+  }
+
+  async #recordAudit(
+    plan: AuditPlan,
+    state: AuditState,
+    params: Readonly<Record<string, string>>,
+    request: Request,
+    response: Response,
+    principal: Principal | undefined,
+  ): Promise<void> {
+    const sink = this.#audit
+    if (!sink) return
+    const address = this.#clientAddress(request)
+    let detail: string | null = null
+    if (plan.related) {
+      const names: string[] = []
+      for (const key of plan.related.keys(state.body))
+        names.push((await sink.describe(plan.related.entityType, key)).entityName ?? key)
+      detail = `${plan.related.label}: ${names.length > 0 ? names.join(', ') : 'none'}`
+    }
+    const records: AuditRecord[] = []
+    for (const draft of auditDrafts(plan, params, response, state.body)) {
+      const key = draft.entityKey ?? (plan.entityType === 'User' ? (principal?.id ?? null) : null)
+      const subject = key
+        ? (state.named.get(key) ?? (await sink.describe(draft.entityType, key)))
+        : undefined
+      // A reset link or an accepted invite is anonymous: the user it names is who acted.
+      const self = !principal && draft.entityType === 'User' && subject
+      records.push({
+        ...draft,
+        entityType: subject?.entityType ?? draft.entityType,
+        entityKey: subject?.entityKey ?? key,
+        entityName: subject?.entityName ?? null,
+        detail,
+        userKey: principal?.id ?? (self ? subject.entityKey : null),
+        userName: principal?.name ?? (self ? subject.entityName : null),
+        ipAddress: address.ipAddress,
+        forwardedFor: address.forwardedFor,
+      })
+    }
+    await sink.record(records)
+  }
+}
+
+interface Subject {
+  entityType: string
+  entityKey: string
+  entityName: string | null
+}
+
+interface AuditState {
+  body: unknown
+  named: Map<string, Subject>
 }

package/src/routes.ts

@@ -2,6 +2,7 @@
  * Composition root for the Management API. Handlers are registered here as they
  * are implemented; every other operation in the contract answers 501.
  */
+import { registerAuditLogHandlers } from './handlers/audit-log.ts'
 import { registerContentTypeHandlers } from './handlers/content-type.ts'
 import { registerDataTypeHandlers } from './handlers/data-type.ts'
 import { registerDictionaryHandlers } from './handlers/dictionary.ts'
@@ -23,6 +24,7 @@ import { registerPublicAccessHandlers } from './handlers/public-access.ts'
 import { registerPublishedCacheHandlers } from './handlers/published-cache.ts'
 import { registerRedirectHandlers } from './handlers/redirects.ts'
 import { registerReferenceHandlers } from './handlers/references.ts'
+import { registerSearchIndexHandlers } from './handlers/search-index.ts'
 import { registerServerHandlers } from './handlers/server.ts'
 import { registerSettingsStubHandlers } from './handlers/settings-stubs.ts'
 import { registerTemplateHandlers } from './handlers/template.ts'
@@ -39,6 +41,8 @@ export interface ManagementApiOptions {
   onServerEvent?: RouterOptions['onServerEvent']
   nodes?: RouterOptions['nodes']
   allowLocalLogin?: boolean
+  audit?: RouterOptions['audit']
+  clientAddress?: RouterOptions['clientAddress']
 }
 
 export function createManagementApiRouter(options: ManagementApiOptions = {}): ManagementApiRouter {
@@ -48,6 +52,8 @@ export function createManagementApiRouter(options: ManagementApiOptions = {}): M
     onServerEvent: options.onServerEvent,
     nodes: options.nodes,
     allowLocalLogin: options.allowLocalLogin,
+    audit: options.audit,
+    clientAddress: options.clientAddress,
   })
   const { deps } = options
   if (!deps) return router
@@ -84,11 +90,22 @@ export function createManagementApiRouter(options: ManagementApiOptions = {}): M
   if (deps.logViewer) registerLogViewerHandlers(router, deps.logViewer)
   if (deps.modelsBuilder) registerModelsBuilderHandlers(router, deps.modelsBuilder)
   if (deps.publishedCache) registerPublishedCacheHandlers(router, deps.publishedCache)
+  if (deps.searchIndex) registerSearchIndexHandlers(router, deps.searchIndex)
   if (deps.temporaryFiles) registerImportHandlers(router, deps.temporaryFiles)
   if (deps.memberGroups) registerMemberGroupHandlers(router, deps.memberGroups)
   if (deps.members) registerMemberHandlers(router, deps.members)
   if (deps.publicAccess) registerPublicAccessHandlers(router, deps.publicAccess)
   if (deps.elements) registerElementHandlers(router, deps.elements, deps.references)
+  registerAuditLogHandlers(
+    router,
+    {
+      documents: deps.documents,
+      media: deps.media,
+      elements: deps.elements,
+      blueprints: deps.blueprints,
+    },
+    deps.auditHistory,
+  )
   if (deps.redirects) registerRedirectHandlers(router, deps.redirects)
   if (deps.packages) registerPackageHandlers(router, deps.packages)
   if (deps.references)