@crombolo/api-management 0.10.0 → 0.12.1

package/src/router.ts

@@ -3,6 +3,7 @@
  * so a path that is not in the contract cannot be served, and an operation in
  * the contract without a handler answers 501 rather than 404.
  */
+
 import { type HttpMethod, listOperations, loadSpec, type OperationInfo } from '@crombolo/contracts'
 import {
   applyNotifications,
@@ -14,8 +15,18 @@ 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'
+import { type RaisedWebhookEvent, webhookEventFor } from './webhook-events.ts'
 
 /**
  * Resolved back-office identity, assembled from a reference token plus the
@@ -75,8 +86,28 @@ 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
+  /** Answers an error a handler threw; undefined lets it propagate. */
+  onError?: (error: unknown) => Response | undefined
+  /** Told about every webhook event a successful operation raises. */
+  onWebhookEvent?: (event: RaisedWebhookEvent) => void
 }
 
+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 +126,10 @@ export class ManagementApiRouter {
   readonly #onServerEvent: RouterOptions['onServerEvent']
   readonly #nodes: NodeLookup | undefined
   readonly #allowLocalLogin: boolean
+  readonly #audit: AuditSink | undefined
+  readonly #clientAddress: (request: Request) => ClientAddress
+  readonly #onError: RouterOptions['onError']
+  readonly #onWebhookEvent: RouterOptions['onWebhookEvent']
 
   constructor(options: RouterOptions = {}) {
     const operations = options.operations ?? listOperations(loadSpec())
@@ -104,6 +139,10 @@ 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
+    this.#onError = options.onError
+    this.#onWebhookEvent = options.onWebhookEvent
     for (const operation of operations) {
       const segments = operation.path.split('/').filter((s) => s.length > 0)
       const paramNames = segments.map((s) =>
@@ -201,16 +240,106 @@ 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 })
+      ? await this.#run(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)
     }
+    if (handler && this.#onWebhookEvent) {
+      const event = webhookEventFor(operation.operationId, params, response)
+      if (event) this.#onWebhookEvent(event)
+    }
     const headers = new Headers(response.headers)
     applyNotifications(headers, request.method, notifications)
     headers.set('cache-control', 'no-store')
     return new Response(response.body, { status: response.status, headers })
   }
+
+  async #run(handler: OperationHandler, ctx: RequestContext): Promise<Response> {
+    try {
+      return await handler(ctx)
+    } catch (error) {
+      const answered = this.#onError?.(error)
+      if (answered) return answered
+      throw error
+    }
+  }
+
+  /** 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,11 +2,17 @@
  * 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 {
+  registerDiagnosticsHandlers,
+  registerTelemetryAndProfilingHandlers,
+} from './handlers/diagnostics.ts'
 import { registerDictionaryHandlers } from './handlers/dictionary.ts'
 import { registerDocumentHandlers } from './handlers/document.ts'
 import { registerDocumentBlueprintHandlers } from './handlers/document-blueprint.ts'
+import { registerDynamicRootHandlers } from './handlers/dynamic-root.ts'
 import { registerEditorServiceHandlers } from './handlers/editor-services.ts'
 import { registerElementHandlers } from './handlers/element.ts'
 import { registerFileSystemHandlers } from './handlers/file-systems.ts'
@@ -22,13 +28,21 @@ import { registerPackageHandlers } from './handlers/package.ts'
 import { registerPublicAccessHandlers } from './handlers/public-access.ts'
 import { registerPublishedCacheHandlers } from './handlers/published-cache.ts'
 import { registerRedirectHandlers } from './handlers/redirects.ts'
+import { registerReferenceDataHandlers } from './handlers/reference-data.ts'
 import { registerReferenceHandlers } from './handlers/references.ts'
+import {
+  registerRecycleBinReferenceHandlers,
+  registerRelationHandlers,
+} from './handlers/relations.ts'
+import { registerSearchIndexHandlers } from './handlers/search-index.ts'
 import { registerServerHandlers } from './handlers/server.ts'
 import { registerSettingsStubHandlers } from './handlers/settings-stubs.ts'
+import { createStaticFiles, registerStaticFileHandlers } from './handlers/static-files.ts'
 import { registerTemplateHandlers } from './handlers/template.ts'
 import { registerTemplateQueryHandlers } from './handlers/template-query.ts'
 import { registerTemporaryFileHandlers } from './handlers/temporary-file.ts'
 import { registerUserHandlers } from './handlers/user.ts'
+import { registerWebhookHandlers } from './handlers/webhook.ts'
 import type { ManagementApiDeps } from './ports.ts'
 import { type Authenticator, ManagementApiRouter, type RouterOptions } from './router.ts'
 
@@ -39,6 +53,10 @@ export interface ManagementApiOptions {
   onServerEvent?: RouterOptions['onServerEvent']
   nodes?: RouterOptions['nodes']
   allowLocalLogin?: boolean
+  audit?: RouterOptions['audit']
+  clientAddress?: RouterOptions['clientAddress']
+  onError?: RouterOptions['onError']
+  onWebhookEvent?: RouterOptions['onWebhookEvent']
 }
 
 export function createManagementApiRouter(options: ManagementApiOptions = {}): ManagementApiRouter {
@@ -48,6 +66,10 @@ export function createManagementApiRouter(options: ManagementApiOptions = {}): M
     onServerEvent: options.onServerEvent,
     nodes: options.nodes,
     allowLocalLogin: options.allowLocalLogin,
+    audit: options.audit,
+    clientAddress: options.clientAddress,
+    onError: options.onError,
+    onWebhookEvent: options.onWebhookEvent,
   })
   const { deps } = options
   if (!deps) return router
@@ -61,6 +83,10 @@ export function createManagementApiRouter(options: ManagementApiOptions = {}): M
     userData: deps.userData,
   })
   registerSettingsStubHandlers(router)
+  registerTelemetryAndProfilingHandlers(router)
+  registerReferenceDataHandlers(router)
+  if (deps.dynamicRoots) registerDynamicRootHandlers(router, deps.dynamicRoots)
+  if (deps.diagnostics) registerDiagnosticsHandlers(router, deps.diagnostics)
   if (deps.contentTypes)
     registerContentTypeHandlers(router, deps.contentTypes, 'document', deps.temporaryFiles)
   if (deps.mediaTypes)
@@ -81,19 +107,39 @@ export function createManagementApiRouter(options: ManagementApiOptions = {}): M
     registerFileSystemHandlers(router, 'PartialView', deps.components, deps.componentSnippets)
   if (deps.stylesheets) registerFileSystemHandlers(router, 'Stylesheet', deps.stylesheets)
   if (deps.scripts) registerFileSystemHandlers(router, 'Script', deps.scripts)
+  if (deps.stylesheets && deps.scripts)
+    registerStaticFileHandlers(
+      router,
+      createStaticFiles({ css: deps.stylesheets, scripts: deps.scripts }),
+    )
   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)
+  if (deps.references) {
     for (const area of ['Document', 'Media', 'Member', 'Element'] as const)
       registerReferenceHandlers(router, area, deps.references)
+    registerRecycleBinReferenceHandlers(router, deps.references)
+  }
+  if (deps.relations) registerRelationHandlers(router, deps.relations)
+  if (deps.webhooks) registerWebhookHandlers(router, deps.webhooks)
   registerEditorServiceHandlers(router, { tags: deps.tags, oembed: deps.oembed })
   return router
 }

package/src/webhook-events.ts

@@ -0,0 +1,74 @@
+/**
+ * The webhook events this site raises, and which Management API operation
+ * raises each. Aliases are Umbraco's, so the backoffice's event picker and an
+ * imported site's choices mean the same thing. docs/webhooks.md.
+ */
+
+export type WebhookEventType = 'Content' | 'Media'
+
+export interface WebhookEventInfo {
+  alias: string
+  eventName: string
+  eventType: WebhookEventType
+}
+
+export const WEBHOOK_EVENTS: readonly WebhookEventInfo[] = [
+  { alias: 'Umbraco.ContentSaved', eventName: 'Content Saved', eventType: 'Content' },
+  { alias: 'Umbraco.ContentPublish', eventName: 'Content Published', eventType: 'Content' },
+  { alias: 'Umbraco.ContentUnpublish', eventName: 'Content Unpublished', eventType: 'Content' },
+  { alias: 'Umbraco.ContentDelete', eventName: 'Content Deleted', eventType: 'Content' },
+  {
+    alias: 'Umbraco.ContentMovedToRecycleBin',
+    eventName: 'Content Moved to Recycle Bin',
+    eventType: 'Content',
+  },
+  { alias: 'Umbraco.ContentMoved', eventName: 'Content Moved', eventType: 'Content' },
+  { alias: 'Umbraco.ContentCopied', eventName: 'Content Copied', eventType: 'Content' },
+  { alias: 'Umbraco.MediaSave', eventName: 'Media Saved', eventType: 'Media' },
+  { alias: 'Umbraco.MediaDelete', eventName: 'Media Deleted', eventType: 'Media' },
+]
+
+export const WEBHOOK_EVENT_ALIASES: ReadonlySet<string> = new Set(
+  WEBHOOK_EVENTS.map((event) => event.alias),
+)
+
+/** Something happened to one item: what, and to which. */
+export interface RaisedWebhookEvent {
+  alias: string
+  key: string
+}
+
+const BY_OPERATION: Record<string, string> = {
+  PostDocument: 'Umbraco.ContentSaved',
+  PutDocumentById: 'Umbraco.ContentSaved',
+  PutDocumentByIdPublish: 'Umbraco.ContentPublish',
+  PutDocumentByIdPublishWithDescendants: 'Umbraco.ContentPublish',
+  PostDocumentCreateAndPublish: 'Umbraco.ContentPublish',
+  PutDocumentByIdUpdateAndPublish: 'Umbraco.ContentPublish',
+  PutDocumentByIdUnpublish: 'Umbraco.ContentUnpublish',
+  DeleteDocumentById: 'Umbraco.ContentDelete',
+  DeleteRecycleBinDocumentById: 'Umbraco.ContentDelete',
+  PutDocumentByIdMoveToRecycleBin: 'Umbraco.ContentMovedToRecycleBin',
+  PutDocumentByIdMove: 'Umbraco.ContentMoved',
+  PostDocumentByIdCopy: 'Umbraco.ContentCopied',
+  PostMedia: 'Umbraco.MediaSave',
+  PutMediaById: 'Umbraco.MediaSave',
+  DeleteMediaById: 'Umbraco.MediaDelete',
+  DeleteRecycleBinMediaById: 'Umbraco.MediaDelete',
+}
+
+/**
+ * The event a successful operation raises, if any. Pure. The item is the one
+ * the operation created (its generated-resource header) or the one it names.
+ */
+export function webhookEventFor(
+  operationId: string,
+  params: Readonly<Record<string, string>>,
+  response: Pick<Response, 'status' | 'headers'>,
+): RaisedWebhookEvent | undefined {
+  if (response.status < 200 || response.status >= 300) return undefined
+  const alias = BY_OPERATION[operationId]
+  if (!alias) return undefined
+  const key = response.headers.get('umb-generated-resource') ?? params.id
+  return key ? { alias, key: key.toLowerCase() } : undefined
+}