@crombolo/server 0.13.2 → 0.14.1

package/src/identity-providers.ts

@@ -0,0 +1,185 @@
+/**
+ * External identity providers (story 031): typed presets a site's config lists,
+ * one list for members and one for backoffice users. Each preset knows its
+ * provider's issuer, scopes and claims; the rest says what a first sign-in may
+ * do and how groups follow the account.
+ *
+ * ```ts
+ * defineConfig({
+ *   backofficeIdentityProviders: [entra({ tenantId, clientId, clientSecret, groups: { map: { … } } })],
+ *   memberIdentityProviders: [awsIdentityCenter({ issuer, clientId, clientSecret })],
+ * })
+ * ```
+ */
+import type { OidcClaims, OidcProviderOptions } from '@crombolo/auth'
+
+/** What every preset takes besides the provider's own settings. */
+export interface IdentityProviderOptions {
+  /** The provider's id, in its URLs and in `external_login`; the preset's name by default. */
+  id?: string
+  /** What its sign-in button says: "Sign in with {name}". */
+  name?: string
+  /** Create a member or user for an account nobody has yet. On by default. */
+  autoCreate?: boolean
+  /**
+   * Link a first sign-in to an existing member or user with the same email,
+   * when the provider says the email is verified. Off by default: without it, an
+   * email already taken is refused rather than merged.
+   */
+  linkByEmail?: boolean
+  /**
+   * Treat every email this provider sends as verified. For a provider whose
+   * emails are the organisation's own, such as one Entra tenant, which sends no
+   * `email_verified` claim.
+   */
+  emailsVerified?: boolean
+  /**
+   * Groups that follow the account: claim values mapped to member groups (for
+   * members) or user group aliases (for users), made to match the claim on
+   * every sign-in. Groups outside the map are left as they are.
+   */
+  groups?: { claim?: string; map: Record<string, string> }
+  /** Groups a new member or user joins, besides the mapped ones. */
+  defaultGroups?: readonly string[]
+  /** Members only: the member type a new member is created as, by alias; `Member` by default. */
+  memberType?: string
+}
+
+/** Which preset made a provider: what the Entra bundle looks for. */
+export type IdentityProviderKind = 'entra' | 'aws' | 'oidc'
+
+/** A provider, ready for the config. */
+export interface IdentityProvider {
+  kind: IdentityProviderKind
+  /** Entra only: the tenant its issuer is for, which an override may change. */
+  tenantId?: string
+  oidc: OidcProviderOptions
+  autoCreate: boolean
+  linkByEmail: boolean
+  emailsVerified: boolean
+  groupMap: Readonly<Record<string, string>>
+  defaultGroups: readonly string[]
+  memberType: string | undefined
+}
+
+const ID = /^[a-z0-9][a-z0-9-]*$/
+
+/** Entra's issuer for a tenant. */
+export const entraIssuer = (tenantId: string) =>
+  `https://login.microsoftonline.com/${tenantId}/v2.0`
+
+function preset(
+  kind: IdentityProviderKind,
+  defaults: { id: string; name: string },
+  provider: { issuer: string; clientId: string; clientSecret?: string; scopes?: readonly string[] },
+  claims: OidcClaims,
+  options: IdentityProviderOptions,
+): IdentityProvider {
+  const id = options.id ?? defaults.id
+  if (!ID.test(id))
+    throw new Error(`An identity provider's id is letters, digits and dashes: "${id}" is not.`)
+  if (!provider.issuer) throw new Error(`The ${defaults.name} identity provider needs an issuer.`)
+  if (!provider.clientId)
+    throw new Error(`The ${defaults.name} identity provider needs a clientId.`)
+  return {
+    kind,
+    oidc: {
+      id,
+      name: options.name ?? defaults.name,
+      issuer: provider.issuer,
+      clientId: provider.clientId,
+      clientSecret: provider.clientSecret,
+      scopes: provider.scopes ?? ['openid', 'profile', 'email'],
+      // A group map with no claim named reads the usual `groups` claim.
+      claims: {
+        ...claims,
+        groups: options.groups?.claim ?? claims.groups ?? (options.groups ? 'groups' : undefined),
+      },
+    },
+    autoCreate: options.autoCreate ?? true,
+    linkByEmail: options.linkByEmail ?? false,
+    emailsVerified: options.emailsVerified ?? false,
+    groupMap: options.groups?.map ?? {},
+    defaultGroups: options.defaultGroups ?? [],
+    memberType: options.memberType,
+  }
+}
+
+/**
+ * Microsoft Entra ID, for one tenant. Register a web app with a client secret
+ * and the redirect URLs in `docs/operations.md`; for groups, add the `groups`
+ * claim to its token configuration.
+ */
+export function entra(
+  options: IdentityProviderOptions & { tenantId: string; clientId: string; clientSecret?: string },
+): IdentityProvider {
+  if (!options.tenantId) throw new Error('The Entra identity provider needs a tenantId.')
+  const provider = preset(
+    'entra',
+    { id: 'entra', name: 'Microsoft' },
+    {
+      issuer: entraIssuer(options.tenantId),
+      clientId: options.clientId,
+      clientSecret: options.clientSecret,
+    },
+    { email: 'email', name: 'name', groups: 'groups' },
+    options,
+  )
+  return { ...provider, tenantId: options.tenantId }
+}
+
+/**
+ * AWS IAM Identity Center, through the OpenID Connect application its
+ * instance issues; `issuer` is that instance's issuer URL.
+ */
+export function awsIdentityCenter(
+  options: IdentityProviderOptions & { issuer: string; clientId: string; clientSecret?: string },
+): IdentityProvider {
+  return preset(
+    'aws',
+    { id: 'aws', name: 'AWS' },
+    { issuer: options.issuer, clientId: options.clientId, clientSecret: options.clientSecret },
+    { email: 'email', name: 'name', groups: 'groups' },
+    options,
+  )
+}
+
+/** Any OpenID Connect provider, by its issuer: Google, Okta, Auth0, Keycloak and the like. */
+export function oidc(
+  options: IdentityProviderOptions & {
+    id: string
+    name: string
+    issuer: string
+    clientId: string
+    clientSecret?: string
+    scopes?: readonly string[]
+    claims?: Partial<OidcClaims>
+  },
+): IdentityProvider {
+  return preset(
+    'oidc',
+    { id: options.id, name: options.name },
+    {
+      issuer: options.issuer,
+      clientId: options.clientId,
+      clientSecret: options.clientSecret,
+      scopes: options.scopes,
+    },
+    { email: 'email', name: 'name', ...options.claims },
+    options,
+  )
+}
+
+/** Refuses two providers with one id in a list, which would share one set of URLs. */
+export function checkIdentityProviders(
+  list: readonly IdentityProvider[],
+  label: string,
+): readonly IdentityProvider[] {
+  const seen = new Set<string>()
+  for (const provider of list) {
+    if (seen.has(provider.oidc.id))
+      throw new Error(`Two ${label} identity providers have the id "${provider.oidc.id}".`)
+    seen.add(provider.oidc.id)
+  }
+  return list
+}

package/src/index.ts

@@ -34,6 +34,7 @@ export * from './email-postmark.ts'
 export * from './email-resend.ts'
 export * from './email-ses.ts'
 export * from './extensions-notice.ts'
+export * from './external-sign-in.ts'
 export * from './file-intake.ts'
 export * from './form-files.ts'
 export * from './form-submit.ts'
@@ -43,6 +44,8 @@ export * from './forms.ts'
 export * from './git.ts'
 export * from './git-github.ts'
 export * from './git-routes.ts'
+export * from './identity-provider-overrides.ts'
+export * from './identity-providers.ts'
 export * from './imaging.ts'
 export * from './jobs.ts'
 export * from './listen.ts'
@@ -67,8 +70,13 @@ export * from './seo.ts'
 export * from './server.ts'
 export * from './server-events.ts'
 export * from './setup.ts'
+export * from './site-file.ts'
+export * from './site-replace.ts'
+export * from './site-sections.ts'
 export * from './status.ts'
+export * from './tar.ts'
 export * from './transfer-dashboard.ts'
+export * from './two-factor.ts'
 export * from './udt.ts'
 export * from './upgrade-summary.ts'
 export * from './url-settings.ts'

package/src/media-store-azure.ts

@@ -156,6 +156,12 @@ export function azureMediaStore(options: AzureMediaStoreOptions): MediaStore {
           if (!response.ok) throw new Error(`Azure GET ${key} failed with ${response.status}.`)
           return new Uint8Array(await response.arrayBuffer())
         },
+        stream: async () => {
+          const response = await send('GET', url)
+          if (!response.ok || !response.body)
+            throw new Error(`Azure GET ${key} failed with ${response.status}.`)
+          return response.body
+        },
       }
     },
 

package/src/media-store-s3.ts

@@ -61,6 +61,7 @@ export function s3MediaStore(options: S3MediaStoreOptions): MediaStore {
           etag: stat.etag.replaceAll('"', ''),
           contentType: stat.type || contentTypeFor(key),
           bytes: async () => new Uint8Array(await file.arrayBuffer()),
+          stream: async () => file.stream(),
         }
       } catch {
         // A missing object is a thrown NoSuchKey, not a null stat.

package/src/media-store.ts

@@ -31,6 +31,8 @@ export interface StoredFile {
   etag: string
   contentType: string
   bytes(): Promise<Uint8Array>
+  /** The bytes as a stream, for a file too big to hold (story 104); `streamOf` falls back to `bytes()`. */
+  stream?(): Promise<ReadableStream<Uint8Array>>
   /** A path on this machine, when the store has one; lets the server stream it. */
   localPath?: string
 }
@@ -51,6 +53,24 @@ export interface MediaStore {
   publicUrl?(key: string): string | undefined
 }
 
+/** A stored file's bytes in chunks: streamed where the store can, whole where it cannot. */
+export async function* streamOf(file: StoredFile): AsyncIterable<Uint8Array> {
+  if (!file.stream) {
+    yield await file.bytes()
+    return
+  }
+  const reader = (await file.stream()).getReader()
+  try {
+    for (;;) {
+      const { done, value } = await reader.read()
+      if (done) return
+      yield value
+    }
+  } finally {
+    reader.releaseLock()
+  }
+}
+
 /** Content types by extension, for stores that do not infer one. */
 const CONTENT_TYPES: Record<string, string> = {
   avif: 'image/avif',
@@ -139,6 +159,7 @@ export function fileSystemMediaStore(
         etag: `${stat.size.toString(16)}-${Math.trunc(stat.mtimeMs).toString(16)}`,
         contentType: file.type || contentTypeFor(key),
         bytes: () => file.bytes(),
+        stream: async () => file.stream(),
         localPath: path,
       }
     },

package/src/member-auth.ts

@@ -12,6 +12,9 @@
  *   POST /umbraco/members/logout
  *   POST /umbraco/members/register  name, email, username, password, returnUrl?
  *   GET  /umbraco/members/current
+ *   POST /umbraco/members/login/2fa  code, returnUrl?   the second step, when 2FA is on
+ *   GET  /umbraco/members/2fa                           the signed-in member's 2FA state
+ *   POST /umbraco/members/2fa/setup | enable | disable   turning it on and off (story 032)
  *
  * A form post is answered with a redirect, a JSON post with JSON, so the same
  * endpoint serves a plain `<form>` in a TSX template and a fetch from the page.
@@ -27,14 +30,17 @@ import {
   passwordConfigJson,
   readCookie,
   readMemberTicket,
+  readShortLived,
   serializeCookie,
   signMemberTicket,
+  signShortLived,
   verifyPassword,
 } from '@crombolo/auth'
 import {
   DEFAULT_PASSWORD_CONFIGURATION,
   isValidPassword,
   localReturnUrl,
+  memberMayOpen,
   ObjectTypes,
 } from '@crombolo/core'
 import {
@@ -45,14 +51,25 @@ import {
   type NodeSchemaState,
   PublicAccessRepository,
 } from '@crombolo/data'
-import type { AccessDecision, PublishedContent, RequestMember } from '@crombolo/render'
+import {
+  type AccessDecision,
+  MEMBER_EXTERNAL_SIGN_IN_PATH,
+  type PublishedContent,
+  type RequestMember,
+} from '@crombolo/render'
 import type { CromboloConfig } from './config.ts'
+import { createExternalSignIn, type ExternalAccount } from './external-sign-in.ts'
+import { IdentityProviderOverrides } from './identity-provider-overrides.ts'
+import { MEMBER_TWO_FACTOR_PROVIDER, TwoFactorService } from './two-factor.ts'
 
 /** The key member tickets are signed with, generated once and shared by every node. */
 const SIGNING_KEY = 'crombolo/memberCookieKey'
 
 export const MEMBER_ROUTE_PREFIX = '/umbraco/members'
 
+/** How long a member has to enter their code after their password. */
+const TWO_FACTOR_PENDING_SECONDS = 5 * 60
+
 export interface MemberAuthOptions {
   /** The schema state this node runs at; a registration is refused without it. */
   nodeState?: NodeSchemaState
@@ -72,6 +89,11 @@ export interface MemberAuth {
   handle(request: Request, pathname: string): Promise<Response | undefined>
   /** The `Set-Cookie` value that ends a member's site session. */
   signOutCookie(): string
+  /**
+   * Where a "Sign in with …" link for a member identity provider goes, by its
+   * id; undefined for a provider the site does not configure.
+   */
+  externalSignInUrl(providerId: string, returnUrl?: string): string | undefined
 }
 
 const isFormPost = (request: Request) =>
@@ -149,6 +171,13 @@ export function createMemberAuth(
     return signingKey
   }
 
+  const twoFactor = new TwoFactorService(db, {
+    secretKey: config.secretKey,
+    issuer: config.siteName,
+  })
+  const pendingCookie = `${cookie}TwoFactor`
+  const flagged = (url: string, flags: string) => `${url}${url.includes('?') ? '&' : '?'}${flags}`
+
   const asRequestMember = (member: {
     key: string
     name: string
@@ -176,6 +205,93 @@ export function createMemberAuth(
     })
   }
 
+  /** Member group keys by name, for the names a registration or a provider names. */
+  const groupKeysFor = async (names: readonly string[]): Promise<string[]> => {
+    const keys: string[] = []
+    for (const groupName of names) {
+      const rows = await db.query<{ unique_id: string }>(
+        'SELECT unique_id FROM node WHERE text = ? AND node_object_type = ?',
+        [groupName, ObjectTypes.MemberGroup],
+      )
+      if (rows[0]) keys.push(String(rows[0].unique_id))
+    }
+    return keys
+  }
+
+  const asAccount = (member: { key: string; email: string; roles: string[] }): ExternalAccount => ({
+    key: member.key,
+    email: member.email,
+    groups: member.roles,
+  })
+
+  const MEMBER_EXTERNAL_PATH = MEMBER_EXTERNAL_SIGN_IN_PATH
+  const external =
+    config.memberIdentityProviders.length === 0
+      ? undefined
+      : createExternalSignIn(
+          db,
+          {
+            audience: 'member',
+            providers: config.memberIdentityProviders,
+            basePath: MEMBER_EXTERNAL_PATH,
+            byKey: async (key) => {
+              const member = await members.byKey(key)
+              return member ? asAccount(member) : undefined
+            },
+            byEmail: async (email) => {
+              const member = await members.byEmail(email)
+              return member ? asAccount(member) : undefined
+            },
+            create: async (identity, provider, groups) => {
+              const alias = provider.memberType ?? config.memberRegistrationType
+              const type = await memberTypes.byAlias(alias)
+              if (!type) throw new Error(`The member type "${alias}" does not exist.`)
+              const email = identity.email as string
+              // The email is the username, as registration makes it, unless
+              // someone already signs in with that name.
+              const username = (await members.taken('username', email))
+                ? `${provider.oidc.id}-${identity.subject}`
+                : email
+              const created = await members.create(
+                {
+                  key: crypto.randomUUID(),
+                  contentTypeKey: type.key,
+                  componentKey: null,
+                  parentKey: null,
+                  values: [],
+                  variants: [{ culture: null, segment: null, name: identity.name || email }],
+                },
+                {
+                  email,
+                  username,
+                  isApproved: true,
+                  isLockedOut: false,
+                  groupKeys: await groupKeysFor(groups),
+                },
+              )
+              return asAccount(created)
+            },
+            setGroups: async (account, groups) => {
+              await members.setGroups(account.key, await groupKeysFor(groups))
+            },
+            signIn: async (account) => {
+              const member = await members.byKey(account.key)
+              if (!member?.isApproved || member.isLockedOut)
+                return { refused: 'This account cannot sign in at the moment.' }
+              await members.recordLogin(member.key)
+              return { cookies: [await issue(member.key, member.securityStamp, false)] }
+            },
+            failed: (returnUrl, reason) =>
+              `${returnUrl}${returnUrl.includes('?') ? '&' : '?'}memberLoginFailed=1&memberLoginError=${encodeURIComponent(reason)}`,
+          },
+          {
+            applicationUrl: config.applicationUrl,
+            secureCookies: config.secureCookies,
+            resolve: (provider) =>
+              new IdentityProviderOverrides(db, config.secretKey).apply('member', provider),
+          },
+        )
+
   const resolve: MemberAuth['resolve'] = async (request) => {
     const ticket = await readMemberTicket(await secret(), readCookie(request, cookie))
     if (!ticket) return undefined
@@ -196,12 +312,7 @@ export function createMemberAuth(
     // branch they serve, or the substitution would never terminate.
     if (here === entry.loginNodeKey || here === entry.errorNodeKey) return { status: 'allowed' }
     if (!member) return { status: 'substitute', contentKey: entry.loginNodeKey }
-    const allowed =
-      entry.memberUserNames.some((name) => name.toLowerCase() === member.username.toLowerCase()) ||
-      entry.memberGroupNames.some((name) =>
-        member.roles.some((role) => role.toLowerCase() === name.toLowerCase()),
-      )
-    return allowed
+    return memberMayOpen(entry, { username: member.username, groups: member.roles })
       ? { status: 'allowed' }
       : { status: 'substitute', contentKey: entry.errorNodeKey }
   }
@@ -268,6 +379,28 @@ export function createMemberAuth(
         await hashPassword(input.password ?? ''),
         passwordConfigJson(),
       )
+    if ((await twoFactor.providers(member.key)).includes(MEMBER_TWO_FACTOR_PROVIDER)) {
+      const pending = await signShortLived(
+        await secret(),
+        { sub: member.key, persist: input.rememberMe === 'true' ? 1 : 0 },
+        TWO_FACTOR_PENDING_SECONDS,
+      )
+      return answer(
+        request,
+        { ok: true, body: { twoFactorRequired: true } },
+        {
+          returnUrl: flagged(back, 'memberTwoFactorRequired=1'),
+          cookies: [
+            serializeCookie({
+              name: pendingCookie,
+              value: pending,
+              secure: config.secureCookies,
+              maxAgeSeconds: TWO_FACTOR_PENDING_SECONDS,
+            }),
+          ],
+        },
+      )
+    }
     await members.recordLogin(member.key)
     return answer(
       request,
@@ -279,6 +412,87 @@ export function createMemberAuth(
     )
   }
 
+  /** The second step: the code from the app, or a recovery code, after the password. */
+  const verifyTwoFactor = async (request: Request): Promise<Response> => {
+    const input = await readInput(request)
+    const back = safeReturnUrl(input.returnUrl) ?? '/'
+    const pending = await readShortLived(await secret(), readCookie(request, pendingCookie))
+    const key = typeof pending?.sub === 'string' ? pending.sub : undefined
+    const member = key ? await members.byKey(key) : undefined
+    if (!member || member.isLockedOut || !member.isApproved)
+      return answer(
+        request,
+        { ok: false, status: 401, error: 'Sign in again.' },
+        {
+          returnUrl: flagged(back, 'memberLoginFailed=1'),
+          cookies: [expireCookie(pendingCookie, config.secureCookies)],
+        },
+      )
+    if (!(await twoFactor.verify(member.key, MEMBER_TWO_FACTOR_PROVIDER, input.code ?? ''))) {
+      await members.recordFailedLogin(member.key, config.maxFailedPasswordAttempts)
+      return answer(
+        request,
+        { ok: false, status: 400, error: 'That code is not right.' },
+        { returnUrl: flagged(back, 'memberTwoFactorRequired=1&memberLoginFailed=1') },
+      )
+    }
+    await members.recordLogin(member.key)
+    return answer(
+      request,
+      { ok: true, body: { member: asRequestMember(member) } },
+      {
+        returnUrl: back,
+        cookies: [
+          await issue(member.key, member.securityStamp, pending?.persist === 1),
+          expireCookie(pendingCookie, config.secureCookies),
+        ],
+      },
+    )
+  }
+
+  /** The signed-in member's own two-factor settings; JSON, as the recovery codes must be shown. */
+  const manageTwoFactor = async (request: Request, step: string): Promise<Response> => {
+    const member = await resolve(request)
+    if (!member) return Response.json({ error: 'Sign in first.' }, { status: 401 })
+    const refused = (message: string, status = 400) => Response.json({ error: message }, { status })
+    if (step === '') {
+      if (request.method !== 'GET') return new Response(null, { status: 405 })
+      return Response.json({
+        available: twoFactor.available,
+        enabled: (await twoFactor.providers(member.key)).includes(MEMBER_TWO_FACTOR_PROVIDER),
+        recoveryCodesLeft: await twoFactor.recoveryCodesLeft(member.key),
+      })
+    }
+    if (request.method !== 'POST') return new Response(null, { status: 405 })
+    if (!fromThisSite(request)) return new Response('Forbidden', { status: 403 })
+    const input = await readInput(request)
+    switch (step) {
+      case 'setup': {
+        const setup = twoFactor.setup(member.email || member.username)
+        return setup.ok ? Response.json(setup.value) : refused(setup.message)
+      }
+      case 'enable': {
+        const enabled = await twoFactor.enable(
+          member.key,
+          MEMBER_TWO_FACTOR_PROVIDER,
+          input.secret ?? '',
+          input.code ?? '',
+        )
+        return enabled.ok ? Response.json(enabled.value) : refused(enabled.message)
+      }
+      case 'disable': {
+        const disabled = await twoFactor.disable(
+          member.key,
+          MEMBER_TWO_FACTOR_PROVIDER,
+          input.code ?? '',
+        )
+        return disabled.ok ? Response.json({ ok: true }) : refused(disabled.message)
+      }
+      default:
+        return new Response(null, { status: 404 })
+    }
+  }
+
   const logout = async (request: Request): Promise<Response> => {
     const input = await readInput(request)
     return answer(
@@ -334,14 +548,7 @@ export function createMemberAuth(
         status: 400,
         error: `A password must be at least ${DEFAULT_PASSWORD_CONFIGURATION.minimumPasswordLength} characters.`,
       })
-    const groupKeys: string[] = []
-    for (const groupName of config.memberRegistrationGroups) {
-      const rows = await db.query<{ unique_id: string }>(
-        'SELECT unique_id FROM node WHERE text = ? AND node_object_type = ?',
-        [groupName, ObjectTypes.MemberGroup],
-      )
-      if (rows[0]) groupKeys.push(String(rows[0].unique_id))
-    }
+    const groupKeys = await groupKeysFor(config.memberRegistrationGroups)
     const created = await members.create(
       {
         key: crypto.randomUUID(),
@@ -375,19 +582,29 @@ export function createMemberAuth(
     resolve,
     decide,
     signOutCookie: () => expireCookie(cookie, config.secureCookies),
+    externalSignInUrl: (providerId, returnUrl) =>
+      config.memberIdentityProviders.some((p) => p.oidc.id === providerId)
+        ? external?.startUrl(providerId, returnUrl)
+        : undefined,
     async handle(request, pathname) {
       if (!pathname.startsWith(`${MEMBER_ROUTE_PREFIX}/`)) return undefined
+      if (pathname.startsWith(`${MEMBER_EXTERNAL_PATH}/`))
+        return external?.handle(request, pathname) ?? undefined
       const action = pathname.slice(MEMBER_ROUTE_PREFIX.length + 1)
       if (action === 'current') {
         if (request.method !== 'GET') return new Response(null, { status: 405 })
         const member = await resolve(request)
         return member ? Response.json({ member }) : Response.json({ member: null }, { status: 401 })
       }
+      if (action === '2fa' || action.startsWith('2fa/'))
+        return manageTwoFactor(request, action.slice(4))
       if (request.method !== 'POST') return new Response(null, { status: 405 })
       if (!fromThisSite(request)) return new Response('Forbidden', { status: 403 })
       switch (action) {
         case 'login':
           return login(request)
+        case 'login/2fa':
+          return verifyTwoFactor(request)
         case 'logout':
           return logout(request)
         case 'register':