@stacksjs/defaults 0.75.90 → 0.75.91

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

@@ -0,0 +1,144 @@
+import { describe, expect, it } from 'bun:test'
+import { feedbackNotification, planFeedbackFanout } from './feedback-notifier'
+
+/**
+ * Who gets told when feedback arrives, and what they are told.
+ *
+ * Both halves are reachable only by filing a card through a live link against
+ * configured channels, so left in the fan-out they would be tested by a
+ * reviewer noticing that nobody heard from them.
+ */
+
+describe('planFeedbackFanout', () => {
+  it('sends nothing while it is off', () => {
+    expect(planFeedbackFanout(undefined)).toEqual({ send: false, reason: 'disabled' })
+    expect(planFeedbackFanout({})).toEqual({ send: false, reason: 'disabled' })
+    expect(planFeedbackFanout({ enabled: false, channels: ['chat'] })).toEqual({ send: false, reason: 'disabled' })
+  })
+
+  it('broadcasts chat once, with no recipient, however many are listed', () => {
+    // Every listed person would otherwise post the same message into the same
+    // Slack channel.
+    const plan = planFeedbackFanout({
+      enabled: true,
+      channels: ['chat'],
+      recipients: [{ email: 'a@example.com' }, { email: 'b@example.com' }],
+    })
+
+    expect(plan).toEqual({ send: true, targets: [{ recipient: {}, channels: ['chat'] }], unreachable: [] })
+  })
+
+  it('defaults to chat when no channel is named', () => {
+    const plan = planFeedbackFanout({ enabled: true })
+    expect(plan.send).toBe(true)
+    expect((plan as any).targets).toEqual([{ recipient: {}, channels: ['chat'] }])
+  })
+
+  it('offers a recipient only the channels whose contact field it carries', () => {
+    // `notify()` throws when the email channel gets a recipient with no
+    // address, and one throw per card is how a half-filled list becomes no
+    // notifications at all.
+    const plan = planFeedbackFanout({
+      enabled: true,
+      channels: ['email', 'sms', 'database'],
+      recipients: [
+        { email: 'chris@example.com' },
+        { phone: '+15550000' },
+        { userId: 7 },
+        { email: 'both@example.com', phone: '+15551111' },
+      ],
+    })
+
+    expect(plan.send).toBe(true)
+    expect((plan as any).targets).toEqual([
+      { recipient: { email: 'chris@example.com' }, channels: ['email'] },
+      { recipient: { phone: '+15550000' }, channels: ['sms'] },
+      { recipient: { userId: 7 }, channels: ['database'] },
+      { recipient: { email: 'both@example.com', phone: '+15551111' }, channels: ['email', 'sms'] },
+    ])
+    expect((plan as any).unreachable).toEqual([])
+  })
+
+  it('leaves out a recipient whose contact field is blank', () => {
+    const plan = planFeedbackFanout({
+      enabled: true,
+      channels: ['email'],
+      recipients: [{ email: '   ' }, { email: 'real@example.com' }],
+    })
+
+    expect((plan as any).targets).toEqual([{ recipient: { email: 'real@example.com' }, channels: ['email'] }])
+  })
+
+  it('reports a channel configured with nobody able to receive it', () => {
+    // "Configured and delivering nothing" and "not configured" look the same
+    // from outside, and only one of them is a mistake.
+    const plan = planFeedbackFanout({
+      enabled: true,
+      channels: ['chat', 'email'],
+      recipients: [{ phone: '+15550000' }],
+    })
+
+    expect(plan.send).toBe(true)
+    expect((plan as any).unreachable).toEqual(['email'])
+  })
+
+  it('refuses a channel list that can reach nobody at all', () => {
+    expect(planFeedbackFanout({ enabled: true, channels: ['email'] }))
+      .toEqual({ send: false, reason: 'no-recipients' })
+    expect(planFeedbackFanout({ enabled: true, channels: ['email'], recipients: [{ phone: '+1' }] }))
+      .toEqual({ send: false, reason: 'no-recipients' })
+    expect(planFeedbackFanout({ enabled: true, channels: [] }))
+      .toEqual({ send: false, reason: 'no-channels' })
+  })
+
+  it('drops a channel name it does not know rather than handing it to notify', () => {
+    const plan = planFeedbackFanout({ enabled: true, channels: ['chat', 'carrier-pigeon' as any] })
+    expect((plan as any).targets).toEqual([{ recipient: {}, channels: ['chat'] }])
+  })
+})
+
+describe('feedbackNotification', () => {
+  const base = {
+    boardId: 4,
+    cardId: 42,
+    title: 'Checkout button does nothing on iPhone',
+    label: 'Pawel',
+  }
+
+  it('names the board, the card and the link it came through', () => {
+    const { subject, body, data } = feedbackNotification({ ...base, boardName: 'Feedback' })
+
+    expect(subject).toBe('New feedback on Feedback: Checkout button does nothing on iPhone')
+    expect(body).toContain('Board: Feedback (/kanban/4)')
+    expect(body).toContain('Card: 42')
+    expect(body).toContain('Through the link for: Pawel')
+    expect(data).toEqual({ boardId: 4, cardId: 42, label: 'Pawel' })
+  })
+
+  it('falls back to the board id when the name could not be read', () => {
+    for (const boardName of [undefined, null, '   ']) {
+      const { subject, body } = feedbackNotification({ ...base, boardName })
+      expect(subject).toContain('board 4')
+      expect(body).toContain('Board: board 4 (/kanban/4)')
+    }
+  })
+
+  it('quotes the description and cuts a long one', () => {
+    const short = feedbackNotification({ ...base, description: 'Tapped it twice, nothing happened.' })
+    expect(short.body).toContain('Tapped it twice, nothing happened.')
+
+    const long = feedbackNotification({ ...base, description: 'x'.repeat(5000) })
+    expect(long.body).toContain('...')
+    // A 10k-character report must not become a 10k-character SMS.
+    expect(long.body.length).toBeLessThan(1200)
+  })
+
+  it('carries no token, by having none to carry', () => {
+    // The whole message is built from the board, the card and the label. An
+    // operator revokes by label, so the raw token never needs to appear and
+    // notifications are stored and forwarded by things nobody audits.
+    const { subject, body, data } = feedbackNotification({ ...base, boardName: 'Feedback', description: 'd' })
+    const everything = `${subject}\n${body}\n${JSON.stringify(data)}`
+    expect(everything).not.toMatch(/[0-9a-f]{64}/)
+  })
+})

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

@@ -0,0 +1,211 @@
+/**
+ * Telling somebody that feedback arrived.
+ *
+ * A card filed through a feedback link lands on a board nobody is necessarily
+ * looking at, so the feature's own brief asks for a notification "so feedback
+ * is not found by accident" (stacksjs/stacks#2872).
+ *
+ * The fan-out mirrors `dashboard.ci.notifications`, down to the channel and
+ * recipient shapes, rather than inventing a second convention for the same
+ * job.
+ *
+ * Two deliberate differences from the CI notifier:
+ *
+ * - No cooldown. CI needs one because a flapping repo re-reports the same
+ *   fact; every feedback card is a different person saying a different thing,
+ *   so a cooldown would not de-duplicate anything, it would silently drop
+ *   reports. The route's rate limit is what bounds the volume.
+ * - A recipient is matched to the channels it can actually carry. `notify()`
+ *   throws when the `email` channel gets a recipient with no address, and a
+ *   throw per card is how a half-filled recipient list turns into no
+ *   notifications at all.
+ */
+
+export type FeedbackNotificationChannel = 'email' | 'sms' | 'chat' | 'database'
+
+export interface FeedbackNotificationRecipient {
+  email?: string
+  phone?: string
+  userId?: number
+}
+
+export interface FeedbackNotificationSettings {
+  enabled?: boolean
+  channels?: FeedbackNotificationChannel[]
+  recipients?: FeedbackNotificationRecipient[]
+}
+
+/** What each channel needs on a recipient before `notify()` will take it. */
+const REQUIRES: Record<FeedbackNotificationChannel, keyof FeedbackNotificationRecipient | null> = {
+  email: 'email',
+  sms: 'phone',
+  database: 'userId',
+  // Already scoped to one Slack channel by its own env, so it carries no
+  // recipient at all.
+  chat: null,
+}
+
+export interface FeedbackFanoutTarget {
+  recipient: FeedbackNotificationRecipient
+  channels: FeedbackNotificationChannel[]
+}
+
+export type FeedbackFanout =
+  | { send: false, reason: 'disabled' | 'no-channels' | 'no-recipients' }
+  | { send: true, targets: FeedbackFanoutTarget[], unreachable: FeedbackNotificationChannel[] }
+
+/**
+ * Who gets told, and through what.
+ *
+ * Pure, so the awkward combinations can be read off a test rather than
+ * discovered by filing feedback: a channel list with nobody who can receive
+ * it, a recipient carrying the wrong contact field for the channel it was
+ * listed under, `chat` alongside channels that do need a recipient.
+ *
+ * `unreachable` names the configured channels that reached nobody. Returned
+ * rather than dropped: "configured and delivering nothing" and "not
+ * configured" look identical from the outside, and only one of them is a
+ * mistake.
+ */
+export function planFeedbackFanout(settings: FeedbackNotificationSettings | undefined): FeedbackFanout {
+  if (!settings?.enabled)
+    return { send: false, reason: 'disabled' }
+
+  const channels = (settings.channels ?? ['chat']).filter(channel => channel in REQUIRES)
+  if (channels.length === 0)
+    return { send: false, reason: 'no-channels' }
+
+  const targets: FeedbackFanoutTarget[] = []
+  const reached = new Set<FeedbackNotificationChannel>()
+
+  // `chat` goes out once with no recipient, however many people are listed:
+  // every one of them would otherwise post the same message to the same
+  // Slack channel.
+  const broadcast = channels.filter(channel => REQUIRES[channel] === null)
+  if (broadcast.length > 0) {
+    targets.push({ recipient: {}, channels: broadcast })
+    for (const channel of broadcast) reached.add(channel)
+  }
+
+  const addressed = channels.filter(channel => REQUIRES[channel] !== null)
+  for (const recipient of settings.recipients ?? []) {
+    const usable = addressed.filter((channel) => {
+      const field = REQUIRES[channel]!
+      const value = recipient[field]
+      return typeof value === 'string' ? value.trim().length > 0 : value !== undefined && value !== null
+    })
+    if (usable.length === 0)
+      continue
+    targets.push({ recipient, channels: usable })
+    for (const channel of usable) reached.add(channel)
+  }
+
+  if (targets.length === 0)
+    return { send: false, reason: 'no-recipients' }
+
+  return { send: true, targets, unreachable: channels.filter(channel => !reached.has(channel)) }
+}
+
+export interface FeedbackNotificationInput {
+  boardId: number
+  boardName?: string | null
+  cardId: number
+  title: string
+  description?: string
+  /** The link's label, so two reviewers' feedback can be told apart. */
+  label: string
+}
+
+/** How long a quoted description runs before it is cut. */
+const EXCERPT = 600
+
+/**
+ * The message itself.
+ *
+ * No URL. The board lives at `/kanban/{id}` of whatever origin serves the
+ * dashboard, which is not always the app's own, and a notification carrying a
+ * link that 404s for everybody is worse than one carrying a path.
+ *
+ * Never the token. The notification says which link a card came through by
+ * its label, which is what an operator revokes by.
+ */
+export function feedbackNotification(input: FeedbackNotificationInput): {
+  subject: string
+  body: string
+  data: Record<string, unknown>
+} {
+  const board = input.boardName?.trim() || `board ${input.boardId}`
+  const description = input.description?.trim()
+
+  const lines = [`${input.title}`, '']
+  if (description)
+    lines.push(description.length > EXCERPT ? `${description.slice(0, EXCERPT)}...` : description, '')
+  lines.push(`Board: ${board} (/kanban/${input.boardId})`)
+  lines.push(`Card: ${input.cardId}`)
+  lines.push(`Through the link for: ${input.label}`)
+
+  return {
+    subject: `New feedback on ${board}: ${input.title}`,
+    body: lines.join('\n'),
+    data: {
+      boardId: input.boardId,
+      cardId: input.cardId,
+      label: input.label,
+    },
+  }
+}
+
+/** The board's own name, for the subject line. Null if it cannot be read. */
+async function boardName(boardId: number): Promise<string | null> {
+  try {
+    const { db } = await import('@stacksjs/database/runtime')
+    const row = await (db as any).selectFrom('boards').select(['name']).where('id', '=', boardId).executeTakeFirst()
+    const name = row?.name
+    return typeof name === 'string' && name.trim() ? name : null
+  }
+  catch {
+    // The message reads fine without it, and a notification is not worth
+    // failing over a name.
+    return null
+  }
+}
+
+/**
+ * Fan the notification out. Call as `void notifyFeedbackFiled(...)`.
+ *
+ * The card is already saved by the time this runs, so nothing here may fail
+ * the submission: a reviewer must not be told their report did not go through
+ * because an SMTP host was down. Every error is logged and swallowed, which is
+ * the same contract `runCiFailureNotifier` has.
+ */
+export async function notifyFeedbackFiled(input: FeedbackNotificationInput): Promise<void> {
+  try {
+    const { dashboard } = await import('@stacksjs/config')
+    const plan = planFeedbackFanout((dashboard as any)?.feedback?.notifications)
+    if (!plan.send)
+      return
+
+    for (const channel of plan.unreachable)
+      console.warn(`[feedback-notifier] the ${channel} channel is configured but nobody can receive it`)
+
+    const { notify } = await import('@stacksjs/notifications')
+    // Only now, because it is a query the submission does not need: the hot
+    // path has already answered the reviewer, and an app with notifications
+    // off never runs this at all.
+    const payload = feedbackNotification({ ...input, boardName: input.boardName ?? await boardName(input.boardId) })
+
+    for (const target of plan.targets) {
+      try {
+        // `ignorePreferences`, as the CI notifier does: this is an operator
+        // alert on a surface they switched on, not a per-user subscription.
+        await notify(target.recipient, payload, target.channels, { ignorePreferences: true })
+      }
+      catch (err) {
+        console.warn(`[feedback-notifier] notify failed: ${err instanceof Error ? err.message : String(err)}`)
+      }
+    }
+  }
+  catch (err) {
+    console.warn(`[feedback-notifier] could not notify: ${err instanceof Error ? err.message : String(err)}`)
+  }
+}

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

@@ -18,6 +18,19 @@ import { createHash, randomBytes } from 'node:crypto'
 /** 256 bits. The raw token is the only secret, so it carries all the entropy. */
 export const FEEDBACK_TOKEN_BYTES = 32
 
+/**
+ * What a submission may carry, matching `cards.title` and
+ * `cards.description`.
+ *
+ * Here rather than in the action so the form can render the same limits it
+ * will be judged against. A `maxlength` the server disagrees with is the
+ * worst of both: the reviewer is either stopped from typing something that
+ * would have been accepted, or allowed to write a report that is refused on
+ * submit.
+ */
+export const FEEDBACK_MAX_TITLE = 300
+export const FEEDBACK_MAX_DESCRIPTION = 10_000
+
 /** A raw token as it appears in a link, and as the column stores it. */
 const RAW_TOKEN = /^[0-9a-f]{64}$/
 

package/app/Actions/Dashboard/Kanban/CardShowAction.ts

@@ -1,6 +1,7 @@
 import type { RequestInstance } from '@stacksjs/types'
 import { Action } from '@stacksjs/actions/runtime'
 import { db, getDatabaseDialect, sqlHelpers } from '@stacksjs/database/runtime'
+import { cardAttachments } from './card-attachments'
 import { modelBoolean } from './kanban-model'
 import { kanbanActionError, kanbanError } from './kanban-response'
 
@@ -29,11 +30,12 @@ interface CardRow {
  * pivots) — this endpoint is for the case where the user lands
  * directly on a card URL or refreshes mid-modal.
  *
- * Three queries via `Promise.all`:
- *   1. The card itself.
- *   2. Labels via the card_labels pivot (with the label row).
- *   3. Assignees via the card_assignees pivot (with user.name/email).
- *   4. Comments (denormalised user name/email for display).
+ * The card itself, then four in parallel via `Promise.all`:
+ *   1. Labels via the card_labels pivot (with the label row).
+ *   2. Assignees via the card_assignees pivot (with user.name/email).
+ *   3. Comments (denormalised user name/email for display).
+ *   4. Attachments, each with a freshly signed, expiring URL. They live on a
+ *      private disk, so there is no path a browser could fetch.
  */
 export default new Action({
   name: 'Kanban Card Show',
@@ -59,7 +61,7 @@ export default new Action({
         return kanbanError('Card not found', 404)
       }
 
-      const [labels, assignees, comments] = await Promise.all([
+      const [labels, assignees, comments, attachments] = await Promise.all([
         db.unsafe(
           `SELECT l.id, l.name, l.color
           FROM card_labels cl
@@ -83,6 +85,9 @@ export default new Action({
           ORDER BY cc.created_at ASC, cc.id ASC`,
           [id],
         ).execute() as Promise<Array<{ id: number, uuid: string | null, user_id: number | null, body: string, created_at: string | null, updated_at: string | null, name: string | null, email: string | null }>>,
+        // Each one carries a freshly signed, expiring URL: the bytes are on a
+        // private disk, so there is no path the browser could fetch.
+        cardAttachments(id),
       ])
 
       return {
@@ -108,6 +113,7 @@ export default new Action({
           assignedByUserId: a.assigned_by_user_id,
           assignedAt: a.created_at,
         })),
+        attachments,
         comments: (comments ?? []).map(c => ({
           id: c.id,
           uuid: c.uuid,

package/app/Actions/Dashboard/Kanban/card-attachments.test.ts

@@ -0,0 +1,125 @@
+import { afterAll, afterEach, describe, expect, it, spyOn } from 'bun:test'
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { CARD_ATTACHMENT_URL_TTL_SECONDS, shapeCardAttachment, signCardAttachmentUrl } from './card-attachments'
+
+const row = {
+  id: 7,
+  uuid: 'c0ffee00-0000-4000-8000-000000000000',
+  disk: 'local',
+  path: 'feedback/42/0190f3b4-7c21-4f0a-9a1e-3d5c7b8e9f00.png',
+  mime_type: 'image/png',
+  size_bytes: 120_000,
+  created_at: '2026-10-08 09:12:00',
+}
+
+describe('shapeCardAttachment', () => {
+  it('returns what the dialog renders and nothing else', () => {
+    expect(shapeCardAttachment(row, 'https://example.com/__storage/x?token=y')).toEqual({
+      id: 7,
+      uuid: 'c0ffee00-0000-4000-8000-000000000000',
+      mimeType: 'image/png',
+      sizeBytes: 120_000,
+      createdAt: '2026-10-08 09:12:00',
+      url: 'https://example.com/__storage/x?token=y',
+    })
+  })
+
+  it('never publishes the storage path or the disk', () => {
+    // The signed URL already carries the path it grants, so the bare path
+    // adds nothing a client can use and does invite trying it without a
+    // token.
+    const shaped = shapeCardAttachment(row, null) as Record<string, unknown>
+    expect(Object.keys(shaped).sort()).toEqual(['createdAt', 'id', 'mimeType', 'sizeBytes', 'url', 'uuid'])
+    expect(JSON.stringify(shaped)).not.toContain('feedback/42')
+    expect(JSON.stringify(shaped)).not.toContain('local')
+  })
+
+  it('lists an attachment whose URL could not be minted', () => {
+    // Null, not omitted and not thrown: "there is a screenshot nobody can
+    // open" is worth chasing and is a different problem from "there is no
+    // screenshot".
+    expect(shapeCardAttachment(row, null).url).toBeNull()
+  })
+
+  it('reads a row whose numbers arrive as strings', () => {
+    // SQLite and Postgres disagree about this often enough that the Kanban
+    // actions already normalise everywhere else.
+    const shaped = shapeCardAttachment({ ...row, id: '7' as never, size_bytes: '120000' as never }, null)
+    expect(shaped.id).toBe(7)
+    expect(shaped.sizeBytes).toBe(120_000)
+  })
+})
+
+describe('the signed URL lifetime', () => {
+  it('outlasts opening a card and not much more', () => {
+    // Long enough to look at a screenshot, short enough that a URL copied
+    // out of devtools is not a handout.
+    expect(CARD_ATTACHMENT_URL_TTL_SECONDS).toBeGreaterThanOrEqual(5 * 60)
+    expect(CARD_ATTACHMENT_URL_TTL_SECONDS).toBeLessThanOrEqual(60 * 60)
+  })
+})
+
+describe('signing one attachment', () => {
+  const warn = spyOn(console, 'warn').mockImplementation(() => {})
+  afterEach(() => warn.mockClear())
+  afterAll(() => warn.mockRestore())
+
+  it('asks the row\'s own disk, for the row\'s path, with the card lifetime', async () => {
+    const asked: unknown[] = []
+    const url = await signCardAttachmentUrl(row, (name) => {
+      asked.push(name)
+      return {
+        signedUrl: async (path, options) => {
+          asked.push(path, options)
+          return `https://app.test/__storage/${path}?token=t`
+        },
+      }
+    })
+    expect(url).toBe(`https://app.test/__storage/${row.path}?token=t`)
+    expect(asked).toEqual(['local', row.path, { expiresIn: CARD_ATTACHMENT_URL_TTL_SECONDS }])
+  })
+
+  it('is null, not a throw, for a disk with no signer', async () => {
+    expect(await signCardAttachmentUrl(row, () => ({}))).toBeNull()
+    expect(String(warn.mock.calls[0]?.[0])).toContain('does not support signedUrl')
+  })
+
+  it('is null, not a throw, for a disk that is no longer configured', async () => {
+    const url = await signCardAttachmentUrl(row, () => {
+      throw new Error('disk \'local\' is not configured')
+    })
+    expect(url).toBeNull()
+    expect(String(warn.mock.calls[0]?.[0])).toContain(`attachment ${row.id}`)
+  })
+
+  it('is null, not a throw, when the signer refuses', async () => {
+    const url = await signCardAttachmentUrl(row, () => ({
+      signedUrl: async () => { throw new Error('APP_KEY is too short to sign with') },
+    }))
+    expect(url).toBeNull()
+  })
+})
+
+describe('the card dialog', () => {
+  const dialog = readFileSync(
+    join(import.meta.dir, '../../../../resources/components/Dashboard/Kanban/KanbanCardDialog.stx'),
+    'utf8',
+  )
+
+  it('renders the attachments it is given', () => {
+    expect(dialog).toContain('openCard()?.attachments')
+    expect(dialog).toContain(':for="attachment in cardAttachments"')
+  })
+
+  it('opens a signed URL in a new tab, with the referrer withheld', () => {
+    // The URL is a bearer credential for one file. `noreferrer` keeps it out
+    // of the next page's `Referer` header.
+    expect(dialog).toContain('rel="noopener noreferrer"')
+    expect(dialog).toContain('target="_blank"')
+  })
+
+  it('shows a placeholder rather than a broken image when there is no URL', () => {
+    expect(dialog).toMatch(/:if="attachment\.url"[\s\S]*?:else/)
+  })
+})

package/app/Actions/Dashboard/Kanban/card-attachments.ts

@@ -0,0 +1,107 @@
+import type { StorageAdapter } from '@stacksjs/storage'
+import { db, getDatabaseDialect, sqlHelpers } from '@stacksjs/database/runtime'
+
+/**
+ * Reading a card's attachments back out.
+ *
+ * The bytes sit on a private disk, because the only thing that writes them
+ * today is the unauthenticated feedback intake and a stranger's upload does
+ * not belong in a web-served directory (stacksjs/stacks#2872). So the
+ * dashboard cannot link to a file path; it links to a short-lived signed URL,
+ * minted per request against `/__storage/{path}`, which verifies the HMAC
+ * against both the path and the expiry.
+ */
+
+export interface CardAttachmentRow {
+  id: number
+  uuid: string | null
+  disk: string
+  path: string
+  mime_type: string
+  size_bytes: number
+  created_at: string | null
+}
+
+export interface CardAttachmentView {
+  id: number
+  uuid: string | null
+  mimeType: string
+  sizeBytes: number
+  createdAt: string | null
+  /**
+   * A signed, expiring URL, or null when one could not be minted.
+   *
+   * Null rather than absent, and rather than throwing: a file whose URL
+   * cannot be signed is one the dashboard should still list, because "the
+   * card has a screenshot nobody can open" is a different problem from "the
+   * card has no screenshot" and only the first one is worth chasing.
+   */
+  url: string | null
+}
+
+/** How long a minted URL lasts. Long enough to open a card, short enough that a copied link is not a handout. */
+export const CARD_ATTACHMENT_URL_TTL_SECONDS = 15 * 60
+
+/**
+ * The response shape, with the storage path deliberately left out.
+ *
+ * The signed URL carries the path it grants, so publishing the bare path
+ * alongside adds nothing a client can use and does invite someone to try it
+ * without a token.
+ */
+export function shapeCardAttachment(row: CardAttachmentRow, url: string | null): CardAttachmentView {
+  return {
+    id: Number(row.id),
+    uuid: row.uuid ?? null,
+    mimeType: String(row.mime_type ?? ''),
+    sizeBytes: Number(row.size_bytes ?? 0),
+    createdAt: row.created_at ?? null,
+    url,
+  }
+}
+
+/** One card's attachments, oldest first, each with a freshly signed URL. */
+export async function cardAttachments(cardId: number): Promise<CardAttachmentView[]> {
+  const { param } = sqlHelpers(getDatabaseDialect())
+  const rows = await db.unsafe(
+    `SELECT id, uuid, disk, path, mime_type, size_bytes, created_at
+     FROM card_attachments
+     WHERE card_id = ${param(1)}
+     ORDER BY created_at ASC, id ASC`,
+    [cardId],
+  ).execute() as unknown as CardAttachmentRow[]
+
+  if (!rows?.length)
+    return []
+
+  const { Storage } = await import('@stacksjs/storage')
+
+  return Promise.all((rows ?? []).map(async row =>
+    shapeCardAttachment(row, await signCardAttachmentUrl(row, name => Storage.disk(name as never))),
+  ))
+}
+
+/**
+ * A signed URL for one attachment, or null when its disk cannot mint one.
+ *
+ * Per attachment, so one unreadable file does not take the card down with it.
+ */
+export async function signCardAttachmentUrl(
+  row: CardAttachmentRow,
+  openDisk: (name: string) => Pick<StorageAdapter, 'signedUrl'>,
+): Promise<string | null> {
+  try {
+    const disk = openDisk(row.disk)
+    // A disk with no signer at all (a driver that cannot mint one) is the
+    // same outcome as one that fails to: listed, but with nothing to open.
+    if (typeof disk.signedUrl !== 'function')
+      throw new Error(`disk '${row.disk}' does not support signedUrl`)
+    return await disk.signedUrl(row.path, { expiresIn: CARD_ATTACHMENT_URL_TTL_SECONDS })
+  }
+  catch (err) {
+    // A disk that is no longer configured or cannot sign, or an APP_KEY too
+    // short to sign with.
+    console.warn(`[card-attachments] could not sign attachment ${row.id}: ${err instanceof Error ? err.message : String(err)}`)
+    return null
+  }
+}