@stacksjs/defaults 0.74.60 → 0.74.62

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

@@ -352,14 +352,34 @@ await authUser.authorize('edit-post', post)  // throws if denied
   providers: { users: { driver: 'database', table: 'users' } },
   username: 'email',      // AUTH_USERNAME_FIELD env
   password: 'password',   // AUTH_PASSWORD_FIELD env
-  tokenExpiry: 30,         // days, AUTH_TOKEN_EXPIRY env
-  tokenRotation: 7,        // days, AUTH_TOKEN_ROTATION env
+  tokenExpiry: 60 * 60 * 1000, // milliseconds, 1 hour
+  refreshTokenExpiry: 30 * 24 * 60 * 60 * 1000, // milliseconds
+  browserSession: {
+    baselineLifetime: 7 * 24 * 60 * 60 * 1000, // absolute milliseconds
+    rememberedLifetime: 30 * 24 * 60 * 60 * 1000,
+    withRefreshToken: false, // fixed browser lifetime, no unused refresh token
+    logoutRedirect: '/login?logged_out=1', // local path for HTML logout only
+  },
+  tokenRotation: 24,       // hours
   defaultAbilities: ['*'],
   defaultTokenName: 'auth-token',
   passwordReset: { expire: 60, throttle: 60 }
 }
 ```
 
+`browserSession` applies to credentials issued by the default login,
+registration, and completed two-factor actions. Dedicated personal access
+token and OAuth issuance remain unchanged. The default login form sends
+`remember`; registration uses the baseline tier unless a custom client sends
+that field. A two-factor challenge preserves the choice without minting a
+session until verification succeeds. Cookie Max-Age comes from the lifetime
+returned by token issuance, so it cannot outlive the token. Cookie-authenticated
+writes use the CSRF flow and same-origin credentials.
+
+When migrating an app that copied framework auth actions, remove only the
+equivalent login, registration, two-factor, logout, and cookie-helper overrides.
+Retain application-specific onboarding and event hooks.
+
 ### config/hashing.ts
 ```typescript
 {

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

@@ -1,6 +1,6 @@
 ---
 name: stacks-dashboard
-description: Use when building or customizing the Stacks admin dashboard, including dashboard pages, model management views, analytics widgets, commerce dashboards, content management, settings panels, deployment monitoring, job/queue management, or the 400 built-in dashboard components. Covers the dashboard system at storage/framework/defaults/.
+description: Use when building or customizing the Stacks admin dashboard, including dashboard pages, model management views, analytics widgets, commerce dashboards, content management, settings panels, deployment monitoring, job/queue management, or the 401 built-in dashboard components. Covers the dashboard system at storage/framework/defaults/.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript
 allowed-tools: Read Edit Write Bash Grep Glob
@@ -8,7 +8,7 @@ allowed-tools: Read Edit Write Bash Grep Glob
 
 # Stacks Dashboard
 
-The Stacks admin dashboard provides a full-featured admin panel with 100+ route views, 400 components, and a multi-section layout.
+The Stacks admin dashboard provides a full-featured admin panel with 100+ route views, 401 components, and a multi-section layout.
 
 ## Key Paths
 - Dashboard components: `storage/framework/defaults/resources/components/Dashboard/`

package/app/Actions/Auth/MagicLinkConsumeAction.ts

@@ -1,5 +1,5 @@
 import { Action } from '@stacksjs/actions'
-import { Auth, authCookie, withMagicLink } from '@stacksjs/auth'
+import { Auth, authCookieForBrowserSession, resolveBrowserSessionPolicy, withMagicLink } from '@stacksjs/auth'
 import { config } from '@stacksjs/config'
 import { response } from '@stacksjs/router'
 import { schema } from '@stacksjs/validation'
@@ -20,9 +20,13 @@ export default new Action({
     if (!config.auth.magicLink?.enabled)
       return response.notFound('Magic-link sign-in is not enabled')
 
+    const policy = resolveBrowserSessionPolicy(false)
     const consumed = await withMagicLink(String(request.get('token')), async grant => ({
       grant,
-      result: await Auth.loginUsingId(grant.userId),
+      result: await Auth.loginUsingId(grant.userId, {
+        expiresInMinutes: policy.expiresInMinutes,
+        withRefreshToken: policy.withRefreshToken,
+      }),
     }))
     if (!consumed.ok) {
       const messages: Record<string, string> = {
@@ -51,6 +55,6 @@ export default new Action({
         email: result.user?.email,
         name: result.user?.name,
       },
-    }, { headers: { 'Set-Cookie': authCookie(result.token) } })
+    }, { headers: { 'Set-Cookie': authCookieForBrowserSession(result.token, result.expiresIn) } })
   },
 })

package/app/Actions/Auth/SocialCallbackAction.ts

@@ -1,5 +1,5 @@
 import { Action } from '@stacksjs/actions'
-import { Auth, authCookie, resolveSocialSignIn, SocialSignInRefusedError } from '@stacksjs/auth'
+import { Auth, authCookieForBrowserSession, resolveBrowserSessionPolicy, resolveSocialSignIn, SocialSignInRefusedError } from '@stacksjs/auth'
 import { log } from '@stacksjs/logging'
 import { response } from '@stacksjs/router'
 import { isSocialProviderConfigured, socialHandoffFailureRedirect, socialHandoffRedirect, socialProvider } from '@stacksjs/socials'
@@ -45,7 +45,11 @@ export default new Action({
 
       const { userId } = await resolveSocialSignIn(provider, identity)
 
-      const session = await Auth.loginUsingId(userId)
+      const policy = resolveBrowserSessionPolicy(false)
+      const session = await Auth.loginUsingId(userId, {
+        expiresInMinutes: policy.expiresInMinutes,
+        withRefreshToken: policy.withRefreshToken,
+      })
       if (!session?.token)
         return socialHandoffFailureRedirect('Sign-in could not be completed. Please try again.')
 
@@ -61,7 +65,7 @@ export default new Action({
       })
 
       // The cookie signs server-rendered pages in; the fragment pack the SPA.
-      redirect.headers.append('Set-Cookie', authCookie(session.token))
+      redirect.headers.append('Set-Cookie', authCookieForBrowserSession(session.token, session.expiresIn))
       return redirect
     }
     catch (error) {

package/app/Models/FailedJob.ts

@@ -36,8 +36,12 @@ export default defineModel({
       factory: () => 'default',
     },
 
+    // Both `text`: a payload is a serialized job envelope and an exception
+    // carries a stack trace, and neither fits the default varchar(255) that
+    // Postgres enforces.
     payload: {
       fillable: true,
+      type: 'text',
       validation: {
         rule: schema.string().required(),
       },
@@ -46,6 +50,7 @@ export default defineModel({
 
     exception: {
       fillable: true,
+      type: 'text',
       validation: {
         rule: schema.string().required(),
       },

package/app/Models/Job.ts

@@ -28,6 +28,11 @@ export default defineModel({
 
     payload: {
       fillable: true,
+      // `text`, not the default varchar(255): a job's serialized envelope is
+      // far longer, and on Postgres every dispatch failed with "value too long
+      // for type character varying(255)". SQLite ignores the length, which is
+      // how it went unnoticed.
+      type: 'text',
       validation: {
         rule: schema.string().required(),
       },

package/functions/auth.ts

@@ -1,6 +1,6 @@
 import { resolveApiBaseUrl } from './api-url'
 import type { Ref } from '@stacksjs/stx'
-import type { AuthUser, LoginError, LoginResponse, MeResponse, RegisterCredentials, RegisterError, RegisterResponse, ResponseError, UserData } from '../types/dashboard'
+import type { AuthUser, LoginError, LoginResponse, LoginResult, MeResponse, RegisterCredentials, RegisterError, RegisterResponse, ResponseError, TwoFactorLoginChallenge, UserData } from '../types/dashboard'
 import { withCsrfHeader } from '@stacksjs/browser/composables/csrf'
 import { useStorage } from '@stacksjs/browser/composables/useStorage'
 import { ref } from '@stacksjs/stx'
@@ -28,30 +28,72 @@ const baseUrl = resolveApiBaseUrl('')
 // Create singleton state
 const isAuthenticated = ref(false)
 
+export function isTwoFactorChallenge(data: unknown): data is TwoFactorLoginChallenge {
+  if (!data || typeof data !== 'object')
+    return false
+  const candidate = data as Record<string, unknown>
+  return candidate.requires_two_factor === true && typeof candidate.challenge_token === 'string' && candidate.challenge_token.length > 0
+}
+
+export function isLoginResponse(data: unknown): data is LoginResponse {
+  if (!data || typeof data !== 'object')
+    return false
+  const candidate = data as Record<string, unknown>
+  return typeof candidate.token === 'string'
+    && candidate.token.length > 0
+    && typeof candidate.user === 'object'
+    && candidate.user !== null
+    && (candidate.refresh_token === undefined
+      || (typeof candidate.refresh_token === 'string' && candidate.refresh_token.length > 0))
+}
+
+/** Normalize a requested post-auth destination and reject cross-origin forms. */
+export function safeAuthRedirect(value: unknown): string {
+  if (typeof value !== 'string')
+    return '/'
+  const candidate = value.trim()
+  if (!candidate.startsWith('/') || candidate.startsWith('//'))
+    return '/'
+
+  try {
+    const base = new URL('https://stacks.invalid')
+    const resolved = new URL(candidate, base)
+    if (resolved.origin !== base.origin)
+      return '/'
+    const target = `${resolved.pathname}${resolved.search}${resolved.hash}`
+    return target.startsWith('/') && !target.startsWith('//') ? target : '/'
+  }
+  catch {
+    return '/'
+  }
+}
+
 export interface AuthComposable {
   isAuthenticated: Ref<boolean>
   user: { value: UserData | null }
-  login: (user: AuthUser) => Promise<LoginResponse | LoginError>
+  login: (user: AuthUser) => Promise<LoginResult | LoginError>
+  verifyTwoFactorLogin: (challengeToken: string, code: string) => Promise<LoginResponse | LoginError>
   register: (user: RegisterCredentials) => Promise<RegisterResponse | RegisterError>
   fetchAuthUser: () => Promise<UserData | null>
   checkAuthentication: () => Promise<boolean>
-  logout: () => void
+  logout: () => Promise<void>
   getToken: () => string | null
   token: { value: string | null }
 }
 
 export function useAuth(): AuthComposable {
+  function storeLogin(data: LoginResponse): void {
+    token.value = data.token
+    user.value = data.user
+    isAuthenticated.value = true
+  }
+
   async function fetchAuthUser(): Promise<UserData | null> {
     try {
-      if (!token.value) {
-        isAuthenticated.value = false
-        user.value = null
-        return null
-      }
-
       const response = await fetch(`${baseUrl}/me`, {
+        credentials: 'same-origin',
         headers: {
-          Authorization: `Bearer ${token.value}`,
+          ...(token.value ? { Authorization: `Bearer ${token.value}` } : {}),
           Accept: 'application/json',
         },
       })
@@ -122,7 +164,7 @@ export function useAuth(): AuthComposable {
     return 'token' in data && 'user' in data
   }
 
-  async function login(credentials: AuthUser): Promise<LoginResponse | LoginError> {
+  async function login(credentials: AuthUser): Promise<LoginResult | LoginError> {
     const url = `${baseUrl}/login`
     const response = await fetch(url, {
       method: 'POST',
@@ -132,37 +174,49 @@ export function useAuth(): AuthComposable {
       }),
       body: JSON.stringify(credentials),
     })
-    const data = await response.json() as LoginResponse | LoginError
+    const data = await response.json() as LoginResult | LoginError
 
-    if (!response.ok || !('token' in data && 'user' in data))
+    if (!response.ok || isTwoFactorChallenge(data))
       return data
 
-    token.value = data.token
-    user.value = data.user
-    isAuthenticated.value = true
+    if (!isLoginResponse(data))
+      return data
+
+    storeLogin(data)
+    return data
+  }
+
+  async function verifyTwoFactorLogin(challengeToken: string, code: string): Promise<LoginResponse | LoginError> {
+    const response = await fetch(`${baseUrl}/verify-two-factor-login`, {
+      method: 'POST',
+      credentials: 'same-origin',
+      headers: withCsrfHeader({ 'Content-Type': 'application/json' }),
+      body: JSON.stringify({ challenge_token: challengeToken, code }),
+    })
+    const data = await response.json() as LoginResponse | LoginError
+    if (!response.ok || !isLoginResponse(data))
+      return data
+
+    storeLogin(data)
     return data
   }
 
   async function logout() {
-    try {
-      if (token.value) {
-        await fetch(`${baseUrl}/logout`, {
-          method: 'POST',
-          headers: {
-            Authorization: `Bearer ${token.value}`,
-            Accept: 'application/json',
-          },
-        })
-      }
-    }
-    catch (error) {
-      console.error('Error during logout:', error)
-    }
-    finally {
-      token.value = ''
-      user.value = null
-      isAuthenticated.value = false
-    }
+    const currentToken = token.value
+    const response = await fetch(`${baseUrl}/logout`, {
+      method: 'POST',
+      credentials: 'same-origin',
+      headers: withCsrfHeader({
+        ...(currentToken ? { Authorization: `Bearer ${currentToken}` } : {}),
+        Accept: 'application/json',
+      }),
+    })
+    if (!response.ok)
+      throw new Error(`Logout failed with status ${response.status}`)
+
+    token.value = ''
+    user.value = null
+    isAuthenticated.value = false
   }
 
   return {
@@ -172,6 +226,7 @@ export function useAuth(): AuthComposable {
     getToken: () => token.value,
     register,
     login,
+    verifyTwoFactorLogin,
     logout,
     fetchAuthUser,
     checkAuthentication,

package/ide/vscode/package.json

@@ -2,7 +2,7 @@
   "publisher": "Stacks",
   "name": "vscode-stacks",
   "displayName": "Stacks",
-  "version": "0.74.60",
+  "version": "0.74.62",
   "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.60",
+  "version": "0.74.62",
   "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.60",
+    "@stacksjs/mobile": "^0.74.62",
     "@stacksjs/sanitizer": "^0.2.113",
     "ts-qr-codes": "^0.1.8"
   }

package/resources/components/Dashboard/Auth/Login.stx

@@ -51,7 +51,7 @@ function handleSubmit(): void {
   emit('submit', {
     email: email(),
     password: password(),
-    rememberMe: rememberMe(),
+    remember: rememberMe(),
   })
 }
 </script>

package/resources/components/Dashboard/Auth/LoginDashboard.stx

@@ -1,16 +1,16 @@
 <script client>
 import type { AuthUser } from '../../../../types/dashboard'
-import { describeAuthError, useAuth } from '../../../../functions/auth'
+import { describeAuthError, isLoginResponse, isTwoFactorChallenge, safeAuthRedirect, useAuth } from '../../../../functions/auth'
 
-const { login } = useAuth()
+const { login, verifyTwoFactorLogin } = useAuth()
 const route = useRoute()
 
 const isLoading = state(false)
 const error = state('')
+const challengeToken = state('')
 
 function safeRedirect(): string {
-  const redirect = String(route.query.redirect || '')
-  return redirect.startsWith('/') && !redirect.startsWith('//') ? redirect : '/'
+  return safeAuthRedirect(route.query.redirect)
 }
 
 async function handleLogin(credentials: AuthUser): Promise<void> {
@@ -20,7 +20,12 @@ async function handleLogin(credentials: AuthUser): Promise<void> {
   try {
     const result = await login(credentials)
 
-    if (!result || !('token' in result)) {
+    if (isTwoFactorChallenge(result)) {
+      challengeToken.set(result.challenge_token)
+      return
+    }
+
+    if (!isLoginResponse(result)) {
       error.set(describeAuthError(result, 'Invalid credentials'))
       return
     }
@@ -34,10 +39,38 @@ async function handleLogin(credentials: AuthUser): Promise<void> {
     isLoading.set(false)
   }
 }
+
+async function handleTwoFactor(code: string): Promise<void> {
+  isLoading.set(true)
+  error.set('')
+
+  try {
+    const result = await verifyTwoFactorLogin(challengeToken(), code)
+    if (!isLoginResponse(result)) {
+      challengeToken.set('')
+      error.set(describeAuthError(result, 'Invalid or expired login attempt. Please sign in again.'))
+      return
+    }
+
+    navigate(safeRedirect())
+  }
+  catch (err) {
+    error.set(err instanceof Error ? err.message : 'Unable to verify the authentication code')
+  }
+  finally {
+    isLoading.set(false)
+  }
+}
+
+function restartLogin(): void {
+  challengeToken.set('')
+  error.set('')
+}
 </script>
 
 <template>
   <Login
+    :if="!challengeToken()"
     @submit="handleLogin"
     :isLoading="isLoading()"
     :error="error()"
@@ -47,4 +80,11 @@ async function handleLogin(credentials: AuthUser): Promise<void> {
          sign-in inside the card. -->
     <template #social><slot name="social" /></template>
   </Login>
+  <TwoFactorLogin
+    :if="challengeToken()"
+    @submit="handleTwoFactor"
+    @restart="restartLogin"
+    :isLoading="isLoading()"
+    :error="error()"
+  />
 </template>

package/resources/components/Dashboard/Auth/TwoFactorLogin.stx

@@ -0,0 +1,63 @@
+@import('../UI/Input', '../UI/Button')
+
+<script client>
+const emit = defineEmits()
+const isLoading = useReactiveProp<boolean>('isLoading', false)
+const error = useReactiveProp<string>('error', '')
+const code = state('')
+const codeError = derived(() => code() && !/^\d{6}$/.test(code()) ? 'Enter the 6-digit code from your authenticator app' : '')
+
+function submit(): void {
+  if (!/^\d{6}$/.test(code()))
+    return
+  emit('submit', code())
+}
+</script>
+
+<div class="flex items-center justify-center px-4 py-12 min-h-screen">
+  <div class="max-w-sm w-full">
+    <div class="mb-8 text-center">
+      <div class="inline-flex items-center justify-center mb-4 h-12 w-12 bg-gradient-to-br from-blue-500 to-blue-600 rounded-xl shadow-blue-500/25 shadow-lg">
+        <span class="h-7 w-7 text-white i-hugeicons-shield-key"></span>
+      </div>
+      <h1 class="font-semibold text-2xl text-neutral-900 dark:text-white">Two-factor authentication</h1>
+      <p class="mt-2 text-neutral-500 text-sm dark:text-neutral-400">Enter the code from your authenticator app.</p>
+    </div>
+
+    <div class="p-6 bg-white dark:bg-neutral-900 border border-neutral-200/60 rounded-2xl dark:border-neutral-800 shadow-black/5 shadow-xl dark:shadow-black/20">
+      <div :if="error()" role="alert" class="mb-4 p-3 bg-red-50 dark:bg-red-900/20 border border-red-200 rounded-lg dark:border-red-800">
+        <p class="text-red-600 text-sm dark:text-red-400">{{ error() }}</p>
+      </div>
+
+      <form @submit.prevent="submit">
+        <Input
+          type="text"
+          name="code"
+          label="Authentication code"
+          placeholder="123456"
+          autocomplete="one-time-code"
+          v-model:value="code"
+          :error="codeError()"
+          required
+          :disabled="isLoading()"
+        />
+
+        <div class="grid gap-3 mt-6">
+          <Button
+            type="submit"
+            variant="primary"
+            size="lg"
+            fullWidth
+            :loading="isLoading()"
+            :disabled="isLoading() || !/^\d{6}$/.test(code())"
+          >
+            Verify and sign in
+          </Button>
+          <Button type="button" variant="ghost" size="lg" fullWidth :disabled="isLoading()" @click="emit('restart')">
+            Back to sign in
+          </Button>
+        </div>
+      </form>
+    </div>
+  </div>
+</div>

package/types/dashboard.ts

@@ -38,7 +38,7 @@ export interface RegisterResponse {
 // is kept alongside `access_token` for backward compatibility.
 export interface LoginResponse {
   access_token: string
-  refresh_token: string
+  refresh_token?: string
   token_type: string
   expires_in: number
   token: string
@@ -49,6 +49,13 @@ export interface LoginResponse {
   }
 }
 
+export interface TwoFactorLoginChallenge {
+  requires_two_factor: true
+  challenge_token: string
+}
+
+export type LoginResult = LoginResponse | TwoFactorLoginChallenge
+
 export interface Response<T> {
   errors: ResponseError
   data: T
@@ -57,6 +64,7 @@ export interface Response<T> {
 export interface AuthUser {
   email: string
   password: string
+  remember?: boolean
 }
 
 export interface RegisterCredentials extends AuthUser {