@stacksjs/defaults 0.74.27 → 0.74.29

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

@@ -378,7 +378,7 @@ import { defineGates } from '@stacksjs/auth'
 
 export default defineGates({
   gates: {
-    'access-admin': user => user?.email?.endsWith('@stacksjs.org') ?? false,
+    'access-admin': user => user?.email?.endsWith('@stacksjs.com') ?? false,
     'edit-settings': user => !!user,
     'view-dashboard': user => !!user,
   },

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

@@ -225,7 +225,7 @@ buddy migrate:fresh -s/--seed   # seed after fresh migration
 buddy migrate:fresh -a/--auth   # include auth tables
 buddy migrate:fresh -d/--diff   # show SQL without running
 
-buddy migrate:dns            # DNS migration for APP_URL domain
+buddy dns:sync               # create the config/dns.ts records at the registrar
 ```
 
 Both `migrate` and `migrate:fresh` validate that models exist in `app/Models` or `storage/framework/defaults/app/Models` before running.

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

@@ -54,7 +54,7 @@ export default {
   // Navigation
   nav: [
     { text: 'Changelog', link: 'https://github.com/stacksjs/stacks/blob/main/CHANGELOG.md' },
-    { text: 'Blog', link: 'https://updates.stacksjs.org' },
+    { text: 'Blog', link: 'https://updates.stacksjs.com' },
   ],
 
   // Markdown settings

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

@@ -290,7 +290,7 @@ are enforced rather than using their legacy warn-once compatibility path.
 Reprocessing refreshes existing messages instead of skipping them, preserves their read state, and repairs body and attachment metadata written by older versions. The dashboard receives opaque attachment IDs, resolves them against the stored message before download, and never accepts arbitrary S3 keys from a client.
 
 ## CLI Commands
-- `buddy email` / `buddy mail` - email management
+- `buddy email` - email management (there is no `buddy mail` alias: `mail:*` is the separate mail-server namespace)
 - `buddy email:verify` - check domain verification
 - `buddy email:test [recipient]` - send test email
 - `buddy email:list` - list mailboxes

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

@@ -155,6 +155,29 @@ route.group({ prefix: '/api/v1', middleware: ['auth', 'throttle'] }, () => {
 })
 ```
 
+### STX Pages
+
+The frontend and API share the same middleware definitions. Stacks loads the
+aliases from `app/Middleware.ts` and the class-style handlers from
+`app/Middleware/` into the normal stx dev and production page servers.
+
+Declare an alias from that registry in a page's server metadata:
+
+```stx
+<script server>
+definePageMeta({ middleware: ['auth', 'verified', 'role:admin'] })
+</script>
+```
+
+Do not create a second frontend-only middleware registry. A custom middleware
+is defined once with `new Middleware({ name, priority, handle })`, added to
+`app/Middleware.ts`, and may then guard an API route, an stx page, or both.
+
+STX prepares the incoming request with the same EnhancedRequest helpers before
+calling `handle`, sorts the combined page chain by priority, writes parameters
+to `request._middlewareParams`, supports exact aliases containing colons and
+`!alias` inversion, and fails closed when an alias is missing.
+
 Group middleware is prepended to all routes inside the callback. Groups can be nested — middleware accumulates.
 
 ### Parameterized Middleware

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

@@ -23,7 +23,7 @@ buddy migrate --diff                # show SQL without running
 buddy migrate --auth                # include auth tables
 buddy migrate:fresh                 # drop ALL tables and re-migrate
 buddy migrate:fresh --seed          # drop, migrate, then seed
-buddy migrate:dns                   # DNS-specific migration
+buddy dns:pull                      # live zone as a config/dns.ts block
 buddy make:migration <name>         # create new migration file
 buddy seed                          # seed database
 buddy generate:migrations           # generate migrations from model diffs

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

@@ -102,7 +102,6 @@ generated model types stay precise.
 | `useApi` | Generates REST actions and routes: `{ uri, routes, middleware? }` |
 | `useSearch` (alias `searchable`) | Search-engine indexing: `{ displayable, searchable, sortable, filterable }` |
 | `useSocials` | OAuth identities, e.g. `['github']` |
-| `useActivityLog` | Writes an `Activity` row per change |
 | `observe` | Emits `{model}:created` / `:updated` / `:deleted` events |
 | `billable` | Stripe methods (`checkout()`, `activeSubscription()`, ...) |
 | `taggable` / `categorizable` / `commentable` / `likeable` | Pivot tables and their relation methods |

package/app/Actions/Dashboard/Marketing/campaign-records.test.ts

@@ -54,7 +54,7 @@ describe('campaign records', () => {
       emailListId: '4',
       scheduledAt: '2030-01-01 09:00:00',
       fromName: 'Product team',
-      fromAddress: 'product@stacksjs.org',
+      fromAddress: 'product@stacksjs.com',
       currency: 'usd',
     })
 
@@ -62,7 +62,7 @@ describe('campaign records', () => {
       email_list_id: 4,
       scheduled_at: '2030-01-01 09:00:00',
       from_name: 'Product team',
-      from_address: 'product@stacksjs.org',
+      from_address: 'product@stacksjs.com',
       currency: 'USD',
     })
     expect(validateCampaignWriteData(data, new Date('2029-01-01T00:00:00'))).toBe('')

package/app/Gates.ts

@@ -11,7 +11,7 @@ import { defineGates } from '@stacksjs/auth'
  * Registered at boot by `initializeAuthorization()`, which every entry point
  * comes through - HTTP, `buddy seed`, a scheduled job, a console command.
  *
- * @see https://stacksjs.org/docs/security/authorization
+ * @see https://stacksjs.com/docs/security/authorization
  */
 export default defineGates({
   /**
@@ -30,7 +30,7 @@ export default defineGates({
   gates: {
     /** Check if user can access admin area */
     'access-admin': (user: UserModel | null) => {
-      return user?.email?.endsWith('@stacksjs.org') ?? false
+      return user?.email?.endsWith('@stacksjs.com') ?? false
     },
 
     /** Check if user can edit application settings */

package/app/Middleware/Csrf.ts

@@ -1,4 +1,4 @@
-import { randomBytes, timingSafeEqual } from 'node:crypto'
+import { timingSafeEqual } from 'node:crypto'
 import { HttpError } from '@stacksjs/error-handling'
 import type { EnhancedRequest } from '@stacksjs/bun-router'
 import { Middleware } from '@stacksjs/router'
@@ -59,9 +59,18 @@ import { Middleware } from '@stacksjs/router'
  */
 
 export const CSRF_COOKIE_NAME = 'X-CSRF-Token'
+const CSRF_SECURE_TRANSPORT = Symbol.for('@stacksjs/router:csrf-secure-transport')
 const CSRF_HEADER_NAME = 'x-csrf-token'
+const CSRF_COOKIE_PREFIX = `${CSRF_COOKIE_NAME}=`
+const LEGACY_CSRF_COOKIE_PREFIX = 'csrf-token='
+const CSRF_COOKIE_SUFFIX = '; Path=/; SameSite=Lax; Max-Age=7200'
+const CSRF_COOKIE_SECURE_SUFFIX = `${CSRF_COOKIE_SUFFIX}; Secure`
 const TOKEN_BYTES = 32
+const TOKEN_HEX_LENGTH = TOKEN_BYTES * 2
+const TOKEN_RANDOM_BYTES = Buffer.allocUnsafe(TOKEN_BYTES)
 const TOKEN_ENCODER = new TextEncoder()
+const LEFT_TOKEN_BYTES = new Uint8Array(TOKEN_HEX_LENGTH)
+const RIGHT_TOKEN_BYTES = new Uint8Array(TOKEN_HEX_LENGTH)
 
 /**
  * Generate a fresh CSRF token (hex-encoded, 32 random bytes → 64 chars).
@@ -73,7 +82,8 @@ const TOKEN_ENCODER = new TextEncoder()
  * ```
  */
 export function generateCsrfToken(): string {
-  return randomBytes(TOKEN_BYTES).toString('hex')
+  crypto.getRandomValues(TOKEN_RANDOM_BYTES)
+  return TOKEN_RANDOM_BYTES.toHex()
 }
 
 /**
@@ -120,16 +130,25 @@ function responseAlreadySeeds(response: Response): boolean {
   )
 }
 
-export function seedCsrfCookieIfMissing(req: Request, response: Response, minted?: string): Response {
-  const cookieHeader = req.headers.get('cookie') || ''
+export function createCsrfCookie(req: Request, minted?: string): string {
+  const token = minted || generateCsrfToken()
+  const knownSecureTransport = (req as unknown as Record<symbol, unknown>)[CSRF_SECURE_TRANSPORT]
+  const suffix = knownSecureTransport === true || (knownSecureTransport === undefined && req.url.startsWith('https://'))
+    ? CSRF_COOKIE_SECURE_SUFFIX
+    : CSRF_COOKIE_SUFFIX
+  return `${CSRF_COOKIE_PREFIX}${token}${suffix}`
+}
 
+export function seedCsrfCookieIfMissing(req: Request, response: Response, minted?: string, responseHasNoCookies = false): Response {
   // A token the router minted before rendering wins over "the header already
   // has one", because it put that value in the header itself - and the page
   // has already embedded it in every form it drew. Generating a second token
   // here would store one string in the browser while the page carries another,
   // which fails in a way indistinguishable from having no token at all.
-  if (!minted && (cookieHeader.includes(`${CSRF_COOKIE_NAME}=`) || cookieHeader.includes('csrf-token='))) {
-    return response
+  if (!minted) {
+    const cookieHeader = req.headers.get('cookie') || ''
+    if (cookieHeader.includes(`${CSRF_COOKIE_NAME}=`) || cookieHeader.includes('csrf-token='))
+      return response
   }
 
   // A token already on its way to the browser counts as present, exactly like
@@ -138,18 +157,10 @@ export function seedCsrfCookieIfMissing(req: Request, response: Response, minted
   // and appending a second here would leave the browser storing the last
   // Set-Cookie while the page embedded the first. Two tokens fail the same way
   // no token does, and are far harder to see.
-  if (responseAlreadySeeds(response))
+  if (!responseHasNoCookies && responseAlreadySeeds(response))
     return response
 
-  const token = minted || generateCsrfToken()
-  const isSecure = req.url.startsWith('https://')
-  const cookie = [
-    `${CSRF_COOKIE_NAME}=${token}`,
-    'Path=/',
-    'SameSite=Lax',
-    'Max-Age=7200',
-    isSecure ? 'Secure' : null,
-  ].filter(Boolean).join('; ')
+  const cookie = createCsrfCookie(req, minted)
 
   // Append (not Set) so multiple Set-Cookie headers can coexist with any
   // cookies the action handler set itself.
@@ -175,6 +186,17 @@ export function seedCsrfCookieIfMissing(req: Request, response: Response, minted
 function csrfCookieToken(req: Request): string {
   const header = req.headers.get('cookie')
   if (!header) return ''
+  // The cookie this framework emits has one exact, whitespace-free shape.
+  // Recognize it before scanning for separators or trimming; browsers send
+  // this common single-cookie form on every authenticated unsafe request.
+  if (header.length === CSRF_COOKIE_PREFIX.length + TOKEN_HEX_LENGTH && header.startsWith(CSRF_COOKIE_PREFIX))
+    return header.slice(CSRF_COOKIE_PREFIX.length)
+  if (!header.includes(';')) {
+    if (header.startsWith(CSRF_COOKIE_PREFIX))
+      return header.slice(CSRF_COOKIE_PREFIX.length).trim()
+    if (header.startsWith(LEGACY_CSRF_COOKIE_PREFIX))
+      return header.slice(LEGACY_CSRF_COOKIE_PREFIX.length).trim()
+  }
   let canonical = ''
   let legacy = ''
   for (const part of header.split(';')) {
@@ -197,6 +219,22 @@ function safeEqual(a: string, b: string): boolean {
   if (typeof a !== 'string' || typeof b !== 'string') return false
   if (a.length !== b.length) return false
   try {
+    // Generated tokens are fixed-width ASCII hex. Reuse module-local scratch
+    // arrays for that dominant path: this function is synchronous, so another
+    // request cannot interleave between encoding and comparison. If either
+    // value is not 64 bytes of UTF-8, retain the allocation-based fallback.
+    if (a.length === TOKEN_HEX_LENGTH) {
+      const left = TOKEN_ENCODER.encodeInto(a, LEFT_TOKEN_BYTES)
+      const right = TOKEN_ENCODER.encodeInto(b, RIGHT_TOKEN_BYTES)
+      if (
+        left.read === TOKEN_HEX_LENGTH
+        && left.written === TOKEN_HEX_LENGTH
+        && right.read === TOKEN_HEX_LENGTH
+        && right.written === TOKEN_HEX_LENGTH
+      ) {
+        return timingSafeEqual(LEFT_TOKEN_BYTES, RIGHT_TOKEN_BYTES)
+      }
+    }
     return timingSafeEqual(TOKEN_ENCODER.encode(a), TOKEN_ENCODER.encode(b))
   }
   catch {
@@ -210,12 +248,10 @@ function safeEqual(a: string, b: string): boolean {
  * an ambient cookie credential, so cross-site forgery doesn't apply).
  */
 function hasBearerToken(req: Request): boolean {
-  const auth = req.headers.get('authorization') || req.headers.get('Authorization')
-  return typeof auth === 'string' && auth.toLowerCase().startsWith('bearer ')
+  const auth = req.headers.get('authorization')
+  return typeof auth === 'string' && /^bearer /i.test(auth)
 }
 
-const SAFE_METHODS = new Set(['GET', 'HEAD', 'OPTIONS'])
-
 /**
  * Validate one request with the framework's native CSRF contract.
  *
@@ -223,18 +259,16 @@ const SAFE_METHODS = new Set(['GET', 'HEAD', 'OPTIONS'])
  * the router, such as the local dashboard config editor, can enforce the same
  * double-submit and bearer-token rules without duplicating security logic.
  */
-export async function validateCsrfRequest(request: Request | EnhancedRequest): Promise<void> {
-  const method = request.method.toUpperCase()
+function assertValidCsrfRequest(request: Request | EnhancedRequest): void {
+  // Fetch normalizes standard methods when constructing the Request.
+  const method = request.method
 
   // Safe methods don't mutate state — no token check needed.
   // Token *seeding* (set the cookie if it's missing) happens after
   // the response is built; we don't have a post-response hook
   // here, so action handlers / SPAs can call `generateCsrfToken()`
   // themselves on the first GET they need it for.
-  if (SAFE_METHODS.has(method)) return
-
-  // API clients with a bearer token are exempt — see header docstring.
-  if (hasBearerToken(request)) return
+  if (method === 'GET' || method === 'HEAD' || method === 'OPTIONS') return
 
   // Per-action opt-out: an action exporting `skipCsrf: true` (or
   // `csrf: false`) has declared it can't participate in CSRF
@@ -247,8 +281,13 @@ export async function validateCsrfRequest(request: Request | EnhancedRequest): P
   // Look up the submitted token. Header is the SPA path; body field
   // is the traditional form-post path. We accept either.
   const headerToken = request.headers.get(CSRF_HEADER_NAME)
-    || request.headers.get('X-CSRF-Token')
-    || request.headers.get('X-Csrf-Token')
+
+  // A browser or SPA that supplied an explicit CSRF header should take the
+  // matching-token path first. Bearer-only clients still exit immediately,
+  // while a malformed CSRF header on a bearer request retains the exemption
+  // after validation fails below.
+  if (!headerToken && hasBearerToken(request)) return
+
   const body = enhanced.jsonBody || enhanced.formBody || {}
   // A parsed body is `unknown`-valued: the token is validated as a string
   // two lines down, so read it as one rather than asserting it is one.
@@ -262,13 +301,20 @@ export async function validateCsrfRequest(request: Request | EnhancedRequest): P
 
   const cookieToken = csrfCookieToken(request)
 
-  if (!submitted || !cookieToken || !safeEqual(submitted, cookieToken)) {
-    // 419 is the convention Laravel popularized for "CSRF token
-    // mismatch" — it's not in the IANA list but most SPAs already
-    // know how to refresh on 419. We use 403 for the strict-correct
-    // status code instead (419 is non-standard).
-    throw new HttpError(403, 'CSRF token mismatch')
-  }
+  if (submitted && cookieToken && safeEqual(submitted, cookieToken)) return
+
+  // Preserve bearer precedence when a client happens to send both headers.
+  if (headerToken && hasBearerToken(request)) return
+
+  // 419 is the convention Laravel popularized for "CSRF token
+  // mismatch" — it's not in the IANA list but most SPAs already
+  // know how to refresh on 419. We use 403 for the strict-correct
+  // status code instead (419 is non-standard).
+  throw new HttpError(403, 'CSRF token mismatch')
+}
+
+export async function validateCsrfRequest(request: Request | EnhancedRequest): Promise<void> {
+  assertValidCsrfRequest(request)
 }
 
 export default new Middleware({
@@ -277,7 +323,7 @@ export default new Middleware({
   // we're going to reject anyway. After maintenance/throttle though.
   priority: 2,
 
-  async handle(request) {
-    await validateCsrfRequest(request)
+  handle(request) {
+    assertValidCsrfRequest(request)
   },
 })

package/app/Middleware.ts

@@ -4,8 +4,9 @@ import { defineMiddleware } from '@stacksjs/router'
  * The application's middleware aliases.
  *
  * Aliases may be used instead of class names to conveniently assign middleware
- * to routes and groups. Each one names a class under `app/Middleware/`, or one
- * of the framework defaults behind it, and the name is checked.
+ * to API routes, route groups, and stx pages through `definePageMeta`. Each one
+ * names a class under `app/Middleware/`, or one of the framework defaults
+ * behind it, and the name is checked.
  *
  * This map is MERGED over the framework defaults rather than replacing them,
  * so an alias the framework adds later is available here without an edit.

package/ide/vscode/package.json

@@ -2,7 +2,7 @@
   "publisher": "Stacks",
   "name": "vscode-stacks",
   "displayName": "Stacks",
-  "version": "0.74.27",
+  "version": "0.74.29",
   "description": "A modern Stacks development environment.",
   "license": "MIT",
   "funding": "https://github.com/sponsors/chrisbbreuer",

package/package.json

@@ -2,7 +2,7 @@
   "name": "@stacksjs/defaults",
   "type": "module",
   "sideEffects": false,
-  "version": "0.74.27",
+  "version": "0.74.29",
   "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.27",
-    "@stacksjs/mobile": "^0.74.27",
+    "@stacksjs/mobile": "^0.74.29",
     "@stacksjs/sanitizer": "^0.2.113",
     "ts-qr-codes": "^0.1.8"
   }

package/resources/components/Dashboard/Home/DashboardHome.stx

@@ -39,7 +39,7 @@ const resourceLinks = [
   {
     title: 'Documentation',
     description: 'Guides and API references',
-    href: 'https://docs.stacksjs.org',
+    href: 'https://docs.stacksjs.com',
     icon: 'i-hugeicons-book-02',
     tone: 'blue',
   },

package/stx-components-plugin.ts

@@ -19,7 +19,48 @@ const candidates = [
   join(process.cwd(), 'node_modules/@stacksjs/components/src/ui'),
 ].filter((dir): dir is string => Boolean(dir))
 
+const library = candidates.find(dir => existsSync(dir)) ?? candidates[candidates.length - 1]
+
+/**
+ * Component directories contributed by installed packages.
+ *
+ * Wrapped on its own rather than left to the plugin loader's catch. stx wraps
+ * plugin loading in `try { … } catch { console.warn(…) }`, so an exception
+ * raised here would drop the WHOLE plugin - and this plugin is what supplies
+ * the dashboard's sidebar. Degrading to "no package components" keeps the
+ * library and the framework defaults working.
+ *
+ * `@stacksjs/config` is imported for the resolution rather than re-implemented,
+ * because it carries the guard that refuses a path escaping the package.
+ */
+function packageDirs(): string[] {
+  try {
+    // eslint-disable-next-line ts/no-require-imports
+    const { packageComponentRoots } = require('@stacksjs/config')
+    return packageComponentRoots().map((root: { dir: string }) => root.dir)
+  }
+  catch {
+    return []
+  }
+}
+
 export default {
   name: '@stacksjs/components',
-  components: candidates.find(dir => existsSync(dir)) ?? candidates[candidates.length - 1],
+  /*
+   * Order is the precedence, because stx searches this list and takes the
+   * first match.
+   *
+   * The framework's own components are listed explicitly, ahead of any
+   * package's. They already resolve today through stx's fallback directory, so
+   * naming them here changes nothing on its own - what it does is put a floor
+   * under the package roots, making an installed package purely ADDITIVE. A
+   * package shipping its own `Button.stx` gets it used where nothing else
+   * defines `<Button />`, and cannot quietly replace the framework's.
+   */
+  components: [
+    library,
+    // Relative to this file, which is what stx resolves plugin entries against.
+    'resources/components',
+    ...packageDirs(),
+  ],
 }