@stacksjs/defaults 0.75.89 → 0.75.91

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}`
+}

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.test.ts

@@ -0,0 +1,166 @@
+import { describe, expect, it } from 'bun:test'
+import { createHash } from 'node:crypto'
+import {
+  authorizeFeedbackToken,
+  hashFeedbackToken,
+  looksLikeFeedbackToken,
+  mintFeedbackToken,
+  parseTokenTime,
+  refusalMessage,
+} from './feedback-token'
+
+/**
+ * The security boundary for an unauthenticated write path.
+ *
+ * Every branch is tested here rather than through the action, because a
+ * decision reachable only via an HTTP request is a decision that does not get
+ * tested properly, and this one decides whether a stranger may write to a
+ * board (stacksjs/stacks#2872).
+ */
+
+const VALID = 'a'.repeat(64)
+const FUTURE = new Date(Date.now() + 86_400_000).toISOString()
+const PAST = new Date(Date.now() - 86_400_000).toISOString()
+
+describe('hashFeedbackToken', () => {
+  it('is SHA-256 hex of the raw value', () => {
+    expect(hashFeedbackToken('hello')).toBe(createHash('sha256').update('hello').digest('hex'))
+    expect(hashFeedbackToken(VALID)).toHaveLength(64)
+  })
+})
+
+describe('mintFeedbackToken', () => {
+  it('mints a raw token that matches its own hash', () => {
+    const { raw, hash } = mintFeedbackToken()
+
+    expect(looksLikeFeedbackToken(raw)).toBe(true)
+    expect(hash).toBe(hashFeedbackToken(raw))
+  })
+
+  it('does not repeat itself', () => {
+    // 256 bits, so a collision here means the generator is broken rather
+    // than that we got unlucky.
+    const mints = new Set(Array.from({ length: 50 }, () => mintFeedbackToken().raw))
+    expect(mints.size).toBe(50)
+  })
+})
+
+describe('looksLikeFeedbackToken', () => {
+  it('accepts a raw token', () => {
+    expect(looksLikeFeedbackToken(VALID)).toBe(true)
+  })
+
+  it('rejects anything that is not one, before any lookup happens', () => {
+    // The point of the shape check: a submit carrying a sentence, a path or a
+    // SQL fragment is refused without touching the database.
+    for (const candidate of [
+      '',
+      'a'.repeat(63),
+      'a'.repeat(65),
+      'A'.repeat(64),
+      `${'a'.repeat(63)}g`,
+      '../../etc/passwd',
+      "' OR 1=1 --",
+      null,
+      undefined,
+      42,
+      { toString: () => VALID },
+    ])
+      expect(looksLikeFeedbackToken(candidate)).toBe(false)
+  })
+})
+
+describe('authorizeFeedbackToken', () => {
+  it('admits a live token and reports its board', () => {
+    expect(authorizeFeedbackToken({ boardId: 7, expiresAt: FUTURE })).toEqual({ ok: true, boardId: 7 })
+    expect(authorizeFeedbackToken({ boardId: 7 })).toEqual({ ok: true, boardId: 7 })
+  })
+
+  it('refuses a token it never found', () => {
+    expect(authorizeFeedbackToken(null)).toEqual({ ok: false, reason: 'unknown' })
+    expect(authorizeFeedbackToken(undefined)).toEqual({ ok: false, reason: 'unknown' })
+  })
+
+  it('refuses a revoked token, which is the point of the design', () => {
+    expect(authorizeFeedbackToken({ boardId: 7, revokedAt: PAST })).toEqual({ ok: false, reason: 'revoked' })
+  })
+
+  it('reports revocation ahead of expiry when a token is both', () => {
+    // An operator who pulled a link wants to see that they pulled it, not
+    // that it later lapsed on its own.
+    const verdict = authorizeFeedbackToken({ boardId: 7, revokedAt: PAST, expiresAt: PAST })
+    expect(verdict).toEqual({ ok: false, reason: 'revoked' })
+  })
+
+  it('refuses an expired token, counting the exact moment as expired', () => {
+    const now = new Date('2026-10-07T12:00:00.000Z')
+    expect(authorizeFeedbackToken({ boardId: 7, expiresAt: PAST }, now)).toEqual({ ok: false, reason: 'expired' })
+    expect(authorizeFeedbackToken({ boardId: 7, expiresAt: now.toISOString() }, now)).toEqual({ ok: false, reason: 'expired' })
+  })
+
+  it('still reads a stored timestamp when deciding expiry', () => {
+    const now = new Date('2026-10-07T12:00:00.000Z')
+    expect(authorizeFeedbackToken({ boardId: 7, expires_at: '2026-10-07 18:00:00' }, now)).toEqual({ ok: true, boardId: 7 })
+    expect(authorizeFeedbackToken({ boardId: 7, expires_at: '2026-10-07 06:00:00' }, now)).toEqual({ ok: false, reason: 'expired' })
+  })
+
+  it('refuses a token bound to no usable board', () => {
+    // Without this the action would resolve a board of `NaN` and the card
+    // would land nowhere, or worse, somewhere.
+    for (const row of [{}, { boardId: 0 }, { boardId: -1 }, { boardId: 'the board' }, { boardId: 1.5 }])
+      expect(authorizeFeedbackToken(row)).toEqual({ ok: false, reason: 'unbound' })
+  })
+
+  it('accepts either spelling the ORM returns', () => {
+    expect(authorizeFeedbackToken({ board_id: 9 })).toEqual({ ok: true, boardId: 9 })
+    expect(authorizeFeedbackToken({ board_id: 9, revoked_at: PAST })).toEqual({ ok: false, reason: 'revoked' })
+  })
+
+  it('never carries the token into its verdict', () => {
+    // The verdict is logged. A reason and a board id are safe; the thing
+    // being checked is not.
+    const verdict = authorizeFeedbackToken({ boardId: 7, revokedAt: PAST })
+    expect(JSON.stringify(verdict)).not.toContain(VALID)
+    expect(JSON.stringify(verdict)).not.toContain('revokedAt')
+  })
+})
+
+describe('parseTokenTime', () => {
+  it('reads a SQLite datetime as UTC, in any timezone', () => {
+    // `YYYY-MM-DD HH:MM:SS` is what SQLite hands back, and `Date` parses it
+    // as local time on some engines. Left alone, a token expires hours early
+    // or late depending on the dialect and the machine's clock.
+    //
+    // Asserted here rather than through a verdict: both readings of a row
+    // usually fall on the same side of `now`, so the verdict-level version of
+    // this test passed with the normalisation deleted.
+    expect(parseTokenTime('2026-10-07 09:00:00')).toBe(Date.parse('2026-10-07T09:00:00Z'))
+    expect(parseTokenTime('2026-10-07 23:59:59')).toBe(Date.parse('2026-10-07T23:59:59Z'))
+  })
+
+  it('passes through the forms that are already unambiguous', () => {
+    expect(parseTokenTime('2026-10-07T09:00:00Z')).toBe(Date.parse('2026-10-07T09:00:00Z'))
+    expect(parseTokenTime(new Date('2026-10-07T09:00:00Z'))).toBe(Date.parse('2026-10-07T09:00:00Z'))
+    expect(parseTokenTime(1_760_000_000_000)).toBe(1_760_000_000_000)
+  })
+
+  it('reports an unreadable value as absent rather than as epoch zero', () => {
+    // `null` means "does not expire". A timestamp that failed to parse must
+    // not become 1970, which would read as expired and lock out a live link.
+    expect(parseTokenTime('not a date')).toBeNull()
+    expect(parseTokenTime(null)).toBeNull()
+    expect(parseTokenTime(undefined)).toBeNull()
+    expect(parseTokenTime({})).toBeNull()
+  })
+})
+
+describe('refusalMessage', () => {
+  it('says the same thing however the token failed', () => {
+    // Distinguishing unknown from revoked from expired tells someone holding
+    // a guessed token which half of the guess was right, and tells a revoked
+    // reviewer they were revoked rather than that the link simply stopped
+    // working.
+    expect(refusalMessage()).toBe('This feedback link is not valid.')
+    expect(refusalMessage()).not.toMatch(/revoke|expire|unknown|board/i)
+  })
+})