@stacksjs/defaults 0.75.228 → 0.75.229

package/app/Actions/Auth/SocialCallbackAction.ts

@@ -1,20 +1,41 @@
 import { Action } from '@stacksjs/actions/runtime'
-import { Auth, authCookieForBrowserSession, resolveBrowserSessionPolicy, resolveSocialSignIn, SocialSignInRefusedError } from '@stacksjs/auth'
+import { createSessionHandoff, resolveSocialSignIn, SocialSignInRefusedError } from '@stacksjs/auth'
 import { log } from '@stacksjs/logging'
 import { response } from '@stacksjs/router'
-import { isSocialProviderConfigured, socialHandoffFailureRedirect, socialHandoffRedirect, socialProvider } from '@stacksjs/socials'
+import {
+  clearOAuthFlowCookie,
+  consumeOAuthFlow,
+  isSocialProviderConfigured,
+  readOAuthFlowCookie,
+  SOCIAL_PROVIDERS,
+  socialHandoffCodeRedirect,
+  socialHandoffFailureRedirect,
+  socialProvider,
+} from '@stacksjs/socials'
+import { safeSocialReturnPath, socialFlowCookieOptions, socialFlowPurpose } from './social-flow'
 
 /**
  * `GET|POST /auth/{provider}/callback` — complete a social sign-in
  * (stacksjs/stacks#2276).
  *
- * The provider redirects back here with a `code`. The driver exchanges it for
- * the provider's user, `resolveSocialSignIn` decides which local user that is
- * (find-or-create, with the unverified-email takeover guard), and the session
- * is handed to the browser twice over: the auth cookie for server-rendered
- * pages, and the fragment handoff `useAuth().completeSocialLogin()` reads for
- * the SPA side. POST as well as GET because Apple mandates
- * `response_mode=form_post` whenever scopes are requested.
+ * 1. The returned `state` must redeem the flow SocialRedirectAction started,
+ *    in this browser (its HttpOnly cookie), once, within ten minutes. A code
+ *    from anywhere else is refused before it is exchanged: that is the login
+ *    CSRF a callback which "exchanges any code" is open to.
+ * 2. The driver exchanges the code; Apple's id_token must carry the flow's
+ *    nonce, X's exchange gets the flow's PKCE verifier back.
+ * 3. `resolveSocialSignIn` decides which local user that is (find-or-create,
+ *    refusing to link an address the provider or the local account has not
+ *    verified).
+ * 4. No session is minted here. The browser gets a 60-second, single-use
+ *    handoff code in the fragment, bound to a new HttpOnly cookie, and
+ *    `useAuth().completeSocialLogin()` redeems it at `POST /auth/handoff`
+ *    (SessionHandoffAction), which answers with the session. Bearer and
+ *    refresh tokens therefore never appear in a URL or in browser history.
+ *
+ * POST as well as GET because Apple mandates `response_mode=form_post`
+ * whenever scopes are requested. On a POST only the form body is read, so a
+ * query string cannot override what Apple sent.
  *
  * A refused sign-in redirects to /login with a `social_error` the page can
  * render; it is a policy decision, not an exception. Provider/exchange
@@ -22,7 +43,7 @@ import { isSocialProviderConfigured, socialHandoffFailureRedirect, socialHandoff
  */
 export default new Action({
   name: 'SocialCallbackAction',
-  description: 'Completes a social provider OAuth flow and signs the browser in.',
+  description: 'Completes a social provider OAuth flow and hands the browser a one-use sign-in code.',
   method: 'GET',
 
   async handle(request: RequestInstance) {
@@ -35,45 +56,91 @@ export default new Action({
     if (!driver)
       return response.notFound(`Social provider "${provider}" is not configured.`)
 
-    const code = String(request.get('code') ?? '')
+    const descriptor = SOCIAL_PROVIDERS[provider as keyof typeof SOCIAL_PROVIDERS]
+    const isPost = String(request.method ?? '').toUpperCase() === 'POST'
+    const form = (request as { formBody?: Record<string, unknown> }).formBody
+    const field = (name: string): string => {
+      const value = isPost ? form?.[name] : request.get(name)
+      return typeof value === 'string' ? value : ''
+    }
+
+    const state = field('state')
+    const cookieOptions = socialFlowCookieOptions(descriptor.postCallback)
+    // Every outcome clears the flow cookie: it is single use either way.
+    const withClearedFlow = async (redirect: Response): Promise<Response> => {
+      if (state)
+        redirect.headers.append('Set-Cookie', await clearOAuthFlowCookie(state, cookieOptions))
+      return redirect
+    }
+    const failure = (reason: string) => withClearedFlow(socialHandoffFailureRedirect(reason))
+
+    const flow = await consumeOAuthFlow(state, {
+      purpose: socialFlowPurpose(provider),
+      browserSecret: readOAuthFlowCookie(request.headers.get('cookie'), state),
+    })
+    if (!flow)
+      return failure('This sign-in expired or was started in another browser. Please try again.')
+
+    if (field('error'))
+      return failure('Sign-in was cancelled.')
+
+    const code = field('code')
     if (!code)
-      return socialHandoffFailureRedirect(`${provider} did not return an authorization code.`)
+      return failure(`${provider} did not return an authorization code.`)
 
     try {
+      const verifier = typeof flow.data?.verifier === 'string' ? flow.data.verifier : ''
+      if (verifier)
+        driver.withCodeVerifier(verifier)
+
       const accessToken = await driver.getAccessToken(code)
-      const identity = await driver.getUserByToken(accessToken)
+      const identity = await driver.getUserByToken(accessToken, flow.nonce ? { nonce: flow.nonce } : undefined)
+
+      if (descriptor.nonce) {
+        // The driver already refuses a mismatched nonce when given one; this
+        // also refuses a flow that somehow carried none.
+        if (!flow.nonce || identity.raw?.nonce !== flow.nonce)
+          return failure('Sign-in could not be completed. Please try again.')
+        // Apple sends the name once, on the first authorization, in the form body.
+        if (!identity.name)
+          identity.name = appleDisplayName(field('user'))
+      }
 
       const { userId } = await resolveSocialSignIn(provider, identity)
 
-      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.')
-
-      const redirect = socialHandoffRedirect({
-        token: session.token,
-        ...(session.refreshToken && { refreshToken: session.refreshToken }),
-        ...(session.expiresIn !== undefined && { expiresIn: session.expiresIn }),
-        user: {
-          id: userId,
-          email: identity.email ?? null,
-          name: identity.name ?? identity.nickname ?? null,
-        },
-      })
-
-      // The cookie signs server-rendered pages in; the fragment pack the SPA.
-      redirect.headers.append('Set-Cookie', authCookieForBrowserSession(session.token, session.expiresIn))
-      return redirect
+      const handoff = await createSessionHandoff(userId, { bindTo: 'cookie' })
+      const redirectTo = safeSocialReturnPath(flow.data?.redirectTo) ?? '/'
+      const redirect = socialHandoffCodeRedirect(handoff.code, { redirectTo })
+      if (handoff.cookie)
+        redirect.headers.append('Set-Cookie', handoff.cookie)
+      return await withClearedFlow(redirect)
     }
     catch (error) {
       if (error instanceof SocialSignInRefusedError)
-        return socialHandoffFailureRedirect(error.message)
+        return failure(error.message)
 
+      // Provider errors can echo codes or addresses; the message stays in the log.
       log.error(`[socials] ${provider} callback failed: ${(error as Error).message}`)
-      return socialHandoffFailureRedirect('Sign-in could not be completed. Please try again.')
+      return failure('Sign-in could not be completed. Please try again.')
     }
   },
 })
+
+/** Apple's first-authorization `user` field: `{"name":{"firstName","lastName"}}`. */
+function appleDisplayName(value: string): string {
+  if (!value || value.length > 4096)
+    return ''
+  try {
+    const name = (JSON.parse(value) as { name?: { firstName?: unknown, lastName?: unknown } })?.name
+    return [name?.firstName, name?.lastName]
+      .filter((part): part is string => typeof part === 'string')
+      .join(' ')
+      // eslint-disable-next-line no-control-regex
+      .replace(/[\u0000-\u001F\u007F]/g, '')
+      .trim()
+      .slice(0, 255)
+  }
+  catch {
+    return ''
+  }
+}

package/app/Actions/Auth/SocialRedirectAction.ts

@@ -1,6 +1,9 @@
+import { Buffer } from 'node:buffer'
+import { randomBytes } from 'node:crypto'
 import { Action } from '@stacksjs/actions/runtime'
 import { response } from '@stacksjs/router'
-import { isSocialProviderConfigured, socialProvider } from '@stacksjs/socials'
+import { isSocialProviderConfigured, issueOAuthFlow, SOCIAL_PROVIDERS, socialProvider } from '@stacksjs/socials'
+import { safeSocialReturnPath, SOCIAL_FLOW_TTL_MS, socialFlowCookieOptions, socialFlowPurpose } from './social-flow'
 
 /**
  * `GET /auth/{provider}` — send the browser to the provider's consent page
@@ -10,6 +13,15 @@ import { isSocialProviderConfigured, socialProvider } from '@stacksjs/socials'
  * half-built OAuth flow: the sign-in page renders its buttons from
  * `configuredSocialProviders()`, so a visitor only reaches this with a name
  * that works — anything else is URL guessing.
+ *
+ * The `state` in the provider URL comes from `issueOAuthFlow()`: single use,
+ * ten minutes, and bound to this browser by an HttpOnly cookie, so the
+ * callback can refuse a code that this browser did not ask for (login CSRF).
+ * Apple's flow also carries a nonce the callback finds in the id_token, and
+ * X's carries its PKCE verifier.
+ *
+ * `?redirect_to=/path` picks where the browser lands afterwards. Only a
+ * same-origin relative path is kept; anything else lands on `/`.
  */
 export default new Action({
   name: 'SocialRedirectAction',
@@ -26,12 +38,35 @@ export default new Action({
     if (!driver)
       return response.notFound(`Social provider "${provider}" is not configured.`)
 
-    return new Response(null, {
-      status: 302,
-      headers: {
-        'Location': await driver.getAuthUrl(),
-        'Cache-Control': 'no-store',
+    const descriptor = SOCIAL_PROVIDERS[provider as keyof typeof SOCIAL_PROVIDERS]
+    const verifier = descriptor.pkce ? Buffer.from(randomBytes(32)).toString('base64url') : undefined
+    const redirectTo = safeSocialReturnPath(request.get('redirect_to'))
+
+    const flow = await issueOAuthFlow({
+      purpose: socialFlowPurpose(provider),
+      ttlMs: SOCIAL_FLOW_TTL_MS,
+      nonce: descriptor.nonce,
+      data: {
+        ...(redirectTo && { redirectTo }),
+        ...(verifier && { verifier }),
       },
+      cookie: socialFlowCookieOptions(descriptor.postCallback),
     })
+
+    driver.withState(flow.state)
+    if (verifier)
+      driver.withCodeVerifier(verifier)
+    if (flow.nonce)
+      driver.with({ nonce: flow.nonce })
+
+    const headers = new Headers({
+      'Location': await driver.getAuthUrl(),
+      'Cache-Control': 'no-store',
+      'Referrer-Policy': 'no-referrer',
+    })
+    if (flow.cookie)
+      headers.append('Set-Cookie', flow.cookie)
+
+    return new Response(null, { status: 302, headers })
   },
 })

package/app/Actions/Auth/social-flow.ts

@@ -0,0 +1,49 @@
+import type { OAuthFlowCookieOptions } from '@stacksjs/socials'
+
+/**
+ * Shared by the default social sign-in actions (SocialRedirectAction,
+ * SocialCallbackAction, SessionHandoffAction). Not an action itself.
+ */
+
+/** A provider round trip: consent screens, 2FA at the provider, a slow phone. */
+export const SOCIAL_FLOW_TTL_MS = 10 * 60_000
+
+/** One purpose per provider, so a Google state can never complete an Apple callback. */
+export function socialFlowPurpose(provider: string): string {
+  return `social:${provider}`
+}
+
+/**
+ * A provider that returns with a cross-site POST (Apple's `form_post`) only
+ * gets the flow cookie back when it is `SameSite=None; Secure`. Everything
+ * else returns with a top-level GET, which `Lax` covers.
+ */
+export function socialFlowCookieOptions(postCallback: boolean): OAuthFlowCookieOptions {
+  return { path: '/', sameSite: postCallback ? 'None' : 'Lax' }
+}
+
+/**
+ * Where a finished sign-in may land: a same-origin path, or nothing.
+ *
+ * Backslashes and control characters are refused because browsers normalize
+ * them while parsing, so `/\evil.example` is an absolute URL to them. `//`
+ * is protocol-relative for the same reason.
+ */
+export function safeSocialReturnPath(value: unknown): string | null {
+  if (typeof value !== 'string' || value.length === 0 || value.length > 2048)
+    return null
+  if (!value.startsWith('/') || value.startsWith('//'))
+    return null
+  // eslint-disable-next-line no-control-regex
+  if (/[\\\u0000-\u001F\u007F]/.test(value))
+    return null
+  try {
+    const parsed = new URL(value, 'https://stacks.invalid')
+    if (parsed.origin !== 'https://stacks.invalid')
+      return null
+    return `${parsed.pathname}${parsed.search}${parsed.hash}`
+  }
+  catch {
+    return null
+  }
+}

package/app/Middleware/Throttle.ts

@@ -1,4 +1,4 @@
-import { clientAddress, createRateLimitMiddleware, Middleware, parseThrottleString } from '@stacksjs/router'
+import { clientAddress, createRateLimitMiddleware, Middleware, parseThrottleString, scaledLimit } from '@stacksjs/router'
 
 // Cache for rate limiters to avoid creating new instances for each request
 const limiterCache = new Map<string, ReturnType<typeof createRateLimitMiddleware>>()
@@ -77,14 +77,15 @@ export default new Middleware({
     if (!limiter) {
       try {
         const config = parseThrottleString(params as Parameters<typeof parseThrottleString>[0])
-        limiter = createRateLimitMiddleware({ ...config, keyGenerator: throttleKey }, `throttle:${params}`)
+        // `config.security.rateLimit.scale` multiplies every application limit.
+        limiter = createRateLimitMiddleware({ ...config, maxAttempts: scaledLimit(config.maxAttempts), keyGenerator: throttleKey }, `throttle:${params}`)
         limiterCache.set(params, limiter)
       }
       catch (error) {
         console.error(`[Throttle] Invalid throttle pattern: ${params}`, error)
         // Use default if pattern is invalid
         const defaultConfig = parseThrottleString('60,1')
-        limiter = createRateLimitMiddleware({ ...defaultConfig, keyGenerator: throttleKey }, 'throttle:default')
+        limiter = createRateLimitMiddleware({ ...defaultConfig, maxAttempts: scaledLimit(defaultConfig.maxAttempts), keyGenerator: throttleKey }, 'throttle:default')
         limiterCache.set(params, limiter)
       }
     }

package/ide/vscode/package.json

@@ -2,7 +2,7 @@
   "publisher": "Stacks",
   "name": "vscode-stacks",
   "displayName": "Stacks",
-  "version": "0.75.228",
+  "version": "0.75.229",
   "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.228",
+  "version": "0.75.229",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/stacksjs/stacks.git",
@@ -44,7 +44,7 @@
   "dependencies": {
     "@iconify-json/f7": "^1.2.2",
     "@iconify-json/hugeicons": "^1.2.35",
-    "@stacksjs/mobile": "0.75.228",
+    "@stacksjs/mobile": "0.75.229",
     "@stacksjs/sanitizer": "^0.2.534",
     "@xterm/addon-fit": "^0.11.0",
     "@xterm/xterm": "^6.0.0",

package/resources/emails/password-reset.stx

@@ -5,7 +5,17 @@ const appName = props.appName || 'Stacks'
 const resetUrl = props.resetUrl || '#'
 const expireMinutes = props.expireMinutes || 60
 const primaryColor = props.primaryColor || '#3451b2'
-const subject = props.subject || `Reset your ${appName} password`
+// `purpose: 'setup'` is a first password for an account someone else created.
+const setup = props.purpose === 'setup'
+const subject = props.subject || (setup ? `Set your ${appName} password` : `Reset your ${appName} password`)
+const heading = setup ? 'Choose your password' : 'Reset your password'
+const intro = setup
+  ? `An account has been created for you on ${appName}. Click the button below to choose your password.`
+  : `You recently requested to reset your password for your ${appName} account. Click the button below to reset it.`
+const action = setup ? 'Set Password' : 'Reset Password'
+const ignore = setup
+  ? 'If you were not expecting this, you can ignore this email.'
+  : 'If you did not request a password reset, please ignore this email or contact support if you have concerns about your account security.'
 const year = props.year || new Date().getFullYear()
 </script>
 
@@ -18,13 +28,13 @@ const year = props.year || new Date().getFullYear()
     </tr>
   </template>
 
-  <EmailText size="heading">Reset your password</EmailText>
-  <EmailText>You recently requested to reset your password for your <strong>{{ appName }}</strong> account. Click the button below to reset it.</EmailText>
+  <EmailText size="heading">{{ heading }}</EmailText>
+  <EmailText>{{ intro }}</EmailText>
 
-  <EmailButton href="{{ resetUrl }}" bg="{{ primaryColor }}">Reset Password</EmailButton>
+  <EmailButton href="{{ resetUrl }}" bg="{{ primaryColor }}">{{ action }}</EmailButton>
 
-  <EmailText size="sm" color="#6b7280">This password reset link will expire in <strong>{{ expireMinutes }} minutes</strong>.</EmailText>
-  <EmailText size="sm" color="#6b7280">If you did not request a password reset, please ignore this email or contact support if you have concerns about your account security.</EmailText>
+  <EmailText size="sm" color="#6b7280">This link will expire in <strong>{{ expireMinutes }} minutes</strong>.</EmailText>
+  <EmailText size="sm" color="#6b7280">{{ ignore }}</EmailText>
 
   <EmailDivider />
   <EmailText size="sm" color="#9ca3af" spacing="8px">If the button above doesn't work, copy and paste the following URL into your browser:</EmailText>

package/routes/socials.ts

@@ -1,10 +1,12 @@
 /**
  * Framework Default Routes - Social sign-in (stacksjs/stacks#2276)
  *
- * `GET /auth/{provider}` sends the browser to the provider's consent page;
- * `/auth/{provider}/callback` completes the exchange, resolves the local user
+ * `GET /auth/{provider}` sends the browser to the provider's consent page
+ * with a single-use, browser-bound `state`; `/auth/{provider}/callback`
+ * redeems that state, completes the exchange, resolves the local user
  * through the find-or-create policy in `@stacksjs/auth` (with its
- * unverified-email takeover guard), and hands the session to the browser.
+ * unverified-email takeover guards), and redirects with a one-use handoff
+ * code that `POST /auth/handoff` trades for the session.
  *
  * Mounted by `defaults/bootstrap.ts` as the `social` bundle. Unlike the other
  * bundles it is NOT part of the implicit default set: it mounts only when the
@@ -29,4 +31,12 @@ import { route } from '@stacksjs/router'
 // provider's authorize page with this app's client id.
 route.get('/auth/{provider}', 'Actions/Auth/SocialRedirectAction').rateLimit(10, 'minute')
 route.get('/auth/{provider}/callback', 'Actions/Auth/SocialCallbackAction').rateLimit(10, 'minute')
-route.post('/auth/{provider}/callback', 'Actions/Auth/SocialCallbackAction').rateLimit(10, 'minute')
+// Apple's form_post is a cross-site POST that cannot carry a CSRF token. The
+// single-use, cookie-bound OAuth `state` the action checks is the CSRF
+// defence here, and a stronger one: it binds the code to the browser that
+// started the flow.
+route.post('/auth/{provider}/callback', 'Actions/Auth/SocialCallbackAction').skipCsrf().rateLimit(10, 'minute')
+// Trades the callback's one-use code for the session (useAuth's
+// completeSocialLogin). Bound to an HttpOnly cookie set beside the code,
+// which is the proof a CSRF token would add.
+route.post('/auth/handoff', 'Actions/Auth/SessionHandoffAction').skipCsrf().rateLimit(10, 'minute')