@crombolo/server 0.0.0-stage → 0.10.0

package/src/media-store.ts

@@ -0,0 +1,248 @@
+/**
+ * Where uploaded files live.
+ *
+ * Umbraco abstracts this as `IFileSystem` with a `MediaFileManager` on top, so a
+ * site can move media to blob storage without touching anything that uses it.
+ * This is the same seam, narrowed to what a media library actually needs: get,
+ * put, delete, and list a prefix. Nothing above this interface knows whether the
+ * bytes are on a disk, in a bucket or in a container.
+ *
+ * The key space is the layout the file system store has always used, so an
+ * existing media folder keeps working unchanged:
+ *
+ *   `ab12cd34/photo.jpg`        a placed file, served at `/media/ab12cd34/photo.jpg`
+ *   `.temp/<uuid>/photo.jpg`    an upload not yet placed, with `meta.json` beside it
+ *   `.cache/ab/<hash>.webp`     a processed image variant
+ *
+ * A site picks a store in `crombolo.config.ts` — `fileSystemMediaStore`,
+ * `s3MediaStore` or `azureMediaStore` — or leaves it to the environment, which
+ * is what a container deployment wants.
+ */
+import { existsSync, mkdirSync, readdirSync, rmSync, statSync } from 'node:fs'
+import { dirname, join, resolve, sep } from 'node:path'
+
+export interface StoredFile {
+  key: string
+  size: number
+  /**
+   * Changes whenever the contents change. Variant cache keys are built from it,
+   * so a replaced original invalidates its crops without anyone tracking that.
+   */
+  etag: string
+  contentType: string
+  bytes(): Promise<Uint8Array>
+  /** A path on this machine, when the store has one; lets the server stream it. */
+  localPath?: string
+}
+
+export interface MediaStore {
+  /** Named in the boot banner and in logs: `media/`, `s3://bucket`, … */
+  readonly description: string
+  get(key: string): Promise<StoredFile | undefined>
+  put(key: string, body: Uint8Array | File, options?: { contentType?: string }): Promise<void>
+  delete(key: string): Promise<void>
+  /** Every key under a prefix, which is how temporary uploads are swept. */
+  list(prefix: string): Promise<string[]>
+  /**
+   * A URL the browser should fetch instead of coming through this server — a CDN
+   * origin, or a presigned link. Undefined means this server serves the bytes,
+   * which is what the file system store always does.
+   */
+  publicUrl?(key: string): string | undefined
+}
+
+/** Content types by extension, for stores that do not infer one. */
+const CONTENT_TYPES: Record<string, string> = {
+  avif: 'image/avif',
+  css: 'text/css',
+  gif: 'image/gif',
+  ico: 'image/x-icon',
+  jpeg: 'image/jpeg',
+  jpg: 'image/jpeg',
+  js: 'text/javascript',
+  json: 'application/json',
+  mp3: 'audio/mpeg',
+  mp4: 'video/mp4',
+  pdf: 'application/pdf',
+  png: 'image/png',
+  svg: 'image/svg+xml',
+  txt: 'text/plain',
+  webm: 'video/webm',
+  webp: 'image/webp',
+  woff2: 'font/woff2',
+  zip: 'application/zip',
+}
+
+export function contentTypeFor(key: string): string {
+  const extension = key.split('.').pop()?.toLowerCase() ?? ''
+  return CONTENT_TYPES[extension] ?? 'application/octet-stream'
+}
+
+/**
+ * A key is `<segment>/<segment>`: no `..`, no leading dot except the two the
+ * layout above reserves, and no backslashes. Checked in one place so every store
+ * is safe, not only the one that touches a file system.
+ */
+export function isSafeMediaKey(key: string): boolean {
+  if (key === '' || key.includes('\\') || key.includes('//')) return false
+  const parts = key.split('/')
+  return parts.every(
+    (part, index) =>
+      part !== '' &&
+      part !== '.' &&
+      part !== '..' &&
+      (!part.startsWith('.') || (index === 0 && (part === '.temp' || part === '.cache'))),
+  )
+}
+
+// ------------------------------------------------------------- file system
+
+export interface FileSystemMediaStoreOptions {
+  /**
+   * A URL prefix that serves the media root directly — a CDN in front of the
+   * same disk, or nginx. Without one the server streams every file itself.
+   */
+  publicUrlPrefix?: string
+}
+
+/**
+ * The default: files under a directory, which is where Umbraco puts them too.
+ * Deleting the last file in a folder deletes the folder, so a media root does not
+ * silt up with empty directories.
+ */
+export function fileSystemMediaStore(
+  root: string,
+  options: FileSystemMediaStoreOptions = {},
+): MediaStore {
+  const base = resolve(root)
+  const prefix = options.publicUrlPrefix?.replace(/\/$/, '')
+
+  const pathOf = (key: string): string | undefined => {
+    if (!isSafeMediaKey(key)) return undefined
+    const path = resolve(base, key)
+    return path === base || path.startsWith(base + sep) ? path : undefined
+  }
+
+  return {
+    description: base,
+
+    async get(key) {
+      const path = pathOf(key)
+      if (!path || !existsSync(path)) return undefined
+      const stat = statSync(path)
+      if (!stat.isFile()) return undefined
+      const file = Bun.file(path)
+      return {
+        key,
+        size: stat.size,
+        // Size and mtime are what a web server would use, and they are cheap.
+        etag: `${stat.size.toString(16)}-${Math.trunc(stat.mtimeMs).toString(16)}`,
+        contentType: file.type || contentTypeFor(key),
+        bytes: () => file.bytes(),
+        localPath: path,
+      }
+    },
+
+    async put(key, body) {
+      const path = pathOf(key)
+      if (!path) throw new Error(`"${key}" is not a usable media key.`)
+      mkdirSync(dirname(path), { recursive: true })
+      await Bun.write(path, body)
+    },
+
+    async delete(key) {
+      const path = pathOf(key)
+      if (!path || !existsSync(path)) return
+      rmSync(path, { recursive: true, force: true })
+      const folder = dirname(path)
+      if (folder !== base && existsSync(folder) && readdirSync(folder).length === 0)
+        rmSync(folder, { recursive: true, force: true })
+    },
+
+    async list(keyPrefix) {
+      // A prefix names a folder as often as a key, so `.temp/<id>/` and
+      // `.temp/<id>` mean the same thing here.
+      const trimmed = keyPrefix.replace(/\/+$/, '')
+      const start = trimmed === '' ? base : pathOf(trimmed)
+      if (!start || !existsSync(start)) return []
+      const found: string[] = []
+      const walk = (dir: string) => {
+        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+          const path = join(dir, entry.name)
+          if (entry.isDirectory()) walk(path)
+          else
+            found.push(
+              path
+                .slice(base.length + 1)
+                .split(sep)
+                .join('/'),
+            )
+        }
+      }
+      if (statSync(start).isDirectory()) walk(start)
+      else found.push(trimmed)
+      return found
+    },
+
+    publicUrl: prefix ? (key) => `${prefix}/${key}` : undefined,
+  }
+}
+
+// -------------------------------------------------------------- from the environment
+
+export type MediaStoreKind = 'filesystem' | 's3' | 'azure'
+
+/**
+ * The store the environment asks for. `CROMBOLO_MEDIA_STORE` picks the kind;
+ * each kind reads its own variables, and an unset one falls back to the
+ * credentials its SDK would find anyway (an instance role, for S3).
+ *
+ *   CROMBOLO_MEDIA_STORE=s3
+ *   CROMBOLO_MEDIA_S3_BUCKET=my-site-media
+ *   CROMBOLO_MEDIA_S3_REGION=ap-southeast-2
+ *
+ *   CROMBOLO_MEDIA_STORE=azure
+ *   CROMBOLO_MEDIA_AZURE_ACCOUNT=mysite
+ *   CROMBOLO_MEDIA_AZURE_CONTAINER=media
+ *   CROMBOLO_MEDIA_AZURE_KEY=…              (or …_SAS=?sv=…)
+ *
+ * Anything unrecognised is the file system, so a mistyped value degrades to the
+ * default rather than losing the media library.
+ */
+export async function mediaStoreFromEnvironment(
+  mediaDir: string,
+  env: Record<string, string | undefined> = Bun.env,
+): Promise<MediaStore> {
+  const kind = (env.CROMBOLO_MEDIA_STORE ?? 'filesystem').toLowerCase()
+  if (kind === 's3') {
+    const { s3MediaStore } = await import('./media-store-s3.ts')
+    return s3MediaStore({
+      bucket: env.CROMBOLO_MEDIA_S3_BUCKET ?? '',
+      region: env.CROMBOLO_MEDIA_S3_REGION,
+      endpoint: env.CROMBOLO_MEDIA_S3_ENDPOINT,
+      accessKeyId: env.CROMBOLO_MEDIA_S3_ACCESS_KEY_ID,
+      secretAccessKey: env.CROMBOLO_MEDIA_S3_SECRET_ACCESS_KEY,
+      sessionToken: env.CROMBOLO_MEDIA_S3_SESSION_TOKEN,
+      prefix: env.CROMBOLO_MEDIA_S3_PREFIX,
+      publicUrlPrefix: env.CROMBOLO_MEDIA_S3_PUBLIC_URL,
+      presignSeconds: env.CROMBOLO_MEDIA_S3_PRESIGN_SECONDS
+        ? Number(env.CROMBOLO_MEDIA_S3_PRESIGN_SECONDS)
+        : undefined,
+    })
+  }
+  if (kind === 'azure') {
+    const { azureMediaStore } = await import('./media-store-azure.ts')
+    return azureMediaStore({
+      account: env.CROMBOLO_MEDIA_AZURE_ACCOUNT ?? '',
+      container: env.CROMBOLO_MEDIA_AZURE_CONTAINER ?? 'media',
+      accountKey: env.CROMBOLO_MEDIA_AZURE_KEY,
+      sasToken: env.CROMBOLO_MEDIA_AZURE_SAS,
+      endpoint: env.CROMBOLO_MEDIA_AZURE_ENDPOINT,
+      prefix: env.CROMBOLO_MEDIA_AZURE_PREFIX,
+      publicUrlPrefix: env.CROMBOLO_MEDIA_AZURE_PUBLIC_URL,
+    })
+  }
+  return fileSystemMediaStore(mediaDir, {
+    publicUrlPrefix: env.CROMBOLO_MEDIA_PUBLIC_URL,
+  })
+}

package/src/member-auth.ts

@@ -0,0 +1,384 @@
+/**
+ * Member authentication on the front end, and the public-access check that
+ * depends on it.
+ *
+ * Umbraco has no fixed URLs for this: a site writes a surface controller and
+ * posts to it. There is no surface-controller equivalent here, so these four
+ * endpoints are ours, under the fixed `/umbraco` namespace rather than the
+ * movable backoffice path, because they belong to the framework and not to the
+ * editor.
+ *
+ *   POST /umbraco/members/login     username, password, rememberMe?, returnUrl?
+ *   POST /umbraco/members/logout
+ *   POST /umbraco/members/register  name, email, username, password, returnUrl?
+ *   GET  /umbraco/members/current
+ *
+ * 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.
+ *
+ * Registration is refused unless the site turns it on: an endpoint that creates
+ * accounts is a decision a site makes, not one a framework makes for it.
+ */
+import {
+  expireCookie,
+  hashPassword,
+  memberCookieName,
+  passwordConfigJson,
+  readCookie,
+  readMemberTicket,
+  serializeCookie,
+  signMemberTicket,
+  verifyPassword,
+} from '@crombolo/auth'
+import {
+  DEFAULT_PASSWORD_CONFIGURATION,
+  isValidPassword,
+  localReturnUrl,
+  ObjectTypes,
+} from '@crombolo/core'
+import {
+  ContentTypeRepository,
+  type Db,
+  ensureKeyValue,
+  MemberRepository,
+  type NodeSchemaState,
+  PublicAccessRepository,
+} from '@crombolo/data'
+import type { AccessDecision, PublishedContent, RequestMember } from '@crombolo/render'
+import type { CromboloConfig } from './config.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'
+
+export interface MemberAuthOptions {
+  /** The schema state this node runs at; a registration is refused without it. */
+  nodeState?: NodeSchemaState
+  nodeId?: string
+}
+
+export interface MemberAuth {
+  /** The member this request carries, or undefined. */
+  resolve(request: Request): Promise<RequestMember | undefined>
+  /**
+   * Whether a member may see a page, and what to render instead when not. The
+   * answer is Umbraco's: the login page for a visitor who is not signed in, the
+   * error page for one who is signed in but not allowed.
+   */
+  decide(content: PublishedContent, member: RequestMember | undefined): Promise<AccessDecision>
+  /** Handles the member endpoints, or undefined when the path is not one. */
+  handle(request: Request, pathname: string): Promise<Response | undefined>
+}
+
+const isFormPost = (request: Request) =>
+  (request.headers.get('content-type') ?? '').includes('form')
+
+async function readInput(request: Request): Promise<Record<string, string>> {
+  if (isFormPost(request)) {
+    const form = await request.formData().catch(() => undefined)
+    if (!form) return {}
+    const out: Record<string, string> = {}
+    for (const [key, value] of form.entries()) if (typeof value === 'string') out[key] = value
+    return out
+  }
+  const body = (await request.json().catch(() => ({}))) as Record<string, unknown>
+  const out: Record<string, string> = {}
+  for (const [key, value] of Object.entries(body ?? {}))
+    if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean')
+      out[key] = String(value)
+  return out
+}
+
+/**
+ * A `returnUrl` must be a path on this site. An absolute URL would let a login
+ * form bounce a visitor somewhere else, which is the open-redirect this closes.
+ *
+ * `localReturnUrl` rather than a prefix test: a browser reads `/\evil.com` as
+ * protocol-relative, so the leading single slash it appears to have is not a
+ * guarantee of anything.
+ */
+const safeReturnUrl = (value: string | undefined): string | undefined => localReturnUrl(value)
+
+/**
+ * Whether a POST came from this site, rather than a form on someone else's.
+ *
+ * These three endpoints take a plain form post and act on the member cookie, and
+ * `SameSite=Lax` does not cover a cross-site POST's effect here: an attacker's
+ * form can sign a visitor into an account the attacker controls, or out of their
+ * own. Umbraco's surface controllers carry an antiforgery token for this; with no
+ * token to hand, the fetch metadata a browser sends is what distinguishes them.
+ *
+ * A request with neither header is allowed: that is a non-browser client, which
+ * carries no ambient cookies to abuse.
+ */
+function fromThisSite(request: Request): boolean {
+  const site = request.headers.get('sec-fetch-site')
+  if (site) return site === 'same-origin' || site === 'none'
+  const origin = request.headers.get('origin')
+  if (!origin) return true
+  try {
+    return origin === new URL(request.url).origin
+  } catch {
+    return false
+  }
+}
+
+export function createMemberAuth(
+  db: Db,
+  config: CromboloConfig,
+  options: MemberAuthOptions = {},
+): MemberAuth {
+  // A registration is a write, so it is refused unless the repository is told
+  // which schema state this node runs at.
+  const members = new MemberRepository(db, { nodeState: options.nodeState, nodeId: options.nodeId })
+  const access = new PublicAccessRepository(db)
+  const memberTypes = new ContentTypeRepository(db, { kind: 'member' })
+  const cookie = memberCookieName({
+    siteName: config.siteName,
+    securePrefix: config.secureCookies,
+  })
+  // Read once and held: every front-end request resolves a member, and that must
+  // not cost a query for the key each time.
+  let signingKey: Promise<string> | undefined
+  const secret = () => {
+    signingKey ??= ensureKeyValue(db, SIGNING_KEY, () => crypto.randomUUID())
+    return signingKey
+  }
+
+  const asRequestMember = (member: {
+    key: string
+    name: string
+    username: string
+    email: string
+    roles: string[]
+  }): RequestMember => ({
+    key: member.key,
+    name: member.name,
+    username: member.username,
+    email: member.email,
+    roles: member.roles,
+  })
+
+  const issue = async (key: string, stamp: string | null, persist: boolean) => {
+    const expires = Math.floor(Date.now() / 1000) + config.memberSessionMinutes * 60
+    const ticket = await signMemberTicket(await secret(), { id: key, stamp: stamp ?? '', expires })
+    return serializeCookie({
+      name: cookie,
+      value: ticket,
+      secure: config.secureCookies,
+      // Without "remember me" the cookie lasts the browser session, though the
+      // ticket inside it still expires.
+      maxAgeSeconds: persist ? config.memberSessionMinutes * 60 : undefined,
+    })
+  }
+
+  const resolve: MemberAuth['resolve'] = async (request) => {
+    const ticket = await readMemberTicket(await secret(), readCookie(request, cookie))
+    if (!ticket) return undefined
+    const member = await members.byKey(ticket.id)
+    if (!member) return undefined
+    // The stamp is what makes revocation immediate: a password change or a
+    // lockout rotates it, and every ticket issued before it is now worthless.
+    if ((member.securityStamp ?? '') !== ticket.stamp) return undefined
+    if (!member.isApproved || member.isLockedOut) return undefined
+    return asRequestMember(member)
+  }
+
+  const decide: MemberAuth['decide'] = async (content, member) => {
+    const entry = await access.entryFor(content.key)
+    if (!entry) return { status: 'allowed' }
+    const here = content.key.toLowerCase()
+    // The login and error pages must render even when they sit inside the
+    // 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
+      ? { status: 'allowed' }
+      : { status: 'substitute', contentKey: entry.errorNodeKey }
+  }
+
+  const answer = (
+    request: Request,
+    result: { ok: true; body?: unknown } | { ok: false; status: number; error: string },
+    options: { returnUrl?: string; cookies?: string[] } = {},
+  ): Response => {
+    const headers = new Headers()
+    for (const value of options.cookies ?? []) headers.append('set-cookie', value)
+    if (isFormPost(request)) {
+      headers.set('location', options.returnUrl ?? '/')
+      // 303 so the browser follows with GET rather than re-posting.
+      return new Response(null, { status: 303, headers })
+    }
+    headers.set('content-type', 'application/json')
+    return new Response(
+      JSON.stringify(result.ok ? (result.body ?? { ok: true }) : { error: result.error }),
+      { status: result.ok ? 200 : result.status, headers },
+    )
+  }
+
+  const login = async (request: Request): Promise<Response> => {
+    const input = await readInput(request)
+    const returnUrl = safeReturnUrl(input.returnUrl)
+    const username = (input.username ?? '').trim()
+    const member = username ? await members.byUsername(username) : undefined
+    // A failed form post lands back where it came from, with a flag the login
+    // template can read; a failed fetch gets a 401.
+    const back = returnUrl ?? '/'
+    const failed = () =>
+      answer(
+        request,
+        { ok: false, status: 401, error: 'The username or password is not correct.' },
+        { returnUrl: `${back}${back.includes('?') ? '&' : '?'}memberLoginFailed=1` },
+      )
+    if (!member) {
+      // Spend the same time as a real verification would, so a missing username
+      // is not distinguishable by how quickly it fails.
+      await verifyPassword(input.password ?? '', await hashPassword(crypto.randomUUID()))
+      return failed()
+    }
+    // Checked before the password, so the answer never depends on whether the
+    // password was right; the same throwaway verify as above keeps the time taken
+    // from saying what the response does not.
+    if (member.isLockedOut || !member.isApproved) {
+      await verifyPassword(input.password ?? '', await hashPassword(crypto.randomUUID()))
+      return failed()
+    }
+    if (!(await verifyPassword(input.password ?? '', member.passwordHash))) {
+      await members.recordFailedLogin(member.key, config.maxFailedPasswordAttempts)
+      return failed()
+    }
+    await members.recordLogin(member.key)
+    return answer(
+      request,
+      { ok: true, body: { member: asRequestMember(member) } },
+      {
+        returnUrl: returnUrl ?? '/',
+        cookies: [await issue(member.key, member.securityStamp, input.rememberMe === 'true')],
+      },
+    )
+  }
+
+  const logout = async (request: Request): Promise<Response> => {
+    const input = await readInput(request)
+    return answer(
+      request,
+      { ok: true },
+      {
+        returnUrl: safeReturnUrl(input.returnUrl) ?? '/',
+        cookies: [expireCookie(cookie, config.secureCookies)],
+      },
+    )
+  }
+
+  const register = async (request: Request): Promise<Response> => {
+    if (!config.allowMemberRegistration)
+      return answer(request, {
+        ok: false,
+        status: 404,
+        error: 'Member registration is not enabled on this site.',
+      })
+    const input = await readInput(request)
+    const email = (input.email ?? '').trim()
+    const username = (input.username ?? '').trim() || email
+    const name = (input.name ?? '').trim() || username
+    const password = input.password ?? ''
+    if (!email || !username || !password)
+      return answer(request, {
+        ok: false,
+        status: 400,
+        error: 'A name, e-mail address and password are required.',
+      })
+    // The configured type, and only that: `memberRegistrationType` is the site's
+    // statement of what a visitor may create, so honouring a type named in the
+    // request would let them register as any member type the site defines.
+    const alias = config.memberRegistrationType
+    const type = await memberTypes.byAlias(alias)
+    if (!type)
+      return answer(request, {
+        ok: false,
+        status: 400,
+        error: `The member type "${alias}" does not exist.`,
+      })
+    if ((await members.taken('username', username)) || (await members.taken('email', email)))
+      return answer(request, {
+        ok: false,
+        status: 409,
+        error: 'That username or e-mail address is already registered.',
+      })
+    // Members were held to no policy at all while backoffice users were; after
+    // uniqueness, as ASP.NET Identity orders its own validators.
+    if (!isValidPassword(password))
+      return answer(request, {
+        ok: false,
+        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 created = await members.create(
+      {
+        key: crypto.randomUUID(),
+        contentTypeKey: type.key,
+        componentKey: null,
+        parentKey: null,
+        values: [],
+        variants: [{ culture: null, segment: null, name }],
+      },
+      {
+        email,
+        username,
+        isApproved: true,
+        isLockedOut: false,
+        passwordHash: await hashPassword(password),
+        passwordConfig: passwordConfigJson(),
+        groupKeys,
+      },
+    )
+    return answer(
+      request,
+      { ok: true, body: { member: asRequestMember(created) } },
+      {
+        returnUrl: safeReturnUrl(input.returnUrl) ?? '/',
+        cookies: [await issue(created.key, created.securityStamp, false)],
+      },
+    )
+  }
+
+  return {
+    resolve,
+    decide,
+    async handle(request, pathname) {
+      if (!pathname.startsWith(`${MEMBER_ROUTE_PREFIX}/`)) return 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 (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 'logout':
+          return logout(request)
+        case 'register':
+          return register(request)
+        default:
+          return undefined
+      }
+    },
+  }
+}