@stacksjs/defaults 0.75.89 → 0.75.90

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 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/.
 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. (106 models)
 - **Request Models**: UserRequest, PostRequest, OrderRequest, etc.
 - **Actions**: Action types and helpers
 - **Schema**: validation schema builder

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/` (236 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 236 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
+- 236 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 106 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 106, 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 106 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/` (106 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,134 @@
+import type { RequestInstance } from '@stacksjs/types'
+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 {
+  authorizeFeedbackToken,
+  hashFeedbackToken,
+  looksLikeFeedbackToken,
+  refusalMessage,
+} from './feedback-token'
+
+interface FeedbackInput {
+  title?: unknown
+  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
+
+/**
+ * `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
+
+    try {
+      const token = await (db as any)
+        .selectFrom('feedback_tokens')
+        .where('token', '=', hashFeedbackToken(raw))
+        .select(['id', 'board_id', 'revoked_at', 'expires_at'])
+        .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()
+
+      // 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')) }
+    }
+    catch (err) {
+      return kanbanActionError(err, 'FeedbackStoreAction')
+    }
+  },
+})

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

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

@@ -0,0 +1,136 @@
+import { createHash, randomBytes } from 'node:crypto'
+
+/**
+ * Whether a feedback link may still file a card, and on which board.
+ *
+ * Kept pure and separate from the action: this is the whole security boundary
+ * for an unauthenticated write path, and a decision that can only be reached
+ * through an HTTP request is a decision that does not get tested properly.
+ * The action does the lookup and the writing; everything that decides *yes or
+ * no* is here.
+ *
+ * A feedback token is a capability, not an identity. It names a board, it is
+ * read only by the intake action, and it never resolves to a user, so it can
+ * authenticate nothing. See the `FeedbackToken` model for why a personal
+ * access token would have been an account in disguise.
+ */
+
+/** 256 bits. The raw token is the only secret, so it carries all the entropy. */
+export const FEEDBACK_TOKEN_BYTES = 32
+
+/** A raw token as it appears in a link, and as the column stores it. */
+const RAW_TOKEN = /^[0-9a-f]{64}$/
+
+/**
+ * SHA-256 hex, which is what `feedback_tokens.token` holds.
+ *
+ * Deterministic on purpose: a submit is one indexed lookup. With 256 bits of
+ * entropy in the raw value an offline attack on a fast hash is irrelevant,
+ * which is the same reasoning `MagicLinkToken` records and deliberately not
+ * the bcrypt-and-scan of password resets.
+ *
+ * `@stacksjs/auth` defines this same one-liner privately three times over
+ * (`tokens.ts`, `authentication.ts`, `magic-link.ts`) and exports none of
+ * them, so this is a fourth rather than a refactor of a security module in
+ * passing.
+ */
+export function hashFeedbackToken(raw: string): string {
+  return createHash('sha256').update(raw).digest('hex')
+}
+
+/** A new link's raw token and the hash to store for it. */
+export function mintFeedbackToken(): { raw: string, hash: string } {
+  const raw = randomBytes(FEEDBACK_TOKEN_BYTES).toString('hex')
+  return { raw, hash: hashFeedbackToken(raw) }
+}
+
+/**
+ * Does this even have the shape of a token?
+ *
+ * Checked before the lookup so a submit carrying a sentence, a path, or a SQL
+ * fragment is refused without touching the database.
+ */
+export function looksLikeFeedbackToken(raw: unknown): raw is string {
+  return typeof raw === 'string' && RAW_TOKEN.test(raw)
+}
+
+export type FeedbackTokenRefusal = 'malformed' | 'unknown' | 'revoked' | 'expired' | 'unbound'
+
+export type FeedbackTokenVerdict =
+  | { ok: true, boardId: number }
+  | { ok: false, reason: FeedbackTokenRefusal }
+
+/**
+ * A `feedback_tokens` row, in either spelling.
+ *
+ * The ORM hands back camelCase or snake_case depending on the path taken, and
+ * the Kanban actions already read `boardId ?? board_id` for the same reason.
+ */
+export interface FeedbackTokenRow {
+  boardId?: unknown
+  board_id?: unknown
+  revokedAt?: unknown
+  revoked_at?: unknown
+  expiresAt?: unknown
+  expires_at?: unknown
+}
+
+function firstDefined(...values: unknown[]): unknown {
+  return values.find(value => value !== undefined && value !== null)
+}
+
+/**
+ * A stored timestamp as epoch milliseconds, read as UTC.
+ *
+ * Exported so the UTC reading can be pinned directly. Asserting it through a
+ * verdict cannot: both interpretations of a given row usually land on the
+ * same side of `now`, so such a test passes whether or not the normalisation
+ * below exists, and it did.
+ */
+export function parseTokenTime(value: unknown): number | null {
+  if (value === undefined || value === null) return null
+  if (value instanceof Date) return value.getTime()
+  // SQLite hands back `YYYY-MM-DD HH:MM:SS`, which `Date` parses as local
+  // time on some engines and UTC on others. Normalising to ISO keeps a token
+  // from appearing to expire an hour early or late depending on the dialect.
+  if (typeof value === 'string') {
+    const normalized = /^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$/.test(value) ? `${value.replace(' ', 'T')}Z` : value
+    const parsed = Date.parse(normalized)
+    return Number.isNaN(parsed) ? null : parsed
+  }
+  if (typeof value === 'number') return value
+  return null
+}
+
+/**
+ * The verdict for a row that has already been looked up by token hash.
+ *
+ * Revocation is checked before expiry, so a token that is both reports the
+ * reason an operator acted on. The verdict carries a board id and a reason
+ * and never the token, so it is safe to log.
+ */
+export function authorizeFeedbackToken(row: FeedbackTokenRow | null | undefined, now: Date = new Date()): FeedbackTokenVerdict {
+  if (!row) return { ok: false, reason: 'unknown' }
+
+  if (firstDefined(row.revokedAt, row.revoked_at) !== undefined)
+    return { ok: false, reason: 'revoked' }
+
+  const expiresAt = parseTokenTime(firstDefined(row.expiresAt, row.expires_at))
+  if (expiresAt !== null && expiresAt <= now.getTime())
+    return { ok: false, reason: 'expired' }
+
+  const boardId = Number(firstDefined(row.boardId, row.board_id))
+  if (!Number.isInteger(boardId) || boardId <= 0)
+    return { ok: false, reason: 'unbound' }
+
+  return { ok: true, boardId }
+}
+
+/** What to tell the submitter. Deliberately the same for every refusal. */
+export function refusalMessage(): string {
+  // One message for unknown, revoked and expired alike: distinguishing them
+  // tells a holder of a guessed token which half of the guess was right, and
+  // tells a revoked reviewer they were revoked rather than that the link is
+  // simply no longer valid.
+  return 'This feedback link is not valid.'
+}

package/app/Models/FeedbackToken.ts

@@ -0,0 +1,129 @@
+import { defineModel } from '@stacksjs/orm'
+import { schema } from '@stacksjs/validation/runtime'
+
+/**
+ * A revocable capability to add one card to one board, and nothing else.
+ *
+ * Deliberately NOT a personal access token. `tokenCan()` and the `abilities`
+ * middleware are opt-in per route, and the dashboard's own actions authorize
+ * by calling `request.user()` rather than by checking scopes, so a
+ * user-owned bearer token authenticates as its owner across the whole
+ * dashboard API. Handing an external reviewer one of those to file feedback
+ * with would hand them an account (stacksjs/stacks#2872).
+ *
+ * This is a capability instead: the auth stack does not know it, so it can
+ * authenticate nothing. It names a board, it is checked only by the feedback
+ * intake action, and it never resolves to a user.
+ *
+ * `token` stores the SHA-256 of the raw value - deterministic, so a submit is
+ * one indexed lookup, and with 256 bits of entropy in the raw token an
+ * offline attack on a fast hash is irrelevant. Same reasoning as
+ * `MagicLinkToken`, and deliberately not the bcrypt-and-scan of password
+ * resets.
+ *
+ * No `useApi`: these rows are minted by a command and read by the intake
+ * action. Exposing them over REST would publish the thing they protect.
+ */
+export default defineModel({
+  name: 'FeedbackToken',
+  table: 'feedback_tokens',
+  primaryKey: 'id',
+  autoIncrement: true,
+
+  traits: {
+    gdpr: { erasure: 'delete', basis: 'legitimate_interests', purpose: 'Invites an external reviewer to file feedback on one board' },
+    useTimestamps: true,
+    useUuid: true,
+  },
+
+  // Cascade, so deleting a board takes its links with it: a token that
+  // outlives the board it names would be admitted carrying a board id that no
+  // longer resolves.
+  //
+  // Declared, not relied on. SQLite enforces this only with
+  // `foreign_keys = ON`, which the framework sets while renaming and not
+  // otherwise - `fk-audit.ts` exists because of exactly that. Verified with
+  // the pragma on (the row goes) and off (it stays), so the intake action
+  // checks the board resolves rather than trusting the constraint to have
+  // removed the token.
+  belongsTo: [{ model: 'Board', onDelete: 'cascade' }],
+
+  attributes: {
+    /** SHA-256 hex of the raw token. Never the raw value. */
+    token: {
+      required: true,
+      order: 1,
+      fillable: true,
+      unique: true,
+      validation: {
+        rule: schema.string().min(64).max(64),
+      },
+      factory: faker => faker.string.hexadecimal({ length: 64, prefix: '' }).toLowerCase(),
+    },
+
+    /**
+     * Who it was issued to, so an operator can tell two links apart and
+     * revoke the right one. Shown in `buddy feedback:tokens`, never sent to
+     * the submitter and never used to authenticate.
+     */
+    label: {
+      personal: true,
+      required: true,
+      order: 2,
+      fillable: true,
+      validation: {
+        rule: schema.string().max(120),
+      },
+      factory: faker => faker.person.firstName(),
+    },
+
+    /**
+     * Revocation, which is the whole point of the design: flipping this stops
+     * the link without a deploy. Nullable rather than a boolean so the
+     * operator can also see *when* it was pulled.
+     */
+    revokedAt: {
+      required: false,
+      order: 3,
+      fillable: true,
+      validation: {
+        rule: schema.timestamp(),
+      },
+      factory: () => null,
+    },
+
+    /** Unset means it does not expire on its own; revocation still applies. */
+    expiresAt: {
+      required: false,
+      order: 4,
+      fillable: true,
+      validation: {
+        rule: schema.timestamp(),
+      },
+      factory: () => null,
+    },
+
+    /**
+     * Last accepted submission. Lets an operator retire a link nobody uses,
+     * and tells them whether a leaked token has been exercised.
+     */
+    lastUsedAt: {
+      required: false,
+      order: 5,
+      fillable: true,
+      validation: {
+        rule: schema.timestamp(),
+      },
+      factory: () => null,
+    },
+
+    /** The user who minted it. Set server-side, surfaced in the listing. */
+    createdByUserId: {
+      required: false,
+      order: 6,
+      fillable: true,
+      validation: { rule: schema.number() },
+      factory: () => null,
+    },
+  },
+} as const)

package/ide/vscode/package.json

@@ -2,7 +2,7 @@
   "publisher": "Stacks",
   "name": "vscode-stacks",
   "displayName": "Stacks",
-  "version": "0.75.89",
+  "version": "0.75.90",
   "description": "Stacks, built into VS Code: stx templates, pickier linting and formatting, encrypted env files, the dev server preview and every buddy command. No other extensions required.",
   "license": "MIT",
   "funding": "https://github.com/sponsors/chrisbbreuer",

package/package.json

@@ -2,7 +2,7 @@
   "name": "@stacksjs/defaults",
   "type": "module",
   "sideEffects": false,
-  "version": "0.75.89",
+  "version": "0.75.90",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/stacksjs/stacks.git",
@@ -55,7 +55,7 @@
   "dependencies": {
     "@iconify-json/f7": "^1.2.2",
     "@iconify-json/hugeicons": "^1.2.35",
-    "@stacksjs/mobile": "^0.75.89",
+    "@stacksjs/mobile": "^0.75.90",
     "@stacksjs/sanitizer": "^0.2.395",
     "@xterm/addon-fit": "^0.11.0",
     "@xterm/xterm": "^6.0.0",

package/routes/dashboard.ts

@@ -47,6 +47,21 @@ route.post('/api/contact', 'Actions/ContactAction').name('contact.send').skipCsr
 route.get('/api/team-invitation-links/{token}', 'Actions/Teams/ShowInvitationAction').rateLimit(30, 'minute')
 route.post('/api/team-invitations/{token}/accept', 'Actions/Teams/AcceptInvitationAction').middleware('auth').rateLimit(10, 'minute')
 
+// An external reviewer files feedback through a revocable link, without an
+// account: the only unauthenticated write the dashboard has. Outside every
+// `auth` group on purpose, and narrow because of it - the token names one
+// board, adds a card to it, and reads nothing.
+//
+// CSRF is skipped for the same reason `/api/contact` above skips it, and more
+// safely: there is no ambient authority to borrow here. The capability is the
+// high-entropy token in the path, not a cookie the browser attaches, so a
+// cross-site POST has nothing to forge with.
+//
+// Rate limited like the other token-bearing unauthenticated routes. The token
+// is 256 bits, so this is about stopping a flood of cards from a link that
+// leaked, not about guessing.
+route.post('/api/feedback/{token}', 'Actions/Dashboard/Feedback/FeedbackStoreAction').name('feedback.store').skipCsrf().rateLimit(10, 'minute')
+
 // ============================================================================
 // Storefront (anonymous cart + multi-step checkout)
 //