@stacksjs/router 0.70.44 → 0.70.53

package/dist/middleware.d.ts

@@ -33,4 +33,5 @@ export declare class Middleware {
   readonly priority: number;
   readonly handle: (request: EnhancedRequest) => void | Promise<void>;
   constructor(config: MiddlewareConfig);
+  toRouterHandler(): (req: EnhancedRequest, next: () => Promise<Response>) => Promise<Response>;
 }

package/dist/path-sanitize.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Validate and return a path parameter, throwing if it's unsafe to use
+ * in filesystem interpolation.
+ *
+ * The default contract is single-segment: no `/`, no `\`, no `..`, no
+ * absolute path, no null bytes, no control characters, length ≤ 255.
+ * Pass `allowSlashes: true` for a multi-segment path (still rejects
+ * the rest).
+ *
+ * @throws {PathParamError} when the value fails any check.
+ */
+export declare function sanitizePathParam(value: unknown, options?: SanitizePathParamOptions): string;
+/**
+ * Non-throwing variant. Returns the sanitized value or `null` if any
+ * check failed. Use when you want a fast yes/no in a conditional
+ * without a try/catch around the throw site.
+ */
+export declare function safePathParam(value: unknown, options?: SanitizePathParamOptions): string | null;
+export declare interface SanitizePathParamOptions {
+  context?: string
+  maxLength?: number
+  allowSlashes?: boolean
+}
+/**
+ * Path-parameter sanitization helpers.
+ *
+ * Route params arrive from the URL as untyped strings and are merged
+ * directly into `req.params`. Actions that interpolate those values
+ * into filesystem paths or shell commands without first scrubbing
+ * them are vulnerable to `..`-traversal, absolute-path takeovers, and
+ * null-byte truncation attacks.
+ *
+ * The router itself can't auto-sanitize every param (some are
+ * deliberately path-shaped — file servers, asset proxies, etc.). What
+ * we ship instead is a single canonical helper that callers reach for
+ * at the boundary where the param meets the filesystem.
+ *
+ * See stacksjs/stacks#1870 R-12.
+ *
+ * @example
+ * ```ts
+ * import { sanitizePathParam } from '@stacksjs/router'
+ *
+ * const filename = sanitizePathParam(req.params.filename, {
+ *   context: 'avatar download',
+ * })
+ * return new Response(Bun.file(path.appPath(`avatars/${filename}`)))
+ * ```
+ */
+/**
+ * Reasons {@link sanitizePathParam} rejects a value. Surfaced via the
+ * thrown error so callers can log or branch.
+ */
+export type PathParamRejection = | 'empty'
+  | 'not-string'
+  | 'absolute-path'
+  | 'traversal'
+  | 'null-byte'
+  | 'control-char'
+  | 'too-long';
+export declare class PathParamError extends Error {
+  readonly reason: PathParamRejection;
+  constructor(reason: PathParamRejection, value: unknown, context?: string);
+}

package/dist/request-augmentation.d.ts

@@ -0,0 +1,67 @@
+import type { FileInfo } from '@stacksjs/bun-router';
+/**
+ * Stacks-specific marker fields attached to the request by the
+ * router itself and the framework's default middleware.
+ *
+ * Markers are deliberately prefixed with `_` so they can't collide
+ * with userland keys on the request, and their lifetimes are bounded
+ * by the request's lifetime — they're never persisted.
+ */
+export declare interface StacksRequestMarkers {
+  _corsConfig?: unknown
+  _forceJson?: boolean
+  _skipCsrf?: boolean
+  _compress?: boolean
+  _middlewareParams?: Record<string, string>
+  _requestId?: string
+  _startNs?: bigint
+  _authenticatedUser?: unknown
+  _currentAccessToken?: unknown
+  _bodyParsed?: boolean
+}
+/**
+ * Laravel-style request-input macros that Stacks attaches in
+ * `enhanceRequest` (router/src/stacks-router.ts). These shadow some
+ * of bun-router's `RequestMacroMethods` with Stacks-specific
+ * implementations (more permissive `T = any` generics so action
+ * callers don't have to specify the return type for every read).
+ *
+ * Listed here as part of the augmentation so call sites like
+ * `request.input(key)` type-check without `as any`.
+ */
+export declare interface StacksRequestMacros {
+  input?: <T = unknown>(key: string, defaultValue?: T) => T
+  get?: <T = unknown>(key: string, defaultValue?: T) => T
+  all?: () => Record<string, unknown>
+  only?: <T extends Record<string, unknown>>(keys: string[]) => T
+  except?: <T extends Record<string, unknown>>(keys: string[]) => T
+  has?: (key: string | string[]) => boolean
+  hasAny?: (keys: string[]) => boolean
+  missing?: (key: string) => boolean
+  filled?: (key: string) => boolean
+  integer?: (key: string, defaultValue?: number) => number
+  float?: (key: string, defaultValue?: number) => number
+  boolean?: (key: string, defaultValue?: boolean) => boolean
+  string?: (key: string, defaultValue?: string) => string
+  array?: <T = unknown>(key: string, defaultValue?: T[]) => T[]
+  file?: (key: string) => FileInfo | null
+  files?: (key: string) => FileInfo[]
+  hasFile?: (key: string) => boolean
+  allFiles?: () => Record<string, FileInfo | FileInfo[]>
+  getFiles?: () => Record<string, FileInfo | FileInfo[]>
+  user?: () => Promise<unknown>
+  userToken?: () => Promise<unknown>
+  tokenCan?: (ability: string) => Promise<boolean>
+  tokenCant?: (ability: string) => Promise<boolean>
+  can?: (ability: string, ...args: unknown[]) => Promise<boolean>
+  cannot?: (ability: string, ...args: unknown[]) => Promise<boolean>
+  authorize?: (ability: string, ...args: unknown[]) => Promise<void>
+}
+/**
+ * Union of Stacks markers + macros — useful as a single type alias for
+ * places that previously cast to `any`.
+ */
+export type StacksRequestExtensions = StacksRequestMarkers & StacksRequestMacros;
+declare module '@stacksjs/bun-router' {
+  interface EnhancedRequestextends StacksRequestExtensions  {}
+}

package/dist/request-context.d.ts

@@ -1,4 +1,5 @@
 import type { EnhancedRequest } from '@stacksjs/bun-router';
+import type { RequestInstance } from '@stacksjs/types';
 /**
  * Read the active trace id, or `undefined` outside any traced scope.
  *
@@ -36,6 +37,16 @@ export declare function cacheRequestQuery<T>(key: string, fetcher: () => T | Pro
  * Called by middleware/router when handling a request
  */
 export declare function setCurrentRequest(req: EnhancedRequest): void;
+/**
+ * Clear the current request context.
+ *
+ * `setCurrentRequest` uses `AsyncLocalStorage.enterWith`, which mutates the
+ * caller's async scope and never restores it. Call this in test teardown
+ * (`afterEach`) whenever a test body calls `setCurrentRequest`, so the leaked
+ * frame doesn't poison subsequently-collected test files (bun's runner
+ * mis-registers tests when collected on a foreign async frame).
+ */
+export declare function clearCurrentRequest(): void;
 /**
  * Run a function with a request context
  * All code executed within the callback will have access to the request
@@ -47,13 +58,25 @@ export declare function runWithRequest<T>(req: EnhancedRequest, fn: () => T): T;
 export declare function getCurrentRequest(): EnhancedRequest | undefined;
 /**
  * Request proxy that provides access to the current request
- * Similar to Laravel's request() helper
+ * (Laravel's `request()` helper, but typed).
  *
- * Methods:
- * - bearerToken() - Get the bearer token from Authorization header
- * - user() - Get the authenticated user (async)
- * - userToken() - Get the current access token (async)
- * - tokenCan(ability) - Check if token has an ability (async)
- * - tokenCant(ability) - Check if token doesn't have an ability (async)
- */
-export declare const request: Proxy;
+ * The proxy is statically typed as {@link RequestInstance} —
+ * the canonical Stacks-side action-request surface
+ * (stacksjs/stacks#1851 Phase 1). All the macros action handlers
+ * reach for (`all`, `get`, `input`, `cookies`, `param`, `validate`,
+ * `user`, `bearerToken`, …) resolve to their declared types instead
+ * of `any`, eliminating most `(request as any)` casts in action code.
+ *
+ * Runtime is unchanged — the proxy still delegates to whichever
+ * `EnhancedRequest` is in the AsyncLocalStorage slot. The type swap
+ * is API-compatible: every method action code uses on `request`
+ * existed on either type already, but only `RequestInstance` carries
+ * the model-aware / path-aware narrowing.
+ *
+ * Methods worth knowing about:
+ * - `bearerToken()` — Authorization header
+ * - `user()` — authenticated user (async)
+ * - `userToken()` — current access token (async)
+ * - `tokenCan(ability)` / `tokenCant(ability)` — async ability checks
+ */
+export declare const request: RequestInstance;

package/dist/route-loader.d.ts

@@ -1,4 +1,4 @@
-import type { RouteRegistry } from '../../../../../app/Routes';
+import type { RouteRegistry } from './route-types';
 /**
  * Load all routes from the registry
  */

package/dist/route-types.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Route registry types — owned by `@stacksjs/router` because the router
+ * consumes them. `app/Routes.ts` (the project-level route map) imports
+ * these via the public package name rather than a relative reach into
+ * the framework defaults tree (stacksjs/stacks#1863, T-10).
+ */
+export declare interface RouteDefinition {
+  path: string
+  prefix?: string
+  middleware?: string | string[]
+}
+export type RouteRegistry = Record<string, string | RouteDefinition>;

package/dist/security-headers.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Apply the default security headers to a Headers instance in-place.
+ *
+ * Headers applied unconditionally (cheap, no compat risk):
+ * - `X-Content-Type-Options: nosniff` — blocks MIME-sniff XSS
+ * - `X-Frame-Options: SAMEORIGIN` — clickjacking protection (CSP
+ *   `frame-ancestors` is the modern equivalent but XFO still ships)
+ * - `Referrer-Policy: strict-origin-when-cross-origin` — modern default
+ *
+ * Production-only:
+ * - `Strict-Transport-Security: max-age=31536000; includeSubDomains` —
+ *   tells browsers to commit to HTTPS for a year. Omits `preload` since
+ *   that's an irreversible commitment to the browser preload list.
+ *
+ * Skips overwriting any header that's already set — explicit userland
+ * config wins. Skips entirely when `STACKS_SECURITY_HEADERS_DISABLE=true`.
+ */
+export declare function applySecurityHeaders(headers: Headers): void;
+/** Test helper — reset the cached env-derived flags. */
+export declare function __resetSecurityHeadersCache(): void;

package/dist/session-factory.d.ts

@@ -0,0 +1,57 @@
+import { createSessionStore } from '@stacksjs/bun-router';
+import type { RedisClient, SessionConfig, SessionData, SessionStore } from '@stacksjs/bun-router';
+// Re-export bun-router's session types so app code only has to
+// import from `@stacksjs/router` (one less package boundary to
+// learn). Drivers stay accessible by name for callers that want
+// to assemble a custom store manually.
+export type {
+  RedisClient,
+  SessionConfig,
+  SessionData,
+  SessionStore,
+};
+/**
+ * Build a session store from the Stacks config. Mirrors what
+ * `mail` / `Jobs` do for their driver registries — call once at
+ * boot, pass the result into the session middleware.
+ *
+ * @example
+ * ```ts
+ * // config/session.ts (typical)
+ * export const session = {
+ *   driver: 'redis',
+ *   ttl: 60 * 60 * 24,         // 24h
+ *   cookie: { name: 'sid', httpOnly: true, sameSite: 'lax' },
+ *   redis: { client: useRedis() },
+ * } satisfies StacksSessionConfig
+ *
+ * // Then at boot:
+ * const store = createStacksSessionStore(session)
+ * app.use(sessionMiddleware({ store }))
+ * ```
+ */
+export declare function createStacksSessionStore(config: StacksSessionConfig): SessionStore<SessionData>;
+/**
+ * Stacks-level session configuration. Extends bun-router's
+ * {@link SessionConfig} with:
+ *
+ *   - `encrypt`: opt-in/out of {@link EncryptedSessionStore}
+ *     wrapping (default: `'auto'` — on in production, off in
+ *     dev/test where readability matters more than encryption-
+ *     at-rest)
+ *   - `appKey`: override key for the encryption (defaults to
+ *     `process.env.APP_KEY`)
+ *
+ * All other fields pass through to bun-router unchanged.
+ */
+export declare interface StacksSessionConfig extends SessionConfig {
+  encrypt?: boolean | 'auto'
+  appKey?: string
+}
+export {
+  DatabaseSessionStore,
+  FileSessionStore,
+  MemorySessionStore,
+  RedisSessionStore,
+  createSessionStore,
+} from '@stacksjs/bun-router';

package/dist/signed-url.d.ts

@@ -0,0 +1,50 @@
+import type { EnhancedRequest } from '@stacksjs/bun-router';
+/**
+ * Sign an existing URL (full or path-only). Returns a new URL string
+ * with `expires` (optional) and `signature` query params appended.
+ *
+ * Path-only inputs (`/api/email/verify?user=42`) inherit `APP_URL` as
+ * the origin — same convention as {@link buildUrl}.
+ */
+export declare function signUrl(input: string, options?: SignedUrlOptions): string;
+/**
+ * Convenience wrapper that resolves a named route to a URL via {@link buildUrl}
+ * and then signs it. Mirrors Laravel's `URL::signedRoute()`.
+ *
+ * @example
+ * ```ts
+ * route.get('/api/email/verify', VerifyEmailAction).name('email.verify')
+ * const link = signedUrl('email.verify', { user: 42 }, { ttl: 60 * 60 * 24 })
+ * // → https://app.example.com/api/email/verify?user=42&expires=1716470400&signature=…
+ * ```
+ */
+export declare function signedUrl(routeName: string, params?: Record<string, string | number>, options?: SignedUrlOptions): string;
+/**
+ * Verify the `signature` (and optional `expires`) on an incoming URL.
+ * Returns a discriminated result so callers can pick their own status
+ * code per failure mode.
+ */
+export declare function verifySignedUrl(input: string | URL): SignedUrlVerifyResult;
+/**
+ * Middleware shape for `route.middleware('signed')`. Verifies the
+ * incoming URL's signature and throws a `Response` (the router's
+ * short-circuit contract) when it fails. Drop in as a route-level
+ * middleware on any URL minted by {@link signedUrl}.
+ *
+ * @example
+ * ```ts
+ * route.get('/email/verify', 'Actions/VerifyEmail').middleware('signed')
+ * ```
+ */
+export declare function verifySignedUrlMiddleware(req: EnhancedRequest): Promise<void>;
+export declare interface SignedUrlOptions {
+  expiresAt?: number
+  ttl?: number
+}
+/**
+ * Result of {@link verifySignedUrl}. The `reason` only fires when `valid`
+ * is `false` — gives callers (and middleware) enough to decide whether
+ * to log, return 401, or return 410 (expired vs. tampered).
+ */
+export type SignedUrlVerifyResult = | { valid: true }
+  | { valid: false, reason: 'missing-signature' | 'expired' | 'invalid-signature' }

package/dist/stacks-router.d.ts

@@ -1,6 +1,8 @@
 import type { Server } from 'bun';
+import './request-augmentation';
 import { Router } from '@stacksjs/bun-router';
 import type { ActionHandler, EnhancedRequest, Route, ServerOptions } from '@stacksjs/bun-router';
+import type { ActionValidations, ValidationResult } from '@stacksjs/actions';
 /**
  * Generate a full URL for a named route, like Laravel's route() helper.
  *
@@ -54,6 +56,39 @@ export declare function clearMiddlewareCache(): void;
  * old version forever.
  */
 export declare function installMiddlewareHotReload(): () => void;
+/**
+ * Resolve every middleware alias referenced by a registered route and
+ * report the ones that don't load. `csrf` is always checked too — it's
+ * auto-injected on unsafe methods even when no route lists it.
+ *
+ * Resolution is inherently lazy (`.middleware(name)` is a sync chainable
+ * that just records a string; the alias map and middleware modules load
+ * via async dynamic import), so a throw at literal registration time is
+ * impossible. Calling this after all routes are registered — the end of
+ * `importRoutes()` and the compiled-binary boot in core/server — IS
+ * effectively registration-time validation. See stacksjs/stacks#1957.
+ */
+export declare function findUnresolvableRouteMiddleware(): Promise<Array<{ alias: string, routes: string[] }>>;
+/**
+ * Throw when any registered route references a middleware alias that
+ * cannot be resolved. Fail-closed boot validation: a typo'd `auth` alias
+ * must abort startup loudly, not serve the route unprotected (the
+ * request-time guard in createMiddlewareHandler 500s as a backstop).
+ */
+export declare function assertRouteMiddlewareResolvable(): Promise<void>;
+/**
+ * Run an action's declarative `validations:` against the request.
+ *
+ * @internal Exported for regression coverage of path-param coercion
+ * (stacksjs/stacks#1865). Production callers should rely on the
+ * router's action-resolution path, which invokes this for you.
+ */
+export declare function validateActionInput(req: EnhancedRequest, validations: ActionValidations): Promise<ValidationResult>;
+export declare function stream(source: ReadableStream | AsyncIterable<string | Uint8Array>, options?: StreamOptions): Response;
+// Decorate the incoming request with the helpers the framework's middleware
+// and actions assume are always available. Names follow Laravel's convention
+// because that's the API surface Stacks userland expects.
+export declare function enhanceRequest(req: EnhancedRequest): EnhancedRequest;
 /**
  * Create a Stacks-enhanced router
  */
@@ -74,6 +109,7 @@ declare interface StacksRouterConfig {
 declare interface GroupOptions {
   prefix?: string
   middleware?: string | string[]
+  apiResponse?: boolean
 }
 declare interface ResourceRouteOptions {
   only?: ResourceAction[]
@@ -87,6 +123,41 @@ declare interface ChainableRoute {
   middleware: (name: string) => ChainableRoute
   name: (routeName: string) => ChainableRoute
   skipCsrf: () => ChainableRoute
+  requireCsrf: () => ChainableRoute
+  rateLimit: (max: number, window: 'second' | 'minute' | 'hour' | 'day' | number) => ChainableRoute
+}
+/**
+ * Helper for streaming responses — wraps a `ReadableStream` or async
+ * generator with the right headers for the chosen content type.
+ *
+ * Common shapes:
+ *
+ *   ```ts
+ *   // Server-Sent Events
+ *   return stream(async function* () {
+ *     for await (const evt of source) yield `data: ${JSON.stringify(evt)}\n\n`
+ *   }, { type: 'sse' })
+ *
+ *   // Chunked JSON (NDJSON) — one JSON object per line
+ *   return stream(async function* () {
+ *     for await (const row of rows) yield `${JSON.stringify(row)}\n`
+ *   }, { type: 'ndjson' })
+ *
+ *   // Raw bytes — caller supplies a ReadableStream of Uint8Array chunks
+ *   return stream(myReadable, { contentType: 'application/octet-stream' })
+ *   ```
+ *
+ * The wrapper sets `Cache-Control: no-cache` and `Connection: keep-alive`
+ * for SSE — the two headers a sane proxy / browser pair won't ignore — and
+ * leaves backpressure / cancellation to the underlying stream.
+ *
+ * See stacksjs/stacks#1870 R-4.
+ */
+export declare interface StreamOptions {
+  type?: 'sse' | 'ndjson'
+  contentType?: string
+  headers?: HeadersInit
+  status?: number
 }
 export declare interface StacksRouterInstance {
   bunRouter: Router
@@ -105,9 +176,31 @@ export declare interface StacksRouterInstance {
   register: (routePath: string, options?: { prefix?: string, middleware?: string | string[] }) => Promise<StacksRouterInstance>
   serve: (options?: ServerOptions) => Promise<Server<unknown>>
   handleRequest: (req: Request) => Promise<Response>
+  getAllowedMethods: (pathname: string, domain?: string) => string[]
   importRoutes: () => Promise<void>
   loadDiscoveredRoutes: () => Promise<void>
 }
 declare type RouteHandlerFn = (_req: EnhancedRequest) => Response | Promise<Response>;
 declare type StacksHandler = string | RouteHandlerFn;
 declare type ResourceAction = 'index' | 'store' | 'show' | 'update' | 'destroy';
+/**
+ * FIFO-bounded Map. Wraps `Map` with a hard size cap; on overflow,
+ * the oldest entry (Map insertion order) is evicted. Used for the
+ * router's small framework-internal caches whose size is normally
+ * bounded by action count, but which had no upper limit before —
+ * tests that instantiate many short-lived routers would leak entries
+ * across `createStacksRouter()` calls (stacksjs/stacks#1863 T-8).
+ *
+ * Insertion-order LRU is appropriate here because the access pattern
+ * is "set once at action-load time, then many reads" — refreshing on
+ * get would buy nothing since reads dominate.
+ */
+declare class BoundedMap<K, V> {
+  constructor(max: number);
+  get(key: K): V | undefined;
+  has(key: K): boolean;
+  set(key: K, value: V): this;
+  delete(key: K): boolean;
+  clear(): void;
+  get size(): number;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@stacksjs/router",
   "type": "module",
-  "version": "0.70.44",
+  "version": "0.70.53",
   "description": "The Stacks framework router.",
   "author": "Chris Breuer",
   "contributors": [
@@ -49,18 +49,18 @@
     "prepublishOnly": "bun run build"
   },
   "dependencies": {
-    "@stacksjs/bun-router": "^0.0.13"
+    "@stacksjs/bun-router": "0.0.17"
   },
   "devDependencies": {
-    "@stacksjs/actions": "^0.70.44",
-    "@stacksjs/config": "^0.70.44",
+    "@stacksjs/actions": "0.70.53",
+    "@stacksjs/config": "0.70.53",
     "better-dx": "^0.2.12",
-    "@stacksjs/error-handling": "^0.70.44",
-    "@stacksjs/logging": "^0.70.44",
-    "@stacksjs/orm": "^0.70.44",
-    "@stacksjs/path": "^0.70.44",
-    "@stacksjs/storage": "^0.70.44",
-    "@stacksjs/types": "^0.70.44",
-    "@stacksjs/validation": "^0.70.44"
+    "@stacksjs/error-handling": "0.70.53",
+    "@stacksjs/logging": "0.70.53",
+    "@stacksjs/orm": "0.70.53",
+    "@stacksjs/path": "0.70.53",
+    "@stacksjs/storage": "0.70.53",
+    "@stacksjs/types": "0.70.53",
+    "@stacksjs/validation": "0.70.53"
   }
 }