@stacksjs/router 0.70.88 → 0.70.91

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/session-factory.js

@@ -0,0 +1,26 @@
+import process from "node:process";
+import { createSessionStore } from "@stacksjs/bun-router";
+import { EncryptedSessionStore } from "./encrypted-session-store";
+export function createStacksSessionStore(config) {
+  const base = createSessionStore(config);
+  if (!resolveEncryptionMode(config.encrypt))
+    return base;
+  const appKey = config.appKey ?? process.env.APP_KEY;
+  if (!appKey || appKey.length < 16)
+    throw Error("[session] createStacksSessionStore: encryption requested but APP_KEY is missing or too short " + "(need \u226516 chars). Either set APP_KEY in env, pass `appKey` in config, or set `encrypt: false` to opt out.");
+  return new EncryptedSessionStore(base, { appKey });
+}
+function resolveEncryptionMode(mode) {
+  if (mode === !0)
+    return !0;
+  if (mode === !1)
+    return !1;
+  return (process.env.APP_ENV ?? process.env.NODE_ENV ?? "").toLowerCase() === "production";
+}
+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/signed-url.js

@@ -0,0 +1,76 @@
+import { timingSafeEqual } from "node:crypto";
+import { Buffer } from "node:buffer";
+import process from "node:process";
+import { url as buildUrl } from "./stacks-router";
+const SIGNATURE_PARAM = "signature", EXPIRES_PARAM = "expires";
+function getSigningSecret() {
+  const secret = process.env.APP_KEY || process.env.STACKS_SIGNED_URL_SECRET;
+  if (!secret || secret.length < 16)
+    throw Error("[router] signed URLs require APP_KEY (\u2265 16 chars) or STACKS_SIGNED_URL_SECRET. " + "Run `./buddy key:generate` or set the env var.");
+  return secret;
+}
+function hmacHex(payload, secret) {
+  return new Bun.CryptoHasher("sha256", secret).update(payload).digest("hex");
+}
+function safeEqualHex(a, b) {
+  const ba = Buffer.from(a.toLowerCase(), "hex"), bb = Buffer.from(b.toLowerCase(), "hex");
+  if (ba.length !== bb.length)
+    return !1;
+  return timingSafeEqual(ba, bb);
+}
+function stripSignatureParam(input) {
+  const u = new URL(input.toString());
+  u.searchParams.delete(SIGNATURE_PARAM);
+  return u;
+}
+function buildSignaturePayload(input) {
+  const stripped = stripSignatureParam(input);
+  stripped.searchParams.sort();
+  return stripped.toString();
+}
+export function signUrl(input, options = {}) {
+  const secret = getSigningSecret(), url = input.startsWith("http") ? new URL(input) : new URL(input.startsWith("/") ? input : `/${input}`, process.env.APP_URL || "https://localhost");
+  if (options.ttl !== void 0 && options.expiresAt !== void 0)
+    warnOnce("dual-expiry", "[router] signUrl: both `ttl` and `expiresAt` provided \u2014 using `ttl`.");
+  if (options.ttl !== void 0)
+    url.searchParams.set(EXPIRES_PARAM, String(Math.floor(Date.now() / 1000) + options.ttl));
+  else if (options.expiresAt !== void 0)
+    url.searchParams.set(EXPIRES_PARAM, String(Math.floor(options.expiresAt)));
+  const payload = buildSignaturePayload(url);
+  url.searchParams.set(SIGNATURE_PARAM, hmacHex(payload, secret));
+  return url.toString();
+}
+const _warnedKeys = new Set;
+function warnOnce(key, message) {
+  if (_warnedKeys.has(key))
+    return;
+  _warnedKeys.add(key);
+  console.warn(message);
+}
+export function signedUrl(routeName, params = {}, options = {}) {
+  return signUrl(buildUrl(routeName, params), options);
+}
+export function verifySignedUrl(input) {
+  const url = typeof input === "string" ? new URL(input, process.env.APP_URL || "https://localhost") : input, presented = url.searchParams.get(SIGNATURE_PARAM);
+  if (!presented)
+    return { valid: !1, reason: "missing-signature" };
+  const expiresRaw = url.searchParams.get(EXPIRES_PARAM);
+  if (expiresRaw !== null) {
+    const expires = Number.parseInt(expiresRaw, 10);
+    if (!Number.isFinite(expires) || Date.now() / 1000 > expires)
+      return { valid: !1, reason: "expired" };
+  }
+  try {
+    const expected = hmacHex(buildSignaturePayload(url), getSigningSecret());
+    return safeEqualHex(presented, expected) ? { valid: !0 } : { valid: !1, reason: "invalid-signature" };
+  } catch {
+    return { valid: !1, reason: "invalid-signature" };
+  }
+}
+export async function verifySignedUrlMiddleware(req) {
+  const result = verifySignedUrl(req.url);
+  if (result.valid)
+    return;
+  const status = result.reason === "expired" ? 410 : 401;
+  throw Response.json({ error: result.reason }, { status });
+}

package/dist/stacks-router.d.ts

@@ -0,0 +1,213 @@
+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';
+/**
+ * Warn (once per process) when more than one @stacksjs/router module has loaded
+ * (stacksjs/stacks#1975 / #1982). Routing still works — the route table and
+ * request context are process-global singletons — but a duplicated install is
+ * worth surfacing. Called at serve() boot. Returns whether a split was detected
+ * so callers/tests can assert on it without capturing logs.
+ */
+export declare function warnOnMultipleRouterInstances(): boolean;
+/**
+ * Generate a full URL for a named route, like Laravel's route() helper.
+ *
+ * Validates path parameters at call time so a typo'd argument
+ * (`url('user.post', { userId: 1 })` against `/users/{id}`) throws
+ * immediately with a list of expected names instead of silently
+ * producing a URL with `{id}` left literal in the path.
+ *
+ * @example
+ * ```typescript
+ * // Define a named route
+ * route.get('/api/email/unsubscribe', 'Actions/UnsubscribeAction').name('email.unsubscribe')
+ *
+ * // Generate URL
+ * url('email.unsubscribe', { token: 'abc-123' })
+ * // → https://stacksjs.com/api/email/unsubscribe?token=abc-123
+ *
+ * // With path parameters
+ * route.get('/users/{id}/posts/{postId}', handler).name('user.post')
+ * url('user.post', { id: 42, postId: 7 })
+ * // → https://stacksjs.com/users/42/posts/7
+ * ```
+ */
+export declare function url(routeName: string, params?: Record<string, string | number>): string;
+/**
+ * List the placeholder names a named route expects — handy for
+ * codegen/test cases and for detecting typos before runtime.
+ */
+export declare function routeParams(routeName: string): string[];
+/**
+ * Snapshot of the registered routes — `{ method, path, name? }` per
+ * route. Used by `buddy route:list` and the dev-server startup banner.
+ */
+export declare function listRegisteredRoutes(): Array<{ method: string, path: string, name?: string }>;
+/**
+ * Clear the middleware cache (useful for hot-reload in development).
+ *
+ * `installMiddlewareHotReload()` will wire this up automatically when
+ * called from the dev server — production should never invoke it.
+ */
+export declare function clearMiddlewareCache(): void;
+/**
+ * Watch `app/Middleware/` and `app/Middleware.ts` and invalidate the
+ * cached middleware modules whenever a file changes. Intended for the
+ * dev server only — calling this in production is a no-op (the
+ * watcher handle is created but never fires anything user code cares
+ * about). Returns a `disposer()` to stop watching.
+ *
+ * Without this hook, editing a middleware file in dev requires a
+ * full server restart to see the change — the import map caches the
+ * 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
+ */
+export declare function createStacksRouter(config?: StacksRouterConfig): StacksRouterInstance;
+/**
+ * Handle a server request through the router
+ * This is the main entry point for the Stacks server
+ */
+export declare function serverResponse(request: Request, _body?: string): Promise<Response>;
+// Export serve function that uses the default router
+export declare function serve(options?: ServerOptions): Promise<Server<unknown>>;
+export declare const route: StacksRouterInstance;
+declare interface StacksRouterConfig {
+  verbose?: boolean
+  apiPrefix?: string
+}
+declare interface GroupOptions {
+  prefix?: string
+  middleware?: string | string[]
+  apiResponse?: boolean
+}
+declare interface ResourceRouteOptions {
+  only?: ResourceAction[]
+  except?: ResourceAction[]
+  middleware?: string | string[]
+}
+/**
+ * Chainable route interface for middleware and naming support
+ */
+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
+  routes: Route[]
+  get: (path: string, handler: StacksHandler) => ChainableRoute
+  post: (path: string, handler: StacksHandler) => ChainableRoute
+  put: (path: string, handler: StacksHandler) => ChainableRoute
+  patch: (path: string, handler: StacksHandler) => ChainableRoute
+  delete: (path: string, handler: StacksHandler) => ChainableRoute
+  options: (path: string, handler: StacksHandler) => ChainableRoute
+  group: (options: GroupOptions, callback: () => void | Promise<void>) => StacksRouterInstance | Promise<StacksRouterInstance>
+  resource: (name: string, handler: string, options?: ResourceRouteOptions) => StacksRouterInstance
+  match: (methods: string[], path: string, handler: StacksHandler) => ChainableRoute
+  health: () => StacksRouterInstance
+  use: (middleware: ActionHandler | ((req: EnhancedRequest, next: () => Promise<Response>) => Response | Promise<Response>)) => 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;
+}