@crombolo/api-management 0.10.0 → 0.12.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crombolo/api-management",
-  "version": "0.10.0",
+  "version": "0.12.1",
   "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.12.1",
+    "@crombolo/contracts": "0.12.1"
   }
 }

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/divergences.ts

@@ -0,0 +1,22 @@
+/**
+ * Operations that answer 501 on purpose, with the reason; `coverage:api` lists
+ * them apart from what is still to build. docs/roadmap.md, "Deliberate divergence".
+ */
+const INSTALL =
+  'There is no browser install wizard: `crombolo init` and schema-as-code stand a site up.'
+const UPGRADE =
+  'Upgrades run from the command line with `crombolo upgrade`, not from the backoffice.'
+
+export const DELIBERATE_DIVERGENCES: Readonly<Record<string, string>> = {
+  GetInstallSettings: INSTALL,
+  PostInstallSetup: INSTALL,
+  PostInstallValidateDatabase: INSTALL,
+  GetUpgradeSettings: UPGRADE,
+  PostUpgradeAuthorize: UPGRADE,
+}
+
+/** Areas still to build, by the story that builds them. */
+export const PLANNED_AREAS: Readonly<Record<string, string>> = {}
+
+/** Operations outside those areas that a story builds. */
+export const PLANNED_OPERATIONS: Readonly<Record<string, string>> = {}

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/data-type.ts

@@ -205,6 +205,31 @@ export function registerDataTypeHandlers(router: ManagementApiRouter, port: Data
     return Response.json({ total: result.total, items: result.items.map(toItem) })
   })
 
+  const isUsed = port.isUsed
+  if (isUsed)
+    router.handle('GetDataTypeByIdIsUsed', async (ctx) => {
+      const used = await isUsed(ctx.params.id as string)
+      if (used === undefined)
+        return problemResponse(notFound('Data type not found', 'The data type could not be found.'))
+      return Response.json(used)
+    })
+  const propertyIsUsed = port.propertyIsUsed
+  if (propertyIsUsed)
+    router.handle('GetPropertyTypeIsUsed', async (ctx) => {
+      const contentTypeId = ctx.url.searchParams.get('contentTypeId')
+      const alias = ctx.url.searchParams.get('propertyAlias')
+      const used = contentTypeId && alias ? await propertyIsUsed(contentTypeId, alias) : undefined
+      if (used === undefined)
+        return problemResponse(
+          problemDetails({
+            title: 'Property type not found',
+            detail: 'There is no property with that alias on that content type.',
+            status: 400,
+          }),
+        )
+      return Response.json(used)
+    })
+
   router.handle('GetDataTypeByIdReferencedBy', async (ctx) => {
     const page = paging(ctx)
     if (!page) return problemResponse(invalidSkipTake())