@crombolo/api-management 0.0.0-stage → 0.9.1

package/src/router.ts

@@ -0,0 +1,216 @@
+/**
+ * Contract-first router: every route comes from the vendored OpenAPI document,
+ * 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,
+  type EventMessage,
+  type GroupGrant,
+  notFound,
+  notImplemented,
+  problemResponse,
+  type StartNodes,
+  unauthorized,
+} from '@crombolo/core'
+import { authorize, LOCAL_LOGIN_OPERATIONS, type NodeLookup } from './authorization.ts'
+import { type ServerEvent, serverEventFor } from './server-events.ts'
+
+/**
+ * Resolved back-office identity, assembled from a reference token plus the
+ * user's group membership. Everything needed to authorise a request is here, so
+ * a handler never queries the identity tables itself.
+ */
+export interface Principal {
+  /** The user's key (a uuid), which is what the API exposes as its id. */
+  id: string
+  userName: string
+  name: string
+  email: string
+  isAdmin: boolean
+  languageIsoCode: string | undefined
+  avatarUrls: string[]
+  /** Section manifest aliases, e.g. `Umb.Section.Content`. */
+  allowedSections: string[]
+  /** Permission verbs granted globally by the user's groups. */
+  permissions: string[]
+  groupKeys: string[]
+  hasAccessToAllLanguages: boolean
+  /** Content languages the user may work in; everything when `hasAccessToAllLanguages`. */
+  languages: string[]
+  /** Where the user may work in each tree, groups' and own start nodes combined. */
+  startNodes: { document: StartNodes; media: StartNodes; element: StartNodes }
+  /** Each group's verbs, for per-node permission checks. */
+  groups: GroupGrant[]
+}
+
+export interface RequestContext {
+  request: Request
+  url: URL
+  /** Path parameters, keyed by the name used in the contract. */
+  params: Readonly<Record<string, string>>
+  operation: OperationInfo
+  /** Messages surfaced to the editor through the Umb-Notifications header. */
+  notifications: EventMessage[]
+  /**
+   * Present only when the request authenticated. The router already rejected
+   * unauthenticated requests to secured operations, so a handler for a secured
+   * operation can rely on this being set.
+   */
+  principal: Principal | undefined
+}
+
+export type Authenticator = (request: Request) => Promise<Principal | undefined>
+
+export interface RouterOptions {
+  operations?: readonly OperationInfo[]
+  /** Resolves the caller's identity. Omitted means every request is anonymous. */
+  authenticate?: Authenticator
+  /** Told about every request that reached an operation with no handler. */
+  onNotImplemented?: (operation: OperationInfo, request: Request) => void
+  /** Told about every change a handler made, before its response is sent. */
+  onServerEvent?: (event: ServerEvent) => void
+  /** Node positions for per-node permission checks; without it only section access is enforced. */
+  nodes?: NodeLookup
+  /** Whether users may sign in with a password, which opens the password-reset endpoints to everyone. */
+  allowLocalLogin?: boolean
+}
+
+export type OperationHandler = (ctx: RequestContext) => Response | Promise<Response>
+
+interface CompiledRoute {
+  operation: OperationInfo
+  segments: string[]
+  paramNames: (string | undefined)[]
+  staticCount: number
+}
+
+export class ManagementApiRouter {
+  readonly operations: readonly OperationInfo[]
+  readonly #handlers = new Map<string, OperationHandler>()
+  readonly #byMethodAndLength = new Map<string, CompiledRoute[]>()
+  readonly #authenticate: Authenticator | undefined
+  readonly #onNotImplemented: RouterOptions['onNotImplemented']
+  readonly #onServerEvent: RouterOptions['onServerEvent']
+  readonly #nodes: NodeLookup | undefined
+  readonly #allowLocalLogin: boolean
+
+  constructor(options: RouterOptions = {}) {
+    const operations = options.operations ?? listOperations(loadSpec())
+    this.operations = operations
+    this.#authenticate = options.authenticate
+    this.#onNotImplemented = options.onNotImplemented
+    this.#onServerEvent = options.onServerEvent
+    this.#nodes = options.nodes
+    this.#allowLocalLogin = options.allowLocalLogin ?? true
+    for (const operation of operations) {
+      const segments = operation.path.split('/').filter((s) => s.length > 0)
+      const paramNames = segments.map((s) =>
+        s.startsWith('{') && s.endsWith('}') ? s.slice(1, -1) : undefined,
+      )
+      const route: CompiledRoute = {
+        operation,
+        segments,
+        paramNames,
+        staticCount: paramNames.filter((p) => p === undefined).length,
+      }
+      const key = `${operation.method}:${segments.length}`
+      const bucket = this.#byMethodAndLength.get(key)
+      if (bucket) bucket.push(route)
+      else this.#byMethodAndLength.set(key, [route])
+    }
+    // Prefer the most literal route when several shapes match.
+    for (const bucket of this.#byMethodAndLength.values()) {
+      bucket.sort((a, b) => b.staticCount - a.staticCount)
+    }
+  }
+
+  /** Register the implementation of a contract operation. */
+  handle(operationId: string, handler: OperationHandler): this {
+    if (!this.operations.some((o) => o.operationId === operationId)) {
+      throw new Error(`Unknown operationId '${operationId}' — it is not in the contract.`)
+    }
+    this.#handlers.set(operationId, handler)
+    return this
+  }
+
+  has(operationId: string): boolean {
+    return this.#handlers.has(operationId)
+  }
+
+  get implementedCount(): number {
+    return this.#handlers.size
+  }
+
+  match(
+    method: string,
+    pathname: string,
+  ): { operation: OperationInfo; params: Record<string, string> } | undefined {
+    const segments = pathname.split('/').filter((s) => s.length > 0)
+    const bucket = this.#byMethodAndLength.get(
+      `${method.toLowerCase() as HttpMethod}:${segments.length}`,
+    )
+    if (!bucket) return undefined
+    for (const route of bucket) {
+      const params: Record<string, string> = {}
+      let matched = true
+      for (let i = 0; i < segments.length; i++) {
+        const name = route.paramNames[i]
+        const segment = segments[i] as string
+        if (name === undefined) {
+          if (route.segments[i] !== segment) {
+            matched = false
+            break
+          }
+        } else {
+          params[name] = decodeURIComponent(segment)
+        }
+      }
+      if (matched) return { operation: route.operation, params }
+    }
+    return undefined
+  }
+
+  async dispatch(request: Request): Promise<Response> {
+    const url = new URL(request.url)
+    const matched = this.match(request.method, url.pathname)
+    if (!matched) {
+      return problemResponse(
+        notFound(
+          'Not Found',
+          `No operation in the contract matches ${request.method} ${url.pathname}`,
+        ),
+      )
+    }
+    const { operation, params } = matched
+    const notifications: EventMessage[] = []
+
+    // Authorisation is driven by the contract: the document requires a
+    // back-office user globally, and 10 operations opt out with `security: []`.
+    const principal = await this.#authenticate?.(request)
+    const anonymous =
+      operation.anonymous ||
+      (this.#allowLocalLogin && LOCAL_LOGIN_OPERATIONS.has(operation.operationId))
+    if (!anonymous && !principal) {
+      return problemResponse(unauthorized())
+    }
+    // Umbraco answers a failed authorization policy with a bare 403.
+    if (principal && !(await authorize(operation, params, request, principal, this.#nodes)))
+      return new Response(null, { status: 403, headers: { 'cache-control': 'no-store' } })
+
+    const handler = this.#handlers.get(operation.operationId)
+    if (!handler) this.#onNotImplemented?.(operation, request)
+    const response = handler
+      ? await handler({ request, url, params, operation, notifications, principal })
+      : problemResponse(notImplemented(operation.operationId))
+    if (handler && this.#onServerEvent) {
+      const event = serverEventFor(operation, params, response)
+      if (event) this.#onServerEvent(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 })
+  }
+}

package/src/routes.ts

@@ -0,0 +1,99 @@
+/**
+ * Composition root for the Management API. Handlers are registered here as they
+ * are implemented; every other operation in the contract answers 501.
+ */
+import { registerContentTypeHandlers } from './handlers/content-type.ts'
+import { registerDataTypeHandlers } from './handlers/data-type.ts'
+import { registerDictionaryHandlers } from './handlers/dictionary.ts'
+import { registerDocumentHandlers } from './handlers/document.ts'
+import { registerDocumentBlueprintHandlers } from './handlers/document-blueprint.ts'
+import { registerEditorServiceHandlers } from './handlers/editor-services.ts'
+import { registerElementHandlers } from './handlers/element.ts'
+import { registerFileSystemHandlers } from './handlers/file-systems.ts'
+import { registerImportHandlers } from './handlers/import.ts'
+import { registerLocalizationHandlers } from './handlers/localization.ts'
+import { registerLogViewerHandlers } from './handlers/log-viewer.ts'
+import { registerManifestHandlers } from './handlers/manifest.ts'
+import { registerMediaHandlers } from './handlers/media.ts'
+import { registerMemberHandlers } from './handlers/member.ts'
+import { registerMemberGroupHandlers } from './handlers/member-group.ts'
+import { registerModelsBuilderHandlers } from './handlers/models-builder.ts'
+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 { registerReferenceHandlers } from './handlers/references.ts'
+import { registerServerHandlers } from './handlers/server.ts'
+import { registerSettingsStubHandlers } from './handlers/settings-stubs.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 type { ManagementApiDeps } from './ports.ts'
+import { type Authenticator, ManagementApiRouter, type RouterOptions } from './router.ts'
+
+export interface ManagementApiOptions {
+  deps?: ManagementApiDeps
+  authenticate?: Authenticator
+  onNotImplemented?: RouterOptions['onNotImplemented']
+  onServerEvent?: RouterOptions['onServerEvent']
+  nodes?: RouterOptions['nodes']
+  allowLocalLogin?: boolean
+}
+
+export function createManagementApiRouter(options: ManagementApiOptions = {}): ManagementApiRouter {
+  const router = new ManagementApiRouter({
+    authenticate: options.authenticate,
+    onNotImplemented: options.onNotImplemented,
+    onServerEvent: options.onServerEvent,
+    nodes: options.nodes,
+    allowLocalLogin: options.allowLocalLogin,
+  })
+  const { deps } = options
+  if (!deps) return router
+
+  registerServerHandlers(router, deps.server)
+  registerManifestHandlers(router, deps.manifests)
+  registerLocalizationHandlers(router, deps.localization)
+  registerUserHandlers(router, deps.currentUser, deps.users, {
+    users: deps.userManagement,
+    groups: deps.userGroups,
+    userData: deps.userData,
+  })
+  registerSettingsStubHandlers(router)
+  if (deps.contentTypes)
+    registerContentTypeHandlers(router, deps.contentTypes, 'document', deps.temporaryFiles)
+  if (deps.mediaTypes)
+    registerContentTypeHandlers(router, deps.mediaTypes, 'media', deps.temporaryFiles)
+  if (deps.memberTypes)
+    registerContentTypeHandlers(router, deps.memberTypes, 'member', deps.temporaryFiles)
+  if (deps.dataTypes) registerDataTypeHandlers(router, deps.dataTypes)
+  if (deps.templates) registerTemplateHandlers(router, deps.templates)
+  if (deps.templateQuery) registerTemplateQueryHandlers(router, deps.templateQuery)
+  if (deps.documents) registerDocumentHandlers(router, deps.documents, deps.preview)
+  if (deps.blueprints) registerDocumentBlueprintHandlers(router, deps.blueprints)
+  if (deps.temporaryFiles) registerTemporaryFileHandlers(router, deps.temporaryFiles)
+  if (deps.media) registerMediaHandlers(router, deps.media)
+  if (deps.dictionary) registerDictionaryHandlers(router, deps.dictionary)
+  // The components tree is served through the PartialView file API: it is the
+  // path-addressed one, so it is the only one that can express a folder.
+  if (deps.components)
+    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.logViewer) registerLogViewerHandlers(router, deps.logViewer)
+  if (deps.modelsBuilder) registerModelsBuilderHandlers(router, deps.modelsBuilder)
+  if (deps.publishedCache) registerPublishedCacheHandlers(router, deps.publishedCache)
+  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)
+  if (deps.redirects) registerRedirectHandlers(router, deps.redirects)
+  if (deps.packages) registerPackageHandlers(router, deps.packages)
+  if (deps.references)
+    for (const area of ['Document', 'Media', 'Member', 'Element'] as const)
+      registerReferenceHandlers(router, area, deps.references)
+  registerEditorServiceHandlers(router, { tags: deps.tags, oembed: deps.oembed })
+  return router
+}

package/src/server-events.ts

@@ -0,0 +1,71 @@
+/**
+ * The server events a successful change announces, as Umbraco's notification
+ * handlers do. The backoffice caches entity details while connected to the
+ * event hub and drops a cached entity only when an event names it, so a change
+ * that announces nothing leaves every open editor, including the one that made
+ * it, showing the old copy.
+ */
+import type { OperationInfo } from '@crombolo/contracts'
+
+export type ServerEventType = 'Created' | 'Updated' | 'Deleted' | 'Trashed'
+
+export interface ServerEvent {
+  eventSource: string
+  eventType: ServerEventType
+  key: string
+}
+
+/** Operation-name entity prefixes, longest first so `DocumentType` wins over `Document`. */
+const ENTITIES = [
+  'DocumentBlueprint',
+  'DocumentType',
+  'Document',
+  'MediaType',
+  'Media',
+  'MemberGroup',
+  'MemberType',
+  'Member',
+  'DataType',
+  'Language',
+  'Script',
+  'Stylesheet',
+  'Template',
+  'DictionaryItem',
+  'PartialView',
+  'UserGroup',
+  'User',
+  'Webhook',
+] as const
+
+/** Operations on an entity that change nothing about it, or are about something else. */
+const NOT_A_CHANGE = /^(Folder|Validate|ByIdValidate|Item|Tree|Filter|Search|Current|Configuration)/
+
+export function serverEventFor(
+  operation: OperationInfo,
+  params: Readonly<Record<string, string>>,
+  response: Response,
+): ServerEvent | undefined {
+  if (response.status < 200 || response.status >= 300) return undefined
+  const verb = /^(Post|Put|Delete)(.+)$/.exec(operation.operationId)
+  if (!verb) return undefined
+  const [, method, verbRest] = verb as unknown as [string, string, string]
+  // `DeleteRecycleBinMediaById` deletes a media item; `…ByIdRestore` updates one.
+  const rest = verbRest.startsWith('RecycleBin') ? verbRest.slice('RecycleBin'.length) : verbRest
+  const entity = ENTITIES.find((name) => rest.startsWith(name))
+  if (!entity) return undefined
+  const after = rest.slice(entity.length)
+  if (NOT_A_CHANGE.test(after)) return undefined
+
+  const generated = response.headers.get('umb-generated-resource')
+  const key = generated ?? params.id ?? params.isoCode ?? params.path
+  if (!key) return undefined
+  const eventType: ServerEventType =
+    method === 'Delete'
+      ? 'Deleted'
+      : after.endsWith('MoveToRecycleBin')
+        ? 'Trashed'
+        : generated
+          ? 'Created'
+          : 'Updated'
+  return { eventSource: `Umbraco:CMS:${entity}`, eventType, key }
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.