@stacksjs/router 0.70.44 → 0.70.53

package/LICENSE.md

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright (c) 2023 Open Web Foundation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/api-shape.d.ts

@@ -0,0 +1,24 @@
+/*`,
+ * not `application/json`). This predicate fixes that asymmetry by making
+ * JSON the default unless the client explicitly opts into HTML.
+ */
+export declare function isApiRequest(req: Request | { headers: Headers }): boolean;
+/**
+ * "Is this request JSON-shaped?" — the single source of truth used across
+ * the framework to decide JSON vs HTML for responses (errors, primitives,
+ * empty results) and to widen request-body parsing to every JSON variant.
+ *
+ * The historical bug was scattered ad-hoc checks: `error-handler` looked at
+ * `Accept`, `formatResult` ignored the request entirely, `parseRequestBody`
+ * did `contentType.includes('application/json')` so `application/vnd.api+json`
+ * went unparsed. Centralizing the decision here means a future tweak (e.g.,
+ * treating an `apiResponse: true` route group as always-JSON) lands in one
+ * place and every response path picks it up.
+ */
+/**
+ * Matches `application/json` plus any RFC-6838 structured-suffix subtype:
+ * `application/vnd.api+json`, `application/ld+json`, `application/hal+json`,
+ * `application/problem+json`, etc. Case-insensitive; tolerates a trailing
+ * `;` (for `;charset=utf-8`) or end-of-string.
+ */
+export declare const JSON_CONTENT_TYPE: unknown;

package/dist/encrypted-session-store.d.ts

@@ -0,0 +1,19 @@
+import type { SessionData, SessionStore } from '@stacksjs/bun-router';
+export declare interface EncryptedSessionStoreOptions {
+  appKey?: string
+}
+/**
+ * Wrap a bun-router `SessionStore<SessionData>` so all writes are
+ * encrypted on the way in and decrypted on the way out. Drop-in
+ * replacement for any of the built-in stores.
+ */
+export declare class EncryptedSessionStore implements SessionStore<SessionData> {
+  constructor(inner: SessionStore<SessionData>, opts?: EncryptedSessionStoreOptions);
+  set(sid: string, session: SessionData, ttl?: number): Promise<void>;
+  touch(sid: string, session: SessionData, ttl?: number): Promise<void>;
+  get(sid: string): Promise<SessionData | null>;
+  destroy(sid: string): Promise<void>;
+  all(): Promise<Record<string, SessionData>>;
+  length(): Promise<number>;
+  clear(): Promise<void>;
+}

package/dist/error-handler.d.ts

@@ -10,12 +10,18 @@ import type { EnhancedRequest } from '@stacksjs/bun-router';
  */
 export declare function trackQuery(query: string, time?: number, connection?: string): void;
 /**
- * Snapshot of query shape counts. Useful for tests asserting that an
- * action ran a single query for `posts` instead of one-per-user.
+ * Snapshot of query shape counts for the active request. Useful for
+ * tests asserting that an action ran a single query for `posts`
+ * instead of one-per-user.
  */
 export declare function getQueryShapeCounts(): ReadonlyMap<string, number>;
 /**
- * Clear tracked queries (e.g., after successful response)
+ * Reset query tracking for the active scope.
+ *
+ * Inside a request, this clears the per-request tracking object — but
+ * the object is also auto-collected when the request goes out of scope,
+ * so the explicit call is mainly useful for tests that re-use a single
+ * request. Outside a request, this clears the process-wide fallback.
  */
 export declare function clearTrackedQueries(): void;
 /**
@@ -41,7 +47,7 @@ export declare function createErrorResponse(error: Error, request: Request | Enh
  * validation middleware leaks out as a 500 with an Ignition error page —
  * which is what we used to ship for `GET /api/me` without a token.
  */
-export declare function createMiddlewareErrorResponse(error: Error & { statusCode?: number, status?: number }, request: Request | EnhancedRequest): Promise<Response>;
+export declare function createMiddlewareErrorResponse(error: Error & { statusCode?: number, status?: number, headers?: Record<string, string> }, request: Request | EnhancedRequest): Promise<Response>;
 /**
  * Create a validation error response
  */

package/dist/index.d.ts

@@ -1,18 +1,27 @@
+import './request-augmentation';
+// Re-export the augmentation types so userland can refer to the marker
+// surface explicitly when needed.
+export type { StacksRequestExtensions, StacksRequestMacros, StacksRequestMarkers } from './request-augmentation';
 export type { MiddlewareConfig, Request } from './middleware';
-// Export route registry types
-export type { RouteDefinition, RouteRegistry } from '../../../../../app/Routes';
-/**
- * @stacksjs/router - Stacks Router
- *
- * A thin wrapper around bun-router that adds Stacks-specific
- * action/controller resolution for string-based route handlers.
- *
- * All routing functionality comes directly from bun-router.
- */
+// Export route registry types — owned here rather than in app/Routes.ts
+// so the path doesn't depend on a 5-level relative reach across the
+// framework defaults tree (stacksjs/stacks#1863, T-10).
+export type { RouteDefinition, RouteRegistry } from './route-types';
+export type { PathParamRejection, SanitizePathParamOptions } from './path-sanitize';
+export type { StreamOptions } from './stacks-router';
+export type { SignedUrlOptions, SignedUrlVerifyResult } from './signed-url';
+export type { EncryptedSessionStoreOptions } from './encrypted-session-store';
+export type {
+  RedisClient,
+  SessionConfig,
+  SessionData,
+  SessionStore,
+  StacksSessionConfig,
+} from './session-factory';
 // Re-export everything from bun-router (includes response factory)
 export * from '@stacksjs/bun-router';
 // Export Stacks-specific action resolver and URL helper
-export { clearMiddlewareCache, createStacksRouter, installMiddlewareHotReload, route, serve, serverResponse, url } from './stacks-router';
+export { assertRouteMiddlewareResolvable, clearMiddlewareCache, createStacksRouter, findUnresolvableRouteMiddleware, installMiddlewareHotReload, route, serve, serverResponse, url } from './stacks-router';
 // Export request context helpers
 export { cacheRequestQuery, getCurrentRequest, getTraceId, request, runWithRequest, setCurrentRequest, withTraceId } from './request-context';
 // Export Middleware class for defining route middleware
@@ -31,5 +40,42 @@ export {
 } from './error-handler';
 // Export route introspection helpers
 export { listRegisteredRoutes, routeParams } from './stacks-router';
+// Export JSON-vs-HTML negotiation predicate so userland can short-circuit
+// the same decision the framework makes in formatResult / error-handler.
+export { isApiRequest, JSON_CONTENT_TYPE } from './api-shape';
 // Export action-level rate limiting helpers
 export { rateLimit, rateLimitStatus, clearRateLimit } from './rate-limit';
+// Export path-param sanitization helper (stacksjs/stacks#1870 R-12).
+// Defense-in-depth for actions that interpolate route params into
+// filesystem paths; the helper enforces no-traversal / no-absolute /
+// no-null-byte / length ceiling at a single chokepoint.
+export { PathParamError, safePathParam, sanitizePathParam } from './path-sanitize';
+// Export the streaming-response helper for SSE / NDJSON / chunked
+// binary returns (stacksjs/stacks#1870 R-4). Actions can return
+// `stream(asyncGen, { type: 'sse' })` and the router pipes it back
+// with the right Content-Type + no-cache headers.
+export { stream } from './stacks-router';
+// Signed-URL helpers — HMAC over the URL + optional expiry so single-
+// use links (email verify, password reset, unsubscribe) can be handed
+// out without long-lived bearer tokens. Pair `signedUrl(...)` with the
+// `signed` middleware (or call `verifySignedUrl(req.url)` directly).
+// See stacksjs/stacks#1870 R-7.
+export { signedUrl, signUrl, verifySignedUrl, verifySignedUrlMiddleware } from './signed-url';
+// Encryption-at-rest wrapper for any bun-router SessionStore
+// (stacksjs/stacks#1878 Se-4). Opt-in: wrap your existing store
+// instance so session payloads are AES-GCM encrypted via APP_KEY
+// before being persisted.
+export { EncryptedSessionStore } from './encrypted-session-store';
+// Session driver factory (stacksjs/stacks#1889, F-2 from #1874).
+// Builds a SessionStore from the Stacks config — picks the right
+// driver from `config.session.driver`, optionally wraps with
+// EncryptedSessionStore. Re-exports all four bun-router store
+// classes so callers can assemble custom stacks manually too.
+export {
+  createSessionStore,
+  createStacksSessionStore,
+  DatabaseSessionStore,
+  FileSessionStore,
+  MemorySessionStore,
+  RedisSessionStore,
+} from './session-factory';