@stacksjs/defaults 0.75.27 → 0.75.29

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

@@ -161,7 +161,28 @@ routes: minting and revoking both carry semantics a generic route does not.
 The authorization server is opt-in through `config/auth.ts` under
 `oauthProvider`. It is separate from social sign-in, where Stacks is the OAuth
 client. The provider profile is Authorization Code with S256 PKCE and rotating
-refresh tokens. It does not support implicit or password grants.
+refresh tokens. It does not support implicit, password, or client-credentials
+grants. It also does not implement token introspection or OpenID Connect.
+
+When enabled, the default auth route bundle registers:
+
+- `GET` and `POST /oauth/authorize`
+- `POST /oauth/token`
+- `POST /oauth/revoke`
+- `GET /.well-known/oauth-authorization-server`
+- owner-managed clients under `/auth/oauth/clients`
+- user-managed connected applications under `/auth/oauth/connections`
+
+Set a canonical `issuer`, then register every scope and resource explicitly.
+Resource audiences are absolute URIs and redirect URIs use exact matching.
+The consent view is `auth/oauth/consent` by default and can be overridden with
+`oauthProvider.consent.view`. Use `oauthProvider.consent.resolveWorkspace` when
+the application must bind consent to current server-owned workspace authority.
+
+Provider actions return 404 while `oauthProvider.enabled` is false. The token
+and revocation endpoints use protocol credentials and intentionally skip
+browser CSRF. Authorization approval, client management, and disconnect remain
+authenticated and CSRF protected.
 
 - `resolveOAuthProviderConfig(options)` returns `null` unless explicitly enabled
 - `generatePkceVerifier()` creates a 256-bit RFC 7636 verifier

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 406 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 407 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, 406 components, and a multi-section layout.
+The Stacks admin dashboard provides a full-featured admin panel with 100+ route views, 407 components, and a multi-section layout.
 
 ## Key Paths
 - Dashboard components: `storage/framework/defaults/resources/components/Dashboard/`

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

@@ -106,6 +106,42 @@ export default {
 }
 ```
 
+## The base design: email components
+
+STX templates build on a bundled component library (`defaults/resources/components/Email`),
+which every bundled template uses and which gives an app a finished look with a few props:
+
+```html
+<EmailLayout
+  title="Your license key"
+  preheader="Shown after the subject in the inbox"
+  brand="Uplink" brandUrl="https://uplink.example" accent="#f59e0b"
+  footer="You are getting this because you bought Uplink."
+>
+  <EmailText size="heading">You have Uplink Monthly.</EmailText>
+  <EmailText>Here is your license key.</EmailText>
+  <EmailCode>UPLK-7RKR-Z2BJ-V6QV-4PUH</EmailCode>
+  <EmailButton href="https://uplink.example/activate" bg="#f59e0b" color="#18181b">Activate</EmailButton>
+  <EmailDivider />
+  <EmailText size="sm">Small print.</EmailText>
+</EmailLayout>
+```
+
+- `<EmailLayout>`: a muted page with one bordered card (a border, not a shadow: Gmail strips
+  shadows), an optional brand header and footer, a hidden `preheader`, and `@media` rules for
+  dark mode and phones on the class hooks the other components carry. Clients that ignore
+  `@media` keep the inline light design.
+- `<EmailText size="heading|lg|md|sm">`, `<EmailButton>`, `<EmailDivider>`, `<EmailSection>`,
+  `<EmailImage>`, `<EmailLink>`.
+- `<EmailCode>`: a key or one-time code, large and monospace, selectable in one tap, wrapping at
+  hyphens on a phone.
+
+A colour passed as a prop is the template's own choice: that element gets no dark-mode hook.
+
+Two stx traps when writing a component or template: never put the literal text of a style
+tag inside a `<script server>` comment (the parser takes it for one), and write head CSS as a
+raw string (`{!! css !!}`) rather than a style element, which stx lifts out as component CSS.
+
 ## Template Locations
 - STX templates: `.stx` files processed by STX engine
 - HTML templates: `.html` files with `{{ }}` variable interpolation

package/app/Actions/Auth/OAuthAuthorizationAction.ts

@@ -0,0 +1,81 @@
+import type { OAuthAuthorizationConsentPageContext } from '@stacksjs/auth'
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { Action } from '@stacksjs/actions'
+import { resolveDefaultsResources } from '@stacksjs/actions/dev/defaults-resources'
+import {
+  authenticatedUser,
+  authUser,
+  handleOAuthAuthorizationPageRequest,
+  resolveOAuthConsentWorkspace,
+  resolveOAuthProviderConfig,
+} from '@stacksjs/auth'
+import { config } from '@stacksjs/config'
+import { path } from '@stacksjs/path'
+import { getCurrentRequest, response } from '@stacksjs/router'
+import { oauthPositiveId } from './oauth-request'
+
+function identityLabel(user: { email: string, [key: string]: unknown }): string {
+  const name = typeof user.name === 'string' ? user.name.trim() : ''
+  return name || user.email.trim()
+}
+
+async function renderConsentView(
+  view: string,
+  context: OAuthAuthorizationConsentPageContext,
+): Promise<string> {
+  const relative = view.endsWith('.stx') ? view : `${view}.stx`
+  const applicationView = path.userViewsPath(relative)
+  const frameworkView = join(resolveDefaultsResources(), 'views', relative)
+  const template = existsSync(applicationView) ? applicationView : frameworkView
+  const { renderTemplate } = await import('@stacksjs/stx')
+
+  return String(await renderTemplate(template, {
+    context,
+    injectCSS: true,
+    templateOnly: true,
+    processClientScripts: false,
+  }))
+}
+
+export default new Action({
+  name: 'OAuthAuthorizationAction',
+  description: 'Start or resume an OAuth authorization request',
+  method: 'GET',
+
+  async handle(request: RequestInstance) {
+    const provider = resolveOAuthProviderConfig(config.auth.oauthProvider)
+    if (!provider)
+      return response.notFound('OAuth provider is not enabled')
+
+    // This GET route must stay public so an anonymous browser can persist the
+    // request before login. `request.user()` only exposes identity populated
+    // by auth middleware, which this route deliberately cannot use, so fall
+    // through to the lazy cookie/bearer resolver after honoring a directly
+    // injected action-test or upstream middleware identity.
+    const user = await authenticatedUser(request)
+      ?? (getCurrentRequest() ? await authUser() : undefined)
+    const subjectId = user ? oauthPositiveId(user.id) : null
+    const workspace = user && subjectId
+      ? await resolveOAuthConsentWorkspace(provider, { request, user })
+      : null
+    const resolveWorkspaceId = user
+      ? async () => (await resolveOAuthConsentWorkspace(provider, { request, user }))?.id ?? null
+      : undefined
+    return handleOAuthAuthorizationPageRequest({
+      provider,
+      request: request as unknown as Request,
+      identity: user ? { label: identityLabel(user), workspaceLabel: workspace?.label } : null,
+      subject: subjectId
+        ? {
+            type: 'users',
+            id: subjectId,
+            workspaceId: workspace?.id,
+            resolveWorkspaceId,
+          }
+        : null,
+      csrfToken: (request as unknown as { _csrfToken?: string })._csrfToken,
+      dependencies: { render: renderConsentView },
+    })
+  },
+})

package/app/Actions/Auth/OAuthClientDisableAction.ts

@@ -0,0 +1,38 @@
+import { Action } from '@stacksjs/actions'
+import { disableOAuthClient, resolveOAuthProviderConfig } from '@stacksjs/auth'
+import { config } from '@stacksjs/config'
+import { response } from '@stacksjs/router'
+import { oauthPositiveId } from './oauth-request'
+
+export default new Action({
+  name: 'OAuthClientDisableAction',
+  description: 'Disable an OAuth client owned by the authenticated user',
+  method: 'POST',
+
+  async handle(request: RequestInstance) {
+    const provider = resolveOAuthProviderConfig(config.auth.oauthProvider)
+    if (!provider)
+      return response.notFound('OAuth provider is not enabled')
+
+    const user = await request.user()
+    const ownerId = user ? oauthPositiveId(user.id) : null
+    if (!ownerId)
+      return response.unauthorized('Authentication required')
+
+    const rawClientId = request.getParam('id')
+    const clientId = /^\d+$/.test(rawClientId) ? oauthPositiveId(rawClientId) : null
+    if (!clientId)
+      return response.badRequest('Invalid OAuth client ID')
+
+    const disabled = await disableOAuthClient(ownerId, clientId)
+    if (!disabled)
+      return response.notFound('OAuth client not found')
+
+    return response.json({
+      message: 'OAuth client disabled successfully',
+      client_id: clientId,
+    }, {
+      headers: { 'Cache-Control': 'no-store' },
+    })
+  },
+})

package/app/Actions/Auth/OAuthClientSecretRotateAction.ts

@@ -0,0 +1,41 @@
+import { Action } from '@stacksjs/actions'
+import { resolveOAuthProviderConfig, rotateOAuthClientSecret } from '@stacksjs/auth'
+import { config } from '@stacksjs/config'
+import { response } from '@stacksjs/router'
+import { oauthPositiveId } from './oauth-request'
+
+export default new Action({
+  name: 'OAuthClientSecretRotateAction',
+  description: 'Rotate an OAuth client secret owned by the authenticated user',
+  method: 'POST',
+
+  async handle(request: RequestInstance) {
+    const provider = resolveOAuthProviderConfig(config.auth.oauthProvider)
+    if (!provider)
+      return response.notFound('OAuth provider is not enabled')
+
+    const user = await request.user()
+    const ownerId = user ? oauthPositiveId(user.id) : null
+    if (!ownerId)
+      return response.unauthorized('Authentication required')
+
+    const rawClientId = request.getParam('id')
+    const clientId = /^\d+$/.test(rawClientId) ? oauthPositiveId(rawClientId) : null
+    if (!clientId)
+      return response.badRequest('Invalid OAuth client ID')
+
+    const clientSecret = await rotateOAuthClientSecret(ownerId, clientId)
+    if (!clientSecret)
+      return response.notFound('OAuth client not found')
+
+    return response.json({
+      client_id: clientId,
+      client_secret: clientSecret,
+    }, {
+      headers: {
+        'Cache-Control': 'no-store',
+        'Pragma': 'no-cache',
+      },
+    })
+  },
+})

package/app/Actions/Auth/OAuthClientStoreAction.ts

@@ -0,0 +1,73 @@
+import { Action } from '@stacksjs/actions'
+import {
+  OAuthClientRegistrationError,
+  registerOAuthClient,
+  resolveOAuthProviderConfig,
+} from '@stacksjs/auth'
+import { config } from '@stacksjs/config'
+import { response } from '@stacksjs/router'
+import { oauthPositiveId, oauthStringList } from './oauth-request'
+
+export default new Action({
+  name: 'OAuthClientStoreAction',
+  description: 'Register an OAuth client for the authenticated user',
+  method: 'POST',
+
+  async handle(request: RequestInstance) {
+    const provider = resolveOAuthProviderConfig(config.auth.oauthProvider)
+    if (!provider)
+      return response.notFound('OAuth provider is not enabled')
+
+    const user = await request.user()
+    const ownerId = user ? oauthPositiveId(user.id) : null
+    if (!ownerId)
+      return response.unauthorized('Authentication required')
+
+    const body = await request.all() as Record<string, unknown>
+    const name = typeof body.name === 'string' ? body.name : null
+    const type = body.type === 'public' || body.type === 'confidential' ? body.type : null
+    const redirectUris = oauthStringList(body.redirect_uris)
+    const scopes = oauthStringList(body.scopes)
+    const resources = oauthStringList(body.resources)
+    if (!name || !type || !redirectUris || !scopes || !resources)
+      return response.badRequest('OAuth client registration metadata is invalid')
+
+    try {
+      const result = await registerOAuthClient(provider, ownerId, {
+        name,
+        type,
+        tokenEndpointAuthMethod: type === 'public' ? 'none' : 'client_secret_basic',
+        redirectUris,
+        grantTypes: ['authorization_code', 'refresh_token'],
+        scopes,
+        resources,
+      })
+
+      return response.json({
+        client: {
+          id: result.client.id,
+          name: result.client.name,
+          type: result.client.type,
+          token_endpoint_auth_method: result.client.tokenEndpointAuthMethod,
+          redirect_uris: result.client.redirectUris,
+          grant_types: result.client.grantTypes,
+          scopes: result.client.scopes,
+          resources: result.client.resources,
+          created_at: result.client.createdAt.toISOString(),
+        },
+        ...(result.plainTextSecret ? { client_secret: result.plainTextSecret } : {}),
+      }, {
+        status: 201,
+        headers: {
+          'Cache-Control': 'no-store',
+          'Pragma': 'no-cache',
+        },
+      })
+    }
+    catch (error) {
+      if (error instanceof OAuthClientRegistrationError)
+        return response.json({ message: error.message }, { status: 422 })
+      throw error
+    }
+  },
+})

package/app/Actions/Auth/OAuthClientUpdateAction.ts

@@ -0,0 +1,73 @@
+import { Action } from '@stacksjs/actions'
+import {
+  OAuthClientRegistrationError,
+  resolveOAuthProviderConfig,
+  updateOAuthClient,
+} from '@stacksjs/auth'
+import { config } from '@stacksjs/config'
+import { response } from '@stacksjs/router'
+import { oauthPositiveId, oauthStringList } from './oauth-request'
+
+export default new Action({
+  name: 'OAuthClientUpdateAction',
+  description: 'Update an OAuth client owned by the authenticated user',
+  method: 'PATCH',
+
+  async handle(request: RequestInstance) {
+    const provider = resolveOAuthProviderConfig(config.auth.oauthProvider)
+    if (!provider)
+      return response.notFound('OAuth provider is not enabled')
+
+    const user = await request.user()
+    const ownerId = user ? oauthPositiveId(user.id) : null
+    if (!ownerId)
+      return response.unauthorized('Authentication required')
+
+    const rawClientId = request.getParam('id')
+    const clientId = /^\d+$/.test(rawClientId) ? oauthPositiveId(rawClientId) : null
+    if (!clientId)
+      return response.badRequest('Invalid OAuth client ID')
+
+    const body = await request.all() as Record<string, unknown>
+    const name = typeof body.name === 'string' ? body.name : null
+    const redirectUris = oauthStringList(body.redirect_uris)
+    const scopes = oauthStringList(body.scopes)
+    const resources = oauthStringList(body.resources)
+    if (!name || !redirectUris || !scopes || !resources)
+      return response.badRequest('OAuth client update metadata is invalid')
+
+    try {
+      const client = await updateOAuthClient(provider, ownerId, clientId, {
+        name,
+        redirectUris,
+        grantTypes: ['authorization_code', 'refresh_token'],
+        scopes,
+        resources,
+      })
+      if (!client)
+        return response.notFound('OAuth client not found')
+
+      return response.json({
+        client: {
+          id: client.id,
+          name: client.name,
+          type: client.type,
+          token_endpoint_auth_method: client.tokenEndpointAuthMethod,
+          redirect_uris: client.redirectUris,
+          grant_types: client.grantTypes,
+          scopes: client.scopes,
+          resources: client.resources,
+          revoked: client.revoked,
+          created_at: client.createdAt.toISOString(),
+        },
+      }, {
+        headers: { 'Cache-Control': 'no-store' },
+      })
+    }
+    catch (error) {
+      if (error instanceof OAuthClientRegistrationError)
+        return response.json({ message: error.message }, { status: 422 })
+      throw error
+    }
+  },
+})

package/app/Actions/Auth/OAuthClientsAction.ts

@@ -0,0 +1,42 @@
+import { Action } from '@stacksjs/actions'
+import { listOAuthClients, resolveOAuthProviderConfig } from '@stacksjs/auth'
+import { config } from '@stacksjs/config'
+import { response } from '@stacksjs/router'
+import { oauthPositiveId } from './oauth-request'
+
+export default new Action({
+  name: 'OAuthClientsAction',
+  description: 'List OAuth clients owned by the authenticated user',
+  method: 'GET',
+
+  async handle(request: RequestInstance) {
+    const provider = resolveOAuthProviderConfig(config.auth.oauthProvider)
+    if (!provider)
+      return response.notFound('OAuth provider is not enabled')
+
+    const user = await request.user()
+    const id = user ? oauthPositiveId(user.id) : null
+    if (!id)
+      return response.unauthorized('Authentication required')
+
+    const clients = await listOAuthClients(id)
+
+    return response.json({
+      clients: clients.map(client => ({
+        id: client.id,
+        name: client.name,
+        type: client.type,
+        token_endpoint_auth_method: client.tokenEndpointAuthMethod,
+        redirect_uris: client.redirectUris,
+        grant_types: client.grantTypes,
+        scopes: client.scopes,
+        resources: client.resources,
+        revoked: client.revoked,
+        created_at: client.createdAt.toISOString(),
+      })),
+      count: clients.length,
+    }, {
+      headers: { 'Cache-Control': 'no-store' },
+    })
+  },
+})

package/app/Actions/Auth/OAuthConnectionsAction.ts

@@ -0,0 +1,40 @@
+import { Action } from '@stacksjs/actions'
+import { listOAuthConnections, resolveOAuthProviderConfig } from '@stacksjs/auth'
+import { config } from '@stacksjs/config'
+import { response } from '@stacksjs/router'
+import { oauthPositiveId } from './oauth-request'
+
+export default new Action({
+  name: 'OAuthConnectionsAction',
+  description: 'List OAuth applications connected to the authenticated user',
+  method: 'GET',
+
+  async handle(request: RequestInstance) {
+    const provider = resolveOAuthProviderConfig(config.auth.oauthProvider)
+    if (!provider)
+      return response.notFound('OAuth provider is not enabled')
+
+    const user = await request.user()
+    const id = user ? oauthPositiveId(user.id) : null
+    if (!id)
+      return response.unauthorized('Authentication required')
+
+    const connections = await listOAuthConnections('users', id)
+
+    return response.json({
+      connections: connections.map(connection => ({
+        grant_id: connection.grantId,
+        client_id: connection.clientId,
+        client_name: connection.clientName,
+        scopes: connection.scopes,
+        resources: connection.resources,
+        audiences: connection.audiences,
+        workspace_id: connection.workspaceId,
+        created_at: connection.createdAt.toISOString(),
+      })),
+      count: connections.length,
+    }, {
+      headers: { 'Cache-Control': 'no-store' },
+    })
+  },
+})

package/app/Actions/Auth/OAuthConsentAction.ts

@@ -0,0 +1,34 @@
+import { Action } from '@stacksjs/actions'
+import {
+  handleOAuthAuthorizationConsentRequest,
+  resolveOAuthConsentWorkspace,
+  resolveOAuthProviderConfig,
+} from '@stacksjs/auth'
+import { config } from '@stacksjs/config'
+import { response } from '@stacksjs/router'
+import { oauthPositiveId } from './oauth-request'
+
+export default new Action({
+  name: 'OAuthConsentAction',
+  description: 'Approve or deny an OAuth authorization request',
+  method: 'POST',
+
+  async handle(request: RequestInstance) {
+    const provider = resolveOAuthProviderConfig(config.auth.oauthProvider)
+    if (!provider)
+      return response.notFound('OAuth provider is not enabled')
+
+    const user = await request.user()
+    const id = user ? oauthPositiveId(user.id) : null
+    if (!id)
+      return response.unauthorized('Authentication required')
+
+    return handleOAuthAuthorizationConsentRequest({
+      provider,
+      request: request as unknown as Request,
+      subjectType: 'users',
+      subjectId: id,
+      resolveWorkspaceId: async () => (await resolveOAuthConsentWorkspace(provider, { request, user }))?.id ?? null,
+    })
+  },
+})

package/app/Actions/Auth/OAuthDisconnectAction.ts

@@ -0,0 +1,37 @@
+import { Action } from '@stacksjs/actions'
+import { disconnectOAuthGrant, resolveOAuthProviderConfig } from '@stacksjs/auth'
+import { config } from '@stacksjs/config'
+import { response } from '@stacksjs/router'
+import { oauthPositiveId } from './oauth-request'
+
+export default new Action({
+  name: 'OAuthDisconnectAction',
+  description: 'Disconnect an OAuth application from the authenticated user',
+  method: 'POST',
+
+  async handle(request: RequestInstance) {
+    const provider = resolveOAuthProviderConfig(config.auth.oauthProvider)
+    if (!provider)
+      return response.notFound('OAuth provider is not enabled')
+
+    const user = await request.user()
+    const id = user ? oauthPositiveId(user.id) : null
+    if (!id)
+      return response.unauthorized('Authentication required')
+
+    const grantId = request.getParam('id')
+    if (!/^[a-f0-9]{32}$/.test(grantId))
+      return response.badRequest('Invalid OAuth grant ID')
+
+    const disconnected = await disconnectOAuthGrant('users', id, grantId)
+    if (!disconnected)
+      return response.notFound('OAuth connection not found')
+
+    return response.json({
+      message: 'OAuth application disconnected successfully',
+      grant_id: grantId,
+    }, {
+      headers: { 'Cache-Control': 'no-store' },
+    })
+  },
+})

package/app/Actions/Auth/OAuthMetadataAction.ts

@@ -0,0 +1,20 @@
+import { Action } from '@stacksjs/actions'
+import { oauthAuthorizationServerMetadata, resolveOAuthProviderConfig } from '@stacksjs/auth'
+import { config } from '@stacksjs/config'
+import { response } from '@stacksjs/router'
+
+export default new Action({
+  name: 'OAuthMetadataAction',
+  description: 'Publish OAuth authorization-server metadata',
+  method: 'GET',
+
+  async handle() {
+    const provider = resolveOAuthProviderConfig(config.auth.oauthProvider)
+    if (!provider)
+      return response.notFound('OAuth provider is not enabled')
+
+    return response.json(oauthAuthorizationServerMetadata(provider), {
+      headers: { 'Cache-Control': 'public, max-age=300' },
+    })
+  },
+})

package/app/Actions/Auth/OAuthRevocationAction.ts

@@ -0,0 +1,24 @@
+import { Action } from '@stacksjs/actions'
+import { handleOAuthRevocationRequest, resolveOAuthProviderConfig } from '@stacksjs/auth'
+import { config } from '@stacksjs/config'
+import { response } from '@stacksjs/router'
+
+export default new Action({
+  name: 'OAuthRevocationAction',
+  description: 'Revoke a delegated OAuth token',
+  method: 'POST',
+  // OAuth clients authenticate with their registered protocol method instead
+  // of a browser session, so they cannot and must not need a CSRF cookie.
+  skipCsrf: true,
+
+  async handle(request: RequestInstance) {
+    if (!resolveOAuthProviderConfig(config.auth.oauthProvider))
+      return response.notFound('OAuth provider is not enabled')
+
+    return handleOAuthRevocationRequest({
+      body: (await request.rawBody?.()) ?? '',
+      contentType: request.headers.get('content-type'),
+      authorization: request.headers.get('authorization'),
+    })
+  },
+})

package/app/Actions/Auth/OAuthTokenAction.ts

@@ -0,0 +1,35 @@
+import type { OAuthSubjectEligibility } from '@stacksjs/auth'
+import { Action } from '@stacksjs/actions'
+import { handleOAuthTokenRequest, resolveOAuthProviderConfig } from '@stacksjs/auth'
+import { config } from '@stacksjs/config'
+import { db } from '@stacksjs/database/runtime'
+import { response } from '@stacksjs/router'
+
+const isSubjectEligible: OAuthSubjectEligibility = async (subject) => {
+  if (subject.type !== 'users') return false
+  return Boolean(await db.primary.selectFrom('users')
+    .where('id', '=', subject.id)
+    .select('id')
+    .executeTakeFirst())
+}
+
+export default new Action({
+  name: 'OAuthTokenAction',
+  description: 'Exchange OAuth authorization codes and refresh tokens',
+  method: 'POST',
+  // OAuth clients authenticate with PKCE or HTTP Basic and cannot obtain the
+  // browser CSRF cookie. The protocol boundary validates its own credentials.
+  skipCsrf: true,
+
+  async handle(request: RequestInstance) {
+    const provider = resolveOAuthProviderConfig(config.auth.oauthProvider)
+    if (!provider)
+      return response.notFound('OAuth provider is not enabled')
+
+    return handleOAuthTokenRequest(provider, {
+      body: (await request.rawBody?.()) ?? '',
+      contentType: request.headers.get('content-type'),
+      authorization: request.headers.get('authorization'),
+    }, { isSubjectEligible })
+  },
+})

package/app/Actions/Auth/oauth-request.ts

@@ -0,0 +1,10 @@
+export function oauthPositiveId(value: number | string): number | null {
+  const id = Number(value)
+  return Number.isSafeInteger(id) && id > 0 ? id : null
+}
+
+export function oauthStringList(value: unknown): string[] | null {
+  return Array.isArray(value) && value.every(item => typeof item === 'string')
+    ? value
+    : null
+}

package/app/Middleware/Csrf.ts

@@ -215,7 +215,7 @@ export function seedCsrfCookieIfMissing(req: Request, response: Response, minted
  * Last duplicate wins; the canonical name takes precedence over the legacy
  * name unless its final value is empty. Malformed pairs are skipped.
  */
-function csrfCookieToken(req: Request): string {
+export 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.

package/ide/vscode/package.json

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

package/resources/components/Email/EmailButton.stx

@@ -23,8 +23,8 @@ const padY = props.padY || '14px'
 </script>
 <table role="presentation" cellpadding="0" cellspacing="0" border="0" style="margin:24px 0;border-collapse:separate;">
   <tr>
-    <td align="center" style="border-radius:6px;background-color:{{ bg }};mso-padding-alt:0;">
-      <a href="{{ href }}" style="display:inline-block;padding:{{ padY }} {{ padX }};color:{{ color }};text-decoration:none;border-radius:6px;font-weight:600;font-size:16px;font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,'Helvetica Neue',Arial,sans-serif;text-align:center;mso-padding-alt:{{ padY }} {{ padX }};">
+    <td align="center" style="border-radius:8px;background-color:{{ bg }};mso-padding-alt:0;">
+      <a href="{{ href }}" style="display:inline-block;padding:{{ padY }} {{ padX }};color:{{ color }};text-decoration:none;border-radius:8px;font-weight:600;font-size:16px;font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,'Helvetica Neue',Arial,sans-serif;text-align:center;mso-padding-alt:{{ padY }} {{ padX }};">
         <slot />
       </a>
     </td>

package/resources/components/Email/EmailCode.stx

@@ -0,0 +1,28 @@
+<script server>
+// A code the reader copies: a license key, a one-time passcode, a recovery
+// code. Large monospace on a tinted block, spaced so O and 0, l and 1 are
+// told apart, and selectable as one unit where the client allows it
+// (`user-select: all`), so a tap or double-click takes the whole code. On a
+// narrow screen it wraps at a hyphen rather than mid-group, and only breaks
+// inside a group when a code has no hyphens to wrap at.
+//
+//   <EmailCode>UPLK-7RKR-Z2BJ-V6QV-4PUH</EmailCode>
+//   <EmailCode size="32px" align="center">482 913</EmailCode>
+interface EmailCodeProps {
+  size?: string
+  align?: 'left' | 'center' | 'right'
+  spacing?: string
+}
+
+const props = defineProps<EmailCodeProps>()
+const size = props.size || '22px'
+const align = props.align || 'center'
+const spacing = props.spacing || '24px'
+</script>
+<table role="presentation" cellpadding="0" cellspacing="0" border="0" style="width:100%;border-collapse:separate;margin:0 0 {{ spacing }} 0;">
+  <tr>
+    <td class="email-code" align="{{ align }}" style="padding:18px 20px;background-color:#f4f4f5;border:1px solid #e4e4e7;border-radius:10px;color:#18181b;font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,'Liberation Mono',monospace;font-size:{{ size }};font-weight:600;letter-spacing:0.08em;line-height:1.4;text-align:{{ align }};-webkit-user-select:all;user-select:all;overflow-wrap:anywhere;">
+      <slot />
+    </td>
+  </tr>
+</table>

package/resources/components/Email/EmailDivider.stx

@@ -10,11 +10,11 @@ interface EmailDividerProps {
 }
 
 const props = defineProps<EmailDividerProps>()
-const color = props.color || '#e5e7eb'
+const color = props.color || '#e4e4e7'
 const spacing = props.spacing || '24px'
 </script>
 <table role="presentation" cellpadding="0" cellspacing="0" border="0" style="width:100%;border-collapse:collapse;margin:{{ spacing }} 0;">
   <tr>
-    <td style="height:1px;font-size:1px;line-height:1px;background-color:{{ color }};">&nbsp;</td>
+    <td class="email-divider" style="height:1px;font-size:1px;line-height:1px;background-color:{{ color }};">&nbsp;</td>
   </tr>
 </table>

package/resources/components/Email/EmailLayout.stx

@@ -3,10 +3,25 @@
 //
 // Wraps content in the table-based body that Outlook + Gmail (Android)
 // require, plus the standard meta block (charset / viewport /
-// X-UA-Compatible / colour-scheme). Two-tone bodyBg / contentBg
-// mirrors the bundled templates: muted page colour outside, white
-// card inside. Named slots: head / header / footer. See README for
-// usage examples.
+// X-UA-Compatible / colour-scheme). Named slots: head / header / footer.
+//
+// The base design, which every bundled template inherits:
+//   - a muted page with one white card, a hairline border and a 12px radius.
+//     A border rather than a shadow: Gmail strips box-shadow, so a shadow-only
+//     card lost its edge in the most-used client.
+//   - `preheader`: the line an inbox shows after the subject. Without it the
+//     inbox shows whatever text comes first - usually the brand name again.
+//   - `brand` / `accent` / `brandUrl`: a small brand header (an accent dot and
+//     the name) when the template does not fill the `header` slot itself.
+//   - `footer`: a muted, centred line under the card when the template does
+//     not fill the `footer` slot.
+//   - dark mode and a tighter phone layout, as `@media` rules on the class
+//     hooks below. The CSS inliner leaves `@media` rules in the head
+//     (stacksjs/stacks#1902), so clients that honour them (Apple Mail, iOS,
+//     Outlook for Mac) get them and the rest keep the inline light design.
+//   - those rules are written out raw from here, not as a style element in
+//     the template: stx treats a component's own style element as component
+//     CSS and lifts it out of the head, which lost them.
 //
 // Notes on `defineProps()`: stx fills missing props with an empty
 // string (not `undefined`), so destructure defaults silently no-op
@@ -17,6 +32,11 @@ interface EmailLayoutProps {
   width?: number | string
   bodyBg?: string
   contentBg?: string
+  preheader?: string
+  brand?: string
+  brandUrl?: string
+  accent?: string
+  footer?: string
 }
 
 const props = defineProps<EmailLayoutProps>()
@@ -24,6 +44,32 @@ const title = props.title || ''
 const width = props.width || 600
 const bodyBg = props.bodyBg || '#f4f4f5'
 const contentBg = props.contentBg || '#ffffff'
+const preheader = props.preheader || ''
+const brand = props.brand || ''
+const brandUrl = props.brandUrl || ''
+const accent = props.accent || '#3451b2'
+const footer = props.footer || ''
+const fontStack = '-apple-system,BlinkMacSystemFont,\'Segoe UI\',Roboto,\'Helvetica Neue\',Arial,sans-serif'
+
+const responsiveCss = [
+  '<style>',
+  '@media only screen and (max-width: 620px) {',
+  '  .email-outer { padding: 16px 8px !important; }',
+  '  .email-pad { padding: 28px 24px !important; }',
+  '  .email-brand { padding: 24px 24px 0 !important; }',
+  '  .email-code { font-size: 18px !important; letter-spacing: 0.04em !important; }',
+  '}',
+  '@media (prefers-color-scheme: dark) {',
+  '  .email-body, .email-outer { background-color: #0c0c0e !important; }',
+  '  .email-card { background-color: #141417 !important; border-color: #27272a !important; }',
+  '  .email-heading, .email-brand-name { color: #f4f4f5 !important; }',
+  '  .email-text { color: #d4d4d8 !important; }',
+  '  .email-muted { color: #a1a1aa !important; }',
+  '  .email-code { background-color: #1c1c20 !important; border-color: #27272a !important; color: #f4f4f5 !important; }',
+  '  .email-divider { background-color: #27272a !important; }',
+  '}',
+  '</style>',
+].join('\n')
 </script>
 
 <!DOCTYPE html>
@@ -35,19 +81,42 @@ const contentBg = props.contentBg || '#ffffff'
   <meta name="color-scheme" content="light dark">
   <meta name="supported-color-schemes" content="light dark">
   <title>{{ title }}</title>
+  {!! responsiveCss !!}
   <slot name="head" />
 </head>
-<body style="margin:0;padding:0;background-color:{{ bodyBg }};font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,'Helvetica Neue',Arial,sans-serif;line-height:1.6;-webkit-text-size-adjust:100%;-ms-text-size-adjust:100%;">
+<body class="email-body" style="margin:0;padding:0;background-color:{{ bodyBg }};font-family:{{ fontStack }};line-height:1.6;-webkit-text-size-adjust:100%;-ms-text-size-adjust:100%;">
+  @if(preheader)
+    <div style="display:none;max-height:0;max-width:0;overflow:hidden;opacity:0;mso-hide:all;font-size:1px;line-height:1px;color:{{ bodyBg }};">{{ preheader }}&#8199;&#847;&#8199;&#847;&#8199;&#847;&#8199;&#847;&#8199;&#847;&#8199;&#847;&#8199;&#847;&#8199;&#847;</div>
+  @endif
   <table role="presentation" cellpadding="0" cellspacing="0" border="0" style="width:100%;border-collapse:collapse;background-color:{{ bodyBg }};">
     <tr>
-      <td align="center" style="padding:40px 20px;">
-        <table role="presentation" cellpadding="0" cellspacing="0" border="0" style="max-width:{{ width }}px;width:100%;background-color:{{ contentBg }};border-radius:8px;overflow:hidden;box-shadow:0 1px 3px rgba(0,0,0,0.1);">
+      <td class="email-outer" align="center" style="padding:40px 20px;background-color:{{ bodyBg }};">
+        <table class="email-card" role="presentation" cellpadding="0" cellspacing="0" border="0" style="max-width:{{ width }}px;width:100%;background-color:{{ contentBg }};border:1px solid #e4e4e7;border-radius:12px;overflow:hidden;border-collapse:separate;">
+          @if(brand)
+            <tr>
+              <td class="email-brand" style="padding:32px 40px 0;">
+                <span style="display:inline-block;width:10px;height:10px;border-radius:5px;background-color:{{ accent }};vertical-align:middle;margin-right:10px;"></span>
+                @if(brandUrl)
+                  <a class="email-brand-name" href="{{ brandUrl }}" style="color:#18181b;text-decoration:none;font-size:15px;font-weight:600;letter-spacing:-0.01em;vertical-align:middle;font-family:{{ fontStack }};">{{ brand }}</a>
+                @else
+                  <span class="email-brand-name" style="color:#18181b;font-size:15px;font-weight:600;letter-spacing:-0.01em;vertical-align:middle;font-family:{{ fontStack }};">{{ brand }}</span>
+                @endif
+              </td>
+            </tr>
+          @endif
           <slot name="header" />
-          <tr><td style="padding:40px;">
+          <tr><td class="email-pad" style="padding:32px 40px 40px;">
             <slot />
           </td></tr>
           <slot name="footer" />
         </table>
+        @if(footer)
+          <table role="presentation" cellpadding="0" cellspacing="0" border="0" style="max-width:{{ width }}px;width:100%;border-collapse:collapse;">
+            <tr>
+              <td class="email-muted" style="padding:20px 24px 0;text-align:center;color:#71717a;font-size:12px;line-height:1.6;font-family:{{ fontStack }};">{{ footer }}</td>
+            </tr>
+          </table>
+        @endif
       </td>
     </tr>
   </table>

package/resources/components/Email/EmailText.stx

@@ -14,17 +14,20 @@ interface EmailTextProps {
 const props = defineProps<EmailTextProps>()
 const align = props.align || 'left'
 const size = props.size || 'md'
-const color = props.color || (size === 'heading' ? '#111827' : '#4b5563')
+const color = props.color || (size === 'heading' ? '#18181b' : size === 'sm' ? '#71717a' : '#3f3f46')
+// Hooks for the dark-mode rules in <EmailLayout>. A colour passed as a prop is
+// the template's own choice, so it gets no hook and dark mode leaves it alone.
+const role = props.color ? '' : size === 'heading' ? 'email-heading' : size === 'sm' ? 'email-muted' : 'email-text'
 const spacing = props.spacing || '16px'
 
 const sizeStyles: Record<string, string> = {
   sm: 'font-size:14px;line-height:1.5;',
   md: 'font-size:16px;line-height:1.6;',
   lg: 'font-size:18px;line-height:1.6;',
-  heading: 'font-size:20px;line-height:1.4;font-weight:600;',
+  heading: 'font-size:22px;line-height:1.3;font-weight:600;letter-spacing:-0.01em;',
 }
 const sizeStyle = sizeStyles[size] || sizeStyles.md
 </script>
-<p style="margin:0 0 {{ spacing }} 0;text-align:{{ align }};color:{{ color }};{{ sizeStyle }}">
+<p class="{{ role }}" style="margin:0 0 {{ spacing }} 0;text-align:{{ align }};color:{{ color }};{{ sizeStyle }}">
   <slot />
 </p>

package/resources/components/Video.stx

@@ -67,10 +67,12 @@ effect(() => {
 })
 </script>
 
+{{-- No src attribute until there is a video: an empty one resolves to the
+     page's own URL, which the browser then downloads as the video. --}}
 <figure class="m-0 {{ className }}">
   <video-player
     ref="player"
-    src="{{ src }}"
+    @if(src) src="{{ src }}" @endif
     :src="liveSrc() || null"
     :poster="livePoster() || null"
     data-media-config="{{ playerConfig }}"
@@ -93,7 +95,7 @@ effect(() => {
     @if(isEmbed)
       <a data-native-fallback href="{{ src }}" target="_blank" rel="noopener" class="flex items-center justify-center h-full w-full text-sm text-white underline">Watch {{ title }}</a>
     @else
-    <video data-native-fallback src="{{ src }}" @if(poster) poster="{{ poster }}" @endif @if(width) width="{{ width }}" @endif @if(height) height="{{ height }}" @endif @if(controls) controls @endif @if(props.autoplay) autoplay @endif @if(props.loop) loop @endif @if(props.muted) muted @endif @if(inline) playsinline @endif preload="{{ preload }}" @if(crossorigin) crossorigin="{{ crossorigin }}" @endif controlslist="{{ controlslist }}" @if(props.disablePictureInPicture) disablepictureinpicture @endif aria-label="{{ title }}" class="object-contain h-full w-full">
+    <video data-native-fallback @if(src) src="{{ src }}" @endif @if(poster) poster="{{ poster }}" @endif @if(width) width="{{ width }}" @endif @if(height) height="{{ height }}" @endif @if(controls) controls @endif @if(props.autoplay) autoplay @endif @if(props.loop) loop @endif @if(props.muted) muted @endif @if(inline) playsinline @endif preload="{{ preload }}" @if(crossorigin) crossorigin="{{ crossorigin }}" @endif controlslist="{{ controlslist }}" @if(props.disablePictureInPicture) disablepictureinpicture @endif aria-label="{{ title }}" class="object-contain h-full w-full">
       @foreach (sources as source)
         <source src="{{ source.src }}" @if(source.type) type="{{ source.type }}" @endif>
       @endforeach

package/resources/components/Video.test.ts

@@ -11,6 +11,14 @@ describe('Video', () => {
     expect(video).toContain(`:poster="livePoster() || null"`)
   })
 
+  it('renders no src attribute without a video, which would fetch the page itself', () => {
+    // An empty src resolves to the document's URL: the browser downloads the
+    // whole page as the video and fails, every time a player with nothing
+    // chosen yet renders.
+    expect(video).not.toMatch(/(?<!@if\(src\) )src="\{\{ src \}\}"/)
+    expect(video.match(/@if\(src\) src="\{\{ src \}\}" @endif/g)?.length).toBe(2)
+  })
+
   it('pauses when its src is cleared, as closing a sheet does', () => {
     expect(video).toContain(`useRef('player')`)
     expect(video).toContain('ref="player"')

package/routes/auth.ts

@@ -23,8 +23,18 @@
  * and user routes load first, so your handler always takes priority.
  */
 
+import { oauthAuthorizationServerMetadataPath, resolveOAuthProviderConfig } from '@stacksjs/auth'
+import { config } from '@stacksjs/config'
 import { route } from '@stacksjs/router'
 
+const oauthProvider = resolveOAuthProviderConfig(config.auth.oauthProvider)
+const oauthAuthorizationPath = oauthProvider ? new URL(oauthProvider.endpoints.authorization).pathname : '/oauth/authorize'
+const oauthTokenPath = oauthProvider ? new URL(oauthProvider.endpoints.token).pathname : '/oauth/token'
+const oauthRevocationPath = oauthProvider ? new URL(oauthProvider.endpoints.revocation).pathname : '/oauth/revoke'
+const oauthMetadataPath = oauthProvider
+  ? oauthAuthorizationServerMetadataPath(oauthProvider.issuer)
+  : '/.well-known/oauth-authorization-server'
+
 // Rate limits on token-issuance + password-reset endpoints
 // (stacksjs/stacks#1921). `Auth.attempt()` already has a per-email
 // lockout but it doesn't stop credential-stuffing across many emails
@@ -34,6 +44,14 @@ import { route } from '@stacksjs/router'
 // `routes/api.ts` (user routes win) gets to pick its own limits.
 route.post('/login', 'Actions/Auth/LoginAction').rateLimit(5, 'minute')
 route.post('/register', 'Actions/Auth/RegisterAction').rateLimit(3, 'minute')
+// OAuth authorization-server token exchange. The action remains a 404 unless
+// config.auth.oauthProvider.enabled is explicitly true. PKCE or HTTP Basic is
+// the endpoint's credential boundary, so the action opts out of browser CSRF.
+route.post(oauthTokenPath, 'Actions/Auth/OAuthTokenAction').rateLimit(30, 'minute')
+route.post(oauthRevocationPath, 'Actions/Auth/OAuthRevocationAction').rateLimit(30, 'minute')
+route.get(oauthAuthorizationPath, 'Actions/Auth/OAuthAuthorizationAction').rateLimit(60, 'minute')
+route.post(oauthAuthorizationPath, 'Actions/Auth/OAuthConsentAction').middleware('auth').rateLimit(30, 'minute')
+route.get(oauthMetadataPath, 'Actions/Auth/OAuthMetadataAction')
 // Magic links (config.auth.magicLink.enabled gates both, 404 when off).
 // The send endpoint answers a uniform 202 either way (anti-enumeration
 // lives in sendMagicLink); the consume endpoint is a POST because email
@@ -67,6 +85,13 @@ route.post('/verify-two-factor-login', 'Actions/Auth/VerifyTwoFactorLoginAction'
 
 route.group({ prefix: '/auth' }, () => {
   route.post('/refresh', 'Actions/Auth/RefreshTokenAction').rateLimit(10, 'minute')
+  route.get('/oauth/clients', 'Actions/Auth/OAuthClientsAction').middleware('auth')
+  route.post('/oauth/clients', 'Actions/Auth/OAuthClientStoreAction').middleware('auth').rateLimit(10, 'minute')
+  route.patch('/oauth/clients/{id}', 'Actions/Auth/OAuthClientUpdateAction').middleware('auth').rateLimit(20, 'minute')
+  route.post('/oauth/clients/{id}/disable', 'Actions/Auth/OAuthClientDisableAction').middleware('auth').rateLimit(10, 'minute')
+  route.post('/oauth/clients/{id}/rotate-secret', 'Actions/Auth/OAuthClientSecretRotateAction').middleware('auth').rateLimit(5, 'minute')
+  route.get('/oauth/connections', 'Actions/Auth/OAuthConnectionsAction').middleware('auth')
+  route.post('/oauth/connections/{id}/disconnect', 'Actions/Auth/OAuthDisconnectAction').middleware('auth').rateLimit(10, 'minute')
   route.get('/tokens', 'Actions/Auth/ListTokensAction').middleware('auth')
   route.post('/token', 'Actions/Auth/CreateTokenAction').middleware('auth').rateLimit(10, 'minute')
   route.delete('/tokens/{id}', 'Actions/Auth/RevokeTokenAction').middleware('auth')