@stacksjs/defaults 0.70.58 → 0.70.59

package/app/Middleware/EnvNotProduction.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: 'EnvNotProduction',
+  priority: 1,
+  async handle() {
+    const currentEnv = config.app.env || 'local'
+
+    // Block access in production environment (allow all others)
+    if (currentEnv === 'production' || currentEnv === 'prod') {
+      throw new HttpError(
+        403,
+        `Access denied. This route is not available in production environment. Current environment: ${currentEnv}`,
+      )
+    }
+  },
+})

package/app/Middleware/EnvNotStaging.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: 'EnvNotStaging',
+  priority: 1,
+  async handle() {
+    const currentEnv = config.app.env || 'local'
+
+    // Block access in staging environment (allow all others)
+    if (currentEnv === 'staging') {
+      throw new HttpError(
+        403,
+        `Access denied. This route is not available in staging environment. Current environment: ${currentEnv}`,
+      )
+    }
+  },
+})

package/app/Middleware/EnvProduction.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: 'EnvProduction',
+  priority: 1,
+  async handle() {
+    const currentEnv = config.app.env || 'local'
+
+    // Only allow access in production environment
+    if (currentEnv !== 'production' && currentEnv !== 'prod') {
+      throw new HttpError(
+        403,
+        `Access denied. This route is only available in production environment. Current environment: ${currentEnv}`,
+      )
+    }
+  },
+})

package/app/Middleware/EnvStaging.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: 'EnvStaging',
+  priority: 1,
+  async handle() {
+    const currentEnv = config.app.env || 'local'
+
+    // Only allow access in staging environment
+    if (currentEnv !== 'staging') {
+      throw new HttpError(
+        403,
+        `Access denied. This route is only available in staging environment. Current environment: ${currentEnv}`,
+      )
+    }
+  },
+})

package/app/Middleware/Guest.ts

@@ -0,0 +1,25 @@
+import { HttpError } from '@stacksjs/error-handling'
+import { Middleware } from '@stacksjs/router'
+
+/**
+ * Guest Middleware
+ *
+ * Ensures that the request is NOT authenticated. Useful for routes
+ * that should only be accessible to unauthenticated users (e.g., login, register).
+ *
+ * Usage:
+ * route.get('/login', 'LoginAction').middleware('guest')
+ * route.post('/register', 'RegisterAction').middleware('guest')
+ */
+export default new Middleware({
+  name: 'guest',
+  priority: 1,
+
+  async handle(request) {
+    const token = request._currentAccessToken || request._authenticatedUser
+
+    if (token) {
+      throw new HttpError(403, 'You are already authenticated.')
+    }
+  },
+})

package/app/Middleware/Logger.ts

@@ -0,0 +1,20 @@
+import { log } from '@stacksjs/cli'
+import { Middleware } from '@stacksjs/router'
+
+export default new Middleware({
+  name: 'Logger',
+  priority: 2,
+  async handle(request) {
+    // eslint-disable-next-line pickier/no-unused-vars
+    const start = performance.now()
+    const method = request?.method || 'UNKNOWN'
+    const url = request?.url || 'unknown'
+    const path = url ? new URL(url, 'http://localhost').pathname : 'unknown'
+
+    log.info(`→ ${method} ${path}`)
+
+    // Return undefined to continue middleware chain
+    // The response timing is logged by the after hook if available
+    return undefined
+  },
+})

package/app/Middleware/Maintenance.ts

@@ -0,0 +1,36 @@
+import { Middleware } from '@stacksjs/router'
+
+/**
+ * Maintenance / Coming-Soon Middleware
+ *
+ * Global middleware that gates every request when the application has
+ * been flipped into a protected site mode via either:
+ *
+ *   - `buddy down` / `buddy up` (maintenance mode), or
+ *   - `buddy coming-soon` / `buddy launch` (coming-soon mode), or
+ *   - the `APP_MAINTENANCE` / `APP_COMING_SOON` env vars in production.
+ *
+ * All gate logic — mode detection, secret-URL bypass, mode-aware bypass
+ * cookies, allowed IPs, always-allowed paths (the holding page itself,
+ * email subscribe, static assets) — lives in one place:
+ * `maintenanceGate()` in `@stacksjs/server`. The dev server's
+ * `onRequest` hook calls the same function, so dev and prod behave
+ * identically.
+ *
+ * Bypass methods:
+ *   1. Secret URL — visit `/your-secret` to set a bypass cookie.
+ *   2. Allowed IPs — configured with `--allow=IP` on either command.
+ *   3. Bypass cookie — automatically set when visiting the secret URL.
+ */
+export default new Middleware({
+  name: 'maintenance',
+  priority: 0, // Run first, before all other middleware
+
+  async handle(request) {
+    const { maintenanceGate } = await import('@stacksjs/server')
+
+    const gated = await maintenanceGate(request)
+    if (gated)
+      throw gated // short-circuit the request
+  },
+})

package/app/Middleware/Permission.ts

@@ -0,0 +1,42 @@
+import { HttpError } from '@stacksjs/error-handling'
+import { Middleware } from '@stacksjs/router'
+
+/**
+ * Permission Middleware
+ *
+ * Checks if the authenticated user has the required permission(s).
+ * Checks both direct permissions and permissions inherited via roles.
+ * Must be used after the 'auth' middleware.
+ *
+ * Usage:
+ * - 'permission:edit-posts' — requires the edit-posts permission
+ * - 'permission:edit-posts,delete-posts' — requires any of the listed permissions
+ *
+ * Examples:
+ * route.put('/posts/:id', 'UpdatePostAction').middleware('auth').middleware('permission:edit-posts')
+ * route.delete('/posts/:id', 'DeletePostAction').middleware('auth').middleware('permission:delete-posts')
+ */
+export default new Middleware({
+  name: 'permission',
+  priority: 3,
+
+  async handle(request) {
+    const requiredPermissions = request._middlewareParams?.permission?.split(',').map((p: string) => p.trim()) || []
+
+    if (requiredPermissions.length === 0) return
+
+    const user = request.user || request._user || null
+
+    if (!user) {
+      throw new HttpError(401, 'Unauthenticated.')
+    }
+
+    const { hasAnyPermission } = await import('@stacksjs/auth')
+
+    const hasRequired = await hasAnyPermission(user, requiredPermissions)
+
+    if (!hasRequired) {
+      throw new HttpError(403, `User does not have any of the required permissions: ${requiredPermissions.join(', ')}`)
+    }
+  },
+})

package/app/Middleware/README.md

@@ -0,0 +1,48 @@
+# What is a Middleware
+
+Middleware is a way to define logic that should be executed before or after a specific event inside the request lifecycle.
+
+## Get Started
+
+The following command will bootstrap a new middleware file in the `app/Middleware` directory.
+
+```sh
+buddy make:middleware Logger
+```
+
+### Example
+
+A simple example of a middleware that logs a message. _For a closer look, take a peak at the [Logger.ts](./Logger.ts) file._
+
+```ts
+const options: MiddlewareOtions = {
+  name: 'Logger', // optional, defaults to the file name
+  description: 'A demo listener that logs a message', // optional, used in the dashboard for context
+  priority: 2, // optional, defaults to 0
+  handle: () => {
+    log.info('Hi, from the Logger middleware 👋')
+  },
+}
+
+export default new Middleware(options)
+```
+
+## 🚜 Contributing
+
+Please review the [Contributing Guide](https://github.com/stacksjs/contributing) for details.
+
+## 🏝 Community
+
+For help, discussion about best practices, or any other conversation that would benefit from being searchable:
+
+[Discussions on GitHub](https://github.com/stacksjs/stacks/discussions)
+
+For casual chit-chat with others using this package:
+
+[Join the Stacks Discord Server](https://discord.gg/stacksjs)
+
+## 📄 License
+
+The MIT License (MIT). Please see [LICENSE](../../LICENSE.md) for more information.
+
+Made with 💙

package/app/Middleware/Role.ts

@@ -0,0 +1,42 @@
+import { HttpError } from '@stacksjs/error-handling'
+import { Middleware } from '@stacksjs/router'
+
+/**
+ * Role Middleware
+ *
+ * Checks if the authenticated user has the required role(s).
+ * Must be used after the 'auth' middleware.
+ *
+ * Usage:
+ * - 'role:admin' — requires the admin role
+ * - 'role:admin,editor' — requires any of the listed roles
+ *
+ * Examples:
+ * route.get('/admin', 'AdminAction').middleware('auth').middleware('role:admin')
+ * route.get('/content', 'ContentAction').middleware('auth').middleware('role:admin,editor')
+ */
+export default new Middleware({
+  name: 'role',
+  priority: 3,
+
+  async handle(request) {
+    const requiredRoles = request._middlewareParams?.role?.split(',').map((r: string) => r.trim()) || []
+
+    if (requiredRoles.length === 0) return
+
+    const user = request.user || request._user || null
+
+    if (!user) {
+      throw new HttpError(401, 'Unauthenticated.')
+    }
+
+    // Dynamically import to avoid circular dependency
+    const { hasAnyRole } = await import('@stacksjs/auth')
+
+    const hasRequired = await hasAnyRole(user, requiredRoles)
+
+    if (!hasRequired) {
+      throw new HttpError(403, `User does not have any of the required roles: ${requiredRoles.join(', ')}`)
+    }
+  },
+})

package/app/Middleware/Signed.ts

@@ -0,0 +1,31 @@
+import { Middleware, verifySignedUrl } from '@stacksjs/router'
+
+/**
+ * Signed-URL verification middleware (stacksjs/stacks#1870 R-7).
+ *
+ * Verifies the HMAC `signature` (and optional `expires`) on the request
+ * URL using the same `APP_KEY` / `STACKS_SIGNED_URL_SECRET` the
+ * `signedUrl(...)` builder signs with. Drop in as `.middleware('signed')`
+ * on any route minted by `signedUrl(...)`.
+ *
+ * Status codes:
+ *   - `410 Gone`         — expired (link existed but is no longer valid)
+ *   - `401 Unauthorized` — missing signature or tampered URL
+ *
+ * The two cases are split so callers can distinguish "your link timed
+ * out, request a new one" from "this URL didn't come from us" in their
+ * frontend UX.
+ *
+ * Priority `5` so this runs ahead of auth (which defaults to 10) — a
+ * URL with a bad signature shouldn't get as far as the auth chain.
+ */
+export default new Middleware({
+  name: 'Signed',
+  priority: 5,
+  async handle(request) {
+    const result = verifySignedUrl(request.url)
+    if (result.valid) return
+    const status = result.reason === 'expired' ? 410 : 401
+    throw Response.json({ error: result.reason }, { status })
+  },
+})

package/app/Middleware/Team.ts

@@ -0,0 +1,36 @@
+import { HttpError } from '@stacksjs/error-handling'
+import { Middleware } from '@stacksjs/router'
+
+/**
+ * Team Middleware
+ *
+ * Ensures the authenticated user belongs to a team. Optionally checks
+ * for a specific team role via parameterized middleware.
+ *
+ * Usage:
+ * route.get('/team/dashboard', 'TeamDashboardAction').middleware('auth').middleware('team')
+ * route.get('/team/settings', 'TeamSettingsAction').middleware('auth').middleware('team:owner')
+ */
+export default new Middleware({
+  name: 'team',
+  priority: 3,
+
+  async handle(request) {
+    const user = request.user || request._user || request._authenticatedUser
+
+    if (!user) {
+      throw new HttpError(401, 'Unauthenticated.')
+    }
+
+    // Check if user belongs to any team
+    if (!user.current_team_id && !user.team_id) {
+      throw new HttpError(403, 'You must belong to a team to access this resource.')
+    }
+
+    // If a specific role is required (e.g., 'team:owner')
+    const requiredRole = request._middlewareParams?.team
+    if (requiredRole && user.team_role !== requiredRole) {
+      throw new HttpError(403, `This action requires the '${requiredRole}' team role.`)
+    }
+  },
+})

package/app/Middleware/Throttle.ts

@@ -0,0 +1,96 @@
+import { createRateLimitMiddleware, Middleware, parseThrottleString } from '@stacksjs/router'
+
+// Cache for rate limiters to avoid creating new instances for each request
+const limiterCache = new Map<string, ReturnType<typeof createRateLimitMiddleware>>()
+
+/**
+ * Throttle Middleware
+ *
+ * Rate limits requests based on IP address or authenticated user.
+ * Uses Laravel-style throttle patterns.
+ *
+ * Usage:
+ *   .middleware('throttle:60,1')     // 60 requests per 1 minute
+ *   .middleware('throttle:100,5')    // 100 requests per 5 minutes
+ *   .middleware('throttle:1000,1h')  // 1000 requests per hour
+ *   .middleware('throttle:10,30s')   // 10 requests per 30 seconds
+ *
+ * Pattern formats:
+ *   - 'maxAttempts' - e.g., '60' (60 per minute, default window)
+ *   - 'maxAttempts,minutes' - e.g., '60,1' (60 per 1 minute)
+ *   - 'maxAttempts,Ns' - e.g., '10,30s' (10 per 30 seconds)
+ *   - 'maxAttempts,Nm' - e.g., '100,5m' (100 per 5 minutes)
+ *   - 'maxAttempts,Nh' - e.g., '1000,1h' (1000 per 1 hour)
+ *
+ * Response (429 Too Many Requests):
+ * {
+ *   "success": false,
+ *   "message": "Too many requests. Please try again in X seconds.",
+ *   "retryAfter": X
+ * }
+ *
+ * Headers added to all responses:
+ *   - X-RateLimit-Limit: Maximum requests allowed
+ *   - X-RateLimit-Remaining: Remaining requests in current window
+ *   - X-RateLimit-Reset: Unix timestamp when the limit resets
+ *   - Retry-After: Seconds until limit resets (only on 429)
+ */
+export default new Middleware({
+  name: 'throttle',
+  priority: 1, // Run early, after maintenance but before auth
+
+  async handle(request) {
+    // Get throttle params from middleware params (e.g., '60,1' from 'throttle:60,1')
+    const params = request._middlewareParams?.throttle || '60,1'
+
+    // Get or create rate limiter for this pattern
+    let limiter = limiterCache.get(params)
+    if (!limiter) {
+      try {
+        const config = parseThrottleString(params)
+        limiter = createRateLimitMiddleware(config, `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, 'throttle:default')
+        limiterCache.set(params, limiter)
+      }
+    }
+
+    // Create a next function that continues the request
+    // The middleware will handle rate limiting and return 429 if needed
+    const result = await limiter(request as any, async () => null)
+
+    // If result is a Response (429), throw it to short-circuit the request
+    if (result instanceof Response) {
+      // Transform the response to match stacks format
+      const _body = await result.clone().json().catch(() => ({}))
+      const retryAfter = result.headers.get('Retry-After') || '60'
+
+      throw new Response(JSON.stringify({
+        success: false,
+        message: `Too many requests. Please try again in ${retryAfter} seconds.`,
+        retryAfter: Number.parseInt(retryAfter, 10),
+      }), {
+        status: 429,
+        headers: {
+          'Content-Type': 'application/json',
+          'X-RateLimit-Limit': result.headers.get('X-RateLimit-Limit') || '',
+          'X-RateLimit-Remaining': result.headers.get('X-RateLimit-Remaining') || '0',
+          'X-RateLimit-Reset': result.headers.get('X-RateLimit-Reset') || '',
+          'Retry-After': retryAfter,
+          // CORS headers (if any) are applied by the router's post-response
+          // CORS wrapper using the configured policy — hardcoding
+          // `Access-Control-Allow-Origin: *` here leaked the rate-limit
+          // body cross-origin even when the configured policy was
+          // restrictive. See stacksjs/stacks#1859 R-3.
+        },
+      })
+    }
+
+    // Continue normally - rate limit not exceeded
+  },
+})

package/app/Middleware.ts

@@ -0,0 +1,35 @@
+export interface Middleware {
+  [key: string]: string
+}
+
+/**
+ * The application's middleware aliases.
+ *
+ * Aliases may be used instead of class names to conveniently assign middleware to routes and groups.
+ */
+export default {
+  'maintenance': 'Maintenance',
+  'cors': 'Cors',
+  'auth': 'Auth',
+  'guest': 'Guest',
+  'api': 'Api',
+  'team': 'Team',
+  'logger': 'Logger',
+  'abilities': 'Abilities',
+  'can': 'Can',
+  'throttle': 'Throttle',
+  'env': 'Env',
+  'env:local': 'EnvLocal',
+  'env:development': 'EnvDevelopment',
+  'env:dev': 'EnvDevelopment',
+  'env:staging': 'EnvStaging',
+  'env:production': 'EnvProduction',
+  'env:prod': 'EnvProduction',
+  'role': 'Role',
+  'permission': 'Permission',
+  'verified': 'EnsureEmailIsVerified',
+  'csrf': 'Csrf',
+  'compress': 'Compress',
+  // Add more middleware aliases here
+  // Note: Use ! prefix for negation (e.g., '!auth', '!env:development')
+} satisfies Middleware

package/app/Models/Activity.ts

@@ -0,0 +1,94 @@
+import { defineModel } from '@stacksjs/orm'
+import { schema } from '@stacksjs/validation'
+
+export default defineModel({
+  name: 'Activity',
+  table: 'activities',
+  primaryKey: 'id',
+  autoIncrement: true,
+
+  traits: {
+    useUuid: true,
+    useTimestamps: true,
+    useSeeder: {
+      count: 50,
+    },
+    useApi: {
+      uri: 'activities',
+      routes: ['index', 'show'],
+    },
+  },
+
+  belongsTo: ['User'],
+
+  attributes: {
+    type: {
+      required: true,
+      fillable: true,
+      validation: {
+        rule: schema.string().max(50),
+      },
+      factory: faker => faker.helpers.arrayElement([
+        'user.created', 'user.updated', 'user.deleted',
+        'order.created', 'order.completed', 'order.cancelled',
+        'product.created', 'product.updated', 'product.deleted',
+        'post.published', 'comment.approved', 'login.success',
+        'login.failed', 'subscription.renewed', 'payment.received',
+      ]),
+    },
+
+    description: {
+      required: true,
+      fillable: true,
+      validation: {
+        rule: schema.string().max(500),
+      },
+      factory: faker => faker.lorem.sentence(),
+    },
+
+    subjectType: {
+      required: false,
+      fillable: true,
+      validation: {
+        rule: schema.string().max(100),
+      },
+      factory: faker => faker.helpers.arrayElement(['User', 'Order', 'Product', 'Post', 'Comment', 'Subscription']),
+    },
+
+    subjectId: {
+      required: false,
+      fillable: true,
+      validation: {
+        rule: schema.number(),
+      },
+      factory: faker => faker.number.int({ min: 1, max: 100 }),
+    },
+
+    causer: {
+      required: false,
+      fillable: true,
+      validation: {
+        rule: schema.string().max(100),
+      },
+      factory: faker => faker.person.fullName(),
+    },
+
+    properties: {
+      required: false,
+      fillable: true,
+      validation: {
+        rule: schema.string(),
+      },
+      factory: () => JSON.stringify({ ip: '192.168.1.1', browser: 'Chrome' }),
+    },
+
+    ipAddress: {
+      required: false,
+      fillable: true,
+      validation: {
+        rule: schema.string().max(45),
+      },
+      factory: faker => faker.internet.ip(),
+    },
+  },
+} as const)