create-mithaq 0.0.0-stage → 0.2.0

package/template/templates/mithaq/src/storage/defaults.ts

@@ -0,0 +1,156 @@
+import { randomUUID } from 'node:crypto'
+import { fileTypeFromBuffer } from 'file-type'
+import { imageDimensionsFromData } from 'image-dimensions'
+import {
+  adapterOf,
+  allowedType,
+  checkReference,
+  fileHeaders,
+  invalid,
+  readForFile,
+  sanitizeFilename,
+  signReference,
+  type StorageConfig,
+  type StorageKayan,
+} from 'mithaq'
+
+/**
+ * `<prefix>/<tenant>/<kayan>/<id>/<filename>`, under the adapter's prefix, the
+ * one folder its sweep lists. The id is the row's own, so two files of one name never meet.
+ */
+export const defaultKey: StorageConfig['key'] = ({ prefix, tenant, kayan, id, filename }) =>
+  [...(prefix ? [prefix] : []), (tenant ?? '_').replaceAll('/', '_'), kayan, id, filename].join('/')
+
+/** The bytes `file-type` reads to tell a type, its own `reasonableDetectionSizeInBytes`. */
+const sniffed = 4100
+
+/**
+ * Checks the stored object is there, of the declared size and no larger than the kayan takes,
+ * and of the declared type as its first bytes tell it, and reads an image's width and height.
+ * A type the bytes cannot tell, such as text/plain, CSV or JSON, is refused; SVG is the one text type taken.
+ */
+export const defaultVerify: StorageConfig['verify'] = async ({ adapter, key, mimeType, size, mimeTypes, fileSize }) => {
+  const head = await adapter.head({ key })
+  if (!head) return { refused: 'No file was uploaded.' }
+  if (head.size !== size) return { refused: `The file holds ${head.size} bytes, and ${size} were declared.` }
+  if (head.size > fileSize) return { refused: `The file holds more than ${fileSize} bytes.` }
+  const bytes = await adapter.readHead({ key, bytes: sniffed })
+  const read = (await fileTypeFromBuffer(bytes))?.mime
+  const svg = (!read || read === 'application/xml') && /<svg[\s>]/i.test(new TextDecoder().decode(bytes))
+  const type = svg ? 'image/svg+xml' : read
+  if (type !== mimeType) return { refused: `The file is ${type ?? 'of no type a file can be told by'}, and ${mimeType} was declared.` }
+  if (!allowedType(type, mimeTypes)) return { refused: `The file is ${type}, which this kayan does not hold.` }
+  const measured = imageDimensionsFromData(bytes)
+  return { width: measured?.width ?? null, height: measured?.height ?? null }
+}
+
+/** The types a browser draws in place and runs nothing in. Everything else is downloaded. */
+const drawn = /^(image\/(png|jpeg|gif|webp|avif)|application\/pdf)$/
+
+/**
+ * `inline` for a raster image and a PDF, `attachment` for every other type, an SVG among them,
+ * with the uploaded name (RFC 6266: `filename` for old clients, `filename*` for the rest).
+ */
+export const defaultDisposition: StorageConfig['disposition'] = ({ filename, mimeType }) => {
+  const plain = filename.replace(/[^\x20-\x7e]|["\\]/g, '_')
+  const encoded = encodeURIComponent(filename).replace(/['()*]/g, (one) => `%${one.charCodeAt(0).toString(16).toUpperCase()}`)
+  return `${drawn.test(mimeType) ? 'inline' : 'attachment'}; filename="${plain}"; filename*=UTF-8''${encoded}`
+}
+
+/** How long an object may sit with no row naming it before it is swept: an upload in flight has an hour. */
+const day = 24 * 60 * 60 * 1000
+
+/** Removes every object older than a day that no row names, or with `check` lists them and leaves them. */
+export const defaultSweep: StorageConfig['sweep'] = async ({ adapter, named, check, now }) => {
+  const orphans: string[] = []
+  for await (const { key, lastModified } of adapter.list!()) {
+    if (named.has(key) || now.getTime() - lastModified.getTime() < day) continue
+    orphans.push(key)
+    if (!check) await adapter.handleDelete({ key })
+  }
+  return orphans
+}
+
+/**
+ * Answers `uploadInstructions` once core has checked the create permission: validates the request,
+ * then returns the row's id, the reference core signs for it and the adapter's signed request.
+ */
+export const defaultUploadInstructions: StorageConfig['instructions'] = async ({ kayan, input, actor }) => {
+  const asked = input as Record<string, unknown> | null
+  if (
+    !asked || typeof asked !== 'object' || Array.isArray(asked)
+    || typeof asked.filename !== 'string' || asked.filename.length > 255
+    || typeof asked.mimeType !== 'string' || !/^[\w.+-]+\/[\w.+-]+$/.test(asked.mimeType)
+    || !Number.isSafeInteger(asked.filesize) || (asked.filesize as number) < 1
+  ) {
+    throw invalid({ message: 'An upload names its filename, 255 characters at most, its mimeType, a type such as image/png, and its filesize, a whole number of bytes above 0.', key: 'error.invalid.upload_request', params: { kayan: kayan.name } })
+  }
+  const filename = sanitizeFilename(asked.filename as string)
+  const mimeType = asked.mimeType as string
+  const filesize = asked.filesize as number
+  if (!filename) throw invalid({ message: 'The file has no name left once its folders and control characters are dropped.', key: 'error.invalid.upload_request', params: { kayan: kayan.name } })
+  if (!allowedType(mimeType, kayan.storage.mimeTypes)) {
+    throw invalid({ message: `A "${kayan.name}" file may not be of type "${mimeType}".`, key: 'error.invalid.upload_type', params: { kayan: kayan.name, type: mimeType } })
+  }
+  if (filesize > kayan.storage.fileSize) {
+    throw invalid({ message: `A "${kayan.name}" file holds ${kayan.storage.fileSize} bytes at most.`, key: 'error.invalid.upload_size', params: { kayan: kayan.name, max: kayan.storage.fileSize } })
+  }
+  const uploadReference = signReference({ kayan, actor, id: randomUUID(), filename, type: mimeType, size: filesize })
+  const request = await adapterOf({ kayan, name: uploadReference.storage }).uploadInstructions.generate({ filename, filesize, mimeType, key: uploadReference.key })
+  return { ...request, file: { filename, mimeType, size: filesize, uploadReference } }
+}
+
+/**
+ * The create's step: checks the reference, runs the project's `verify` and writes every file column
+ * from what the server measured. It runs before the transaction so no lock is held while the object is read.
+ */
+export const defaultUploaded: StorageConfig['uploaded'] = async (ctx) => {
+  const reference = await checkReference({ kayan: ctx.kayan, value: ctx.data.uploadReference, actor: ctx.actor })
+  const { storage } = ctx.kayan as StorageKayan
+  const adapter = adapterOf({ kayan: ctx.kayan, name: reference.storage })
+  const verified = await storage.config.verify({ adapter, key: reference.key, mimeType: reference.type, size: reference.size, mimeTypes: storage.mimeTypes, fileSize: storage.fileSize })
+  if ('refused' in verified) {
+    throw invalid({ message: `The uploaded file was refused: ${verified.refused}`, key: 'error.invalid.upload_verify', params: { kayan: ctx.kayan.name } })
+  }
+  const { uploadReference: _used, ...data } = ctx.data
+  return {
+    ...ctx,
+    data: {
+      ...data,
+      id: reference.id,
+      key: reference.key,
+      storage: reference.storage,
+      filename: reference.filename,
+      mimeType: reference.type,
+      filesize: reference.size,
+      width: verified.width ?? null,
+      height: verified.height ?? null,
+    },
+  }
+}
+
+/**
+ * Deletes the removed row's object after the commit, so a failure leaves an orphan for the sweep,
+ * never a row naming no object. A kayan that marks its rows deleted keeps the object for a restore.
+ */
+export const defaultRemoveFile: StorageConfig['removed'] = async (ctx) => {
+  if (ctx.kayan.softDelete) return ctx
+  const row = ctx.dataBefore ?? ctx.data
+  if (typeof row.key === 'string') await adapterOf({ kayan: ctx.kayan, name: row.storage }).handleDelete({ key: row.key })
+  return ctx
+}
+
+/**
+ * `GET /api/<kayan>/file/<id>`: reads the row through core's read gate, where every miss is the same 404,
+ * then answers with the adapter's redirect or bytes under the project's `disposition`.
+ */
+export const defaultServeFile: StorageConfig['serve'] = async ({ request, kayan, id, read }) => {
+  const doc = await readForFile({ kayan, id, read })
+  const adapter = adapterOf({ kayan, name: doc.storage })
+  return fileHeaders({
+    doc,
+    disposition: kayan.storage.config.disposition({ filename: doc.filename, mimeType: doc.mimeType }),
+    answer: ({ disposition }) => adapter.staticHandler(request, { doc, disposition }),
+  })
+}
+// mithaq-admin b06d8d335d306c07556f8f2b81fba20ba7ded198 af2cd4436012c35d6e1d868b3f5cc2efec50c61983d2559609ebec55d1b4acf5

package/template/templates/mithaq/src/storage/index.ts

@@ -0,0 +1,97 @@
+// Where this project's files go, every piece named here and nothing taken
+// from core by default: the language lays down `storage(storageConfig)`, whose
+// target holds this config, and a kayan holding files names the `uploaded` and
+// `removed` below in its own create and delete. It holds the secret every
+// upload reference is signed with, so it is imported by the server's modules
+// alone: the screens read their generated `screen.json` and never the language.
+// The adapters and `defaults.ts` beside this file are copied from the
+// `mithaq-storage` registry item and owned by the project: `mithaq upgrade
+// --check` reports one that was edited, and an edit is merged by hand.
+import { randomBytes } from 'node:crypto'
+import { defaultFileSize, defaultMaxBodyBytes, type StorageConfig } from 'mithaq'
+import {
+  defaultDisposition,
+  defaultKey,
+  defaultRemoveFile,
+  defaultServeFile,
+  defaultSweep,
+  defaultUploaded,
+  defaultUploadInstructions,
+  defaultVerify,
+} from './defaults.ts'
+import { local } from './local.ts'
+import { r2 } from './r2.ts'
+
+const production = process.env.NODE_ENV === 'production'
+/** A production boot names every setting below, so none falls back where it would surprise anyone. */
+const required = (name: string, fallback: string) => {
+  const value = process.env[name]
+  if (value) return value
+  if (production) throw new Error(`A production boot needs ${name}: ${explained[name]}`)
+  return fallback
+}
+const explained: Record<string, string> = {
+  STORAGE_SECRET: 'every upload reference is signed with it.',
+  STORAGE_PREFIX: 'the folder of the bucket this project owns, which every key starts with and the sweep lists alone.',
+  STORAGE_ADAPTER: 'which adapter new uploads go to, "r2" or "local", named so a missing setting never sends files to the server\'s own disk.',
+}
+
+/**
+ * What upload references and local upload tokens are signed with. In
+ * development a fresh random one per process does: nobody can forge a
+ * reference with it, and an upload in flight across a restart is asked for
+ * again, since a reference lasts an hour. Said once, so nobody runs several
+ * instances on it by accident.
+ */
+const secret = required('STORAGE_SECRET', randomBytes(32).toString('base64url'))
+if (!process.env.STORAGE_SECRET) console.warn('STORAGE_SECRET is not set, so this process signs uploads with a secret of its own, which another process refuses.')
+
+const prefix = required('STORAGE_PREFIX', 'mithaq/asas')
+
+/** R2's four settings, all or none. */
+const r2Settings = ['R2_ACCOUNT_ID', 'R2_BUCKET', 'R2_ACCESS_KEY_ID', 'R2_SECRET_ACCESS_KEY'] as const
+const r2Unset = r2Settings.filter((name) => !process.env[name])
+if (r2Unset.length && r2Unset.length < r2Settings.length) {
+  throw new Error(`R2 is half set: ${r2Unset.join(', ')} ${r2Unset.length === 1 ? 'is' : 'are'} missing. Set all four, or none.`)
+}
+
+/** Every adapter by the name a row's `storage` column holds: R2 where its four settings are set, and a folder always. */
+const adapters: StorageConfig['adapters'] = {
+  local: local({ dir: process.env.STORAGE_DIR ?? '.storage', secret, prefix }),
+  ...(!r2Unset.length && {
+    r2: r2({
+      accountId: process.env.R2_ACCOUNT_ID!,
+      bucket: process.env.R2_BUCKET!,
+      accessKeyId: process.env.R2_ACCESS_KEY_ID!,
+      secretAccessKey: process.env.R2_SECRET_ACCESS_KEY!,
+      prefix,
+    }),
+  }),
+}
+
+/** Where new uploads go, named: the folder in development unless told otherwise. */
+const adapter = required('STORAGE_ADAPTER', 'local')
+if (!Object.hasOwn(adapters, adapter)) {
+  throw new Error(`STORAGE_ADAPTER names "${adapter}", which is none of ${Object.keys(adapters).map((one) => `"${one}"`).join(', ')}. R2 needs its four settings.`)
+}
+
+export const storageConfig: StorageConfig = {
+  secret,
+  adapters,
+  adapter,
+  // The largest file a kayan holds when its targets.storage names no fileSize.
+  fileSize: defaultFileSize,
+  // The largest instructions request read; files themselves never come this way.
+  maxBodyBytes: defaultMaxBodyBytes,
+  key: defaultKey,
+  verify: defaultVerify,
+  disposition: defaultDisposition,
+  sweep: defaultSweep,
+  instructions: defaultUploadInstructions,
+  uploaded: defaultUploaded,
+  removed: defaultRemoveFile,
+  serve: defaultServeFile,
+  // What a file route threw that is no refusal, before it answers 500. The
+  // console is this project's log; a project with an error tracker names it here.
+  onError: console.error,
+}

package/template/templates/mithaq/src/storage/local.ts

@@ -0,0 +1,143 @@
+// A folder on this machine as a mithaq storage adapter, for development and CI. A folder has
+// no signed URLs, so an upload is a PUT to `<route>/<token>`, the token signed for one key,
+// type and size; the bytes become the object only when their count is exactly the size signed.
+import { createHmac, randomUUID, timingSafeEqual } from 'node:crypto'
+import { createReadStream } from 'node:fs'
+import { link, mkdir, open, readdir, rm, stat } from 'node:fs/promises'
+import { dirname, relative, resolve, sep } from 'node:path'
+import { Readable } from 'node:stream'
+import type { StorageAdapter } from 'mithaq'
+
+export type LocalOptions = {
+  dir: string
+  /** What the upload tokens are signed with, 32 characters at least. */
+  secret: string
+  /** The folder under `dir` this project's keys start with, and the one the sweep lists. */
+  prefix: string
+  /** The path the upload route answers under, `/api/storage/local` unless named. */
+  route?: string
+}
+
+const tokenSeconds = 600
+
+type Token = { key: string; type: string; size: number; exp: number }
+
+const refused = (status: number, message: string) => Response.json({ message }, { status })
+
+/**
+ * The local adapter. A key that leaves `dir`, or holds an empty, `.` or `..` part, a backslash
+ * or a NUL, is refused before any file is touched, whoever handed it in.
+ */
+export const local = ({ dir, secret, prefix, route = '/api/storage/local' }: LocalOptions): StorageAdapter => {
+  if (secret.length < 32) throw new Error('The local storage adapter signs its uploads with a secret of 32 characters at least.')
+  if (!prefix || prefix.split('/').some((part) => !part || part === '.' || part === '..')) {
+    throw new Error(`The local storage adapter's prefix ${JSON.stringify(prefix)} names no folder. Name one, such as "mithaq/asas".`)
+  }
+  const root = resolve(dir)
+  const pathOf = (key: string) => {
+    if (typeof key !== 'string' || !key || /[\\\0]/.test(key) || key.split('/').some((part) => part === '' || part === '.' || part === '..')) {
+      throw new Error(`The key ${JSON.stringify(key)} names no file inside the storage folder.`)
+    }
+    const full = resolve(root, key)
+    if (!full.startsWith(root + sep)) throw new Error(`The key ${JSON.stringify(key)} names no file inside the storage folder.`)
+    return full
+  }
+  const sign = (body: string) => createHmac('sha256', secret).update(body).digest('base64url')
+  const tokenOf = (token: Token) => {
+    const body = Buffer.from(JSON.stringify(token)).toString('base64url')
+    return `${body}.${sign(body)}`
+  }
+  const held = (token: string): Token | undefined => {
+    const [body = '', signature = ''] = token.split('.')
+    const given = Buffer.from(signature)
+    const expected = Buffer.from(sign(body))
+    if (given.length !== expected.length || !timingSafeEqual(given, expected)) return undefined
+    const read = JSON.parse(Buffer.from(body, 'base64url').toString()) as Token
+    return read.exp * 1000 < Date.now() ? undefined : read
+  }
+  return {
+    prefix,
+    uploadInstructions: {
+      generate: async ({ filesize, mimeType, key }) => {
+        pathOf(key)
+        const token = tokenOf({ key, type: mimeType, size: filesize, exp: Math.floor(Date.now() / 1000) + tokenSeconds })
+        return { type: 'http', request: { method: 'PUT', url: `${route}/${token}`, headers: { 'Content-Type': mimeType } } }
+      },
+    },
+    handler: async (request) => {
+      const { pathname } = new URL(request.url)
+      if (request.method !== 'PUT' || !pathname.startsWith(`${route}/`)) return null
+      const token = held(pathname.slice(route.length + 1))
+      if (!token) return refused(403, 'The upload token is not one this server signed, or it has expired.')
+      if (request.headers.get('content-type') !== token.type) return refused(400, 'The upload is not of the type that was signed.')
+      let path: string
+      try {
+        path = pathOf(token.key)
+      } catch {
+        return refused(400, 'The upload names no file inside the storage folder.')
+      }
+      await mkdir(dirname(path), { recursive: true })
+      const partial = `${path}.${randomUUID()}.part`
+      const file = await open(partial, 'wx')
+      let written = 0
+      try {
+        try {
+          const reader = request.body?.getReader()
+          while (reader) {
+            const { done, value } = await reader.read()
+            if (done) break
+            written += value.byteLength
+            if (written > token.size) return refused(400, 'The upload is larger than the size that was signed.')
+            await file.write(value)
+          }
+        } finally {
+          await file.close()
+        }
+        if (written !== token.size) return refused(400, 'The upload is not the size that was signed.')
+        // A second PUT with the same token must not change an object its create already
+        // verified: a link fails where the object exists, where a rename would replace it.
+        try {
+          await link(partial, path)
+        } catch (error) {
+          if ((error as { code?: unknown }).code === 'EEXIST') return refused(409, 'This upload was already sent.')
+          throw error
+        }
+        return new Response(null, { status: 204 })
+      } finally {
+        await rm(partial, { force: true })
+      }
+    },
+    handleDelete: async ({ key }) => {
+      await rm(pathOf(key), { force: true })
+    },
+    staticHandler: async (_request, { doc }) => {
+      const path = pathOf(doc.key)
+      const { size } = await stat(path)
+      return new Response(Readable.toWeb(createReadStream(path)) as ReadableStream, { status: 200, headers: { 'Content-Length': String(size) } })
+    },
+    head: async ({ key }) => {
+      const found = await stat(pathOf(key)).catch(() => undefined)
+      return found?.isFile() ? { size: found.size } : null
+    },
+    readHead: async ({ key, bytes }) => {
+      const file = await open(pathOf(key))
+      try {
+        const buffer = new Uint8Array(bytes)
+        const { bytesRead } = await file.read(buffer, 0, bytes, 0)
+        return buffer.subarray(0, bytesRead)
+      } finally {
+        await file.close()
+      }
+    },
+    // The prefix's folder alone, so another project sharing `dir` keeps its files.
+    list: async function* () {
+      const entries = await readdir(resolve(root, prefix), { recursive: true, withFileTypes: true }).catch(() => [])
+      for (const entry of entries) {
+        if (!entry.isFile()) continue
+        const path = resolve(entry.parentPath, entry.name)
+        yield { key: relative(root, path).split(sep).join('/'), lastModified: (await stat(path)).mtime }
+      }
+    },
+  }
+}
+// mithaq-admin b06d8d335d306c07556f8f2b81fba20ba7ded198 86a4471247d69e5f9d5427bb88decdb6d05a0fe5b7252ea88b47e37484dd510c

package/template/templates/mithaq/src/storage/r2.ts

@@ -0,0 +1,5 @@
+import { s3, type S3Options } from './s3.ts'
+
+export const r2 = ({ accountId, ...rest }: Omit<S3Options, 'endpoint' | 'region'> & { accountId: string }) =>
+  s3({ ...rest, endpoint: `https://${accountId}.r2.cloudflarestorage.com`, region: 'auto' })
+// mithaq-admin b06d8d335d306c07556f8f2b81fba20ba7ded198 3f592d20f1b51223f76dba6cc10eb9903abcf5084fe8bec1424e5f929769acff

package/template/templates/mithaq/src/storage/s3.ts

@@ -0,0 +1,91 @@
+// An S3 bucket as a mithaq storage adapter, over aws4fetch, so it runs on Node, Bun and
+// Workers alike and reaches AWS S3, Cloudflare R2, MinIO and Backblaze B2 the same way.
+import { AwsClient } from 'aws4fetch'
+import type { StorageAdapter } from 'mithaq'
+
+export type S3Options = {
+  /** The service's address without the bucket, such as `https://s3.eu-west-1.amazonaws.com`. */
+  endpoint: string
+  bucket: string
+  region: string
+  accessKeyId: string
+  secretAccessKey: string
+  /**
+   * The bucket folder this project owns, such as `mithaq/asas`, with no slash at either end.
+   * The sweep lists nothing outside it, so a bucket other apps share keeps their objects.
+   */
+  prefix: string
+  /** Where the bucket is read publicly, for a kayan that writes `public: true`. */
+  publicURL?: string
+}
+
+const putSeconds = 600
+const getSeconds = 300
+
+const pathOf = (key: string) => key.split('/').map(encodeURIComponent).join('/')
+
+const entities: Record<string, string> = { amp: '&', lt: '<', gt: '>', quot: '"', apos: "'" }
+const text = (xml: string, tag: string) => xml.match(new RegExp(`<${tag}>([\\s\\S]*?)</${tag}>`))?.[1]?.replace(/&(amp|lt|gt|quot|apos);/g, (_, name: string) => entities[name]!)
+
+/**
+ * The S3 adapter: uploads are signed PUTs bound to the declared type and size, and downloads
+ * are 302s to a signed GET that carries the project's disposition.
+ */
+export const s3 = ({ endpoint, bucket, region, accessKeyId, secretAccessKey, prefix, publicURL }: S3Options): StorageAdapter => {
+  if (!prefix || prefix.startsWith('/') || prefix.endsWith('/') || prefix.split('/').some((part) => !part || part === '.' || part === '..')) {
+    throw new Error(`The S3 adapter's prefix ${JSON.stringify(prefix)} names no folder of the bucket. Name one, such as "mithaq/asas".`)
+  }
+  const client = new AwsClient({ accessKeyId, secretAccessKey, service: 's3', region })
+  const base = `${endpoint.replace(/\/+$/, '')}/${bucket}`
+  const urlOf = (key: string) => `${base}/${pathOf(key)}`
+  const signed = async (url: string, init: { method: string; headers?: Record<string, string> }) =>
+    (await client.sign(url, { ...init, aws: { signQuery: true, allHeaders: true } })).url
+  return {
+    prefix,
+    uploadInstructions: {
+      // Signing the type and size makes the bucket refuse any other body, and signing
+      // `If-None-Match: *` makes it refuse a second PUT rather than replace a verified object.
+      generate: async ({ filesize, mimeType, key }) => {
+        const headers = { 'Content-Type': mimeType, 'Content-Length': String(filesize), 'If-None-Match': '*' }
+        return { type: 'http', request: { method: 'PUT', url: await signed(`${urlOf(key)}?X-Amz-Expires=${putSeconds}`, { method: 'PUT', headers }), headers } }
+      },
+    },
+    handleDelete: async ({ key }) => {
+      const answered = await client.fetch(urlOf(key), { method: 'DELETE' })
+      if (!answered.ok && answered.status !== 404) throw new Error(`S3 refused to delete an object: ${answered.status}.`)
+    },
+    generateURL: ({ key }) => {
+      if (!publicURL) throw new Error('This S3 adapter was given no publicURL, so it has no public address for a file.')
+      return `${publicURL.replace(/\/+$/, '')}/${pathOf(key)}`
+    },
+    staticHandler: async (_request, { doc, disposition }) => {
+      const query = new URLSearchParams({ 'X-Amz-Expires': String(getSeconds), 'response-content-disposition': disposition, 'response-content-type': doc.mimeType })
+      return new Response(null, { status: 302, headers: { Location: await signed(`${urlOf(doc.key)}?${query}`, { method: 'GET' }) } })
+    },
+    head: async ({ key }) => {
+      const answered = await client.fetch(urlOf(key), { method: 'HEAD' })
+      if (answered.status === 404) return null
+      if (!answered.ok) throw new Error(`S3 answered a HEAD with ${answered.status}.`)
+      return { size: Number(answered.headers.get('content-length')) }
+    },
+    readHead: async ({ key, bytes }) => {
+      const answered = await client.fetch(urlOf(key), { headers: { Range: `bytes=0-${bytes - 1}` } })
+      if (!answered.ok) throw new Error(`S3 answered a ranged GET with ${answered.status}.`)
+      return new Uint8Array(await answered.arrayBuffer()).subarray(0, bytes)
+    },
+    list: async function* () {
+      let token: string | undefined
+      do {
+        const query = new URLSearchParams({ 'list-type': '2', prefix: `${prefix}/`, ...(token && { 'continuation-token': token }) })
+        const answered = await client.fetch(`${base}?${query}`)
+        if (!answered.ok) throw new Error(`S3 answered a list with ${answered.status}.`)
+        const xml = await answered.text()
+        for (const [, one] of xml.matchAll(/<Contents>([\s\S]*?)<\/Contents>/g)) {
+          yield { key: text(one!, 'Key')!, lastModified: new Date(text(one!, 'LastModified')!) }
+        }
+        token = text(xml, 'IsTruncated') === 'true' ? text(xml, 'NextContinuationToken') : undefined
+      } while (token)
+    },
+  }
+}
+// mithaq-admin b06d8d335d306c07556f8f2b81fba20ba7ded198 a6b1f7b3a13ef66fb811f35844279694bfb8f3d08657170fa98e882bc0f5e079

package/template/templates/mithaq/src/storage/uploadthing.ts

@@ -0,0 +1,59 @@
+// UploadThing as a mithaq storage adapter for files already stored there: it reads, signs a
+// short-lived address and deletes by key, and never uploads, so new files go to another adapter.
+import type { StorageAdapter } from 'mithaq'
+
+export type UploadThingOptions = {
+  /** `UPLOADTHING_TOKEN`, the base64 JSON that names the API key and the app. */
+  token: string
+  /** The fetch every request goes through, which a test replaces. */
+  fetch?: typeof fetch
+}
+
+const getSeconds = 300
+const api = 'https://api.uploadthing.com/v6'
+
+export const uploadthing = ({ token, fetch: send = fetch }: UploadThingOptions): StorageAdapter => {
+  const { apiKey, appId } = JSON.parse(Buffer.from(token, 'base64').toString()) as { apiKey: string; appId: string }
+  const fileURL = (key: string) => `https://${appId}.ufs.sh/f/${encodeURIComponent(key)}`
+  const call = async (path: string, body: unknown) => {
+    const answered = await send(`${api}/${path}`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', 'x-uploadthing-api-key': apiKey },
+      body: JSON.stringify(body),
+    })
+    if (!answered.ok) throw new Error(`UploadThing answered ${path} with ${answered.status}.`)
+    return answered.json() as Promise<Record<string, unknown>>
+  }
+  return {
+    // UploadThing chose these keys and lists none of them, so no sweep ever reaches them.
+    prefix: '',
+    uploadInstructions: {
+      generate: async () => {
+        throw new Error('The UploadThing adapter reads and deletes the files already there, and uploads none. Send new uploads to another adapter.')
+      },
+    },
+    handleDelete: async ({ key }) => {
+      await call('deleteFiles', { fileKeys: [key] })
+    },
+    generateURL: ({ key }) => fileURL(key),
+    // UploadThing's signed address takes no disposition, so the stored type stands and an SVG
+    // stored there is served to draw, not to download.
+    staticHandler: async (_request, { doc }) => {
+      const { url } = await call('requestFileAccess', { fileKey: doc.key, expiresIn: getSeconds })
+      if (typeof url !== 'string') throw new Error('UploadThing answered requestFileAccess with no url.')
+      return new Response(null, { status: 302, headers: { Location: url } })
+    },
+    head: async ({ key }) => {
+      const answered = await send(fileURL(key), { method: 'HEAD' })
+      if (answered.status === 404) return null
+      if (!answered.ok) throw new Error(`UploadThing answered a HEAD with ${answered.status}.`)
+      return { size: Number(answered.headers.get('content-length')) }
+    },
+    readHead: async ({ key, bytes }) => {
+      const answered = await send(fileURL(key), { headers: { Range: `bytes=0-${bytes - 1}` } })
+      if (!answered.ok) throw new Error(`UploadThing answered a ranged GET with ${answered.status}.`)
+      return new Uint8Array(await answered.arrayBuffer()).subarray(0, bytes)
+    },
+  }
+}
+// mithaq-admin b06d8d335d306c07556f8f2b81fba20ba7ded198 edb513da5b7d5ee1a405e8943b00bd25fa0b1cbf0c6c3d1a2854deaea95b8564

package/template/templates/mithaq/src/ui/activity-page.tsx

@@ -0,0 +1,33 @@
+// The dashboard's Activity page: every change in the organization, read as the
+// viewer from the log's `find`, which answers this tenant's entries alone, of
+// the kayan the viewer lists. A file of its own beside `activity.tsx`, since the
+// shell it draws in holds the app's own pieces.
+import { useEffect, useState } from 'react'
+import { useAccess, useLocale } from 'mithaq/admin/react'
+import { ActivityLog, filtersOf, type ActivityQuery } from './activity.tsx'
+import { AppShell } from './app-shell.tsx'
+
+/**
+ * The page, filtered at first by what its link names, such as one record's
+ * entries from that record's panel. The link is read once the page is in the
+ * browser, since the server renders no location.
+ */
+export function ActivityPage() {
+  const { t } = useLocale()
+  const people = useAccess().collections?.user?.read === true
+  const [query, setQuery] = useState<ActivityQuery>()
+  useEffect(() => setQuery(filtersOf({ search: window.location.search, people })), [])
+  return (
+    <AppShell
+      regions={{
+        header: <h1>{t('auditLog.activity', 'Activity')}</h1>,
+        main: (
+          <section data-dashboard="activity" className="grid gap-4">
+            <p className="text-muted-foreground">{t('auditLog.about', 'Every change in this organization, newest first.')}</p>
+            {query ? <ActivityLog query={query} onQuery={setQuery} /> : <p className="text-muted-foreground text-sm">{t('auditLog.loading', 'Loading activity…')}</p>}
+          </section>
+        ),
+      }}
+    />
+  )
+}