@crombolo/server 0.13.2 → 0.14.4

package/src/config.ts

@@ -1,12 +1,17 @@
 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_BACKOFFICE_PATH,
+  DEFAULT_PASSWORD_CONFIGURATION,
+  isValidPassword,
+} from '@crombolo/core'
 import { DEFAULT_RENDER_TIMEOUT_MS, type RedirectRule, type SnapshotLimits } from '@crombolo/render'
 import type { AssistantConfig } from './assistant.ts'
 import type { ServerBundle } from './bundles.ts'
 import type { EmailPort } from './email.ts'
 import type { GitConfig } from './git-routes.ts'
+import { checkIdentityProviders, type IdentityProvider } from './identity-providers.ts'
 import type { MediaStore } from './media-store.ts'
 import type { SchemaStore } from './schema-store.ts'
 
@@ -29,6 +34,65 @@ export type UserLinkSender = (message: {
   message: string | null
 }) => Promise<void>
 
+export interface RemoteSettings {
+  enabled: boolean
+  /** The environment this server is, as the remote protocol names it. */
+  environment: string
+  /** A push here replaces something people rely on: it needs its own permission. */
+  protected: boolean
+  /** A push to a protected environment waits for another person's approval. */
+  approvals: boolean
+  /**
+   * The largest push file or media file a client may upload. Every other route
+   * keeps `maxRequestBodyBytes`, checked per request, since Bun's own limit is
+   * the server's.
+   */
+  maxUploadBytes: number
+}
+
+/** The prefix every API client id carries, as the Management API requires. */
+export const API_CLIENT_ID_PREFIX = 'crombolo-back-office-'
+
+/** Refuses a seeded API client that the Management API would refuse, naming the variable. */
+function checkApiClient(client: CromboloConfig['apiClient']): void {
+  if (!client) return
+  if (!client.id || !client.secret)
+    throw new Error(
+      'CROMBOLO_API_CLIENT_ID and CROMBOLO_API_CLIENT_SECRET go together: set both, or neither.',
+    )
+  if (
+    !client.id.startsWith(API_CLIENT_ID_PREFIX) ||
+    client.id.length <= API_CLIENT_ID_PREFIX.length
+  )
+    throw new Error(`CROMBOLO_API_CLIENT_ID must start with "${API_CLIENT_ID_PREFIX}".`)
+  if (!isValidPassword(client.secret))
+    throw new Error(
+      `CROMBOLO_API_CLIENT_SECRET must be at least ${DEFAULT_PASSWORD_CONFIGURATION.minimumPasswordLength} characters.`,
+    )
+}
+
+/**
+ * Whether this site runs on the developer's own machine: development, and an
+ * application URL that is unset or names localhost. What `localAdmin` needs.
+ */
+export function runsOnLocalhost(config: CromboloConfig): boolean {
+  if (!config.development) return false
+  if (!config.applicationUrl) return true
+  try {
+    const host = new URL(config.applicationUrl).hostname
+    return host === 'localhost' || host === '127.0.0.1' || host === '[::1]' || host === '::1'
+  } catch {
+    return false
+  }
+}
+
+/** The body limit to listen with: raised for remote uploads when the remote is on. */
+export function listeningBodyLimit(config: CromboloConfig): number {
+  return config.remote.enabled
+    ? Math.max(config.maxRequestBodyBytes, config.remote.maxUploadBytes)
+    : config.maxRequestBodyBytes
+}
+
 export interface CromboloConfig {
   port: number
   /** The largest request body the server will read, media uploads included. */
@@ -73,6 +137,20 @@ export interface CromboloConfig {
   adminPassword: string | undefined
   /** Guards "Set up your new site". Chosen by the owner; never printed, logged or shown. */
   setupCode: string | undefined
+  /**
+   * The API client an unattended install seeds (story 034), so a pipeline can
+   * administer a site whose backoffice only takes an identity provider. Seeded
+   * once and never rotated from here; the secret is never printed or logged.
+   * With it set, no password administrator is seeded unless `adminPassword` is
+   * — or `localAdmin` is, on a site running on localhost.
+   */
+  apiClient: { id: string; secret: string } | undefined
+  /**
+   * Seed the password administrator even with `apiClient` set, so local
+   * development keeps printing a sign-in. Honoured only on localhost
+   * (`runsOnLocalhost`); ignored, with a warning, anywhere else.
+   */
+  localAdmin: boolean
   /** Seals secrets kept in the database, such as a webhook's headers; never stored. */
   secretKey: string | undefined
   /**
@@ -232,6 +310,23 @@ export interface CromboloConfig {
   memberSessionMinutes: number
   /** Failed sign-ins that lock a member out; Umbraco's default is 5. 0 never locks out. */
   maxFailedPasswordAttempts: number
+  /**
+   * Identity providers members may sign in with on the site: `entra()`,
+   * `awsIdentityCenter()`, `oidc()`. Separate from the backoffice's, so staff
+   * and members can sign in through different ones.
+   */
+  memberIdentityProviders: readonly IdentityProvider[]
+  /** Identity providers backoffice users may sign in with. `allowLocalLogin: false` makes them the only way in. */
+  backofficeIdentityProviders: readonly IdentityProvider[]
+  /**
+   * Answering the remote protocol (story 107): a developer's `crombolo` pulls a
+   * copy of this site and pushes work back. Off unless `enabled`. This server
+   * offers one environment, itself, named `environment`; `protected` makes a
+   * push need the protected-push permission, and `approvals` makes it wait for
+   * someone else with that permission to approve it, which needs
+   * `CROMBOLO_SECRET_KEY`. docs/remote-protocol.md.
+   */
+  remote: RemoteSettings
   /**
    * Redirects the site declares itself, built with `redirect()`. They are synced
    * into the database at boot, so the backoffice lists them beside the tracked
@@ -418,6 +513,14 @@ 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,
+    apiClient:
+      Bun.env.CROMBOLO_API_CLIENT_ID || Bun.env.CROMBOLO_API_CLIENT_SECRET
+        ? {
+            id: Bun.env.CROMBOLO_API_CLIENT_ID ?? '',
+            secret: Bun.env.CROMBOLO_API_CLIENT_SECRET ?? '',
+          }
+        : undefined,
+    localAdmin: Bun.env.CROMBOLO_LOCAL_ADMIN === 'true',
     setupCode: Bun.env.CROMBOLO_SETUP_CODE,
     secretKey: Bun.env.CROMBOLO_SECRET_KEY,
     secureCookies: Bun.env.CROMBOLO_INSECURE_COOKIES !== 'true',
@@ -502,6 +605,16 @@ export function loadConfig(
     maxFailedPasswordAttempts: Number(
       Bun.env.CROMBOLO_MAX_FAILED_PASSWORD_ATTEMPTS ?? DEFAULTS.maxFailedPasswordAttempts,
     ),
+    // No environment variable: a provider is a preset, which is code.
+    memberIdentityProviders: [],
+    backofficeIdentityProviders: [],
+    remote: {
+      enabled: Bun.env.CROMBOLO_REMOTE_ENABLED === 'true',
+      environment: Bun.env.CROMBOLO_REMOTE_ENVIRONMENT || 'production',
+      protected: Bun.env.CROMBOLO_REMOTE_PROTECTED !== 'false',
+      approvals: Bun.env.CROMBOLO_REMOTE_APPROVALS === 'true',
+      maxUploadBytes: Number(Bun.env.CROMBOLO_REMOTE_MAX_UPLOAD_GB ?? 50) * 1024 ** 3,
+    },
     redirects: [],
     trackRedirects: Bun.env.CROMBOLO_TRACK_REDIRECTS !== 'false',
     applyBundleContentOnInstall: Bun.env.CROMBOLO_APPLY_BUNDLE_CONTENT !== 'false',
@@ -529,8 +642,16 @@ export function loadConfig(
     assistant: undefined,
   }
   const merged: CromboloConfig = { ...fromEnv, ...stripUndefined(overrides) }
+  checkIdentityProviders(merged.memberIdentityProviders, 'member')
+  checkIdentityProviders(merged.backofficeIdentityProviders, 'backoffice')
   // Field by field, so a site setting its title suffix keeps the environment's switches.
   merged.seo = { ...fromEnv.seo, ...stripUndefined(overrides.seo ?? {}) }
+  merged.remote = { ...fromEnv.remote, ...stripUndefined(overrides.remote ?? {}) }
+  checkApiClient(merged.apiClient)
+  if (!/^[a-z][a-z0-9-]{0,62}$/.test(merged.remote.environment))
+    throw new Error(
+      `remote.environment "${merged.remote.environment}" must be lower case letters, digits and dashes.`,
+    )
   merged.deliveryApi = {
     ...fromEnv.deliveryApi,
     ...stripUndefined(overrides.deliveryApi ?? {}),
@@ -618,4 +739,4 @@ export function describeDatabase(
   }
 }
 
-export const VERSION = '0.13.2'
+export const VERSION = '0.14.4'

package/src/database.ts

@@ -21,8 +21,10 @@ import {
   seedContent,
   seedIdentity,
 } from '@crombolo/data'
+import { ensureApiClient } from './api-client.ts'
 import { type BundleChain, migrateBundles, pendingBundleSteps } from './bundle-tables.ts'
-import type { CromboloConfig } from './config.ts'
+import { type CromboloConfig, runsOnLocalhost } from './config.ts'
+import { logger } from './logging.ts'
 
 /** Production never auto-upgrades: an existing database with steps pending refuses to boot. */
 export class UpgradePendingError extends Error {
@@ -127,17 +129,28 @@ export async function installDatabase(
   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)
+  // the owner sets the site up in the browser (docs/operations.md). With an API
+  // client to seed (story 034) a machine administers the site instead, and no
+  // password administrator exists unless asked for — `adminPassword`, or
+  // `localAdmin` on the developer's own machine.
+  const localAdmin = config.localAdmin && runsOnLocalhost(config)
+  if (config.localAdmin && !localAdmin)
+    logger('install').warning(
+      'CROMBOLO_LOCAL_ADMIN is ignored: this site does not run on localhost',
+    )
+  const machineOnly = config.apiClient !== undefined && !config.adminPassword && !localAdmin
+  const settingUp = !machineOnly && !config.development && !config.adminPassword
+  const password = config.adminPassword || crypto.randomUUID().replaceAll('-', '').slice(0, 20)
   const seeded = await seedIdentity(db, {
-    admin: settingUp
-      ? undefined
-      : { name: 'Administrator', login: config.adminLogin, email: config.adminLogin, password },
+    admin:
+      settingUp || machineOnly
+        ? undefined
+        : { name: 'Administrator', login: config.adminLogin, email: config.adminLogin, password },
     hashPassword,
     passwordConfig: passwordConfigJson(),
   })
   if (seeded && settingUp) await markSetupPending(db)
+  if (config.apiClient) await ensureApiClient(db, config.apiClient)
 
   await seedContent(db)
   // A database from an older version gains the built-ins it lacks.
@@ -146,5 +159,5 @@ export async function installDatabase(
   await ensureSystemMemberTypes(db)
   await ensureSystemContentTypes(db)
 
-  return seeded && !settingUp && !config.adminPassword ? password : undefined
+  return seeded && !settingUp && !machineOnly && !config.adminPassword ? password : undefined
 }

package/src/delivery-members.ts

@@ -39,7 +39,7 @@ const tokenError = (error: string, description: string, status = 400) =>
     { error, error_description: description },
     {
       status,
-      headers: status === 401 ? { 'www-authenticate': 'Basic realm="Umbraco"' } : undefined,
+      headers: status === 401 ? { 'www-authenticate': 'Basic realm="Crombolo"' } : undefined,
     },
   )
 
@@ -83,7 +83,7 @@ export interface DeliveryMemberSecurity {
 export function createDeliveryMemberSecurity(options: {
   db: Db
   settings: DeliveryApiSettings
-  members: Pick<MemberAuth, 'resolve' | 'signOutCookie'>
+  members: Pick<MemberAuth, 'resolve' | 'signOutCookie' | 'externalSignInUrl'>
 }): DeliveryMemberSecurity {
   const { db, settings } = options
   const tokens = new DeliveryMemberTokenRepository(db)
@@ -175,6 +175,15 @@ export function createDeliveryMemberSecurity(options: {
 
     const signedIn = await options.members.resolve(request)
     if (!signedIn) {
+      // `identity_provider` names a member provider, as Umbraco's
+      // `UmbracoMembers.{id}` scheme or by its id: straight there, then back here.
+      const named = q('identity_provider').replace(/^UmbracoMembers\./i, '')
+      if (named) {
+        const external = options.members.externalSignInUrl(named, `${url.pathname}${url.search}`)
+        if (!external)
+          return local('invalid_request', "The specified 'identity_provider' is not configured.")
+        return new Response(null, { status: 302, headers: { location: external } })
+      }
       if (!code.loginPage)
         return local(
           'login_required',

package/src/external-sign-in.ts

@@ -0,0 +1,270 @@
+/**
+ * Signing in through an external identity provider (story 031), for members on
+ * the site and users in the backoffice alike: the browser leaves for the
+ * provider and comes back to a callback, which verifies who signed in, finds or
+ * links or creates their account, makes their groups follow the provider, and
+ * ends exactly as a password sign-in does. docs/operations.md.
+ *
+ *   GET {base}/{provider}?returnUrl=…   leave for the provider
+ *   GET {base}/{provider}/callback      come back from it
+ */
+import {
+  OidcClient,
+  OidcError,
+  type OidcIdentity,
+  readCookie,
+  readFlowState,
+  serializeCookie,
+  signFlowState,
+} from '@crombolo/auth'
+import { localReturnUrl } from '@crombolo/core'
+import {
+  type Db,
+  type ExternalLoginAudience,
+  ExternalLoginRepository,
+  ensureKeyValue,
+  externalLoginProvider,
+} from '@crombolo/data'
+import type { IdentityProvider } from './identity-providers.ts'
+
+/** A member or user, as far as signing in is concerned. */
+export interface ExternalAccount {
+  key: string
+  email: string
+  /** Member group names, or user group aliases. */
+  groups: readonly string[]
+}
+
+/** What a first sign-in through a provider comes to. Pure. */
+export type SignInDecision =
+  | { kind: 'signIn'; ownerKey: string }
+  | { kind: 'link'; ownerKey: string }
+  | { kind: 'create' }
+  | { kind: 'refuse'; reason: string }
+
+/**
+ * Who a provider's sign-in is, given who is already linked to it and who has
+ * its email. An account already linked signs in. Otherwise an account with the
+ * same email is linked only when the provider allows it and vouches for the
+ * email; it is never merged otherwise. Nobody at all is created, when allowed.
+ */
+export function decideSignIn(input: {
+  linked: string | undefined
+  sameEmail: string | undefined
+  identity: Pick<OidcIdentity, 'email' | 'emailVerified'>
+  provider: Pick<IdentityProvider, 'autoCreate' | 'linkByEmail' | 'emailsVerified'> & {
+    name: string
+  }
+}): SignInDecision {
+  const { linked, sameEmail, identity, provider } = input
+  if (linked) return { kind: 'signIn', ownerKey: linked }
+  if (!identity.email)
+    return { kind: 'refuse', reason: `${provider.name} did not say what your email address is.` }
+  if (sameEmail) {
+    const verified = identity.emailVerified || provider.emailsVerified
+    if (provider.linkByEmail && verified) return { kind: 'link', ownerKey: sameEmail }
+    return {
+      kind: 'refuse',
+      reason:
+        'An account with this email address already exists. Sign in the way you usually do, or ask for the two to be linked.',
+    }
+  }
+  if (!provider.autoCreate)
+    return { kind: 'refuse', reason: `No account here is linked to your ${provider.name} sign-in.` }
+  return { kind: 'create' }
+}
+
+/**
+ * An account's groups once the provider's claim is applied: the groups the
+ * mapping manages are made to match the claim, and every other group is kept.
+ * Pure.
+ */
+export function syncedGroups(
+  current: readonly string[],
+  claimValues: readonly string[],
+  map: Readonly<Record<string, string>>,
+): string[] {
+  const managed = new Set(Object.values(map).map((g) => g.toLowerCase()))
+  const wanted = claimValues.flatMap((value) => (map[value] ? [map[value]] : []))
+  const kept = current.filter((group) => !managed.has(group.toLowerCase()))
+  const out: string[] = []
+  for (const group of [...kept, ...wanted])
+    if (!out.some((g) => g.toLowerCase() === group.toLowerCase())) out.push(group)
+  return out
+}
+
+/** What one audience — members or users — does at each step. */
+export interface ExternalSignInAudience {
+  audience: ExternalLoginAudience
+  providers: readonly IdentityProvider[]
+  /** Where the routes answer: `{base}/{provider}` and `{base}/{provider}/callback`. */
+  basePath: string
+  byKey(key: string): Promise<ExternalAccount | undefined>
+  byEmail(email: string): Promise<ExternalAccount | undefined>
+  create(
+    identity: OidcIdentity,
+    provider: IdentityProvider,
+    groups: string[],
+  ): Promise<ExternalAccount>
+  setGroups(account: ExternalAccount, groups: string[]): Promise<void>
+  /** Signs the account in: the cookies to set, or why it may not. */
+  signIn(
+    account: ExternalAccount,
+    request: Request,
+  ): Promise<{ cookies: string[] } | { refused: string }>
+  /** Where a sign-in goes back to when it fails, with the reason to show. */
+  failed(returnUrl: string, reason: string): string
+}
+
+export interface ExternalSignIn {
+  /** The provider URL to start a sign-in, for a link or button. */
+  startUrl(providerId: string, returnUrl?: string): string
+  handle(request: Request, pathname: string): Promise<Response | undefined>
+}
+
+const FLOW_KEY = 'crombolo/externalLoginKey'
+
+export function createExternalSignIn(
+  db: Db,
+  audience: ExternalSignInAudience,
+  options: {
+    applicationUrl: string
+    secureCookies: boolean
+    log?: (message: string) => void
+    /** The provider as a sign-in uses it, with an administrator's overrides on top (story 033). */
+    resolve?: (provider: IdentityProvider) => Promise<IdentityProvider>
+  },
+): ExternalSignIn {
+  const logins = new ExternalLoginRepository(db)
+  // One client per effective configuration, so discovery stays cached until a
+  // setting changes, and a changed one is used at once.
+  const clients = new Map<string, OidcClient>()
+  const clientFor = (provider: IdentityProvider) => {
+    const key = JSON.stringify(provider.oidc)
+    let client = clients.get(key)
+    if (!client) {
+      client = new OidcClient(provider.oidc)
+      clients.set(key, client)
+    }
+    return client
+  }
+  const byId = new Map(audience.providers.map((provider) => [provider.oidc.id, provider]))
+  let key: Promise<string> | undefined
+  const secret = () => {
+    key ??= ensureKeyValue(db, FLOW_KEY, () => crypto.randomUUID())
+    return key
+  }
+  const flowCookie = `crombolo-external-${audience.audience}`
+  const originOf = (request: Request) =>
+    (options.applicationUrl || new URL(request.url).origin).replace(/\/$/, '')
+  const callbackUrl = (request: Request, id: string) =>
+    `${originOf(request)}${audience.basePath}/${id}/callback`
+  const redirect = (location: string, cookies: string[] = []) => {
+    const headers = new Headers({ location })
+    for (const cookie of cookies) headers.append('set-cookie', cookie)
+    return new Response(null, { status: 302, headers })
+  }
+  // Lax (as every cookie here is), not Strict: the provider sends the browser
+  // back with a top-level GET, which a Strict cookie would not ride along on.
+  const flowCookieValue = (value: string, maxAgeSeconds: number) =>
+    serializeCookie({
+      name: flowCookie,
+      value,
+      secure: options.secureCookies,
+      maxAgeSeconds,
+      path: audience.basePath,
+    })
+
+  const start = async (request: Request, provider: IdentityProvider, client: OidcClient) => {
+    const returnUrl = localReturnUrl(new URL(request.url).searchParams.get('returnUrl')) ?? '/'
+    try {
+      const { url, flow } = await client.start(callbackUrl(request, provider.oidc.id), returnUrl)
+      return redirect(url, [flowCookieValue(await signFlowState(await secret(), flow), 600)])
+    } catch (error) {
+      options.log?.(`${provider.oidc.name} sign-in could not start: ${(error as Error).message}`)
+      return redirect(
+        audience.failed(returnUrl, `${provider.oidc.name} is not reachable right now.`),
+      )
+    }
+  }
+
+  const finish = async (request: Request, provider: IdentityProvider, client: OidcClient) => {
+    const clear = flowCookieValue('', 0)
+    const flow = await readFlowState(await secret(), readCookie(request, flowCookie))
+    if (!flow || flow.provider !== provider.oidc.id)
+      return redirect(
+        audience.failed('/', 'That sign-in took too long, or was not started here. Try again.'),
+        [clear],
+      )
+    const back = (reason: string) => redirect(audience.failed(flow.returnUrl, reason), [clear])
+    let identity: OidcIdentity
+    try {
+      identity = await client.finish(
+        new URL(request.url),
+        flow,
+        callbackUrl(request, provider.oidc.id),
+      )
+    } catch (error) {
+      if (!(error instanceof OidcError)) throw error
+      options.log?.(error.message)
+      return back(`Signing in with ${provider.oidc.name} did not work.`)
+    }
+
+    const loginProvider = externalLoginProvider(audience.audience, provider.oidc.id)
+    const linked = await logins.find(loginProvider, identity.subject)
+    // A link to an account that has since been deleted counts for nothing.
+    const linkedAccount = linked ? await audience.byKey(linked.ownerKey) : undefined
+    const sameEmail =
+      !linkedAccount && identity.email ? await audience.byEmail(identity.email) : undefined
+    const decision = decideSignIn({
+      linked: linkedAccount?.key,
+      sameEmail: sameEmail?.key,
+      identity,
+      provider: { ...provider, name: provider.oidc.name },
+    })
+    let account: ExternalAccount
+    switch (decision.kind) {
+      case 'refuse':
+        return back(decision.reason)
+      case 'signIn':
+        account = linkedAccount as ExternalAccount
+        break
+      case 'link':
+        account = sameEmail as ExternalAccount
+        await logins.link(account.key, loginProvider, identity.subject)
+        break
+      case 'create': {
+        const groups = syncedGroups(provider.defaultGroups, identity.groups, provider.groupMap)
+        account = await audience.create(identity, provider, groups)
+        await logins.link(account.key, loginProvider, identity.subject)
+        break
+      }
+    }
+    if (decision.kind !== 'create' && Object.keys(provider.groupMap).length > 0) {
+      const groups = syncedGroups(account.groups, identity.groups, provider.groupMap)
+      if (groups.join('\n') !== account.groups.join('\n')) await audience.setGroups(account, groups)
+    }
+    const signedIn = await audience.signIn(account, request)
+    if ('refused' in signedIn) return back(signedIn.refused)
+    return redirect(flow.returnUrl, [clear, ...signedIn.cookies])
+  }
+
+  return {
+    startUrl(providerId, returnUrl) {
+      const query = returnUrl ? `?returnUrl=${encodeURIComponent(returnUrl)}` : ''
+      return `${audience.basePath}/${providerId}${query}`
+    },
+    async handle(request, pathname) {
+      if (!pathname.startsWith(`${audience.basePath}/`)) return undefined
+      const [id, step, ...rest] = pathname.slice(audience.basePath.length + 1).split('/')
+      const declared = id ? byId.get(id) : undefined
+      if (!declared || rest.length > 0) return undefined
+      if (request.method !== 'GET') return new Response(null, { status: 405 })
+      const provider = options.resolve ? await options.resolve(declared) : declared
+      const client = clientFor(provider)
+      if (step === undefined || step === '') return start(request, provider, client)
+      if (step === 'callback') return finish(request, provider, client)
+      return undefined
+    },
+  }
+}