@stacksjs/defaults 0.75.90 → 0.75.91

package/ai/skills/stacks-actions/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: stacks-actions
-description: Use when working with Stacks server actions - creating actions in app/Actions/, auto-generated API actions from the useApi model trait, the 660 default framework actions (auth, dashboard, commerce, content, deployment, jobs), action request/response handling, or action registration. Covers @stacksjs/actions and storage/framework/defaults/app/Actions/.
+description: Use when working with Stacks server actions - creating actions in app/Actions/, auto-generated API actions from the useApi model trait, the 663 default framework actions (auth, dashboard, commerce, content, deployment, jobs), action request/response handling, or action registration. Covers @stacksjs/actions and storage/framework/defaults/app/Actions/.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript
 allowed-tools: Read Edit Write Bash Grep Glob

package/ai/skills/stacks-auto-imports/SKILL.md

@@ -66,7 +66,7 @@ globalThis.toggleDark = toggleDark
 - **Custom Functions**: From `resources/functions/` (counter, dark mode, GPX, geo utilities)
 
 ### Server Auto-Imports (100+)
-- **All ORM Models**: User, Post, Author, Product, Order, Payment, Customer, etc. (106 models)
+- **All ORM Models**: User, Post, Author, Product, Order, Payment, Customer, etc. (107 models)
 - **Request Models**: UserRequest, PostRequest, OrderRequest, etc.
 - **Actions**: Action types and helpers
 - **Schema**: validation schema builder

package/ai/skills/stacks-dashboard/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: stacks-dashboard
-description: Use when building or customizing the Stacks admin dashboard, including dashboard pages, model management views, analytics widgets, commerce dashboards, content management, settings panels, deployment monitoring, job/queue management, or the 408 built-in dashboard components. Covers the dashboard system at storage/framework/defaults/.
+description: Use when building or customizing the Stacks admin dashboard, including dashboard pages, model management views, analytics widgets, commerce dashboards, content management, settings panels, deployment monitoring, job/queue management, or the 409 built-in dashboard components. Covers the dashboard system at storage/framework/defaults/.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript
 allowed-tools: Read Edit Write Bash Grep Glob
@@ -8,7 +8,7 @@ allowed-tools: Read Edit Write Bash Grep Glob
 
 # Stacks Dashboard
 
-The Stacks admin dashboard provides a full-featured admin panel with 100+ route views, 408 components, and a multi-section layout.
+The Stacks admin dashboard provides a full-featured admin panel with 100+ route views, 409 components, and a multi-section layout.
 
 ## Key Paths
 - Dashboard components: `storage/framework/defaults/resources/components/Dashboard/`

package/ai/skills/stacks-database/SKILL.md

@@ -12,7 +12,7 @@ allowed-tools: Read Edit Write Bash Grep Glob
 - Database package: `storage/framework/core/database/src/`
 - Configuration: `config/database.ts`
 - QB config: `config/query-builder.ts`
-- Migrations: `database/migrations/` (236 migration files, `.sql` format)
+- Migrations: `database/migrations/` (237 migration files, `.sql` format)
 - QB state: `.qb/`
 - ORM: `storage/framework/orm/`
 

package/ai/skills/stacks-migrations/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: stacks-migrations
-description: Use when working with database migrations in a Stacks application - creating migration files, running migrations, fresh migration (drop + recreate), seeding after migration, migration file naming conventions, or the 236 built-in migration files. For the database API itself (queries, connections, SQL helpers), see stacks-database.
+description: Use when working with database migrations in a Stacks application - creating migration files, running migrations, fresh migration (drop + recreate), seeding after migration, migration file naming conventions, or the 237 built-in migration files. For the database API itself (queries, connections, SQL helpers), see stacks-database.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript, SQLite >= 3.47.2
 allowed-tools: Read Edit Write Bash Grep Glob
@@ -119,6 +119,6 @@ The framework includes migrations for all built-in models:
 - Do not commit a second snapshot under `.qb/`; that indicates a missing `snapshotDir` configuration
 - If a generated SQLite migration rebuilds tables, test it against a copy of the current database and run `PRAGMA integrity_check` plus `PRAGMA foreign_key_check`
 - `--seed` flag after `migrate:fresh` seeds the database with factory data
-- 236 migration files exist by default for all framework models
+- 237 migration files exist by default for all framework models
 - SQLite >= 3.47.2 is required (system requirement)
 - For the database API (queries, connections), see the `stacks-database` skill

package/ai/skills/stacks-models/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: stacks-models
-description: Use when working with data models in Stacks - the defineModel() API, model attributes with validation and factories, relationships (hasOne/hasMany/belongsTo/belongsToMany), traits (useAuth, useUuid, useTimestamps, useSearch, useApi, billable, taggable, categorizable, commentable, likeable, observe), computed properties (get/set), model generation, and the 106 built-in framework models. Covers model definitions and storage/framework/defaults/app/Models/.
+description: Use when working with data models in Stacks - the defineModel() API, model attributes with validation and factories, relationships (hasOne/hasMany/belongsTo/belongsToMany), traits (useAuth, useUuid, useTimestamps, useSearch, useApi, billable, taggable, categorizable, commentable, likeable, observe), computed properties (get/set), model generation, and the 107 built-in framework models. Covers model definitions and storage/framework/defaults/app/Models/.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript, SQLite >= 3.47.2
 allowed-tools: Read Edit Write Bash Grep Glob
@@ -304,7 +304,7 @@ honoured: fewer rows are seeded rather than a duplicate combination.
 ## Built-in models by category
 
 The ones below are worth knowing by name. They are a selection, not the set:
-`storage/framework/defaults/app/Models/` holds 106, and that directory is the
+`storage/framework/defaults/app/Models/` holds 107, and that directory is the
 authority. This section said "All 62 built-in models by category" while
 listing fewer than that against 102 on disk, so an agent reading to the end
 had no way to tell it was short.

package/ai/skills/stacks-orm/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: stacks-orm
-description: Use when working with the Stacks ORM - defining models with defineModel(), model relationships (hasOne, hasMany, belongsTo, belongsToMany, morphOne, hasManyThrough), attributes, traits, factories, computed properties, query building, transactions, or the 106 built-in models. Covers @stacksjs/orm, storage/framework/orm/, and storage/framework/defaults/app/Models/.
+description: Use when working with the Stacks ORM - defining models with defineModel(), model relationships (hasOne, hasMany, belongsTo, belongsToMany, morphOne, hasManyThrough), attributes, traits, factories, computed properties, query building, transactions, or the 107 built-in models. Covers @stacksjs/orm, storage/framework/orm/, and storage/framework/defaults/app/Models/.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript, SQLite >= 3.47.2
 allowed-tools: Read Edit Write Bash Grep Glob
@@ -11,7 +11,7 @@ allowed-tools: Read Edit Write Bash Grep Glob
 ## Key Paths
 - Core ORM package: `storage/framework/core/orm/src/`
 - ORM implementation: `storage/framework/orm/`
-- Model definitions: `storage/framework/defaults/app/Models/` (106 models)
+- Model definitions: `storage/framework/defaults/app/Models/` (107 models)
 - Application models: `app/Models/`
 - Default model templates: `storage/framework/defaults/app/Models/`
 - ORM type globals: `storage/framework/types/orm-globals.d.ts`

package/app/Actions/Dashboard/Feedback/FeedbackStoreAction.ts

@@ -1,10 +1,21 @@
 import type { RequestInstance } from '@stacksjs/types'
+import { randomUUID } from 'node:crypto'
 import { Action } from '@stacksjs/actions/runtime'
 import { db, getDatabaseDialect, sqlHelpers } from '@stacksjs/database/runtime'
 import { response } from '@stacksjs/router'
 import { kanbanActionError } from '../Kanban/kanban-response'
+import {
+  acceptAttachment,
+  acceptAttachmentSize,
+  FEEDBACK_ATTACHMENT_MAX_FILES,
+  feedbackAttachmentPath,
+  SNIFF_BYTES,
+} from './feedback-attachment'
+import { notifyFeedbackFiled } from './feedback-notifier'
 import {
   authorizeFeedbackToken,
+  FEEDBACK_MAX_DESCRIPTION as MAX_DESCRIPTION,
+  FEEDBACK_MAX_TITLE as MAX_TITLE,
   hashFeedbackToken,
   looksLikeFeedbackToken,
   refusalMessage,
@@ -15,11 +26,43 @@ interface FeedbackInput {
   description?: unknown
 }
 
-/** Matches `Card.description`, so a submission cannot be longer than the column. */
-const MAX_DESCRIPTION = 10_000
-
-/** Matches `Card.title`. */
-const MAX_TITLE = 300
+/**
+ * Write the screenshot and record it against the card.
+ *
+ * Runs after the card exists, because the path is keyed by card id. A failure
+ * here is logged and swallowed: the report is already saved and is worth more
+ * than the picture, and telling the reviewer their submission failed would
+ * invite a resubmit that files the card twice.
+ */
+async function storeAttachment(
+  cardId: number,
+  attachment: { bytes: Uint8Array, mimeType: string, extension: string },
+): Promise<void> {
+  try {
+    const { dashboard } = await import('@stacksjs/config')
+    // `local` is private storage under `storage/app`. The default is not read
+    // from `filesystems.driver`, which an app may point at `public`: an
+    // unauthenticated stranger's upload does not belong in a web-served
+    // directory.
+    const disk = String((dashboard as any)?.feedback?.attachments?.disk || 'local')
+    const path = feedbackAttachmentPath(cardId, randomUUID(), attachment.extension)
+
+    const { Storage } = await import('@stacksjs/storage')
+    await Storage.disk(disk as never).write(path, attachment.bytes)
+
+    const { CardAttachment } = await import('@stacksjs/orm')
+    await CardAttachment.create({
+      cardId,
+      disk,
+      path,
+      mimeType: attachment.mimeType,
+      sizeBytes: attachment.bytes.byteLength,
+    })
+  }
+  catch (err) {
+    console.warn(`[FeedbackStoreAction] card ${cardId} was filed without its screenshot: ${err instanceof Error ? err.message : String(err)}`)
+  }
+}
 
 /**
  * `POST /api/feedback/{token}`.
@@ -63,11 +106,46 @@ export default new Action({
       return response.json({ message: `The description must be ${MAX_DESCRIPTION} characters or fewer.` }, 400)
     const description = rawDescription || undefined
 
+    // The screenshot is judged BEFORE anything is written. Filing the card
+    // first and then refusing the file would show the reviewer an error for a
+    // report that was in fact saved, and the obvious thing to do about an
+    // error is to send it again.
+    const sent = request.getFiles('screenshot')
+    const screenshot = sent.length > 0 ? sent[0] : request.file('screenshot')
+    if (sent.length > FEEDBACK_ATTACHMENT_MAX_FILES)
+      return response.json({ message: `Attach ${FEEDBACK_ATTACHMENT_MAX_FILES === 1 ? 'one screenshot' : `${FEEDBACK_ATTACHMENT_MAX_FILES} screenshots`} at most.` }, 400)
+
+    let attachment: { bytes: Uint8Array, mimeType: string, extension: string } | undefined
+    if (screenshot) {
+      // Size first, and on its own. The router hands this an `UploadedFile`
+      // wrapper, which reports `size` synchronously and has no `slice`, so
+      // reading the leading bytes means reading the whole file. Sniffing
+      // first would load a 2 GB upload into memory to decide it was too
+      // large.
+      const size = Number(screenshot.size || 0)
+      const sized = acceptAttachmentSize(size)
+      if (!sized.ok)
+        return response.json({ message: sized.message }, 400)
+
+      const bytes = await screenshot.bytes()
+      const verdict = acceptAttachment({ size, head: bytes.subarray(0, SNIFF_BYTES) })
+      if (!verdict.ok)
+        return response.json({ message: verdict.message }, 400)
+
+      attachment = {
+        bytes,
+        // From the bytes, never from `screenshot.mimeType`, which the
+        // submitter writes. The dashboard serves the file as this.
+        mimeType: verdict.type,
+        extension: verdict.extension,
+      }
+    }
+
     try {
       const token = await (db as any)
         .selectFrom('feedback_tokens')
         .where('token', '=', hashFeedbackToken(raw))
-        .select(['id', 'board_id', 'revoked_at', 'expires_at'])
+        .select(['id', 'board_id', 'revoked_at', 'expires_at', 'label'])
         .executeTakeFirst()
 
       const verdict = authorizeFeedbackToken(token)
@@ -123,9 +201,26 @@ export default new Action({
         [new Date().toISOString().slice(0, 19).replace('T', ' '), Number(token.id)],
       ).execute()
 
+      const cardId = Number(card.get('id'))
+
+      if (attachment)
+        await storeAttachment(cardId, attachment)
+
+      // `void`: the card is saved, so the reviewer is told it went through
+      // whatever the notification does. Blocking on an SMTP round-trip would
+      // make a mail outage look like a failed submission, and failing on one
+      // would be worse.
+      void notifyFeedbackFiled({
+        boardId: verdict.boardId,
+        cardId,
+        title,
+        description,
+        label: String(token.label ?? ''),
+      })
+
       // Acknowledgement only. Returning the card, its position or anything
       // about the board would make this a read endpoint, which it is not.
-      return { filed: true, id: Number(card.get('id')) }
+      return { filed: true, id: cardId }
     }
     catch (err) {
       return kanbanActionError(err, 'FeedbackStoreAction')

package/app/Actions/Dashboard/Feedback/feedback-attachment.test.ts

@@ -0,0 +1,192 @@
+import { describe, expect, it } from 'bun:test'
+import {
+  acceptAttachment,
+  acceptAttachmentSize,
+  FEEDBACK_ATTACHMENT_MAX_BYTES,
+  FEEDBACK_ATTACHMENT_TYPES,
+  feedbackAttachmentPath,
+  sniffImageType,
+  SNIFF_BYTES,
+} from './feedback-attachment'
+
+/**
+ * The attachment rules, which are the whole security boundary of an
+ * unauthenticated upload.
+ *
+ * Every one of these is reachable only by POSTing a crafted file to a live
+ * feedback link, so left in the action they would be rules nobody ever
+ * checked (stacksjs/stacks#2872).
+ */
+
+/** Leading bytes of a real file of each type, padded to the sniff window. */
+const HEADS: Record<string, number[]> = {
+  png: [0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A, 0x00, 0x00, 0x00, 0x0D],
+  jpeg: [0xFF, 0xD8, 0xFF, 0xE0, 0x00, 0x10, 0x4A, 0x46, 0x49, 0x46, 0x00, 0x01],
+  webp: [0x52, 0x49, 0x46, 0x46, 0x24, 0x00, 0x00, 0x00, 0x57, 0x45, 0x42, 0x50],
+  gif: [0x47, 0x49, 0x46, 0x38, 0x39, 0x61, 0x01, 0x00, 0x01, 0x00, 0x80, 0x00],
+}
+
+const head = (name: keyof typeof HEADS) => new Uint8Array(HEADS[name])
+const bytes = (text: string) => new TextEncoder().encode(text.padEnd(SNIFF_BYTES, ' '))
+
+describe('sniffImageType', () => {
+  it('reads each accepted format from its own leading bytes', () => {
+    expect(sniffImageType(head('png'))).toBe('image/png')
+    expect(sniffImageType(head('jpeg'))).toBe('image/jpeg')
+    expect(sniffImageType(head('webp'))).toBe('image/webp')
+    expect(sniffImageType(head('gif'))).toBe('image/gif')
+  })
+
+  it('reads GIF87a as well as GIF89a', () => {
+    const gif87 = new Uint8Array([0x47, 0x49, 0x46, 0x38, 0x37, 0x61, 0, 0, 0, 0, 0, 0])
+    expect(sniffImageType(gif87)).toBe('image/gif')
+  })
+
+  it('refuses a RIFF container that is not WebP', () => {
+    // A WAV file is RIFF too. Checking only the first four bytes would store
+    // audio as an image.
+    const wav = new Uint8Array([0x52, 0x49, 0x46, 0x46, 0x24, 0, 0, 0, 0x57, 0x41, 0x56, 0x45])
+    expect(sniffImageType(wav)).toBeNull()
+  })
+
+  it('refuses SVG, however it is dressed up', () => {
+    // SVG is XML and can carry script. It would be uploaded by an
+    // unauthenticated stranger and opened by a signed-in operator, which is a
+    // stored XSS rather than a screenshot. This must never start passing.
+    expect(sniffImageType(bytes('<svg xmlns='))).toBeNull()
+    expect(sniffImageType(bytes('<?xml versio'))).toBeNull()
+    expect(sniffImageType(bytes('<svg>'))).toBeNull()
+  })
+
+  it('refuses the things people try to pass off as images', () => {
+    for (const probe of ['<!DOCTYPE htm', '<html><body>', 'PK\u0003\u0004zip', '%PDF-1.7', '#!/bin/sh', 'GIF', ''])
+      expect(sniffImageType(bytes(probe))).toBeNull()
+  })
+
+  it('refuses a file too short to identify rather than reading past its end', () => {
+    expect(sniffImageType(new Uint8Array([0x89, 0x50]))).toBeNull()
+    expect(sniffImageType(new Uint8Array([0x52, 0x49, 0x46, 0x46]))).toBeNull()
+    expect(sniffImageType(new Uint8Array())).toBeNull()
+  })
+})
+
+describe('acceptAttachmentSize', () => {
+  it('is the gate that passes before a byte is read', () => {
+    // The router hands an action an `UploadedFile` wrapper, which reports
+    // `size` synchronously and has NO `slice` - reading the leading bytes
+    // means reading the whole file. The first version of the action sniffed
+    // first and threw `screenshot.slice is not a function` on every upload,
+    // which only a real multipart POST found: every unit test here passes a
+    // plain Uint8Array, and so did the one the action was written against.
+    expect(acceptAttachmentSize(120_000)).toEqual({ ok: true })
+    expect(acceptAttachmentSize(FEEDBACK_ATTACHMENT_MAX_BYTES)).toEqual({ ok: true })
+  })
+
+  it('refuses an empty or absurd size', () => {
+    for (const size of [0, -1, Number.NaN, Number.POSITIVE_INFINITY])
+      expect(acceptAttachmentSize(size)).toMatchObject({ ok: false, reason: 'empty' })
+  })
+
+  it('refuses one byte over the cap', () => {
+    expect(acceptAttachmentSize(FEEDBACK_ATTACHMENT_MAX_BYTES + 1))
+      .toMatchObject({ ok: false, reason: 'too-large' })
+  })
+
+  it('agrees with acceptAttachment, so the order of refusals is the same either way', () => {
+    for (const size of [0, 1, FEEDBACK_ATTACHMENT_MAX_BYTES, FEEDBACK_ATTACHMENT_MAX_BYTES + 1]) {
+      const gate = acceptAttachmentSize(size)
+      const full = acceptAttachment({ size, head: head('png') })
+      expect(full.ok).toBe(gate.ok)
+      if (!gate.ok && !full.ok)
+        expect(full.reason).toBe(gate.reason)
+    }
+  })
+})
+
+describe('acceptAttachment', () => {
+  it('accepts a real screenshot and names what to store it as', () => {
+    expect(acceptAttachment({ size: 120_000, head: head('png') }))
+      .toEqual({ ok: true, type: 'image/png', extension: 'png' })
+    // JPEG stores as `jpg`, which is the extension and not the type name.
+    expect(acceptAttachment({ size: 1, head: head('jpeg') }))
+      .toEqual({ ok: true, type: 'image/jpeg', extension: 'jpg' })
+  })
+
+  it('refuses an empty file', () => {
+    for (const size of [0, -1, Number.NaN, Number.POSITIVE_INFINITY]) {
+      const verdict = acceptAttachment({ size, head: head('png') })
+      expect(verdict).toMatchObject({ ok: false, reason: 'empty' })
+    }
+  })
+
+  it('refuses one byte over the cap, and accepts the cap itself', () => {
+    expect(acceptAttachment({ size: FEEDBACK_ATTACHMENT_MAX_BYTES, head: head('png') }).ok).toBe(true)
+    const over = acceptAttachment({ size: FEEDBACK_ATTACHMENT_MAX_BYTES + 1, head: head('png') })
+    expect(over).toMatchObject({ ok: false, reason: 'too-large' })
+    expect((over as { message: string }).message).toContain('5 MB')
+  })
+
+  it('checks the size before the bytes, so an enormous upload costs nothing to refuse', () => {
+    // Head deliberately empty: a verdict of `too-large` rather than
+    // `unsupported` is what says the size was decided first.
+    expect(acceptAttachment({ size: 2 ** 31, head: new Uint8Array() }))
+      .toMatchObject({ ok: false, reason: 'too-large' })
+  })
+
+  it('refuses a file whose bytes are not an accepted image', () => {
+    const verdict = acceptAttachment({ size: 400, head: bytes('%PDF-1.7') })
+    expect(verdict).toMatchObject({ ok: false, reason: 'unsupported' })
+    // Says which rule was hit. "Could not attach that" leaves a reviewer
+    // guessing between the size and the format.
+    expect((verdict as { message: string }).message).toContain('PNG')
+  })
+
+  it('tells a reviewer which rule they hit, in words', () => {
+    for (const probe of [
+      { size: 0, head: head('png') },
+      { size: FEEDBACK_ATTACHMENT_MAX_BYTES * 2, head: head('png') },
+      { size: 10, head: bytes('nope') },
+    ]) {
+      const verdict = acceptAttachment(probe)
+      expect(verdict.ok).toBe(false)
+      expect((verdict as { message: string }).message.length).toBeGreaterThan(10)
+      // User-visible copy: no em-dashes, per the project's own rule.
+      expect((verdict as { message: string }).message).not.toMatch(/[–—]/)
+    }
+  })
+})
+
+describe('feedbackAttachmentPath', () => {
+  const id = '0190f3b4-7c21-4f0a-9a1e-3d5c7b8e9f00'
+
+  it('writes under a fixed prefix, keyed by card', () => {
+    expect(feedbackAttachmentPath(42, id, 'png')).toBe(`feedback/42/${id}.png`)
+  })
+
+  it('lower-cases the generated id so one file has one path', () => {
+    expect(feedbackAttachmentPath(42, id.toUpperCase(), 'png')).toBe(`feedback/42/${id}.png`)
+  })
+
+  it('refuses an id that is not one it generated', () => {
+    // The submitter contributes no segment of the path, so anything shaped
+    // like traversal or an absolute path is a bug upstream rather than input
+    // to sanitise.
+    for (const bad of ['../../etc/passwd', 'a/b', '/abs', '', 'short', 'id with spaces', 'x'.repeat(65)])
+      expect(() => feedbackAttachmentPath(42, bad, 'png')).toThrow('Refusing to build')
+  })
+
+  it('refuses an extension it did not choose', () => {
+    for (const bad of ['', 'svg+xml', '../', 'PNG', 'phtml'])
+      expect(() => feedbackAttachmentPath(42, id, bad)).toThrow('Refusing to build')
+  })
+
+  it('refuses to build a path without a card', () => {
+    for (const bad of [0, -1, 1.5, Number.NaN])
+      expect(() => feedbackAttachmentPath(bad, id, 'png')).toThrow('needs the id of the card')
+  })
+
+  it('builds a path for every extension it may be handed', () => {
+    for (const extension of Object.values(FEEDBACK_ATTACHMENT_TYPES))
+      expect(feedbackAttachmentPath(1, id, extension)).toBe(`feedback/1/${id}.${extension}`)
+  })
+})

package/app/Actions/Dashboard/Feedback/feedback-attachment.ts

@@ -0,0 +1,161 @@
+/**
+ * What a feedback submission may attach, and where it is written.
+ *
+ * A screenshot is most of what a reviewer sends, which is why
+ * stacksjs/stacks#2872 asks for it. It is also the one part of this feature
+ * that is an unauthenticated write, so every decision is here rather than in
+ * the action: a limit that can only be reached through an HTTP request with a
+ * crafted file is a limit nobody tests.
+ *
+ * The existing `FileUploadAction` is deliberately not reused. It takes `disk`
+ * and `path` from the request, which is right for a signed-in dashboard user
+ * and an arbitrary-write primitive for a feedback link.
+ */
+
+/**
+ * One file per submission.
+ *
+ * A reviewer sends one screenshot of one thing; the brief asks for one thing
+ * per message so each can be picked up on its own. More than one is a
+ * multi-file upload API on an endpoint that authenticates nobody.
+ */
+export const FEEDBACK_ATTACHMENT_MAX_FILES = 1
+
+/**
+ * 5 MB, which is a generous full-window PNG screenshot on a retina display
+ * and far below what would make this worth using as free object storage. The
+ * route's rate limit caps the rest.
+ */
+export const FEEDBACK_ATTACHMENT_MAX_BYTES = 5 * 1024 * 1024
+
+/**
+ * The image types accepted, and the extension each is stored under.
+ *
+ * SVG is deliberately absent and must stay absent. It is XML, it can carry
+ * script, and it would be uploaded by an unauthenticated stranger and later
+ * opened by a signed-in operator looking at their own dashboard, which is
+ * the shape of a stored cross-site scripting bug rather than a screenshot.
+ *
+ * Nothing here is decided from the declared `Content-Type`, which the
+ * submitter writes.
+ */
+export const FEEDBACK_ATTACHMENT_TYPES = {
+  'image/png': 'png',
+  'image/jpeg': 'jpg',
+  'image/webp': 'webp',
+  'image/gif': 'gif',
+} as const
+
+export type FeedbackAttachmentType = keyof typeof FEEDBACK_ATTACHMENT_TYPES
+
+/** How many leading bytes {@link sniffImageType} needs. */
+export const SNIFF_BYTES = 12
+
+function startsWith(bytes: Uint8Array, signature: readonly number[], offset = 0): boolean {
+  if (bytes.length < offset + signature.length)
+    return false
+  return signature.every((byte, index) => bytes[offset + index] === byte)
+}
+
+/**
+ * The type the bytes actually are, or null.
+ *
+ * Read from the file's own leading bytes, because the declared content type
+ * and the filename are both written by whoever is uploading. A `.png` that is
+ * an HTML document would otherwise be stored as an image and served as one.
+ */
+export function sniffImageType(bytes: Uint8Array): FeedbackAttachmentType | null {
+  // \x89PNG\r\n\x1a\n
+  if (startsWith(bytes, [0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A]))
+    return 'image/png'
+  // JPEG's SOI, then any marker.
+  if (startsWith(bytes, [0xFF, 0xD8, 0xFF]))
+    return 'image/jpeg'
+  // RIFF....WEBP: the size field sits between the two, so the second
+  // signature is checked at its own offset rather than appended.
+  if (startsWith(bytes, [0x52, 0x49, 0x46, 0x46]) && startsWith(bytes, [0x57, 0x45, 0x42, 0x50], 8))
+    return 'image/webp'
+  // GIF87a and GIF89a share these four.
+  if (startsWith(bytes, [0x47, 0x49, 0x46, 0x38]))
+    return 'image/gif'
+  return null
+}
+
+export type FeedbackAttachmentRefusal = 'empty' | 'too-large' | 'unsupported'
+
+export type FeedbackAttachmentVerdict =
+  | { ok: true, type: FeedbackAttachmentType, extension: string }
+  | { ok: false, reason: FeedbackAttachmentRefusal, message: string }
+
+/**
+ * Whether a file of this size may be attached at all.
+ *
+ * Separate from {@link acceptAttachment} because it is the gate that has to
+ * be passed BEFORE the bytes are read. The router hands an action an
+ * `UploadedFile` wrapper, which exposes `size` synchronously and has no
+ * `slice`, so reading the leading bytes means reading the whole file: a
+ * caller that sniffed first would load a 2 GB upload into memory to decide
+ * it was too large. Checked by itself, nothing is read.
+ */
+export function acceptAttachmentSize(size: number): { ok: true } | { ok: false, reason: FeedbackAttachmentRefusal, message: string } {
+  if (!Number.isFinite(size) || size <= 0)
+    return { ok: false, reason: 'empty', message: 'That file is empty.' }
+
+  if (size > FEEDBACK_ATTACHMENT_MAX_BYTES) {
+    const mb = Math.floor(FEEDBACK_ATTACHMENT_MAX_BYTES / (1024 * 1024))
+    return { ok: false, reason: 'too-large', message: `A screenshot must be ${mb} MB or smaller.` }
+  }
+
+  return { ok: true }
+}
+
+/**
+ * Whether this file may be attached.
+ *
+ * `size` is the whole file's length and `head` its leading bytes. The size is
+ * judged first, through {@link acceptAttachmentSize}, so the order of the
+ * refusals is the same whether a caller gates on size separately or not.
+ */
+export function acceptAttachment(input: { size: number, head: Uint8Array }): FeedbackAttachmentVerdict {
+  const sized = acceptAttachmentSize(input.size)
+  if (!sized.ok)
+    return sized
+
+  const type = sniffImageType(input.head)
+  if (!type) {
+    // Named rather than vague: a reviewer who tried to attach a PDF or a zip
+    // should know which of the two rules they hit.
+    return { ok: false, reason: 'unsupported', message: 'Attach a PNG, JPEG, WebP or GIF image.' }
+  }
+
+  return { ok: true, type, extension: FEEDBACK_ATTACHMENT_TYPES[type] }
+}
+
+const ALLOWED_EXTENSIONS: ReadonlySet<string> = new Set(Object.values(FEEDBACK_ATTACHMENT_TYPES))
+
+/**
+ * Where the file is written.
+ *
+ * Every segment is generated. The submitter contributes no part of the path,
+ * not even the extension, which comes from the sniffed type: a filename is an
+ * untrusted string and path traversal through an upload name is the oldest
+ * bug in this category.
+ *
+ * Under a fixed `feedback/` prefix so an operator can find, audit or sweep
+ * the whole lot, and keyed by card so a deleted card's screenshot is one
+ * prefix to remove.
+ */
+export function feedbackAttachmentPath(cardId: number, id: string, extension: string): string {
+  if (!Number.isSafeInteger(cardId) || cardId <= 0)
+    throw new Error('A feedback attachment needs the id of the card it belongs to.')
+  if (!/^[0-9a-f-]{8,64}$/i.test(id))
+    throw new Error(`Refusing to build an attachment path from ${JSON.stringify(id)}.`)
+  // An allowlist, not a shape check. `^[a-z0-9]{2,5}$` admitted `phtml`,
+  // which is a shape a `.png` can never have and a suffix some web servers
+  // will happily execute. The extension always comes from
+  // FEEDBACK_ATTACHMENT_TYPES, so membership is the real rule.
+  if (!ALLOWED_EXTENSIONS.has(extension))
+    throw new Error(`Refusing to build an attachment path with extension ${JSON.stringify(extension)}.`)
+
+  return `feedback/${cardId}/${id.toLowerCase()}.${extension}`
+}