@crombolo/server 0.11.0 → 0.12.1

package/src/bundle-install.ts

@@ -25,11 +25,13 @@ import {
 } from '@crombolo/backoffice-host'
 import { ObjectTypes } from '@crombolo/core'
 import {
+  answersByNode,
   type Db,
   describeRefFailure,
   type NodeRow,
   recordInLedger,
   resolveNodeRef,
+  TransferAnswerRepository,
   writeReport,
 } from '@crombolo/data'
 import {
@@ -40,8 +42,15 @@ import {
   isPackageName,
   loadBundle,
   loadResolutions,
+  mergeResolutions,
+  type NodeResolutions,
+  openBundle,
   type Resolution,
+  rehearsePublish,
+  SealedFileError,
   type TransferCheck,
+  WrongPassphraseError,
+  writeResolutions,
 } from '@crombolo/transfer'
 import { type BackupResult, backupBefore } from './backup.ts'
 import {
@@ -75,6 +84,9 @@ export class CommandError extends Error {
   }
 }
 
+/** The bundle is encrypted, and the passphrase given does not open it, or none was. */
+export class PassphraseError extends CommandError {}
+
 export interface BundleSummary {
   id: string
   from: string
@@ -95,10 +107,14 @@ export interface ResolvedBundle {
   payloadDir: string
   /** Whether it was found as one of the site's dependencies rather than a directory. */
   dependency: boolean
+  /** The package's directory. */
+  directory: string
   set: ContentSet
   blobs: ReadonlyMap<string, string>
   /** The sections it carries beyond its content; empty for a content-only bundle. */
   carried: CarriedSections
+  /** A carried media file's bytes as exported: opened, when the bundle sealed them. */
+  openBlob: (key: string, bytes: Uint8Array) => Uint8Array
 }
 
 /** Where a package directory or a dependency's name points, before anything is read. */
@@ -122,7 +138,7 @@ function locate(target: string, siteDir: string): { directory: string; dependenc
  * The bundle a path or a package name names, read whole, or a refusal: a
  * half-copied bundle must never be checked as though complete.
  */
-export function readBundle(target: string, siteDir: string): ResolvedBundle {
+export function readBundle(target: string, siteDir: string, passphrase?: string): ResolvedBundle {
   const { directory, dependency } = locate(target, siteDir)
   const json = readPackageJson(join(directory, 'package.json'))
   if (!json) {
@@ -154,13 +170,34 @@ export function readBundle(target: string, siteDir: string): ResolvedBundle {
       'The bundle is incomplete or damaged; nothing was read from it.',
       problems,
     )
+  // Opened only when given the passphrase: without one the set stays sealed,
+  // and the check says what it needs rather than comparing what it cannot read.
+  let opened: ReturnType<typeof openBundle> = {
+    set: loaded.set,
+    people: undefined,
+    openBlob: (_key, bytes) => bytes,
+  }
+  if (passphrase !== undefined && passphrase !== '')
+    try {
+      opened = openBundle(loaded, passphrase)
+    } catch (error) {
+      if (error instanceof WrongPassphraseError)
+        throw new PassphraseError(
+          'The passphrase does not open this bundle; nothing was read from it.',
+        )
+      if (error instanceof SealedFileError)
+        throw new CommandError('The bundle is damaged; nothing was read from it.', [error.message])
+      throw error
+    }
   return {
     package: pkg,
     payloadDir: pkg.contentDir,
     dependency,
-    set: loaded.set,
+    directory,
+    set: opened.set,
     blobs: loaded.blobs,
     carried: carriedSections(loaded),
+    openBlob: opened.openBlob,
   }
 }
 
@@ -200,13 +237,22 @@ export interface TransferInput extends SectionOptions {
   bundle: string
   /** Where the bundle's roots go: a path or a key. */
   under?: string
-  /** A decision per node key, on top of any the bundle carries. */
-  resolutions?: Record<string, Resolution>
+  /** Decisions by node key, on top of any the bundle carries: `"*"` and per property. */
+  resolutions?: Record<string, NodeResolutions>
   resolveAll?: Resolution
   allowMissingBlobs?: boolean
+  /** Publish what was live at the source; the check then says which pages would be refused. */
+  publish?: boolean
+  /** Who asked, recorded on the pending import. */
+  by?: string
+  /** Opens what the bundle sealed; used for this request only, never stored. */
+  passphrase?: string
 }
 
-/** The options `check` and `import` share: saved decisions, then the caller's, then placement. */
+/**
+ * The options `check` and `import` share: the bundle's saved decisions, then
+ * those given in the backoffice, then the caller's; then placement.
+ */
 export async function transferOptions(
   db: Db,
   config: CromboloConfig,
@@ -214,7 +260,16 @@ export async function transferOptions(
   input: Omit<TransferInput, 'bundle'>,
 ): Promise<{ options: CheckOptions; under: NodeRow | undefined; problems: string[] }> {
   const saved = loadResolutions(bundle.payloadDir, bundle.set.manifest.id)
-  const resolutions = { ...(saved.file?.byNode ?? {}), ...(input.resolutions ?? {}) }
+  const answers = new TransferAnswerRepository(db)
+  const given = answersByNode(await answers.answers(bundle.set.manifest.id)) as Record<
+    string,
+    NodeResolutions
+  >
+  const pending = await answers.pending(bundle.set.manifest.id)
+  const resolutions = mergeResolutions(
+    mergeResolutions(saved.file?.byNode ?? {}, given),
+    input.resolutions ?? {},
+  )
   const resolveAll = input.resolveAll ?? saved.file?.all ?? undefined
   const underRef = input.under ?? saved.file?.under ?? undefined
   let under: NodeRow | undefined
@@ -232,7 +287,7 @@ export async function transferOptions(
       resolutions,
       resolveAll,
       componentAliases: componentAliasesIn(config.componentsDir),
-      allowMissingBlobs: input.allowMissingBlobs ?? false,
+      allowMissingBlobs: input.allowMissingBlobs ?? pending?.allowMissingBlobs ?? false,
       hasBlob: async (key: string) => Boolean(await store.get(key)),
       backOfficePath: config.backOfficePath,
     },
@@ -251,8 +306,10 @@ export interface ContentCheckResult {
   sections: SectionPlan | undefined
   /** Nothing outstanding: the bundle would import cleanly. */
   clean: boolean
+  /** With `publish`: the pages the import would not publish, and the reason publish gives. */
+  publishRefusals: { key: string; reason: string }[]
   /** The decisions this check ran with — the bundle's saved ones under the caller's. */
-  decisions: { all: Resolution | null; byNode: Record<string, Resolution> }
+  decisions: { all: Resolution | null; byNode: Record<string, NodeResolutions> }
   problems: string[]
 }
 
@@ -262,10 +319,30 @@ export async function checkBundleContent(
   config: CromboloConfig,
   input: TransferInput,
 ): Promise<ContentCheckResult> {
-  const bundle = readBundle(input.bundle, config.siteDir)
+  const bundle = readBundle(input.bundle, config.siteDir, input.passphrase)
   const set = bundle.set
   const prepared = await transferOptions(db, config, bundle, input)
   const check = await checkBundle(db, set, prepared.options)
+  await recordPending(db, bundle, input, prepared.options.allowMissingBlobs ?? false)
+  // Rehearsed rather than predicted, so the refusals are publish's own, word
+  // for word; only once nothing is outstanding, since the import stops there.
+  const refusals =
+    input.publish && check.outstanding.length === 0
+      ? ((await rehearsePublish(db, set, prepared.options)) ?? [])
+      : []
+  const names = new Map(set.nodes.map((node) => [node.key, node.variants[0]?.name ?? node.key]))
+  for (const refusal of refusals)
+    check.findings.push({
+      kind: 'auto',
+      code: 'publish-refused',
+      subjectType: 'document',
+      subjectKey: refusal.key,
+      subjectName: names.get(refusal.key) ?? refusal.key,
+      propertyAlias: null,
+      culture: null,
+      message: `"${names.get(refusal.key) ?? refusal.key}" would not be published: ${refusal.reason}`,
+      link: null,
+    })
   // Under this bundle's own scope, so two bundles in flight do not resolve each other's.
   await writeReport(db, check.findings, { source: 'transfer', scope: set.manifest.id })
   return {
@@ -277,9 +354,10 @@ export async function checkBundleContent(
       ? await planSections(db, config, bundle.carried, input)
       : undefined,
     clean: check.outstanding.length === 0,
+    publishRefusals: refusals,
     decisions: {
       all: prepared.options.resolveAll ?? null,
-      byNode: prepared.options.resolutions ?? {},
+      byNode: { ...(prepared.options.resolutions ?? {}) },
     },
     problems: prepared.problems,
   }
@@ -314,14 +392,66 @@ export interface ContentImportResult {
   problems: string[]
 }
 
+/**
+ * What the dashboard needs to run this bundle's import again: where it was
+ * found and what it was asked to do. A directory is this server's path.
+ */
+async function recordPending(
+  db: Db,
+  bundle: ResolvedBundle,
+  input: TransferInput,
+  allowMissingBlobs: boolean,
+): Promise<void> {
+  const manifest = bundle.set.manifest
+  await new TransferAnswerRepository(db).recordCheck({
+    bundleId: manifest.id,
+    label: manifest.label ?? (bundle.package.name || bundle.package.packageName),
+    target: bundle.dependency ? bundle.package.packageName : bundle.directory,
+    targetKind: bundle.dependency ? 'package' : 'directory',
+    under: input.under ?? null,
+    publish: input.publish ?? false,
+    allowMissingBlobs,
+    checkedAt: new Date(),
+    checkedBy: input.by ?? null,
+  })
+}
+
+/**
+ * The decisions an import of this bundle would run with — saved, then given
+ * in the backoffice — as the `resolutions.json` the CLI's `--save` writes.
+ */
+export async function pendingResolutionsFile(
+  db: Db,
+  config: CromboloConfig,
+  bundleId: string,
+): Promise<string | undefined> {
+  const pending = await new TransferAnswerRepository(db).pending(bundleId)
+  if (!pending) return undefined
+  const bundle = readBundle(pending.target, config.siteDir)
+  const saved = loadResolutions(bundle.payloadDir, bundleId)
+  const given = answersByNode(await new TransferAnswerRepository(db).answers(bundleId))
+  return writeResolutions({
+    bundleId,
+    under: pending.under ?? saved.file?.under ?? null,
+    all: saved.file?.all ?? null,
+    byNode: mergeResolutions(saved.file?.byNode ?? {}, given as Record<string, NodeResolutions>),
+  })
+}
+
 /** Back up, re-check, then apply in one transaction and record the run. */
 export async function installBundleContent(
   db: Db,
   config: CromboloConfig,
   input: ContentImportInput,
 ): Promise<ContentImportResult> {
-  const bundle = readBundle(input.bundle, config.siteDir)
+  const bundle = readBundle(input.bundle, config.siteDir, input.passphrase)
   const { set, blobs, carried } = bundle
+  // Before the backup and the sections: nothing of a bundle that cannot be
+  // opened is applied.
+  if (set.sealed)
+    throw new PassphraseError(
+      'This bundle is encrypted: give the passphrase it was exported with. Nothing was written.',
+    )
   // The coarse layer, under the fine-grained revert: in-place conversion is not
   // reversible by itself, so the same rule as `upgrade` applies here.
   const backup = await backupBefore(config, {
@@ -402,10 +532,15 @@ export async function installBundleContent(
     problems: prepared.problems,
     sections,
   }
-  if (!result.runId) return outcome
+  if (!result.runId) {
+    await recordPending(db, bundle, input, prepared.options.allowMissingBlobs ?? false)
+    return outcome
+  }
+  await new TransferAnswerRepository(db).clear(set.manifest.id)
   // The backups become the run's, so `content revert` can find them.
   if (staging) outcome.replacedFilesKept = promoteBackups(config, staging, result.runId)
-  if (blobs.size > 0) outcome.blobs = await placeBlobs(await mediaStoreFor(config), blobs)
+  if (blobs.size > 0)
+    outcome.blobs = await placeBlobs(await mediaStoreFor(config), blobs, bundle.openBlob)
   await recordInLedger(db, {
     name: `content import ${set.manifest.id}`,
     kind: 'transfer',

package/src/bundles.ts

@@ -40,6 +40,7 @@
  * Deliberately not offered: raw SQL, a `Db`, and anything that writes the
  * site's files.
  */
+
 import { hasCultureAccess, hasSection, type Principal } from '@crombolo/api-management'
 import { BUNDLE_ID, type BundlePackage, peerRangeProblem } from '@crombolo/backoffice-host'
 import {
@@ -60,6 +61,8 @@ import {
   type RedirectTargetKind,
 } from '@crombolo/data'
 import { normaliseRedirectPath, type PublishedCache } from '@crombolo/render'
+import type { BundleForms } from './form-types.ts'
+import type { BundleEvents } from './webhooks.ts'
 
 /** The segment every bundle's routes hang below, inside the plugin API. */
 export const BUNDLE_API_SEGMENT = 'bundle'
@@ -232,6 +235,17 @@ export interface ServerBundle<
   routes: readonly ServerBundleRoute<C, T>[]
   /** Tables the bundle owns, from `defineBundleTables`, under its own id. */
   tables?: T
+  /**
+   * Form field and workflow types it adds. Unlike its routes and tables these
+   * are honoured on every node, because forms render and submit on `web` nodes.
+   */
+  forms?: BundleForms
+  /**
+   * Handlers for webhook events, by alias. Each event reaches each handler
+   * through the webhook delivery queue: once per cluster, after the change,
+   * retried on failure, and in the delivery log (docs/webhooks.md).
+   */
+  events?: BundleEvents
 }
 
 /** A bundle as mounted, with the prefix its routes answer below. */

package/src/busy.ts

@@ -0,0 +1,13 @@
+/** Contention a write could not get past, answered as a retryable 503 rather than a 500. */
+import { problemResponse, serviceBusy } from '@crombolo/core'
+import { ContentBusyError, classifyContention } from '@crombolo/data'
+
+/** The response for an error that is lock contention; undefined for anything else. */
+export function busyResponse(error: unknown): Response | undefined {
+  const contention = classifyContention(error)
+  if (!contention) return undefined
+  const busy = error instanceof ContentBusyError ? error : new ContentBusyError(contention)
+  return problemResponse(serviceBusy(busy.message), {
+    'retry-after': String(busy.retryAfterSeconds),
+  })
+}

package/src/config.ts

@@ -1,5 +1,6 @@
 import { hostname, tmpdir } from 'node:os'
 import { join, resolve } from 'node:path'
+import type { DeliveryApiOptions } from '@crombolo/api-delivery'
 import { DEFAULT_BACKOFFICE_PATH } from '@crombolo/core'
 import { DEFAULT_RENDER_TIMEOUT_MS, type RedirectRule, type SnapshotLimits } from '@crombolo/render'
 import type { AssistantConfig } from './assistant.ts'
@@ -65,8 +66,15 @@ export interface CromboloConfig {
   /** SQLite file, or ':memory:'. Ignored when CROMBOLO_DB=postgres. */
   sqliteFile: string
   adminLogin: string
-  /** When unset, a password is generated on first run and printed once. */
+  /**
+   * Seeds the first administrator of a fresh database. Unset in development, one
+   * is generated and printed; unset in production, the site waits to be set up.
+   */
   adminPassword: string | undefined
+  /** Guards "Set up your new site". Chosen by the owner; never printed, logged or shown. */
+  setupCode: string | undefined
+  /** Seals secrets kept in the database, such as a webhook's headers; never stored. */
+  secretKey: string | undefined
   /**
    * The `__Host-` cookie prefix requires Secure. Browsers treat http://localhost
    * as secure, so this stays on in local development.
@@ -242,6 +250,13 @@ export interface CromboloConfig {
    * answers on. Every field may also be set in the backoffice, which wins.
    */
   seo: SeoConfig
+  /**
+   * Umbraco's Delivery API (`docs/delivery-api.md`): off unless enabled.
+   * `CROMBOLO_DELIVERY_API`, `CROMBOLO_DELIVERY_API_KEY`,
+   * `CROMBOLO_DELIVERY_API_PUBLIC` and `CROMBOLO_DELIVERY_API_MEDIA`; member
+   * sign-in is configured here, since its clients and secrets are a list.
+   */
+  deliveryApi: DeliveryApiOptions
   /**
    * Bundles whose server half this site runs, each the result of calling the
    * factory its package exports. Imported and listed here by hand on purpose:
@@ -393,6 +408,8 @@ export function loadConfig(
     sqliteFile: Bun.env.CROMBOLO_SQLITE_FILE ?? DEFAULTS.sqliteFile,
     adminLogin: Bun.env.CROMBOLO_ADMIN_LOGIN ?? DEFAULTS.adminLogin,
     adminPassword: Bun.env.CROMBOLO_ADMIN_PASSWORD,
+    setupCode: Bun.env.CROMBOLO_SETUP_CODE,
+    secretKey: Bun.env.CROMBOLO_SECRET_KEY,
     secureCookies: Bun.env.CROMBOLO_INSECURE_COOKIES !== 'true',
     siteName: Bun.env.CROMBOLO_SITE_NAME ?? DEFAULTS.siteName,
     siteDir: cwd,
@@ -482,6 +499,15 @@ export function loadConfig(
       sitemap: envFlag(Bun.env.CROMBOLO_SITEMAP),
       indexable: envFlag(Bun.env.CROMBOLO_INDEXABLE),
     }),
+    deliveryApi: stripUndefined({
+      enabled: envFlag(Bun.env.CROMBOLO_DELIVERY_API),
+      apiKey: Bun.env.CROMBOLO_DELIVERY_API_KEY || undefined,
+      publicAccess: envFlag(Bun.env.CROMBOLO_DELIVERY_API_PUBLIC),
+      media:
+        envFlag(Bun.env.CROMBOLO_DELIVERY_API_MEDIA) === undefined
+          ? undefined
+          : { enabled: envFlag(Bun.env.CROMBOLO_DELIVERY_API_MEDIA) },
+    }),
     // No environment variable: a bundle is an import, which is code.
     bundles: [],
     marketplaceUrl: Bun.env.CROMBOLO_MARKETPLACE_URL ?? DEFAULTS.marketplaceUrl,
@@ -493,6 +519,11 @@ export function loadConfig(
   const merged: CromboloConfig = { ...fromEnv, ...stripUndefined(overrides) }
   // Field by field, so a site setting its title suffix keeps the environment's switches.
   merged.seo = { ...fromEnv.seo, ...stripUndefined(overrides.seo ?? {}) }
+  merged.deliveryApi = {
+    ...fromEnv.deliveryApi,
+    ...stripUndefined(overrides.deliveryApi ?? {}),
+    media: { ...fromEnv.deliveryApi.media, ...(overrides.deliveryApi?.media ?? {}) },
+  }
   // A schema store makes backoffice writes durable, so it carries writability with
   // it — that is the point of configuring one. An explicit setting still wins.
   if (
@@ -566,4 +597,4 @@ export function describeDatabase(
   }
 }
 
-export const VERSION = '0.11.0'
+export const VERSION = '0.12.1'

package/src/database.ts

@@ -14,6 +14,7 @@ import {
   ensureSystemMediaTypes,
   ensureSystemMemberTypes,
   INITIAL_STATE,
+  markSetupPending,
   migrate,
   pendingMigrations,
   readState,
@@ -125,17 +126,18 @@ export async function installDatabase(
   // Core first, so a bundle step always runs against a core it declared itself compatible with.
   await migrateBundles(db, chains, { by: config.nodeId })
 
+  // In production a password is never made up: the pipeline supplies one, or
+  // the owner sets the site up in the browser (docs/operations.md).
+  const settingUp = !config.development && !config.adminPassword
   const password = config.adminPassword ?? crypto.randomUUID().replaceAll('-', '').slice(0, 20)
   const seeded = await seedIdentity(db, {
-    admin: {
-      name: 'Administrator',
-      login: config.adminLogin,
-      email: config.adminLogin,
-      password,
-    },
+    admin: settingUp
+      ? undefined
+      : { name: 'Administrator', login: config.adminLogin, email: config.adminLogin, password },
     hashPassword,
     passwordConfig: passwordConfigJson(),
   })
+  if (seeded && settingUp) await markSetupPending(db)
 
   await seedContent(db)
   // A database from an older version gains the built-ins it lacks.
@@ -144,5 +146,5 @@ export async function installDatabase(
   await ensureSystemMemberTypes(db)
   await ensureSystemContentTypes(db)
 
-  return seeded && !config.adminPassword ? password : undefined
+  return seeded && !settingUp && !config.adminPassword ? password : undefined
 }