@stacksjs/defaults 0.75.15 → 0.75.17

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

@@ -35,8 +35,9 @@ const head = getAnalyticsHead(analytics)
 ```
 
 The registry is loud on purpose. A `driver` value with no implementation throws,
-and so does a driver that is selected but missing its config (the message names
-the exact key to set). Only an app with no `driver` at all gets an empty result.
+and so does a selected third-party driver missing its config (the message names
+the exact key to set). An app with no `driver` defaults to AnalyticsHQ. It emits
+nothing until `drivers.analyticshq.siteId` is set.
 
 Nothing injects the script for you - a framework that silently posted pageviews
 to a third party would be the wrong default. Render it yourself in the layout
@@ -142,9 +143,9 @@ interface SelfHostedConfig {
 
 ```typescript
 {
-  driver: 'fathom',              // 'fathom' | 'plausible' | 'google-analytics' | 'self-hosted' | 'analyticshq'
+  driver: 'analyticshq',         // 'analyticshq' | 'fathom' | 'plausible' | 'google-analytics' | 'self-hosted'
   drivers: {
-    analyticshq: { siteId: '' },
+    analyticshq: { siteId: '' }, // empty means no tracking tags
     googleAnalytics: { trackingId: '' },
     fathom: { siteId: '' },
     plausible: { domain: '' },
@@ -169,7 +170,8 @@ Analytics dashboard at `/dashboard/analytics` displays:
 
 ## Gotchas
 - Selecting a driver does not inject anything - call `generateAnalyticsScript()` in your layout
-- A misconfigured driver throws rather than emitting nothing; the message names the config key
+- A misconfigured third-party driver throws rather than emitting nothing; the message names the config key
+- AnalyticsHQ is the first-party default and emits nothing until its site id is set
 - `honorDnt: true` respects browser Do Not Track settings
 - Attribute values are escaped, and inline script values are JS-escaped, to prevent XSS
 - Fathom is a paid service - self-hosted is free but requires infrastructure

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

@@ -75,7 +75,8 @@ The `PersonalAccessToken` model maps the same table, so `owner.with('tokenable')
 lists exactly what `createToken` minted. It deliberately generates no CRUD
 routes: minting and revoking both carry semantics a generic route does not.
 - `Auth.once(credentials: AuthCredentials): Promise<boolean>` — one-time auth without token
-- `Auth.requestToken(credentials, clientId, clientSecret): Promise<{ token } | null>` — OAuth token request
+- `Auth.requestUserTokenWithClient(credentials, clientId, clientSecret): Promise<{ token } | null>` authenticates both a legacy OAuth client and an end user password, then issues a user token. It is not the client credentials grant.
+- `Auth.requestToken(...)` is the deprecated compatibility alias for that same legacy exchange. New delegated integrations use the authorization-code provider.
 
 ### User State
 - `Auth.user(): Promise<UserModel | undefined>` — get authenticated user from bearer token
@@ -155,6 +156,19 @@ routes: minting and revoking both carry semantics a generic route does not.
 - `createClient(options: CreateClientOptions): Promise<CreateClientResult>`
 - `revokeClient(clientId): Promise<void>`
 
+### OAuth Provider and PKCE
+
+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.
+
+- `resolveOAuthProviderConfig(options)` returns `null` unless explicitly enabled
+- `generatePkceVerifier()` creates a 256-bit RFC 7636 verifier
+- `createS256CodeChallenge(verifier)` derives its S256 challenge
+- `verifyS256CodeChallenge(verifier, challenge)` validates without a plain fallback
+- `isValidPkceVerifier(value)` checks the required 43 to 128 character syntax
+
 ## Two-Factor Authentication (authenticator.ts)
 
 - `generateTwoFactorSecret(): string`

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

@@ -77,9 +77,7 @@ bcryptEncode(value, rounds?)     // bcrypt hash
 bcryptVerify(value, hash)        // bcrypt verify
 argon2Encode(value, options?)    // argon2 hash
 argon2Verify(value, hash)        // argon2 verify
-md5Encode(value)                  // MD5 (legacy only)
 base64Encode(value)               // base64
-base64Verify(value, encoded)      // base64 compare
 ```
 
 ## HashMakeOptions
@@ -124,6 +122,7 @@ interface HashMakeOptions {
 - APP_KEY is used for `encrypt()`/`decrypt()` — generate via `buddy key:generate`
 - APP_KEY format is colon-separated (validated during deployment)
 - Argon2 requires more memory/time but is more resistant to GPU attacks
-- `md5Encode()` exists for legacy compatibility only — never use for passwords
+- Base64 is encoding, not hashing. Never use `base64Encode()` for credentials.
+- MD5 and base64 password verification are intentionally absent from the main security API.
 - The firewall config is used by cloud deployment for WAF rules
 - Rate limiting is per-minute per-IP (500 default)

package/ide/cursor/rules/readme.mdc

@@ -309,7 +309,7 @@ Convention over configuration, while staying wholly configurable. _No more boile
 - 🔤 **Spell Checker** _be notified once there are typos_
 - 🛠️ **Essential Utilities** _powers at your fingertips. Collections, STX composables, and more_
 - 👥 **Team Management** _manage your team & their permissions_
-- 🧪 **Streamlined Testing** _unit & e2e tests powered by Bun, Vitest & Playwright_
+- 🧪 **Streamlined Testing** _unit, feature & component tests powered by Bun & very-happy-dom_
 
 No matter whether you are a beginner or an expert, the approachable Stacks design allows you to learn at your own pace, using our thorough documentation covering every aspect of the framework. Stacks is extremely beginner & expert-friendly.
 

package/ide/vscode/package.json

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

package/resources/plugins/preloader.ts

@@ -6,6 +6,49 @@
  * automatically be injected into the Bun process.
  */
 
+/**
+ * Every global the runtime defined before this file assigned any.
+ *
+ * Taken first, at module load, because the auto-import loops below write
+ * framework exports onto globalThis, and a name the runtime already owns must
+ * never be one of them. A hand-kept list of such names is how `Worker` slipped
+ * through: `@stacksjs/queue` exports a queue `Worker`, it replaced Bun's Web
+ * Worker in every Stacks process, and anything calling `new Worker(url)` built
+ * a queue worker instead - stx's image warm-up failed silently, an app's own
+ * syntax-highlighter worker broke. `reportError` from `@stacksjs/validation`
+ * was overwriting the web `reportError` the same way.
+ */
+const HOST_GLOBALS: ReadonlySet<string> = new Set(Object.getOwnPropertyNames(globalThis))
+
+/**
+ * Names never auto-imported onto globalThis, even when the runtime does not
+ * define them: another runtime's globals (`window`, `Deno`), module-scope
+ * bindings (`require`, `__dirname`), and the ones listed long before the
+ * snapshot above existed, kept so nothing that relied on them changes.
+ */
+const RESERVED_GLOBALS: ReadonlySet<string> = new Set([
+  'process', 'globalThis', 'global', 'window', 'self',
+  'console', 'require', 'module', 'exports', '__dirname', '__filename',
+  'Buffer', 'setTimeout', 'setInterval', 'clearTimeout', 'clearInterval',
+  'setImmediate', 'clearImmediate', 'queueMicrotask',
+  'fetch', 'Request', 'Response', 'Headers', 'URL', 'URLSearchParams',
+  'TextEncoder', 'TextDecoder', 'Blob', 'File', 'FormData',
+  'crypto', 'performance', 'navigator', 'location',
+  'Promise', 'Symbol', 'Proxy', 'Reflect', 'WeakMap', 'WeakSet', 'Map', 'Set',
+  'Array', 'Object', 'String', 'Number', 'Boolean', 'Date', 'RegExp', 'Error',
+  'JSON', 'Math', 'Intl', 'eval', 'isNaN', 'isFinite', 'parseInt', 'parseFloat',
+  'encodeURI', 'encodeURIComponent', 'decodeURI', 'decodeURIComponent',
+  'Bun', 'Deno', 'Node',
+])
+
+/**
+ * Whether an auto-import must leave `name` alone: the runtime already defines
+ * it, or it is reserved. `hostGlobals` is injectable for tests.
+ */
+export function isProtectedGlobal(name: string, hostGlobals: ReadonlySet<string> = HOST_GLOBALS): boolean {
+  return RESERVED_GLOBALS.has(name) || hostGlobals.has(name)
+}
+
 // Skip preloader for fast CLI commands (e.g. `buddy dev`, `buddy --version`) to
 // maximize startup speed. We must NOT skip when running a server script directly
 // (e.g. `bun --watch storage/framework/core/actions/src/dev/api.ts`) — Bun
@@ -214,22 +257,6 @@ export async function loadAutoImports() {
   const path = await import('../../../core/path/src/index.ts')
     .catch(() => import(pathPackage))
 
-  // CRITICAL: Never overwrite these built-in globals
-  const protectedGlobals = new Set([
-    'process', 'globalThis', 'global', 'window', 'self',
-    'console', 'require', 'module', 'exports', '__dirname', '__filename',
-    'Buffer', 'setTimeout', 'setInterval', 'clearTimeout', 'clearInterval',
-    'setImmediate', 'clearImmediate', 'queueMicrotask',
-    'fetch', 'Request', 'Response', 'Headers', 'URL', 'URLSearchParams',
-    'TextEncoder', 'TextDecoder', 'Blob', 'File', 'FormData',
-    'crypto', 'performance', 'navigator', 'location',
-    'Promise', 'Symbol', 'Proxy', 'Reflect', 'WeakMap', 'WeakSet', 'Map', 'Set',
-    'Array', 'Object', 'String', 'Number', 'Boolean', 'Date', 'RegExp', 'Error',
-    'JSON', 'Math', 'Intl', 'eval', 'isNaN', 'isFinite', 'parseInt', 'parseFloat',
-    'encodeURI', 'encodeURIComponent', 'decodeURI', 'decodeURIComponent',
-    'Bun', 'Deno', 'Node',
-  ])
-
   // 1. Load Stacks framework packages into globalThis
   const stacksPackages = [
     '@stacksjs/actions',
@@ -275,8 +302,8 @@ export async function loadAutoImports() {
     try {
       const module = await import(pkg)
       for (const [name, value] of Object.entries(module)) {
-        // Skip default exports and protected globals
-        if (name === 'default' || protectedGlobals.has(name)) continue
+        // Skip default exports and anything the runtime already owns
+        if (name === 'default' || isProtectedGlobal(name)) continue
         if (typeof value !== 'undefined') {
           Reflect.set(globalThis, name, value)
         }
@@ -295,8 +322,8 @@ export async function loadAutoImports() {
     try {
       const module = await import(file)
       for (const [name, value] of Object.entries(module)) {
-        // Skip default exports and protected globals
-        if (name === 'default' || protectedGlobals.has(name)) continue
+        // Skip default exports and anything the runtime already owns
+        if (name === 'default' || isProtectedGlobal(name)) continue
         if (typeof value !== 'undefined') {
           Reflect.set(globalThis, name, value)
         }
@@ -326,7 +353,7 @@ export async function loadAutoImports() {
         if (file.endsWith('.d.ts') || file.endsWith('/index.ts')) continue
 
         const modelName = file.split('/').pop()?.replace('.ts', '') || ''
-        if (!modelName || loadedModels.has(modelName) || protectedGlobals.has(modelName)) continue
+        if (!modelName || loadedModels.has(modelName) || isProtectedGlobal(modelName)) continue
 
         try {
           const module = await import(file)
@@ -357,7 +384,7 @@ export async function loadAutoImports() {
       if (file.endsWith('.d.ts') || file.endsWith('/index.ts')) continue
 
       const jobName = file.split('/').pop()?.replace('.ts', '') || ''
-      if (!jobName || loadedJobs.has(jobName) || protectedGlobals.has(jobName)) continue
+      if (!jobName || loadedJobs.has(jobName) || isProtectedGlobal(jobName)) continue
 
       try {
         const module = await import(file)
@@ -392,7 +419,7 @@ export async function loadAutoImports() {
         if (file.endsWith('.d.ts') || file.endsWith('/index.ts')) continue
 
         const controllerName = file.split('/').pop()?.replace('.ts', '') || ''
-        if (!controllerName || loadedControllers.has(controllerName) || protectedGlobals.has(controllerName)) continue
+        if (!controllerName || loadedControllers.has(controllerName) || isProtectedGlobal(controllerName)) continue
 
         try {
           const module = await import(file)

package/resources/views/errors/tester.stx

@@ -8,10 +8,19 @@
  */
 import { isLocalDeployment } from '@stacksjs/env'
 
+/*
+ * Handed in by TestErrorAction's renderTemplate call, which spreads its
+ * `context` into the template scope - there is no `context` variable here.
+ * Undefined when the view fallback serves this file on its own. Read into a
+ * differently named list: a local `const scenarios = ...` shadows the injected
+ * one and the page lists nothing.
+ */
+declare const scenarios: Array<{ title: string, description: string, status: number, href: string }> | undefined
+
 if (!isLocalDeployment())
   notFound()
 
-const scenarios = typeof context !== 'undefined' && Array.isArray(context?.scenarios) ? context.scenarios : []
+const scenarioList = typeof scenarios !== 'undefined' && Array.isArray(scenarios) ? scenarios : []
 </script>
 
 <div class="mx-auto px-6 py-12 max-w-3xl">
@@ -21,7 +30,7 @@ const scenarios = typeof context !== 'undefined' && Array.isArray(context?.scena
   </p>
 
   <div class="grid gap-3">
-    @foreach(scenarios as scenario)
+    @foreach(scenarioList as scenario)
     <a
       href="{{ scenario.href }}"
       class="block p-4 bg-white dark:bg-white/[2%] border border-neutral-200 rounded-lg dark:border-white/10 hover:border-rose-500 transition-colors"