@stacksjs/defaults 0.70.57 → 0.70.59

package/app/Middleware/Cors.ts

@@ -0,0 +1,320 @@
+import type { CorsConfig, ResolvedCorsConfig } from '@stacksjs/types'
+import { config } from '@stacksjs/config'
+import { Middleware } from '@stacksjs/router'
+
+/**
+ * CORS Middleware
+ *
+ * Implements the Cross-Origin Resource Sharing protocol on top of the
+ * Stacks middleware pipeline. Two responsibilities:
+ *
+ *   1. **Preflight (OPTIONS)** — short-circuit with a 204 + CORS headers.
+ *      No further middleware runs, no action runs.
+ *   2. **Regular requests** — pass through to the action, then attach the
+ *      configured CORS headers to the outgoing response.
+ *
+ * Because the Stacks middleware runner only invokes `handle()` *before* the
+ * action (no native post-response hook), the response-mutation half of
+ * this middleware uses the same marker pattern as `Compress.ts`: `handle`
+ * stamps the request with `_corsOptions`, and the router applies the
+ * headers via {@link applyCorsHeaders} after the action returns.
+ *
+ * **Configuration**
+ *
+ * Reads from `config.cors`. If unset, sensible defaults are used:
+ * - `origin: '*'`
+ * - `methods: ['GET', 'HEAD', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS']`
+ * - `allowedHeaders: ['Content-Type', 'Authorization', 'X-Requested-With']`
+ * - `exposedHeaders: []`
+ * - `credentials: false`
+ * - `maxAge: 86400` (24h)
+ *
+ * Expected config shape (add to `config/cors.ts` or under `config/app.ts`):
+ * ```ts
+ * export default {
+ *   cors: {
+ *     origin: '*' | string[] | (origin: string) => boolean,
+ *     methods?: string[],
+ *     allowedHeaders?: string[],
+ *     exposedHeaders?: string[],
+ *     credentials?: boolean,
+ *     maxAge?: number,
+ *   }
+ * }
+ * ```
+ *
+ * **Vary header**
+ *
+ * `Vary: Origin` is set unconditionally on responses that include CORS
+ * headers. Without it, an HTTP cache could serve a response with
+ * `Access-Control-Allow-Origin: https://a.com` to a request from
+ * `https://b.com`. We also append `Access-Control-Request-Headers` and
+ * `Access-Control-Request-Method` to Vary on preflight so caches don't
+ * conflate two preflights with different requested headers/methods.
+ *
+ * **Credentials safety**
+ *
+ * When `credentials: true`, the spec forbids `Access-Control-Allow-Origin: *`.
+ * In that case we echo the request's Origin (only if it matches the
+ * configured allow-list) or omit the header entirely — never `*`. This
+ * prevents the most common credentials-bypass misconfiguration.
+ *
+ * @example
+ * ```ts
+ * route.get('/api/*', 'Actions/Api').middleware('cors')
+ * route.options('/api/*', () => new Response(null)).middleware('cors')
+ * ```
+ */
+
+// `CorsConfig` + `ResolvedCorsConfig` live in `@stacksjs/types` so
+// `config/cors.ts` files can import them by package name and get
+// IntelliSense. The middleware re-exports them here for backwards
+// compatibility with consumers that previously imported them from this
+// file directly (stacksjs/stacks#1859 H-2).
+export type { CorsConfig, ResolvedCorsConfig }
+
+/** Defaults used when `config.cors` is missing or partial. */
+const DEFAULT_CORS: ResolvedCorsConfig = {
+  origin: '*',
+  methods: ['GET', 'HEAD', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'],
+  allowedHeaders: ['Content-Type', 'Authorization', 'X-Requested-With'],
+  exposedHeaders: [],
+  credentials: false,
+  maxAge: 86_400,
+}
+
+/**
+ * Read `config.cors` and merge with defaults. Fail-soft — if config access
+ * throws (e.g. before bootstrap), we fall back to defaults rather than
+ * crashing the request.
+ */
+function resolveCorsConfig(): ResolvedCorsConfig {
+  try {
+    // `config.cors` is now typed via `StacksOptions.cors?: CorsConfig`
+    // (stacksjs/stacks#1859 H-2). The proxy returns undefined when the
+    // key is missing, which the fall-through below handles.
+    const userConfig: CorsConfig | undefined = config.cors
+    if (!userConfig)
+      return DEFAULT_CORS
+    return {
+      origin: userConfig.origin ?? DEFAULT_CORS.origin,
+      methods: userConfig.methods ?? DEFAULT_CORS.methods,
+      allowedHeaders: userConfig.allowedHeaders ?? DEFAULT_CORS.allowedHeaders,
+      exposedHeaders: userConfig.exposedHeaders ?? DEFAULT_CORS.exposedHeaders,
+      credentials: userConfig.credentials ?? DEFAULT_CORS.credentials,
+      maxAge: userConfig.maxAge ?? DEFAULT_CORS.maxAge,
+    }
+  }
+  catch {
+    return DEFAULT_CORS
+  }
+}
+
+/**
+ * Decide whether a given Origin is allowed under the configured policy.
+ *
+ * - `'*'` — every origin allowed (but see credentials note below).
+ * - `string[]` — exact-match list.
+ * - `(origin) => boolean` — caller-defined predicate.
+ */
+function isOriginAllowed(origin: string, policy: ResolvedCorsConfig['origin']): boolean {
+  if (policy === '*')
+    return true
+  if (Array.isArray(policy))
+    return policy.includes(origin)
+  if (typeof policy === 'function')
+    return policy(origin)
+  return false
+}
+
+/**
+ * Compute the value to send in `Access-Control-Allow-Origin`, honoring the
+ * "no `*` with credentials" rule.
+ *
+ * Returns:
+ * - the matched origin string (echoes the request, or `*` when no creds + wildcard policy)
+ * - `null` if the origin is disallowed (caller should omit the header entirely)
+ */
+function computeAllowOrigin(
+  requestOrigin: string | null,
+  cfg: ResolvedCorsConfig,
+): string | null {
+  // No Origin header → not a CORS request from the browser's perspective;
+  // we still set Vary in case a cache later serves the same URL.
+  if (!requestOrigin)
+    return cfg.origin === '*' && !cfg.credentials ? '*' : null
+
+  if (!isOriginAllowed(requestOrigin, cfg.origin))
+    return null
+
+  // Credentials mode forbids the literal `*` per the CORS spec — browsers
+  // reject the response if both are present. Echo the actual origin
+  // instead so the Allow-Credentials response is usable.
+  if (cfg.credentials)
+    return requestOrigin
+
+  // Non-credentials wildcard policy: prefer `*` so caches collapse all
+  // origins onto one stored response (more cacheable than per-origin echo).
+  if (cfg.origin === '*')
+    return '*'
+
+  return requestOrigin
+}
+
+/**
+ * Append a token to a comma-separated header value if not already present
+ * (case-insensitive). Returns the new header value.
+ */
+function appendVary(existing: string | null, token: string): string {
+  if (!existing)
+    return token
+  const tokens = existing.split(',').map(s => s.trim().toLowerCase())
+  if (tokens.includes(token.toLowerCase()))
+    return existing
+  return `${existing}, ${token}`
+}
+
+/**
+ * Build the preflight (OPTIONS) response. Returns 204 with the configured
+ * CORS headers — does NOT proceed to the next middleware or action.
+ *
+ * @example
+ * ```ts
+ * if (request.method === 'OPTIONS')
+ *   throw buildPreflightResponse(request, resolveCorsConfig())
+ * ```
+ */
+export function buildPreflightResponse(request: Request, cfg: ResolvedCorsConfig): Response {
+  const headers = new Headers()
+  const requestOrigin = request.headers.get('origin')
+  const allowOrigin = computeAllowOrigin(requestOrigin, cfg)
+
+  if (allowOrigin !== null)
+    headers.set('Access-Control-Allow-Origin', allowOrigin)
+
+  // Vary on every dimension that influences the preflight response so
+  // shared caches don't blend two clients' answers.
+  headers.set('Vary', 'Origin, Access-Control-Request-Method, Access-Control-Request-Headers')
+
+  if (cfg.credentials)
+    headers.set('Access-Control-Allow-Credentials', 'true')
+
+  // Echo the requested method if it's in our allow-list; otherwise advertise
+  // the configured methods. This keeps the preflight tight when the client
+  // is asking about a specific method.
+  const requestedMethod = request.headers.get('access-control-request-method')
+  const methods
+    = requestedMethod && cfg.methods.includes(requestedMethod.toUpperCase())
+      ? [requestedMethod.toUpperCase()]
+      : cfg.methods
+  headers.set('Access-Control-Allow-Methods', methods.join(', '))
+
+  // Echo the requested headers (typically lowercase) — the browser sends
+  // them and the spec allows us to reflect rather than enumerate.
+  const requestedHeaders = request.headers.get('access-control-request-headers')
+  if (requestedHeaders)
+    headers.set('Access-Control-Allow-Headers', requestedHeaders)
+  else if (cfg.allowedHeaders.length > 0)
+    headers.set('Access-Control-Allow-Headers', cfg.allowedHeaders.join(', '))
+
+  if (cfg.maxAge > 0)
+    headers.set('Access-Control-Max-Age', String(cfg.maxAge))
+
+  // 204 No Content is the canonical preflight response — it's what
+  // express/cors, fastify-cors, and Hono all emit.
+  return new Response(null, { status: 204, headers })
+}
+
+/**
+ * Apply CORS headers to a non-preflight response. Mutates a clone of the
+ * original (Headers may be immutable on some Response shapes) and returns
+ * the new instance. Always sets `Vary: Origin` so caches don't serve
+ * cross-origin responses for the wrong origin.
+ *
+ * @example
+ * ```ts
+ * const response = await action.handle(req)
+ * return applyCorsHeaders(req, response)
+ * ```
+ */
+export function applyCorsHeaders(request: Request, response: Response, cfg?: ResolvedCorsConfig): Response {
+  const config = cfg ?? resolveCorsConfig()
+  const requestOrigin = request.headers.get('origin')
+  const allowOrigin = computeAllowOrigin(requestOrigin, config)
+
+  // Try to mutate in place first — fastest path. If headers are immutable
+  // (some Response implementations), fall through to the rebuild path.
+  try {
+    if (allowOrigin !== null)
+      response.headers.set('Access-Control-Allow-Origin', allowOrigin)
+    response.headers.set('Vary', appendVary(response.headers.get('Vary'), 'Origin'))
+    if (config.credentials)
+      response.headers.set('Access-Control-Allow-Credentials', 'true')
+    if (config.exposedHeaders.length > 0)
+      response.headers.set('Access-Control-Expose-Headers', config.exposedHeaders.join(', '))
+    return response
+  }
+  catch {
+    // Fall through: response headers are immutable — rebuild.
+  }
+
+  const newHeaders = new Headers(response.headers)
+  if (allowOrigin !== null)
+    newHeaders.set('Access-Control-Allow-Origin', allowOrigin)
+  newHeaders.set('Vary', appendVary(newHeaders.get('Vary'), 'Origin'))
+  if (config.credentials)
+    newHeaders.set('Access-Control-Allow-Credentials', 'true')
+  if (config.exposedHeaders.length > 0)
+    newHeaders.set('Access-Control-Expose-Headers', config.exposedHeaders.join(', '))
+
+  return new Response(response.body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers: newHeaders,
+  })
+}
+
+/**
+ * Public re-export for the router to consume without re-deriving config.
+ *
+ * @example
+ * ```ts
+ * const cfg = getResolvedCorsConfig()
+ * ```
+ */
+export function getResolvedCorsConfig(): ResolvedCorsConfig {
+  return resolveCorsConfig()
+}
+
+export default new Middleware({
+  name: 'cors',
+  // CORS gating must run before auth/throttle so a 401/429 response still
+  // carries the right CORS headers (otherwise the browser hides the body
+  // from the SPA and the user sees a confusing "CORS error" instead of the
+  // actual auth failure).
+  priority: 0,
+
+  async handle(request) {
+    const cfg = resolveCorsConfig()
+
+    // Preflight short-circuit — throwing a Response is the documented way
+    // to halt the chain and return immediately. The router catches it and
+    // sends it as-is.
+    if (request.method === 'OPTIONS') {
+      // Only treat as preflight if the spec-required header is present.
+      // A bare OPTIONS without `Access-Control-Request-Method` may be a
+      // server-status probe or method-discovery request — let the action
+      // handle it.
+      if (request.headers.get('access-control-request-method')) {
+        // eslint-disable-next-line no-throw-literal
+        throw buildPreflightResponse(request as unknown as Request, cfg)
+      }
+    }
+
+    // Mark the request so the router's response-finalization step picks
+    // up the CORS config. We stash the resolved config to avoid resolving
+    // it twice per request.
+    // eslint-disable-next-line ts/no-explicit-any
+    ;request._corsConfig = cfg
+  },
+})

package/app/Middleware/Csrf.ts

@@ -0,0 +1,224 @@
+import { randomBytes, timingSafeEqual } from 'node:crypto'
+import { Buffer } from 'node:buffer'
+import { HttpError } from '@stacksjs/error-handling'
+import { Middleware } from '@stacksjs/router'
+
+/**
+ * CSRF Protection Middleware (default-on for unsafe methods)
+ *
+ * Design decision: enforce by default.
+ *  Historical Stacks ran the CSRF middleware as opt-in, which left every
+ *  POST/PUT/PATCH/DELETE route undefended unless an author remembered to
+ *  add `.middleware('csrf')`. Forgetting is a security regression by
+ *  default — flipping the polarity (default-on, explicit opt-out) is the
+ *  modern Rails/Laravel posture.
+ *
+ * Pattern: stateless double-submit cookie.
+ *   1. Server issues a 32-byte random token in a non-HttpOnly cookie
+ *      (`X-CSRF-Token`) on safe (GET/HEAD/OPTIONS) responses.
+ *   2. Client-side JS reads that cookie and echoes it back on unsafe
+ *      requests via the `X-CSRF-Token` header (or a `_token` body field
+ *      for traditional form submissions).
+ *   3. Server compares header/body value to cookie value with a
+ *      timing-safe equality check.
+ *
+ * Why double-submit (and not server-stored tokens):
+ *   - Stateless. No session/cache lookup on the hot path — just a
+ *     constant-time string compare.
+ *   - Same origin policy means a cross-site attacker can't read the
+ *     cookie value, so they can't forge the matching header.
+ *   - Cookie is `SameSite=Lax`, so most cross-site contexts won't even
+ *     ship it; the double-submit check is a belt-and-braces layer for
+ *     the gaps SameSite leaves (e.g. top-level GET → POST chains via
+ *     forms).
+ *
+ * Bypass (in priority order):
+ *   1. Safe methods (GET/HEAD/OPTIONS) — no body to forge, no check.
+ *   2. `Authorization: Bearer …` present — API token clients are
+ *      immune by definition (a CSRF attacker can't read tokens from
+ *      Authorization headers, only forge cookie-auth requests).
+ *   3. Per-action `skipCsrf: true` — webhooks/callbacks that legitimately
+ *      can't carry a CSRF cookie. The action sets this on its default
+ *      export and the router's CSRF check skips it.
+ *   4. Per-route `.skipCsrf()` — same intent, route-level.
+ *
+ * @example
+ * ```ts
+ * // Implicit — every POST is CSRF-checked
+ * route.post('/posts', 'Actions/CreatePost')
+ *
+ * // Explicit opt-out for a webhook
+ * route.post('/webhooks/stripe', 'Actions/StripeWebhook').skipCsrf()
+ *
+ * // Or via the action itself
+ * export default {
+ *   skipCsrf: true,
+ *   async handle(req) { … },
+ * }
+ * ```
+ */
+
+export const CSRF_COOKIE_NAME = 'X-CSRF-Token'
+const CSRF_HEADER_NAME = 'x-csrf-token'
+const TOKEN_BYTES = 32
+
+/**
+ * Generate a fresh CSRF token (hex-encoded, 32 random bytes → 64 chars).
+ *
+ * @example
+ * ```ts
+ * const token = generateCsrfToken()
+ * // → 'a3f1...cd9e'
+ * ```
+ */
+export function generateCsrfToken(): string {
+  return randomBytes(TOKEN_BYTES).toString('hex')
+}
+
+/**
+ * Seed the CSRF cookie on the outgoing response if the incoming request
+ * didn't already carry one. Used by the router as a post-response step
+ * on safe-method (GET/HEAD/OPTIONS) responses so SPAs get a usable
+ * cookie value before they ever submit an unsafe request.
+ *
+ * The audit (stacksjs/stacks#1859 INVESTIGATE → confirmed) found that
+ * the CSRF middleware was reading the cookie but nothing was ever
+ * writing it — every browser POST without a Bearer token therefore
+ * failed CSRF by default. This helper closes that gap.
+ *
+ * The cookie is:
+ * - `SameSite=Lax` (sufficient for cross-site CSRF mitigation while
+ *   still allowing top-level navigation to set it)
+ * - **NOT** `HttpOnly` (SPA JS needs to read the value and echo it as
+ *   a header — the whole point of the double-submit pattern)
+ * - `Secure` only over HTTPS (so localhost dev still works)
+ * - 2-hour `Max-Age` — short enough to limit replay if leaked, long
+ *   enough that idle tabs don't constantly re-fetch tokens
+ */
+export function seedCsrfCookieIfMissing(req: Request, response: Response): Response {
+  const cookieHeader = req.headers.get('cookie') || ''
+  if (cookieHeader.includes(`${CSRF_COOKIE_NAME}=`) || cookieHeader.includes('csrf-token=')) {
+    return response
+  }
+
+  const token = generateCsrfToken()
+  const isSecure = req.url.startsWith('https://')
+  const cookie = [
+    `${CSRF_COOKIE_NAME}=${token}`,
+    'Path=/',
+    'SameSite=Lax',
+    'Max-Age=7200',
+    isSecure ? 'Secure' : null,
+  ].filter(Boolean).join('; ')
+
+  // Append (not Set) so multiple Set-Cookie headers can coexist with any
+  // cookies the action handler set itself.
+  try {
+    response.headers.append('Set-Cookie', cookie)
+    return response
+  }
+  catch {
+    // Response headers can be immutable (e.g., when the response was
+    // built from a static asset). Clone with a fresh Headers object
+    // to attach the cookie.
+    const headers = new Headers(response.headers)
+    headers.append('Set-Cookie', cookie)
+    return new Response(response.body, { status: response.status, statusText: response.statusText, headers })
+  }
+}
+
+/**
+ * Parse the Cookie header into a key→value map.
+ * Lenient: malformed pairs are skipped, not thrown.
+ */
+function parseCookies(req: Request): Record<string, string> {
+  const header = req.headers.get('cookie')
+  if (!header) return {}
+  const out: Record<string, string> = {}
+  for (const part of header.split(';')) {
+    const idx = part.indexOf('=')
+    if (idx === -1) continue
+    const k = part.slice(0, idx).trim()
+    const v = part.slice(idx + 1).trim()
+    if (k) out[k] = v
+  }
+  return out
+}
+
+/**
+ * Constant-time string compare. `===` leaks token length & match-prefix
+ * length via timing — `timingSafeEqual` does not.
+ */
+function safeEqual(a: string, b: string): boolean {
+  if (typeof a !== 'string' || typeof b !== 'string') return false
+  if (a.length !== b.length) return false
+  try {
+    return timingSafeEqual(Buffer.from(a), Buffer.from(b))
+  }
+  catch {
+    return false
+  }
+}
+
+/**
+ * Returns true when the request carries a `Authorization: Bearer …`
+ * credential — those clients are exempt from CSRF (they're not riding
+ * an ambient cookie credential, so cross-site forgery doesn't apply).
+ */
+function hasBearerToken(req: Request): boolean {
+  const auth = req.headers.get('authorization') || req.headers.get('Authorization')
+  return typeof auth === 'string' && auth.toLowerCase().startsWith('bearer ')
+}
+
+const SAFE_METHODS = new Set(['GET', 'HEAD', 'OPTIONS'])
+
+export default new Middleware({
+  name: 'csrf',
+  // Run early — before auth, so we don't waste auth work on a request
+  // we're going to reject anyway. After maintenance/throttle though.
+  priority: 2,
+
+  async handle(request) {
+    const method = request.method.toUpperCase()
+
+    // Safe methods don't mutate state — no token check needed.
+    // Token *seeding* (set the cookie if it's missing) happens after
+    // the response is built; we don't have a post-response hook
+    // here, so action handlers / SPAs can call `generateCsrfToken()`
+    // themselves on the first GET they need it for.
+    if (SAFE_METHODS.has(method)) return
+
+    // API clients with a bearer token are exempt — see header docstring.
+    if (hasBearerToken(request)) return
+
+    // Per-action opt-out: an action exporting `skipCsrf: true` (or
+    // `csrf: false`) has declared it can't participate in CSRF
+    // (webhooks, third-party callbacks). The router stamps a hint on
+    // the request when it resolves such an action; if that hint is
+    // present, skip enforcement.
+    if (request._skipCsrf === true) return
+
+    // Look up the submitted token. Header is the SPA path; body field
+    // is the traditional form-post path. We accept either.
+    const headerToken = request.headers.get(CSRF_HEADER_NAME)
+      || request.headers.get('X-CSRF-Token')
+      || request.headers.get('X-Csrf-Token')
+    const body = request.jsonBody || request.formBody || {}
+    const bodyToken: string | undefined = body?._token ?? body?.csrf_token
+
+    const submitted = (typeof headerToken === 'string' && headerToken)
+      || (typeof bodyToken === 'string' && bodyToken)
+      || ''
+
+    const cookies = parseCookies(request)
+    const cookieToken = cookies[CSRF_COOKIE_NAME] || cookies['csrf-token'] || ''
+
+    if (!submitted || !cookieToken || !safeEqual(submitted, cookieToken)) {
+      // 419 is the convention Laravel popularized for "CSRF token
+      // mismatch" — it's not in the IANA list but most SPAs already
+      // know how to refresh on 419. We use 403 for the strict-correct
+      // status code instead (419 is non-standard).
+      throw new HttpError(403, 'CSRF token mismatch')
+    }
+  },
+})

package/app/Middleware/EnsureEmailIsVerified.ts

@@ -0,0 +1,28 @@
+import { HttpError } from '@stacksjs/error-handling'
+import { Middleware } from '@stacksjs/router'
+
+/**
+ * Ensure Email Is Verified Middleware
+ *
+ * Checks that the authenticated user has a verified email address.
+ * Must be used after the 'auth' middleware.
+ *
+ * Usage:
+ * route.get('/dashboard', 'DashboardAction').middleware('auth').middleware('verified')
+ */
+export default new Middleware({
+  name: 'verified',
+  priority: 4,
+
+  async handle(request) {
+    const user = request.user || request._user || null
+
+    if (!user) {
+      throw new HttpError(401, 'Unauthenticated.')
+    }
+
+    if (!user.email_verified_at) {
+      throw new HttpError(403, 'Your email address is not verified.')
+    }
+  },
+})

package/app/Middleware/Env.ts

@@ -0,0 +1,24 @@
+import { config } from '@stacksjs/config'
+import { HttpError } from '@stacksjs/error-handling'
+import { Middleware } from '@stacksjs/router'
+
+export default new Middleware({
+  name: 'Env',
+  priority: 1,
+  async handle() {
+    // Get the current environment from config
+    const currentEnv = config.app.env || 'local'
+
+    // For now, we'll create separate middleware for each environment
+    // This can be extended later to support parameters
+    const allowedEnvs = ['local', 'dev', 'development', 'staging', 'prod', 'production']
+
+    // Check if current environment is in allowed environments
+    if (!allowedEnvs.includes(currentEnv)) {
+      throw new HttpError(
+        403,
+        `Access denied. This route is only available in specific environments. Current environment: ${currentEnv}`,
+      )
+    }
+  },
+})

package/app/Middleware/EnvDevelopment.ts

@@ -0,0 +1,19 @@
+import { config } from '@stacksjs/config'
+import { HttpError } from '@stacksjs/error-handling'
+import { Middleware } from '@stacksjs/router'
+
+export default new Middleware({
+  name: 'EnvDevelopment',
+  priority: 1,
+  async handle() {
+    const currentEnv = config.app.env || 'local'
+
+    // Only allow access in development environment
+    if (currentEnv !== 'development' && currentEnv !== 'dev') {
+      throw new HttpError(
+        403,
+        `Access denied. This route is only available in development environment. Current environment: ${currentEnv}`,
+      )
+    }
+  },
+})

package/app/Middleware/EnvLocal.ts

@@ -0,0 +1,19 @@
+import { config } from '@stacksjs/config'
+import { HttpError } from '@stacksjs/error-handling'
+import { Middleware } from '@stacksjs/router'
+
+export default new Middleware({
+  name: 'EnvLocal',
+  priority: 1,
+  async handle() {
+    const currentEnv = config.app.env || 'local'
+
+    // Only allow access in local environment
+    if (currentEnv !== 'local') {
+      throw new HttpError(
+        403,
+        `Access denied. This route is only available in local environment. Current environment: ${currentEnv}`,
+      )
+    }
+  },
+})

package/app/Middleware/EnvNotDevelopment.ts

@@ -0,0 +1,19 @@
+import { config } from '@stacksjs/config'
+import { HttpError } from '@stacksjs/error-handling'
+import { Middleware } from '@stacksjs/router'
+
+export default new Middleware({
+  name: 'EnvNotDevelopment',
+  priority: 1,
+  async handle() {
+    const currentEnv = config.app.env || 'local'
+
+    // Block access in development environment (allow all others)
+    if (currentEnv === 'development' || currentEnv === 'dev') {
+      throw new HttpError(
+        403,
+        `Access denied. This route is not available in development environment. Current environment: ${currentEnv}`,
+      )
+    }
+  },
+})

package/app/Middleware/EnvNotLocal.ts

@@ -0,0 +1,19 @@
+import { config } from '@stacksjs/config'
+import { HttpError } from '@stacksjs/error-handling'
+import { Middleware } from '@stacksjs/router'
+
+export default new Middleware({
+  name: 'EnvNotLocal',
+  priority: 1,
+  async handle() {
+    const currentEnv = config.app.env || 'local'
+
+    // Block access in local environment (allow all others)
+    if (currentEnv === 'local') {
+      throw new HttpError(
+        403,
+        `Access denied. This route is not available in local environment. Current environment: ${currentEnv}`,
+      )
+    }
+  },
+})