@crombolo/server 0.11.0 → 0.12.1

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,12 @@ 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 { 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 +83,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 +120,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 +347,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 +381,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 +430,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 +466,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 +528,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 +542,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(),

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')
+}