@crombolo/server 0.12.1 → 0.13.1

package/package.json

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

package/src/adapters/bundles.ts

@@ -49,6 +49,7 @@ import {
   type BundleNode,
   type BundleSection,
   bundleIdFor,
+  bundlePeerRange,
   type ContentSet,
   exportBundle,
   isPackageName,
@@ -442,7 +443,7 @@ export function createPackagePort(db: Db, options: PackagePortOptions): PackageP
         version: pkg.version,
         id: bundleIdFor(pkg.name.replace(/^@[^/]+\//, '')),
         label: from.name,
-        peerRange: `^${VERSION}`,
+        peerRange: bundlePeerRange(VERSION),
       })
       const entries = files.map((file) => ({
         path: file.path,

package/src/approvals-api.ts

@@ -0,0 +1,189 @@
+/**
+ * The Workflow section's and the page tab's reads and actions (story 028),
+ * under `<backoffice>/crombolo/api/approvals/`, and saving a workflow drawn in
+ * the designer back to `schema/workflows/`. docs/workflows.md.
+ *
+ * A workflow is written as its file, validated against the whole set first,
+ * then synced at once, so the gate follows it without a restart; the file is
+ * the truth, as for forms, and a read-only schema directory refuses the save.
+ */
+import { existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import type { Principal } from '@crombolo/api-management'
+import type { SchemaWorkflow } from '@crombolo/core'
+import { type Db, readWorkflows, syncWorkflows, UserGroupRepository } from '@crombolo/data'
+import {
+  fileNameFor,
+  loadSchemaDirectory,
+  parseWorkflow,
+  validateWorkflows,
+  workflowVersion,
+  writeWorkflow,
+} from '@crombolo/schema'
+import { ApprovalRefused, type Approvals } from './approvals.ts'
+
+export interface ApprovalsApiContext {
+  db: Db
+  approvals: Approvals
+  principal: Principal
+  schemaDir: string
+  /** False on a deployed node with no schema store: a save would not last. */
+  writable: boolean
+  onChanged?: () => Promise<void>
+}
+
+const json = (body: unknown, status = 200) => Response.json(body, { status })
+
+/** The workflows in `schema/workflows/`, synced into the database: what the gate reads. */
+export async function syncWorkflowFiles(db: Db, schemaDir: string) {
+  const workflows = loadSchemaDirectory(schemaDir).set.workflows ?? []
+  return syncWorkflows(
+    db,
+    workflows.map((workflow) => ({ workflow, version: workflowVersion(workflow) })),
+  )
+}
+
+/** What saving a workflow would do to the requests in flight under it. */
+async function changePreview(approvals: Approvals, principal: Principal, workflow: SchemaWorkflow) {
+  const id = workflow.key ?? workflow.alias
+  const stored = (await approvals.workflows()).find(
+    (s) => (s.workflow.key ?? s.workflow.alias) === id,
+  )
+  const version = workflowVersion(workflow)
+  if (stored && stored.version === version) return []
+  const waiting = (await approvals.inFlight(principal)).filter(
+    (r) => (r.workflow.key ?? r.workflow.alias) === id,
+  )
+  return waiting.map((r) => ({ key: r.key, page: r.nodeName, outcome: workflow.onChange }))
+}
+
+export async function handleApprovalsApi(
+  request: Request,
+  path: string,
+  ctx: ApprovalsApiContext,
+): Promise<Response | undefined> {
+  const { approvals, principal } = ctx
+  const body = async () => (await request.json().catch(() => ({}))) as Record<string, unknown>
+  const text = (value: unknown) => (typeof value === 'string' ? value : undefined)
+  try {
+    let match = /^page\/([^/]+)$/.exec(path)
+    if (match && request.method === 'GET')
+      return json(await approvals.forPage(principal, decodeURIComponent(match[1] as string)))
+
+    match = /^page\/([^/]+)\/send$/.exec(path)
+    if (match && request.method === 'POST') {
+      const b = await body()
+      const cultures = Array.isArray(b.cultures) ? b.cultures.map(String) : null
+      return json(
+        await approvals.send(
+          principal,
+          decodeURIComponent(match[1] as string),
+          b.action === 'unpublish' ? 'unpublish' : 'publish',
+          cultures && cultures.length > 0 ? cultures : null,
+          text(b.comment),
+        ),
+      )
+    }
+
+    match = /^request\/([^/]+)\/(approve|send-back|withdraw)$/.exec(path)
+    if (match && request.method === 'POST') {
+      const key = decodeURIComponent(match[1] as string)
+      const b = await body()
+      if (match[2] === 'approve')
+        return json(await approvals.approve(principal, key, text(b.stage), text(b.comment)))
+      if (match[2] === 'send-back')
+        return json(await approvals.sendBack(principal, key, text(b.stage), text(b.comment)))
+      return json(await approvals.withdraw(principal, key))
+    }
+
+    if (path === 'waiting' && request.method === 'GET')
+      return json({ items: await approvals.waitingFor(principal) })
+    if (path === 'in-flight' && request.method === 'GET')
+      return json({ items: await approvals.inFlight(principal) })
+    if (path === 'history' && request.method === 'GET') {
+      const url = new URL(request.url)
+      const skip = Math.max(0, Number(url.searchParams.get('skip') ?? 0) || 0)
+      const take = Math.min(100, Math.max(1, Number(url.searchParams.get('take') ?? 25) || 25))
+      return json(await approvals.finished(principal, skip, take))
+    }
+
+    if (path === 'workflows' && request.method === 'GET') {
+      const loaded = loadSchemaDirectory(ctx.schemaDir)
+      return json({
+        items: (await readWorkflows(ctx.db)).map((s) => s.workflow),
+        editable: ctx.writable && principal.isAdmin,
+        groups: (await new UserGroupRepository(ctx.db).all()).map((g) => ({
+          alias: g.alias,
+          name: g.name,
+        })),
+        contentTypes: loaded.set.contentTypes.map((t) => ({ alias: t.alias, name: t.name })),
+      })
+    }
+
+    match = /^workflows\/([^/]+)(\/preview)?$/.exec(path)
+    if (match) {
+      if (!principal.isAdmin)
+        return json({ ok: false, message: 'Only administrators change workflows.' }, 403)
+      const alias = decodeURIComponent(match[1] as string)
+      const file = join(ctx.schemaDir, 'workflows', fileNameFor(alias))
+      if (request.method === 'DELETE') {
+        if (!ctx.writable) return readOnly()
+        if (!existsSync(file))
+          return json({ ok: false, message: 'There is no such workflow.' }, 404)
+        rmSync(file)
+        await ctx.onChanged?.()
+        return json({ ok: true, report: await syncWorkflowFiles(ctx.db, ctx.schemaDir) })
+      }
+      if (request.method !== 'PUT' && request.method !== 'POST') return undefined
+      const b = await body()
+      // Through the file and the strict parser, as a hand-written one would be.
+      const source = writeWorkflow(b.workflow as SchemaWorkflow)
+      const parsed = parseWorkflow(`schema/workflows/${fileNameFor(alias)}`, source)
+      if (!parsed.value) return json({ ok: false, problems: parsed.problems }, 400)
+      const workflow = parsed.value
+      const loaded = loadSchemaDirectory(ctx.schemaDir)
+      const others = (loaded.set.workflows ?? []).filter(
+        (w) => w.alias !== alias && w.alias !== workflow.alias,
+      )
+      const problems = validateWorkflows(
+        [...others, workflow],
+        new Set(loaded.set.contentTypes.map((t) => t.alias)),
+      )
+      const groups = new Set((await new UserGroupRepository(ctx.db).all()).map((g) => g.alias))
+      workflow.stages.forEach((stage, i) => {
+        for (const approver of stage.approvers)
+          if (!groups.has(approver))
+            problems.push({
+              file: `schema/workflows/${fileNameFor(workflow.alias)}`,
+              path: `stage[${i}].approvers`,
+              message: `there is no user group "${approver}"`,
+            })
+      })
+      if (problems.length > 0) return json({ ok: false, problems }, 400)
+      const affected = await changePreview(approvals, principal, workflow)
+      if (match[2]) return json({ ok: true, affected })
+      if (!ctx.writable) return readOnly()
+      mkdirSync(join(ctx.schemaDir, 'workflows'), { recursive: true })
+      // A renamed workflow leaves its old file behind otherwise.
+      if (alias !== workflow.alias && existsSync(file)) rmSync(file)
+      writeFileSync(join(ctx.schemaDir, 'workflows', fileNameFor(workflow.alias)), source, 'utf8')
+      await ctx.onChanged?.()
+      return json({ ok: true, affected, report: await syncWorkflowFiles(ctx.db, ctx.schemaDir) })
+    }
+  } catch (error) {
+    if (error instanceof ApprovalRefused)
+      return json({ ok: false, message: error.message }, error.status)
+    throw error
+  }
+  return undefined
+}
+
+const readOnly = () =>
+  json(
+    {
+      ok: false,
+      message:
+        'The schema directory is read-only on this server, so a workflow cannot be saved here. Change the file in the repository and deploy it.',
+    },
+    409,
+  )

package/src/approvals.ts

@@ -0,0 +1,823 @@
+/**
+ * Approval before publishing (story 028): which workflow covers a page, the
+ * gate that refuses publishing a covered page directly, and the requests that
+ * go through a workflow's stages. docs/workflows.md.
+ *
+ * The graph rules are `@crombolo/core`'s; the record is `ApprovalRepository`'s.
+ * This decides: who may act, what an edit does to a waiting request, when a
+ * stage is done, and when the page is published.
+ */
+import type { Principal } from '@crombolo/api-management'
+import {
+  approvalsNeeded,
+  DocumentPermissions,
+  descendantStages,
+  normaliseUuid,
+  permissionsForPath,
+  type SchemaWorkflow,
+  SEND_BACK_TO_EDITOR,
+  stagesNowWaiting,
+  startStages,
+  workflowComplete,
+  workflowFor,
+} from '@crombolo/core'
+import {
+  type ApprovalAction,
+  ApprovalRepository,
+  type ApprovalRepository as ApprovalRepositoryType,
+  type ApprovalRequest,
+  type ApprovalStep,
+  AuditLog,
+  type Db,
+  DocumentRepository,
+  NodeRepository,
+  type NodeSchemaState,
+  readWorkflows,
+  type StoredWorkflow,
+  UserGroupRepository,
+} from '@crombolo/data'
+import type { EmailPort } from './email.ts'
+
+/** What publishing and unpublishing go through when approval says yes. */
+export interface ApprovalPublisher {
+  publish(
+    key: string,
+    cultures: string[] | null,
+  ): Promise<{ ok: true } | { ok: false; reason: string }>
+  unpublish(
+    key: string,
+    cultures: string[] | null,
+  ): Promise<{ ok: true } | { ok: false; reason: string }>
+}
+
+export interface ApprovalsOptions {
+  db: Db
+  publisher: ApprovalPublisher
+  nodeState?: NodeSchemaState
+  email?: EmailPort
+  /** Where a link in an e-mail points, e.g. `https://site.example/crombolo`. */
+  backOfficeUrl?: string
+}
+
+/** A refusal a person reads: why, and what to do instead. */
+export class ApprovalRefused extends Error {
+  constructor(
+    message: string,
+    readonly status = 400,
+  ) {
+    super(message)
+  }
+}
+
+/** The page a request or a check is about, as the engine needs it. */
+interface PageFacts {
+  key: string
+  name: string
+  chain: string[]
+  contentTypeAlias: string | undefined
+}
+
+export interface PageApproval {
+  /** The workflow that covers the page, as it stands now. */
+  workflow: SchemaWorkflow | undefined
+  request: RequestView | undefined
+  /** Earlier requests, newest first. */
+  past: RequestView[]
+  can: { send: boolean; requestUnpublish: boolean; publishDirectly: boolean }
+}
+
+export interface RequestView {
+  key: string
+  nodeKey: string
+  nodeName: string
+  action: ApprovalAction
+  cultures: string[] | null
+  state: ApprovalRequest['state']
+  requestedBy: string
+  requestedAt: string
+  workflow: SchemaWorkflow
+  stages: Array<{
+    alias: string
+    state: 'waiting' | 'approved' | 'pending' | 'discarded'
+    approvals: number
+    needed: number
+  }>
+  history: Array<{
+    kind: string
+    stage: string | null
+    userKey: string | null
+    comment: string | null
+    at: string
+  }>
+  /** What the asking user may do now. */
+  can: { approve: string[]; sendBack: string[]; withdraw: boolean }
+}
+
+export interface Approvals {
+  /** The workflows the site has, as last synced. */
+  workflows(): Promise<StoredWorkflow[]>
+  /** Undefined when the caller may go ahead; otherwise why not. */
+  publishRefusal(
+    principal: Principal,
+    key: string,
+    action: ApprovalAction,
+  ): Promise<string | undefined>
+  /** A branch publish: the root and every page below it. */
+  branchRefusal(principal: Principal, key: string): Promise<string | undefined>
+  /** For a page being created and published at once: by its parent and type. */
+  newPageRefusal(
+    principal: Principal,
+    parentKey: string | null,
+    contentTypeKey: string,
+  ): Promise<string | undefined>
+  /** Undefined when the save may go ahead; otherwise why not. */
+  beforeSave(principal: Principal, key: string): Promise<string | undefined>
+  /** What the save does to a waiting request, once it has gone through. */
+  afterSave(principal: Principal, key: string): Promise<void>
+  send(
+    principal: Principal,
+    key: string,
+    action: ApprovalAction,
+    cultures: string[] | null,
+    comment?: string,
+  ): Promise<RequestView>
+  approve(
+    principal: Principal,
+    requestKey: string,
+    stage?: string,
+    comment?: string,
+  ): Promise<RequestView>
+  sendBack(
+    principal: Principal,
+    requestKey: string,
+    stage: string | undefined,
+    comment?: string,
+  ): Promise<RequestView>
+  withdraw(principal: Principal, requestKey: string): Promise<RequestView>
+  forPage(principal: Principal, key: string): Promise<PageApproval>
+  /** Requests waiting on a stage the user may approve. */
+  waitingFor(principal: Principal): Promise<RequestView[]>
+  inFlight(principal: Principal): Promise<RequestView[]>
+  finished(
+    principal: Principal,
+    skip: number,
+    take: number,
+  ): Promise<{ total: number; items: RequestView[] }>
+}
+
+export function createApprovals(options: ApprovalsOptions): Approvals {
+  const { db } = options
+  const requests = (tx: Db = db): ApprovalRepositoryType => new ApprovalRepository(tx)
+  const nodes = new NodeRepository(db)
+  const groups = new UserGroupRepository(db)
+  const audit = new AuditLog(db)
+
+  const page = async (key: string): Promise<PageFacts | undefined> => {
+    const node = await nodes.byKey(key)
+    if (!node) return undefined
+    const ids = node.path
+      .split(',')
+      .map(Number)
+      .filter((id) => id > 0)
+    const rows = await nodes.byIds(ids)
+    const keyOf = new Map(rows.map((r) => [r.id, r.key]))
+    const type = await db.query<{ alias: string }>(
+      `SELECT ct.alias FROM content c JOIN content_type ct ON ct.node_id = c.content_type_id WHERE c.node_id = ?`,
+      [node.id],
+    )
+    return {
+      key: node.key,
+      name: node.text ?? node.key,
+      chain: ids.flatMap((id) => keyOf.get(id) ?? []),
+      contentTypeAlias: type[0]?.alias,
+    }
+  }
+
+  const covering = async (facts: PageFacts): Promise<SchemaWorkflow | undefined> =>
+    workflowFor(
+      (await readWorkflows(db)).map((s) => s.workflow),
+      facts.chain,
+      facts.contentTypeAlias,
+    )
+
+  const groupAliases = async (principal: Principal): Promise<Set<string>> =>
+    new Set((await groups.byKeys(principal.groupKeys)).map((g) => g.alias))
+
+  const mayPublish = (principal: Principal, facts: PageFacts, action: ApprovalAction): boolean =>
+    principal.isAdmin ||
+    permissionsForPath(principal.groups, facts.chain).has(
+      action === 'publish' ? DocumentPermissions.Publish : DocumentPermissions.Unpublish,
+    )
+
+  const covers = (workflow: SchemaWorkflow | undefined, action: ApprovalAction) =>
+    workflow !== undefined && (action === 'publish' || workflow.unpublish)
+
+  const refusalFor = (
+    principal: Principal,
+    facts: PageFacts,
+    workflow: SchemaWorkflow | undefined,
+    action: ApprovalAction,
+  ): string | undefined => {
+    if (!workflow || !covers(workflow, action)) return undefined
+    if (workflow.publishersMaySkip && mayPublish(principal, facts, action)) return undefined
+    return action === 'publish'
+      ? `"${facts.name}" needs approval through "${workflow.name}" before it is published. Send it for approval from its Workflow tab.`
+      : `Taking "${facts.name}" down needs approval through "${workflow.name}". Request it from its Workflow tab.`
+  }
+
+  const membersOf = async (aliases: readonly string[]): Promise<number> => {
+    if (aliases.length === 0) return 0
+    const rows = await db.query<{ n: number }>(
+      `SELECT COUNT(DISTINCT m.user_id) AS n FROM user_group_member m
+       JOIN user_group g ON g.id = m.user_group_id WHERE g.alias IN (${aliases.map(() => '?').join(', ')})`,
+      [...aliases],
+    )
+    return Number(rows[0]?.n ?? 0)
+  }
+
+  const stageOf = (workflow: SchemaWorkflow, alias: string) =>
+    workflow.stages.find((s) => s.alias === alias)
+
+  /** Approvals given in a stage visit, by distinct user. */
+  const approvalsIn = async (
+    repo: ApprovalRepositoryType,
+    request: ApprovalRequest,
+    step: ApprovalStep,
+  ) => {
+    const history = await repo.history(request.id)
+    return new Set(
+      history
+        .filter((h) => h.kind === 'approved' && h.stepId === step.id && h.userKey)
+        .map((h) => h.userKey as string),
+    )
+  }
+
+  const notify = async (
+    to: 'approvers' | 'editor',
+    request: ApprovalRequest,
+    stages: readonly string[],
+    subject: string,
+    body: string,
+  ) => {
+    if (!options.email) return
+    let emails: string[] = []
+    if (to === 'editor') {
+      const rows = await db.query<{ email: string }>(
+        'SELECT email FROM user_account WHERE key = ?',
+        [request.requestedBy],
+      )
+      emails = rows.map((r) => r.email)
+    } else {
+      const aliases = stages.flatMap((s) => stageOf(request.workflow, s)?.approvers ?? [])
+      if (aliases.length === 0) return
+      const rows = await db.query<{ email: string }>(
+        `SELECT DISTINCT u.email FROM user_account u
+         JOIN user_group_member m ON m.user_id = u.id JOIN user_group g ON g.id = m.user_group_id
+         WHERE g.alias IN (${aliases.map(() => '?').join(', ')}) AND u.is_approved = ?`,
+        [...aliases, db.dialect.boolValue(true)],
+      )
+      emails = rows.map((r) => r.email)
+    }
+    if (emails.length === 0) return
+    const link = options.backOfficeUrl
+      ? `\n\n${options.backOfficeUrl}/section/content/workspace/document/edit/${request.nodeKey}`
+      : ''
+    await options.email.send({
+      to: emails.map((email) => ({ email })),
+      subject,
+      text: `${body}${link}`,
+    })
+  }
+
+  const auditStep = async (
+    principal: Principal | undefined,
+    facts: PageFacts | undefined,
+    action: string,
+    detail: string,
+  ) => {
+    await audit.record({
+      category: 'content',
+      action,
+      source: 'request',
+      userKey: principal?.id ?? null,
+      userName: principal?.name ?? null,
+      entityType: 'Document',
+      entityKey: facts?.key ?? null,
+      entityName: facts?.name ?? null,
+      detail,
+    })
+  }
+
+  /**
+   * Stages just reached count the person who made the change as approving
+   * when the workflow says so and they are in the stage's groups.
+   */
+  const reach = async (
+    repo: ApprovalRepositoryType,
+    request: ApprovalRequest,
+    stages: readonly string[],
+  ): Promise<void> => {
+    for (const stage of stages) {
+      const stepId = await repo.addStep(request.id, stage)
+      if (request.workflow.selfApproval !== 'automatic') continue
+      const approvers = stageOf(request.workflow, stage)?.approvers ?? []
+      const member = await db.query<{ n: number }>(
+        `SELECT COUNT(*) AS n FROM user_group_member m JOIN user_group g ON g.id = m.user_group_id
+         JOIN user_account u ON u.id = m.user_id WHERE u.key = ? AND g.alias IN (${approvers.map(() => '?').join(', ') || "''"})`,
+        [request.requestedBy, ...approvers],
+      )
+      if (Number(member[0]?.n ?? 0) > 0)
+        await repo.record(request.id, {
+          kind: 'approved',
+          stepId,
+          stage,
+          userKey: request.requestedBy,
+          comment: 'counted automatically: they made the change',
+        })
+    }
+  }
+
+  /** Marks done whatever stages have their approvals, reaches what follows, and publishes at the end. */
+  /** True when every last stage has approved: the caller publishes, once its transaction is over. */
+  const settle = async (
+    repo: ApprovalRepositoryType,
+    request: ApprovalRequest,
+  ): Promise<boolean> => {
+    for (let round = 0; round < request.workflow.stages.length + 1; round++) {
+      const steps = await repo.steps(request.id)
+      let moved = false
+      for (const step of steps.filter((s) => s.state === 'waiting')) {
+        const stage = stageOf(request.workflow, step.stage)
+        if (!stage) continue
+        const given = await approvalsIn(repo, request, step)
+        if (given.size >= approvalsNeeded(stage.required, await membersOf(stage.approvers))) {
+          await repo.setStepState(step.id, 'approved')
+          moved = true
+        }
+      }
+      const now = await repo.steps(request.id)
+      const approved = new Set(now.filter((s) => s.state === 'approved').map((s) => s.stage))
+      const reached = new Set(
+        now.filter((s) => s.state === 'waiting' || s.state === 'approved').map((s) => s.stage),
+      )
+      if (workflowComplete(request.workflow, approved)) return true
+      const next = stagesNowWaiting(request.workflow, approved, reached)
+      if (next.length > 0) {
+        await reach(repo, request, next)
+        const facts = await page(request.nodeKey)
+        await notify(
+          'approvers',
+          request,
+          next,
+          `Waiting for your approval: ${facts?.name ?? 'a page'}`,
+          `"${facts?.name}" is waiting for approval through "${request.workflow.name}".`,
+        )
+        moved = true
+      }
+      if (!moved) return false
+    }
+    return false
+  }
+
+  /**
+   * Publishes (or takes down) a fully approved page, outside any transaction:
+   * publishing takes the content tree's lock, which must never be waited on
+   * from inside one. A page that cannot be published goes back to its editor
+   * with the reason, rather than sitting approved and unpublished.
+   */
+  const finish = async (
+    request: ApprovalRequest,
+    principal: Principal | undefined,
+  ): Promise<void> => {
+    const repo = requests()
+    const facts = await page(request.nodeKey)
+    const result =
+      request.action === 'publish'
+        ? await options.publisher.publish(request.nodeKey, request.cultures)
+        : await options.publisher.unpublish(request.nodeKey, request.cultures)
+    if (!result.ok) {
+      await repo.setState(request.id, 'sent-back')
+      await repo.record(request.id, {
+        kind: 'sent-back',
+        comment: `approved, but it could not be ${request.action === 'publish' ? 'published' : 'taken down'}: ${result.reason}`,
+      })
+      await notify(
+        'editor',
+        request,
+        [],
+        `Could not publish: ${facts?.name ?? 'a page'}`,
+        `"${facts?.name}" was approved but could not be published: ${result.reason}`,
+      )
+      return
+    }
+    await repo.setState(request.id, 'approved')
+    await repo.record(request.id, {
+      kind: request.action === 'publish' ? 'published' : 'unpublished',
+      userKey: principal?.id ?? null,
+    })
+    await auditStep(
+      principal,
+      facts,
+      request.action === 'publish' ? 'Published on approval' : 'Unpublished on approval',
+      `through "${request.workflow.name}"`,
+    )
+    await notify(
+      'editor',
+      request,
+      [],
+      `Approved: ${facts?.name ?? 'a page'}`,
+      `"${facts?.name}" was approved through "${request.workflow.name}" and is now ${request.action === 'publish' ? 'published' : 'taken down'}.`,
+    )
+  }
+
+  const view = async (principal: Principal, request: ApprovalRequest): Promise<RequestView> => {
+    const repo = requests()
+    const steps = await repo.steps(request.id)
+    const history = await repo.history(request.id)
+    const mine = await groupAliases(principal)
+    const facts = await page(request.nodeKey)
+    const current = new Map<string, ApprovalStep>()
+    for (const step of steps)
+      if (step.state === 'waiting' || step.state === 'approved') current.set(step.stage, step)
+    const stages: RequestView['stages'] = []
+    for (const stage of request.workflow.stages) {
+      const step = current.get(stage.alias)
+      const given = step
+        ? history.filter((h) => h.kind === 'approved' && h.stepId === step.id).length
+        : 0
+      stages.push({
+        alias: stage.alias,
+        state: step
+          ? (step.state as 'waiting' | 'approved')
+          : steps.some((s) => s.stage === stage.alias)
+            ? 'discarded'
+            : 'pending',
+        approvals: given,
+        needed: approvalsNeeded(stage.required, await membersOf(stage.approvers)),
+      })
+    }
+    const waiting = request.state === 'waiting'
+    const actionable = waiting
+      ? request.workflow.stages.filter(
+          (s) => current.get(s.alias)?.state === 'waiting' && s.approvers.some((a) => mine.has(a)),
+        )
+      : []
+    const already = (alias: string) =>
+      history.some(
+        (h) =>
+          h.kind === 'approved' &&
+          h.stepId === current.get(alias)?.id &&
+          h.userKey === normaliseUuid(principal.id),
+      )
+    const ownChange = normaliseUuid(principal.id) === request.requestedBy
+    return {
+      key: request.key,
+      nodeKey: request.nodeKey,
+      nodeName: facts?.name ?? request.nodeKey,
+      action: request.action,
+      cultures: request.cultures,
+      state: request.state,
+      requestedBy: request.requestedBy,
+      requestedAt: request.requestedAt.toISOString(),
+      workflow: request.workflow,
+      stages,
+      history: history.map((h) => ({
+        kind: h.kind,
+        stage: h.stage,
+        userKey: h.userKey,
+        comment: h.comment,
+        at: h.createDate.toISOString(),
+      })),
+      can: {
+        approve:
+          ownChange && request.workflow.selfApproval === 'refused'
+            ? []
+            : actionable.filter((s) => !already(s.alias)).map((s) => s.alias),
+        sendBack: actionable.map((s) => s.alias),
+        withdraw: waiting && (ownChange || principal.isAdmin),
+      },
+    }
+  }
+
+  /** After a decision's transaction: publishes when it completed the workflow, then the request as it stands. */
+  const concluded = async (
+    principal: Principal,
+    outcome: { request: ApprovalRequest; complete: boolean },
+  ): Promise<RequestView> => {
+    if (outcome.complete) await finish(outcome.request, principal)
+    return view(principal, (await requests().byKey(outcome.request.key)) as ApprovalRequest)
+  }
+
+  const needsComment = (
+    workflow: SchemaWorkflow,
+    decision: 'approve' | 'send-back',
+    comment: string | undefined,
+  ) =>
+    (workflow.comments === 'always' ||
+      (workflow.comments === 'on-send-back' && decision === 'send-back')) &&
+    !comment?.trim()
+
+  const waitingRequest = async (requestKey: string): Promise<ApprovalRequest> => {
+    const request = await requests().byKey(requestKey)
+    if (!request) throw new ApprovalRefused('There is no such request.', 404)
+    if (request.state !== 'waiting')
+      throw new ApprovalRefused('This request has already been decided.', 409)
+    return request
+  }
+
+  return {
+    workflows: () => readWorkflows(db),
+
+    async publishRefusal(principal, key, action) {
+      const facts = await page(key)
+      if (!facts) return undefined
+      return refusalFor(principal, facts, await covering(facts), action)
+    },
+
+    async branchRefusal(principal, key) {
+      const root = await nodes.byKey(key)
+      if (!root) return undefined
+      const workflows = (await readWorkflows(db)).map((s) => s.workflow)
+      if (workflows.length === 0) return undefined
+      const below = await db.query<{ unique_id: string }>(
+        'SELECT unique_id FROM node WHERE id = ? OR path LIKE ? ORDER BY level',
+        [root.id, `${root.path},%`],
+      )
+      for (const row of below) {
+        const facts = await page(String(row.unique_id))
+        if (!facts) continue
+        const refusal = refusalFor(principal, facts, await covering(facts), 'publish')
+        if (refusal) return refusal
+      }
+      return undefined
+    },
+
+    async newPageRefusal(principal, parentKey, contentTypeKey) {
+      const parent = parentKey ? await page(parentKey) : undefined
+      const type = await db.query<{ alias: string }>(
+        'SELECT ct.alias FROM content_type ct JOIN node n ON n.id = ct.node_id WHERE n.unique_id = ?',
+        [normaliseUuid(contentTypeKey)],
+      )
+      const facts: PageFacts = {
+        key: '',
+        name: 'This page',
+        chain: parent?.chain ?? [],
+        contentTypeAlias: type[0]?.alias,
+      }
+      return refusalFor(principal, facts, await covering(facts), 'publish')
+    },
+
+    async beforeSave(principal, key) {
+      const request = await requests().waitingFor(key)
+      if (!request || principal.isAdmin) return undefined
+      const edit = request.workflow.onEdit
+      if (edit === 'lock')
+        return 'This page is waiting for approval and cannot be changed until it is decided.'
+      if (edit === 'lock-after-first-approval') {
+        const history = await requests().history(request.id)
+        if (history.some((h) => h.kind === 'approved'))
+          return 'This page has been approved by someone already, and cannot be changed until the request is decided.'
+      }
+      return undefined
+    },
+
+    async afterSave(principal, key) {
+      const repo = requests()
+      const request = await repo.waitingFor(key)
+      if (!request) return
+      const head =
+        (await new DocumentRepository(db, { nodeState: options.nodeState }).eventMarkers(key))
+          ?.head ?? null
+      if (head === request.eventId) return
+      // Administrators may always edit; the request goes on, on what they saved.
+      if (!principal.isAdmin && request.workflow.onEdit === 'withdraw') {
+        await repo.setState(request.id, 'withdrawn')
+        await repo.record(request.id, {
+          kind: 'withdrawn',
+          userKey: principal.id,
+          comment: 'the page was changed after it was sent',
+        })
+        return
+      }
+      await repo.setEvent(request.id, head)
+      await repo.record(request.id, { kind: 'edited', userKey: principal.id })
+    },
+
+    async send(principal, key, action, cultures, comment) {
+      const facts = await page(key)
+      if (!facts) throw new ApprovalRefused('The page could not be found.', 404)
+      const workflow = await covering(facts)
+      if (!workflow || !covers(workflow, action))
+        throw new ApprovalRefused(
+          action === 'publish'
+            ? 'No workflow covers this page: it can be published directly.'
+            : 'Taking this page down needs no approval.',
+        )
+      const stored = (await readWorkflows(db)).find(
+        (s) => (s.workflow.key ?? s.workflow.alias) === (workflow.key ?? workflow.alias),
+      )
+      const outcome = await db.transaction(async (tx) => {
+        const repo = requests(tx)
+        if (await repo.waitingFor(key))
+          throw new ApprovalRefused('This page is already waiting for approval.', 409)
+        const head =
+          (await new DocumentRepository(tx, { nodeState: options.nodeState }).eventMarkers(key))
+            ?.head ?? null
+        const request = await repo.create({
+          nodeKey: key,
+          cultures,
+          action,
+          eventId: head,
+          workflow,
+          workflowVersion: stored?.version ?? '',
+          requestedBy: principal.id,
+        })
+        await repo.record(request.id, {
+          kind: 'sent',
+          userKey: principal.id,
+          comment: comment?.trim() || null,
+        })
+        const first = startStages(workflow)
+        await reach(repo, request, first)
+        await notify(
+          'approvers',
+          request,
+          first,
+          `Waiting for your approval: ${facts.name}`,
+          `${principal.name} sent "${facts.name}" for approval through "${workflow.name}".${comment ? `\n\n${comment}` : ''}`,
+        )
+        const complete = await settle(repo, request)
+        await auditStep(
+          principal,
+          facts,
+          action === 'publish' ? 'Sent for approval' : 'Requested unpublish',
+          `through "${workflow.name}"`,
+        )
+        return { request, complete }
+      })
+      return concluded(principal, outcome)
+    },
+
+    async approve(principal, requestKey, stage, comment) {
+      const request = await waitingRequest(requestKey)
+      const current = await view(principal, request)
+      const target = stage ?? current.can.approve[0]
+      if (!target || !current.can.approve.includes(target))
+        throw new ApprovalRefused(
+          normaliseUuid(principal.id) === request.requestedBy &&
+            request.workflow.selfApproval === 'refused'
+            ? 'You made this change, so someone else has to approve it.'
+            : 'There is no stage waiting for your approval on this request.',
+          403,
+        )
+      if (needsComment(request.workflow, 'approve', comment))
+        throw new ApprovalRefused('This workflow asks for a comment with every decision.')
+      const outcome = await db.transaction(async (tx) => {
+        const repo = requests(tx)
+        const step = (await repo.steps(request.id)).find(
+          (s) => s.stage === target && s.state === 'waiting',
+        )
+        await repo.record(request.id, {
+          kind: 'approved',
+          stepId: step?.id ?? null,
+          stage: target,
+          userKey: principal.id,
+          comment: comment?.trim() || null,
+        })
+        const complete = await settle(repo, request)
+        await auditStep(
+          principal,
+          await page(request.nodeKey),
+          'Approved',
+          `stage "${target}" of "${request.workflow.name}"`,
+        )
+        return { request, complete }
+      })
+      return concluded(principal, outcome)
+    },
+
+    async sendBack(principal, requestKey, stage, comment) {
+      const request = await waitingRequest(requestKey)
+      const current = await view(principal, request)
+      const from = stage ?? current.can.sendBack[0]
+      if (!from || !current.can.sendBack.includes(from))
+        throw new ApprovalRefused(
+          'There is no stage waiting for your decision on this request.',
+          403,
+        )
+      if (needsComment(request.workflow, 'send-back', comment))
+        throw new ApprovalRefused('Say why it is being sent back.')
+      const to = stageOf(request.workflow, from)?.sendBack ?? SEND_BACK_TO_EDITOR
+      const outcome = await db.transaction(async (tx) => {
+        const repo = requests(tx)
+        let complete = false
+        const steps = await repo.steps(request.id)
+        await repo.record(request.id, {
+          kind: 'sent-back',
+          stage: from,
+          userKey: principal.id,
+          comment: comment?.trim() || null,
+        })
+        const facts = await page(request.nodeKey)
+        if (to === SEND_BACK_TO_EDITOR) {
+          for (const step of steps.filter((s) => s.state === 'waiting' || s.state === 'approved'))
+            await repo.setStepState(step.id, step.stage === from ? 'sent-back' : 'discarded')
+          await repo.setState(request.id, 'sent-back')
+          await notify(
+            'editor',
+            request,
+            [],
+            `Sent back: ${facts?.name ?? 'a page'}`,
+            `"${facts?.name}" was sent back${comment ? `:\n\n${comment}` : '.'}`,
+          )
+        } else {
+          // The stage it goes back to runs again, and so does everything after it.
+          const redo = new Set([to, ...descendantStages(request.workflow, to)])
+          for (const step of steps.filter(
+            (s) => (s.state === 'waiting' || s.state === 'approved') && redo.has(s.stage),
+          ))
+            await repo.setStepState(step.id, step.stage === from ? 'sent-back' : 'discarded')
+          await reach(repo, request, [to])
+          await notify(
+            'approvers',
+            request,
+            [to],
+            `Back for your approval: ${facts?.name ?? 'a page'}`,
+            `"${facts?.name}" was sent back to you${comment ? `:\n\n${comment}` : '.'}`,
+          )
+          complete = await settle(repo, request)
+        }
+        await auditStep(
+          principal,
+          facts,
+          'Sent back',
+          `from stage "${from}" of "${request.workflow.name}" to ${to === SEND_BACK_TO_EDITOR ? 'the editor' : `"${to}"`}`,
+        )
+        return { request, complete }
+      })
+      return concluded(principal, outcome)
+    },
+
+    async withdraw(principal, requestKey) {
+      const request = await waitingRequest(requestKey)
+      if (normaliseUuid(principal.id) !== request.requestedBy && !principal.isAdmin)
+        throw new ApprovalRefused(
+          'Only the person who sent it, or an administrator, can withdraw it.',
+          403,
+        )
+      await requests().setState(request.id, 'withdrawn')
+      await requests().record(request.id, { kind: 'withdrawn', userKey: principal.id })
+      await auditStep(
+        principal,
+        await page(request.nodeKey),
+        'Withdrew approval request',
+        `under "${request.workflow.name}"`,
+      )
+      return view(principal, (await requests().byKey(request.key)) as ApprovalRequest)
+    },
+
+    async forPage(principal, key) {
+      const facts = await page(key)
+      if (!facts) throw new ApprovalRefused('The page could not be found.', 404)
+      const workflow = await covering(facts)
+      const all = await requests().forNode(key)
+      const waiting = all.find((r) => r.state === 'waiting')
+      return {
+        workflow,
+        request: waiting ? await view(principal, waiting) : undefined,
+        past: await Promise.all(
+          all
+            .filter((r) => r !== waiting)
+            .slice(0, 10)
+            .map((r) => view(principal, r)),
+        ),
+        can: {
+          send: !waiting && covers(workflow, 'publish'),
+          requestUnpublish: !waiting && covers(workflow, 'unpublish'),
+          publishDirectly: refusalFor(principal, facts, workflow, 'publish') === undefined,
+        },
+      }
+    },
+
+    async waitingFor(principal) {
+      const out: RequestView[] = []
+      for (const request of await requests().waiting()) {
+        const v = await view(principal, request)
+        if (v.can.approve.length > 0 || v.can.sendBack.length > 0) out.push(v)
+      }
+      return out
+    },
+
+    async inFlight(principal) {
+      return Promise.all((await requests().waiting()).map((r) => view(principal, r)))
+    },
+
+    async finished(principal, skip, take) {
+      const page = await requests().finished(skip, take)
+      return {
+        total: page.total,
+        items: await Promise.all(page.items.map((r) => view(principal, r))),
+      }
+    },
+  }
+}

package/src/config.ts

@@ -272,6 +272,16 @@ export interface CromboloConfig {
    * deploy turns it off, and an install can decline it for itself.
    */
   applyBundleContentOnInstall: boolean
+  /**
+   * Whether the Packages section may install and remove packages on the running
+   * site (`bun add` on the node that served the request). Off, the Marketplace
+   * still lists packages and says to add them to `package.json` and deploy:
+   * what a site of several nodes, or of containers that start afresh, needs —
+   * an install there reaches one node and is lost at its next restart. On unless
+   * set, or unless a schema store is configured, which says the same thing
+   * about the nodes' disks. `CROMBOLO_RUNTIME_INSTALLS`.
+   */
+  runtimeInstalls: boolean
   /**
    * Where the Packages section's Marketplace sends someone browsing for
    * extensions. Never framed — npm refuses to be framed — so the native view
@@ -495,6 +505,8 @@ export function loadConfig(
     redirects: [],
     trackRedirects: Bun.env.CROMBOLO_TRACK_REDIRECTS !== 'false',
     applyBundleContentOnInstall: Bun.env.CROMBOLO_APPLY_BUNDLE_CONTENT !== 'false',
+    // Resolved again below, once it is known whether a store was configured.
+    runtimeInstalls: Bun.env.CROMBOLO_RUNTIME_INSTALLS !== 'false',
     seo: stripUndefined({
       sitemap: envFlag(Bun.env.CROMBOLO_SITEMAP),
       indexable: envFlag(Bun.env.CROMBOLO_INDEXABLE),
@@ -533,6 +545,15 @@ export function loadConfig(
   ) {
     merged.schemaWritable = true
   }
+  // Likewise a store says the nodes' disks do not last, so an install on one of
+  // them would not either. An explicit setting still wins.
+  if (
+    merged.schemaStore &&
+    Bun.env.CROMBOLO_RUNTIME_INSTALLS === undefined &&
+    overrides.runtimeInstalls === undefined
+  ) {
+    merged.runtimeInstalls = false
+  }
   // Relative paths are relative to the site, not to wherever the process started.
   merged.siteDir = resolve(cwd, merged.siteDir)
   // Against the site rather than the working directory: it has to sit where the
@@ -597,4 +618,4 @@ export function describeDatabase(
   }
 }
 
-export const VERSION = '0.12.1'
+export const VERSION = '0.13.1'

package/src/marketplace.ts

@@ -88,6 +88,11 @@ export interface MarketplaceOptions {
   applyContent?: (packageName: string) => Promise<ContentOutcome>
   /** The site's `applyBundleContentOnInstall`. */
   applyContentOnInstall?: boolean
+  /**
+   * False refuses installing and removing here: the dependency belongs in
+   * `package.json` and a deploy, so every node has it and it outlives a restart.
+   */
+  installs?: boolean
 }
 
 export interface InstallOutcome {
@@ -308,6 +313,7 @@ export function createMarketplace(options: MarketplaceOptions): Marketplace {
     },
 
     async install(name, version, request = {}) {
+      if (options.installs === false) return refusedHere(name, 'add')
       if (!isValidPackageName(name))
         return { ok: false, message: `'${name}' is not a package name npm would accept.` }
       if (version !== undefined && !isValidVersion(version))
@@ -365,6 +371,7 @@ export function createMarketplace(options: MarketplaceOptions): Marketplace {
     },
 
     async uninstall(name) {
+      if (options.installs === false) return refusedHere(name, 'remove')
       if (!isValidPackageName(name))
         return { ok: false, message: `'${name}' is not a package name npm would accept.` }
       const result = await install('remove', name, options.siteDir)
@@ -379,4 +386,15 @@ export function createMarketplace(options: MarketplaceOptions): Marketplace {
   }
 }
 
+/** What a site that does not install at runtime says instead, with what to do. */
+function refusedHere(name: string, verb: 'add' | 'remove'): InstallOutcome {
+  return {
+    ok: false,
+    message:
+      verb === 'add'
+        ? `Packages are not installed from the backoffice on this site. Add ${name} to the site's package.json (bun add ${name}) and deploy, so every server has it.`
+        : `Packages are not removed from the backoffice on this site. Remove ${name} from the site's package.json (bun remove ${name}) and deploy.`,
+  }
+}
+
 export { EXTENSION_KEYWORD }

package/src/ports.ts

@@ -70,6 +70,7 @@ import { createTemplateFileStore } from './adapters/template-files.ts'
 import { createTemplateQueryPort } from './adapters/template-query.ts'
 import { avatarUrls, createUserPorts } from './adapters/users.ts'
 import { createWebhookPort } from './adapters/webhooks.ts'
+import { createApprovals } from './approvals.ts'
 import { COMPONENT_SNIPPETS } from './component-snippets.ts'
 import { type CromboloConfig, type UserLinkSender, VERSION } from './config.ts'
 import { type EmailPort, resolveEmailPort } from './email.ts'
@@ -603,6 +604,20 @@ export function createDeps(options: DepsOptions): ManagementApiDeps {
         }),
         options.config.siteDir,
       )
+    if (deps.documents) {
+      const documents = deps.documents
+      deps.approvals = createApprovals({
+        db: options.db,
+        nodeState: options.schema?.nodeState,
+        email,
+        // Through the same port an editor's publish takes, so what approval
+        // publishes is cached, tracked and announced as any publish is.
+        publisher: {
+          publish: (key, cultures) => documents.publish(key, cultures),
+          unpublish: (key, cultures) => documents.unpublish(key, cultures),
+        },
+      })
+    }
   }
   return deps
 }

package/src/server.ts

@@ -84,6 +84,8 @@ import { createAuditHost, createAuditSink, pluginAuditPlan, recordAudit } from '
 import { readCreatedBundlePackage, writeCreatedBundlePackage } from './adapters/bundles.ts'
 import { createPublishedContentSource, loadDraftNode } from './adapters/documents.ts'
 import { createSchemaProposals } from './adapters/schema-proposals.ts'
+import type { Approvals } from './approvals.ts'
+import { handleApprovalsApi } from './approvals-api.ts'
 import { CommandError, installBundleContent } from './bundle-install.ts'
 import { bundleChains, bundleTablesReport } from './bundle-tables.ts'
 import { createBundleRedirects, createServerBundles, validateServerBundles } from './bundles.ts'
@@ -247,6 +249,7 @@ export async function createServer(config: CromboloConfig = loadConfig()): Promi
     contentApplied: async (packageName) =>
       (await new TransferRunRepository(db).appliedForPackage(packageName))?.packageVersion ?? null,
     applyContentOnInstall: config.applyBundleContentOnInstall,
+    installs: config.runtimeInstalls,
     applyContent: async (packageName) => {
       // A package from the marketplace is for anyone, so nothing in it can be
       // sealed; one that is is refused rather than half applied.
@@ -657,37 +660,36 @@ export async function createServer(config: CromboloConfig = loadConfig()): Promi
         }
       : undefined,
   })
-  const api = createManagementApiRouter({
-    deps: {
-      ...createDeps({
-        config,
-        paths,
-        extensions,
-        db,
-        webhooks,
-        cache,
-        schema,
-        mediaFiles,
-        email,
-        onSearchQueued: () => jobs.kickSearchIndexing(),
-        // This node looks again at once; the others are told to. The write has
-        // already landed wherever `componentsDir` points, so there is nothing to
-        // distribute — only the fact that it happened.
-        onViewsChange: async (alias) => {
-          // The snapshot first, and awaited: the hash announced is then the one
-          // this write produced rather than the generation it replaced, and the
-          // editor's next request renders what they just saved.
-          const hash = await snapshots.refresh()
-          void appendCacheInstruction(db, {
-            kind: 'components',
-            payload: hash ? { alias, hash } : { alias },
-            by: schema.nodeId,
-          }).catch((error: unknown) => {
-            renderLog.error('Could not announce the template {alias}: {error}', { alias, error })
-          })
-        },
-      }),
+  const managementDeps = createDeps({
+    config,
+    paths,
+    extensions,
+    db,
+    webhooks,
+    cache,
+    schema,
+    mediaFiles,
+    email,
+    onSearchQueued: () => jobs.kickSearchIndexing(),
+    // This node looks again at once; the others are told to. The write has
+    // already landed wherever `componentsDir` points, so there is nothing to
+    // distribute — only the fact that it happened.
+    onViewsChange: async (alias) => {
+      // The snapshot first, and awaited: the hash announced is then the one
+      // this write produced rather than the generation it replaced, and the
+      // editor's next request renders what they just saved.
+      const hash = await snapshots.refresh()
+      void appendCacheInstruction(db, {
+        kind: 'components',
+        payload: hash ? { alias, hash } : { alias },
+        by: schema.nodeId,
+      }).catch((error: unknown) => {
+        renderLog.error('Could not announce the template {alias}: {error}', { alias, error })
+      })
     },
+  })
+  const api = createManagementApiRouter({
+    deps: managementDeps,
     authenticate,
     nodes: createNodeLookup(db),
     allowLocalLogin: config.allowLocalLogin,
@@ -1089,6 +1091,7 @@ export async function createServer(config: CromboloConfig = loadConfig()): Promi
           url: marketplace.url(),
           keyword: config.packageKeyword,
           appliesContent: config.applyBundleContentOnInstall,
+          installs: config.runtimeInstalls,
           items: await marketplace.search(url.searchParams.get('q') ?? undefined),
         })
       }
@@ -1110,7 +1113,10 @@ export async function createServer(config: CromboloConfig = loadConfig()): Promi
       }
 
       if (action === 'installed' && request.method === 'GET') {
-        return Response.json({ items: await marketplace.installed() })
+        return Response.json({
+          installs: config.runtimeInstalls,
+          items: await marketplace.installed(),
+        })
       }
 
       if ((action === 'install' || action === 'uninstall') && request.method === 'POST') {
@@ -1460,6 +1466,43 @@ export async function createServer(config: CromboloConfig = loadConfig()): Promi
         : Response.json({ ok: false, message: outcome.message }, { status: outcome.status })
     }
 
+    // Non-contract: approval workflows (story 028) — the page's Workflow tab, the
+    // Workflow section and its designer. Content or Workflow, as either screen is.
+    if (pathname.startsWith(`${paths.pluginPath}/api/approvals/`)) {
+      const principal = await authenticate(request)
+      if (!principal) return new Response('Unauthorized', { status: 401 })
+      if (!hasSection(principal, 'content') && !hasSection(principal, 'workflow'))
+        return new Response('Forbidden', { status: 403 })
+      const approvals = managementDeps.approvals as Approvals | undefined
+      if (!approvals) return new Response('Not Found', { status: 404 })
+      const response = await handleApprovalsApi(
+        request,
+        pathname.slice(`${paths.pluginPath}/api/approvals/`.length),
+        {
+          db,
+          approvals,
+          principal,
+          schemaDir: config.schemaDir,
+          writable: config.schemaWritable,
+          onChanged: config.schemaStore
+            ? async () => {
+                await publishSchema(config.schemaStore as SchemaStore, config.schemaDir)
+              }
+            : undefined,
+        },
+      )
+      if (response) {
+        if (request.method !== 'GET')
+          log.info('{user} {verb} on approvals: {status}', {
+            user: principal.email,
+            verb: pathname.split('/').slice(-1)[0],
+            status: response.status,
+          })
+        return response
+      }
+      return new Response('Not Found', { status: 404 })
+    }
+
     // Non-contract, Packages: answering a content import's conflicts and running
     // it, from the Changes dashboard. Packages, because installing is.
     if (pathname.startsWith(`${paths.pluginPath}/api/transfers/`)) {