@stacksjs/defaults 0.75.89 → 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 658 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. (105 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/` (235 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 235 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
-- 235 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 105 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 105, 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 105 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/` (105 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

@@ -0,0 +1,229 @@
+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,
+} from './feedback-token'
+
+interface FeedbackInput {
+  title?: unknown
+  description?: unknown
+}
+
+/**
+ * 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}`.
+ *
+ * The one unauthenticated write path the dashboard has, so it is deliberately
+ * narrow: a feedback link may add a card to the one board its token names,
+ * and may not read anything (stacksjs/stacks#2872).
+ *
+ * Every refusal answers 404 with the same sentence. A 401 would confirm the
+ * link once existed, and distinguishing unknown from revoked from expired
+ * tells a holder of a guessed token which half of the guess was right, or
+ * tells a revoked reviewer they were revoked rather than that the link simply
+ * stopped working. The reason is logged, not returned.
+ *
+ * Rate limited at the route rather than here, the way the other
+ * unauthenticated endpoints are.
+ */
+export default new Action({
+  name: 'Feedback Store',
+  description: 'Files a card on one board from a revocable feedback link.',
+  method: 'POST',
+  apiResponse: true,
+
+  async handle(request: RequestInstance<FeedbackInput>) {
+    const raw = String(request.getParam('token') || '')
+
+    // Shape before lookup, so a submit carrying a sentence, a path or a SQL
+    // fragment costs no query.
+    if (!looksLikeFeedbackToken(raw))
+      return response.json({ message: refusalMessage() }, 404)
+
+    const body = request.all()
+    const title = typeof body.title === 'string' ? body.title.trim() : ''
+    if (!title || title.length > MAX_TITLE)
+      return response.json({ message: `A title is required, up to ${MAX_TITLE} characters.` }, 400)
+
+    // Rejected rather than truncated. Silently dropping the end of somebody's
+    // report is worse than telling them it was too long.
+    const rawDescription = typeof body.description === 'string' ? body.description.trim() : ''
+    if (rawDescription.length > MAX_DESCRIPTION)
+      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', 'label'])
+        .executeTakeFirst()
+
+      const verdict = authorizeFeedbackToken(token)
+      if (!verdict.ok) {
+        // Logged with its reason and never with the token, so an operator can
+        // tell a revoked link from a guessed one without the log holding a
+        // live credential.
+        console.warn(`[FeedbackStoreAction] refused a submission: ${verdict.reason}`)
+        return response.json({ message: refusalMessage() }, 404)
+      }
+
+      const { param } = sqlHelpers(getDatabaseDialect())
+
+      // The board is checked rather than assumed. `feedback_tokens.board_id`
+      // cascades on delete, but SQLite enforces that only with
+      // `foreign_keys = ON`, which the framework sets while renaming and not
+      // otherwise, so a token can outlive its board.
+      const column = await db.unsafe(
+        `SELECT id FROM board_columns WHERE board_id = ${param(1)} ORDER BY position ASC, id ASC LIMIT 1`,
+        [verdict.boardId],
+      ).execute() as Array<{ id: number }>
+      const columnId = Number(column?.[0]?.id)
+      if (!Number.isInteger(columnId) || columnId <= 0) {
+        // The link is valid and there is nowhere to put the card. Not the
+        // submitter's problem to diagnose, so they get the same sentence.
+        console.warn(`[FeedbackStoreAction] board ${verdict.boardId} has no column to file into`)
+        return response.json({ message: refusalMessage() }, 404)
+      }
+
+      const maxRow = await db.unsafe(
+        `SELECT COALESCE(MAX(position), -1) AS m FROM cards WHERE column_id = ${param(1)}`,
+        [columnId],
+      ).execute() as Array<{ m: number }>
+      const nextPosition = (Number(maxRow?.[0]?.m ?? -1) + 1) || 0
+
+      const { Card } = await import('@stacksjs/orm')
+      const card = await Card.create({
+        columnId,
+        boardId: verdict.boardId,
+        title,
+        description,
+        position: nextPosition,
+        // No user. A feedback link authenticates nobody, which is the point
+        // of it, so the card is attributed by its board and its label rather
+        // than by an account that does not exist.
+        createdByUserId: null,
+        dueDate: null,
+        archived: false,
+      })
+
+      await db.unsafe(
+        `UPDATE feedback_tokens SET last_used_at = ${param(1)} WHERE id = ${param(2)}`,
+        [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: 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}`)
+  })
+})