@crombolo/server 0.11.0 → 0.13.1

package/src/models-builder.ts

@@ -7,6 +7,7 @@
  * "out of date" is answered by generating the types and comparing them with
  * what is on disk, which cannot drift from the question being asked.
  */
+
 import { existsSync } from 'node:fs'
 import { readFile, writeFile } from 'node:fs/promises'
 import { join, relative } from 'node:path'
@@ -15,9 +16,11 @@ import type {
   ModelsBuilderPort,
   OutOfDateStatus,
 } from '@crombolo/api-management'
+import type { FormTypes } from '@crombolo/core'
 import { generateTypes, loadSchemaDirectory, validateSchemaSet } from '@crombolo/schema'
 import type { CromboloConfig } from './config.ts'
 import { VERSION } from './config.ts'
+import { formTypesFor } from './form-types.ts'
 import { logger } from './logging.ts'
 
 /** The file `crombolo generate` writes, inside the schema directory. */
@@ -26,10 +29,10 @@ export const GENERATED_FILE = 'content-types.d.ts'
 export type Intended = { types: string } | { problems: string[] }
 
 /** What `crombolo generate` would write now, or the problems stopping it. */
-export function intendedTypes(schemaDir: string): Intended {
+export function intendedTypes(schemaDir: string, formTypes?: FormTypes): Intended {
   if (!existsSync(schemaDir)) return { problems: [`No schema directory at ${schemaDir}`] }
-  const loaded = loadSchemaDirectory(schemaDir)
-  const problems = [...loaded.problems, ...validateSchemaSet(loaded.set)]
+  const loaded = loadSchemaDirectory(schemaDir, { formTypes })
+  const problems = [...loaded.problems, ...validateSchemaSet(loaded.set, { types: formTypes })]
   if (problems.length > 0)
     return {
       problems: problems.map((p) => `${p.file}${p.path ? ` (${p.path})` : ''}: ${p.message}`),
@@ -40,8 +43,9 @@ export function intendedTypes(schemaDir: string): Intended {
 /** Undefined when the schema does not generate, so staleness is unknowable. */
 export async function compareModels(
   schemaDir: string,
+  formTypes?: FormTypes,
 ): Promise<{ outOfDate: boolean } | undefined> {
-  const intended = intendedTypes(schemaDir)
+  const intended = intendedTypes(schemaDir, formTypes)
   if ('problems' in intended) return undefined
   const target = join(schemaDir, GENERATED_FILE)
   if (!existsSync(target)) return { outOfDate: true }
@@ -50,7 +54,7 @@ export async function compareModels(
 }
 
 export function createModelsBuilderPort(
-  config: Pick<CromboloConfig, 'schemaDir'>,
+  config: Pick<CromboloConfig, 'schemaDir'> & Partial<Pick<CromboloConfig, 'bundles'>>,
 ): ModelsBuilderPort {
   // Umbraco keeps the last generation error in memory and shows it on the
   // dashboard; a build that succeeds clears it.
@@ -58,7 +62,7 @@ export function createModelsBuilderPort(
   const log = logger('models-builder')
 
   const describe = async (): Promise<ModelsBuilderInfo> => {
-    const compared = await compareModels(config.schemaDir)
+    const compared = await compareModels(config.schemaDir, formTypesFor(config))
     return {
       // The models are TypeScript source, written on request: Umbraco's mode for
       // exactly that. The client only explains its own four mode strings.
@@ -78,13 +82,13 @@ export function createModelsBuilderPort(
     info: describe,
 
     async status(): Promise<OutOfDateStatus> {
-      const compared = await compareModels(config.schemaDir)
+      const compared = await compareModels(config.schemaDir, formTypesFor(config))
       if (!compared) return 'Unknown'
       return compared.outOfDate ? 'OutOfDate' : 'Current'
     },
 
     async build() {
-      const intended = intendedTypes(config.schemaDir)
+      const intended = intendedTypes(config.schemaDir, formTypesFor(config))
       if ('problems' in intended) {
         lastError = intended.problems.join('\n')
         log.warn('Models were not generated: {problems}', { problems: intended.problems.length })

package/src/ports.ts

@@ -1,16 +1,19 @@
 /** Implementations of the Management API ports. */
+
+import { resolveDeliveryApiSettings } from '@crombolo/api-delivery'
 import type {
   CurrentUserPort,
   LocalizationPort,
   ManagementApiDeps,
   ManifestPort,
   NodeLookup,
+  PreviewPort,
   Principal,
   ServerPort,
   TemporaryFilePort,
   UserItemPort,
 } from '@crombolo/api-management'
-import { AuthStore } from '@crombolo/auth'
+import { AuthStore, expireCookie, serializeCookie } from '@crombolo/auth'
 import {
   ASSISTANT_MANIFEST_ID,
   type BackOfficePaths,
@@ -28,6 +31,7 @@ import {
 import {
   ContentTypeRepository,
   type Db,
+  DynamicRootRepository,
   LanguageRepository,
   RedirectRepository,
   TagRepository,
@@ -48,12 +52,14 @@ import { createDictionaryPort } from './adapters/dictionary.ts'
 import { createDocumentPort } from './adapters/documents.ts'
 import { createElementPort } from './adapters/elements.ts'
 import { createFileSystemPort } from './adapters/file-system.ts'
+import { createDiagnosticsPort } from './adapters/health.ts'
 import { createMediaPort } from './adapters/media.ts'
 import { createMemberGroupPort } from './adapters/member-groups.ts'
 import { createMemberPort } from './adapters/members.ts'
 import { createPublicAccessPort } from './adapters/public-access.ts'
 import { createRedirectPort } from './adapters/redirects.ts'
 import { createReferencePort } from './adapters/references.ts'
+import { createRelationPort } from './adapters/relations.ts'
 import {
   createSchemaFileWriter,
   type SchemaFiles,
@@ -63,10 +69,13 @@ import { createSearchIndexPort } from './adapters/search-index.ts'
 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'
 import { createFileIntake } from './file-intake.ts'
+import { formTypesFor } from './form-types.ts'
 import { createLogViewerPort } from './log-viewer.ts'
 import { logger } from './logging.ts'
 import { MediaFileStore } from './media-files.ts'
@@ -75,6 +84,7 @@ import { createOEmbedService } from './oembed.ts'
 import { createRedirectTracker } from './redirects.ts'
 import { componentAliasesIn, type SchemaBoot } from './schema.ts'
 import { publishSchema } from './schema-store.ts'
+import { createWebhookService, type WebhookService } from './webhooks.ts'
 
 /** Re-exported for tests; the canonical list lives in @crombolo/core. */
 export const CORE_SECTIONS = CORE_SECTION_ALIASES
@@ -111,6 +121,18 @@ function createServerPort(config: CromboloConfig, canSendUserLinks: boolean): Se
   }
 }
 
+/** Umbraco's preview cookie; with a signed-in editor it turns on draft rendering. */
+export const PREVIEW_COOKIE = 'UMB_PREVIEW'
+
+function createPreviewPort(config: CromboloConfig): PreviewPort {
+  return {
+    enter: () => [
+      serializeCookie({ name: PREVIEW_COOKIE, value: 'preview', secure: config.secureCookies }),
+    ],
+    exit: () => [expireCookie(PREVIEW_COOKIE, config.secureCookies)],
+  }
+}
+
 function createManifestPort(
   paths: BackOfficePaths,
   extensions: ExtensionRegistry,
@@ -326,12 +348,13 @@ export function resolveUserLinkSender(
 }
 
 /** Where the backoffice writes schema files, and whether it may. */
-function schemaFiles(config: CromboloConfig): SchemaFiles {
+export function schemaFiles(config: CromboloConfig): SchemaFiles {
   const store = config.schemaStore
   return {
     schemaDir: config.schemaDir,
     writable: config.schemaWritable,
     componentAliases: () => componentAliasesIn(config.componentsDir),
+    formTypes: formTypesFor(config),
     // Only when a store is configured: a schema directory in a repository is
     // already where the files durably live.
     onChanged: store
@@ -359,6 +382,8 @@ export interface DepsOptions {
   extensions: ExtensionRegistry
   /** Omitted only by tests that exercise the contract without a database. */
   db?: Db
+  /** The site's webhooks, shared with the delivery job and the event source. */
+  webhooks?: WebhookService
   /** Required alongside `db` to serve documents, which invalidate the cache. */
   cache?: PublishedCache
   schema?: SchemaBoot
@@ -406,6 +431,7 @@ export function createDeps(options: DepsOptions): ManagementApiDeps {
   const sendUserLink = resolveUserLinkSender(options.config, email)
   const deps: ManagementApiDeps = {
     server: createServerPort(options.config, Boolean(sendUserLink)),
+    preview: createPreviewPort(options.config),
     // An unconfigured assistant contributes no extension, so the backoffice has
     // no drawer, no button and nothing to load.
     manifests: createManifestPort(
@@ -441,6 +467,16 @@ export function createDeps(options: DepsOptions): ManagementApiDeps {
   deps.stylesheets = createFileSystemPort(options.config.stylesheetsDir, { extension: '.css' })
   deps.scripts = createFileSystemPort(options.config.scriptsDir, { extension: '.js' })
   if (options.db) {
+    const dynamicRoots = new DynamicRootRepository(options.db)
+    deps.dynamicRoots = { resolve: (query) => dynamicRoots.resolve(query) }
+    deps.diagnostics = createDiagnosticsPort({
+      config: options.config,
+      db: options.db,
+      media: mediaFiles.store,
+      email,
+      nodeState: options.schema?.nodeState,
+      fetch: options.fetch,
+    })
     const tags = new TagRepository(options.db)
     deps.tags = { list: (filter) => tags.all(filter) }
     deps.users = createUserItemPort(options.db)
@@ -493,6 +529,9 @@ export function createDeps(options: DepsOptions): ManagementApiDeps {
       nodeState: options.schema?.nodeState,
       nodeId: options.schema?.nodeId,
       valueIntake,
+      apiMemberUserNames: resolveDeliveryApiSettings(
+        options.config.deliveryApi,
+      ).memberAuthorization.clientCredentialsFlow.associatedMembers.map((m) => m.userName),
     })
     deps.publicAccess = createPublicAccessPort(options.db, {
       onChange: () => options.cache?.invalidate(),
@@ -504,6 +543,17 @@ export function createDeps(options: DepsOptions): ManagementApiDeps {
       onChange: () => options.cache?.invalidate(),
     })
     deps.references = createReferencePort(options.db)
+    deps.relations = createRelationPort(options.db)
+    deps.webhooks = createWebhookPort(
+      options.webhooks ??
+        createWebhookService({
+          db: options.db,
+          schemaDir: options.config.schemaDir,
+          filesWritable: options.config.schemaWritable,
+          secretKey: options.config.secretKey,
+          bundles: options.config.bundles,
+        }),
+    )
     deps.redirects = createRedirectPort(options.db, options.cache, {
       isTracking: options.config.trackRedirects,
       onChange: () => options.cache?.invalidate(),
@@ -554,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/schema.ts

@@ -6,6 +6,7 @@
 
 import { existsSync, watch } from 'node:fs'
 import {
+  CACHE_INSTRUCTION_CHANNEL,
   type CacheInstructionKind,
   cacheInstructionsAfter,
   compareStates,
@@ -39,7 +40,8 @@ import {
   writeKeysBack,
 } from '@crombolo/schema'
 import { listComponents } from './components.ts'
-import type { CromboloConfig } from './config.ts'
+import { type CromboloConfig, VERSION } from './config.ts'
+import { formTypesFor } from './form-types.ts'
 import { logger } from './logging.ts'
 import { materialiseSchema } from './schema-store.ts'
 
@@ -72,7 +74,7 @@ export async function checkSchemaDirectory(
   node: { nodeId: string; revision: string },
   options: { set?: Record<string, unknown> } = {},
 ): Promise<CheckReport> {
-  const loaded = loadSchemaDirectory(config.schemaDir)
+  const loaded = loadSchemaDirectory(config.schemaDir, { formTypes: formTypesFor(config) })
   return runCheck(
     db,
     loaded,
@@ -108,6 +110,7 @@ export function syncOptionsFor(config: CromboloConfig): SyncOptions {
   return {
     mode: config.development ? 'development' : 'production',
     componentAliases: componentAliasesIn(config.componentsDir),
+    formTypes: formTypesFor(config),
   }
 }
 
@@ -121,7 +124,7 @@ export async function syncSchemaDirectory(
   // The files are read under the lock the backoffice's schema writes hold, so a
   // sync never applies a snapshot that a later backoffice change has overtaken.
   return db.locks.withLock(Locks.Schema, async () => {
-    const loaded = loadSchemaDirectory(config.schemaDir)
+    const loaded = loadSchemaDirectory(config.schemaDir, { formTypes: formTypesFor(config) })
     const report = await syncSchema(
       db,
       loaded,
@@ -145,15 +148,15 @@ export async function bootSchema(db: Db, config: CromboloConfig): Promise<Schema
   const nodeId = config.nodeId
   if (!existsSync(config.schemaDir)) {
     const nodeState = { version: '0', revision: config.schemaRevision }
-    await touchServer(db, { nodeId, ...nodeState, role: config.role })
+    await touchServer(db, { nodeId, ...nodeState, role: config.role, cromboloVersion: VERSION })
     await ensureSystemMediaTypes(db, { linkFolderChildren: true })
     await ensureSystemMemberTypes(db)
     await ensureSystemContentTypes(db)
     return { nodeState, nodeId, report: undefined, compatibilityMode: false }
   }
-  const loaded = loadSchemaDirectory(config.schemaDir)
+  const loaded = loadSchemaDirectory(config.schemaDir, { formTypes: formTypesFor(config) })
   const nodeState = { version: loaded.set.version, revision: config.schemaRevision }
-  await touchServer(db, { nodeId, ...nodeState, role: config.role })
+  await touchServer(db, { nodeId, ...nodeState, role: config.role, cromboloVersion: VERSION })
   if (!config.syncSchemaAtBoot)
     return { nodeState, nodeId, report: undefined, compatibilityMode: false }
 
@@ -246,11 +249,18 @@ export interface CachePollerOptions {
   onInstruction(kind: CacheInstructionKind, payload: Record<string, unknown>): void
 }
 
-/** Polls `cache_instruction` from where this node came in; own instructions are skipped. */
+/**
+ * Polls `cache_instruction` from where this node came in; own instructions are
+ * skipped. Where the database can notify, a write wakes it at once and the
+ * timer is only the fallback.
+ */
 export class CacheInstructionPoller {
   #options: CachePollerOptions
   #cursor = 0
   #timer: ReturnType<typeof setInterval> | undefined
+  #unlisten: (() => Promise<void>) | undefined
+  #running: Promise<number> | undefined
+  #queued: Promise<number> | undefined
   #behind = false
   #bootLedgerId = 0
   #readsUnsafe = false
@@ -287,11 +297,39 @@ export class CacheInstructionPoller {
     if (intervalMs > 0) {
       this.#timer = setInterval(() => void this.poll().catch(() => {}), intervalMs)
       this.#timer.unref()
+      // Without it the timer still delivers everything, only later.
+      this.#unlisten = await this.#options.db
+        .listen?.(CACHE_INSTRUCTION_CHANNEL, () => void this.poll().catch(() => {}))
+        .catch(() => undefined)
     }
   }
 
-  /** Returns how many foreign instructions were applied. */
-  async poll(): Promise<number> {
+  /**
+   * Returns how many foreign instructions were applied. One poll at a time: a
+   * call while one runs waits for a single follow-up, so a burst of wake-ups
+   * reads the table twice, not once each.
+   */
+  poll(): Promise<number> {
+    if (this.#queued) return this.#queued
+    if (!this.#running) return this.#start()
+    this.#queued = this.#running
+      .catch(() => 0)
+      .then(() => {
+        this.#queued = undefined
+        return this.#start()
+      })
+    return this.#queued
+  }
+
+  #start(): Promise<number> {
+    const run = this.#pollOnce().finally(() => {
+      if (this.#running === run) this.#running = undefined
+    })
+    this.#running = run
+    return run
+  }
+
+  async #pollOnce(): Promise<number> {
     const { db, nodeId, nodeState, onInstruction } = this.#options
     const instructions = await cacheInstructionsAfter(db, this.#cursor)
     let applied = 0
@@ -301,7 +339,12 @@ export class CacheInstructionPoller {
       onInstruction(instruction.kind, instruction.payload)
       applied += 1
     }
-    await touchServer(db, { nodeId, ...nodeState, role: this.#options.role })
+    await touchServer(db, {
+      nodeId,
+      ...nodeState,
+      role: this.#options.role,
+      cromboloVersion: VERSION,
+    })
     const current = await currentSchemaState(db)
     const behind = compareStates(nodeState, current) < 0
     if (behind && !this.#behind) onInstruction('schema', { stateId: current.id })
@@ -317,6 +360,8 @@ export class CacheInstructionPoller {
   stop(): void {
     if (this.#timer) clearInterval(this.#timer)
     this.#timer = undefined
+    void this.#unlisten?.().catch(() => {})
+    this.#unlisten = undefined
   }
 }
 
@@ -376,7 +421,9 @@ export async function importSchema(
 
   const report = await syncSchemaDirectory(db, config, node)
   if (report.action === 'applied') {
-    boot.nodeState.version = loadSchemaDirectory(config.schemaDir).set.version
+    boot.nodeState.version = loadSchemaDirectory(config.schemaDir, {
+      formTypes: formTypesFor(config),
+    }).set.version
     boot.nodeState.revision = config.schemaRevision
   }
   return {

package/src/secrets.ts

@@ -0,0 +1,36 @@
+/**
+ * Secrets kept in the database, sealed with `CROMBOLO_SECRET_KEY`: AES-256-GCM,
+ * so a value cannot be read or quietly altered without the key. The key lives
+ * only in the environment, so a database dump alone reveals nothing.
+ * docs/webhooks.md.
+ */
+import { createCipheriv, createDecipheriv, createHash, randomBytes } from 'node:crypto'
+
+export const SECRET_KEY_VARIABLE = 'CROMBOLO_SECRET_KEY'
+export const MIN_SECRET_KEY_LENGTH = 32
+
+const VERSION = 'v1'
+
+/** The configured key, or undefined when it is missing or too short to trust. */
+export function usableSecretKey(value: string | undefined): string | undefined {
+  return value && value.length >= MIN_SECRET_KEY_LENGTH ? value : undefined
+}
+
+const keyBytes = (key: string) => createHash('sha256').update(key, 'utf8').digest()
+
+export function sealSecret(plain: string, key: string): string {
+  const iv = randomBytes(12)
+  const cipher = createCipheriv('aes-256-gcm', keyBytes(key), iv)
+  const body = Buffer.concat([cipher.update(plain, 'utf8'), cipher.final()])
+  return `${VERSION}:${Buffer.concat([iv, cipher.getAuthTag(), body]).toString('base64')}`
+}
+
+/** Throws when the value was sealed with another key, or has been altered. */
+export function openSecret(sealed: string, key: string): string {
+  const [version, encoded] = sealed.split(':', 2)
+  if (version !== VERSION || !encoded) throw new Error('Not a sealed secret.')
+  const raw = Buffer.from(encoded, 'base64')
+  const decipher = createDecipheriv('aes-256-gcm', keyBytes(key), raw.subarray(0, 12))
+  decipher.setAuthTag(raw.subarray(12, 28))
+  return Buffer.concat([decipher.update(raw.subarray(28)), decipher.final()]).toString('utf8')
+}