@stacksjs/router 0.75.225 → 0.75.230

package/dist/index.d.ts

@@ -84,7 +84,10 @@ export {
 // 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 { rateLimit, rateLimitStatus, clearRateLimit, resetRateLimiters } from './rate-limit';
+// `clientAddress` here shadows bun-router's (re-exported above) with one that
+// reads `config.security.trustedProxies`.
+export { cacheRedisConnection, clientAddress, fallbackStorage, rateLimitScale, resetSharedRateLimitStorage, scaledLimit, sharedRateLimitStorage, trustedProxies, useRateLimitStorage } from './security-settings';
 // 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 /

package/dist/index.js

@@ -1 +1 @@
-import"./request-augmentation";export{readJsonBody,readTextBody,RequestBodyError}from"./body";export*from"@stacksjs/bun-router";export{assertRouteMiddlewareResolvable,configureViewDirectories,clearCsrfModuleCache,clearMiddlewareCache,createStacksRouter,disableViewRouting,enhanceRequest,findUnresolvableRouteMiddleware,installMiddlewareHotReload,loadMiddlewareHandlers,resetBootHooks,route,runBootHooks,serve,serverResponse,url,warnOnMultipleRouterInstances}from"./stacks-router";export{cacheRequestQuery,clearCurrentRequest,getCurrentRequest,getTraceId,request,runWithRequest,setCurrentRequest,withTraceId}from"./request-context";export{defineMiddleware,Middleware}from"./middleware";export{appRouteRegistry,bundleMounts,DEFAULT_ROUTE_BUNDLE_FEATURES,DEFAULT_ROUTE_REGISTRY,listRootMountedAppRoutes,loadRoutes,mountedDefaultRouteBundles}from"./route-loader";export{clearTrackedQueries,createErrorResponse,createMiddlewareErrorResponse,createNotFoundResponse,createValidationErrorResponse,getQueryShapeCounts,trackQuery}from"./error-handler";export{listNamedRoutes,listRegisteredRoutes,routeParams}from"./stacks-router";export{DASHBOARD_ROUTE_GROUPS,dashboardGroupMiddleware,describeUnknownDashboardGroups,resolveDashboardAccess}from"./dashboard-access";export{isRouterAction,wrapAction}from"./stacks-router";export{createTypedRouter}from"./typed-router";export{clearRouteModelBindings,defineRouteModelBinding,resolveRouteModel,routeModelBindings,setRouteModelFallback}from"./route-model-binding";export{isApiRequest,JSON_CONTENT_TYPE}from"./api-shape";export{rateLimit,rateLimitStatus,clearRateLimit}from"./rate-limit";export{PathParamError,safePathParam,sanitizePathParam}from"./path-sanitize";export{checkApplicationHealth,runHealthProbes}from"./health";export{stream}from"./stacks-router";export{signedUrl,signUrl,verifySignedUrl,verifySignedUrlMiddleware}from"./signed-url";export{EncryptedSessionStore}from"./encrypted-session-store";export{createSessionStore,createStacksSessionStore,DatabaseSessionStore,FileSessionStore,MemorySessionStore,RedisSessionStore}from"./session-factory";
+import"./request-augmentation";export{readJsonBody,readTextBody,RequestBodyError}from"./body";export*from"@stacksjs/bun-router";export{assertRouteMiddlewareResolvable,configureViewDirectories,clearCsrfModuleCache,clearMiddlewareCache,createStacksRouter,disableViewRouting,enhanceRequest,findUnresolvableRouteMiddleware,installMiddlewareHotReload,loadMiddlewareHandlers,resetBootHooks,route,runBootHooks,serve,serverResponse,url,warnOnMultipleRouterInstances}from"./stacks-router";export{cacheRequestQuery,clearCurrentRequest,getCurrentRequest,getTraceId,request,runWithRequest,setCurrentRequest,withTraceId}from"./request-context";export{defineMiddleware,Middleware}from"./middleware";export{appRouteRegistry,bundleMounts,DEFAULT_ROUTE_BUNDLE_FEATURES,DEFAULT_ROUTE_REGISTRY,listRootMountedAppRoutes,loadRoutes,mountedDefaultRouteBundles}from"./route-loader";export{clearTrackedQueries,createErrorResponse,createMiddlewareErrorResponse,createNotFoundResponse,createValidationErrorResponse,getQueryShapeCounts,trackQuery}from"./error-handler";export{listNamedRoutes,listRegisteredRoutes,routeParams}from"./stacks-router";export{DASHBOARD_ROUTE_GROUPS,dashboardGroupMiddleware,describeUnknownDashboardGroups,resolveDashboardAccess}from"./dashboard-access";export{isRouterAction,wrapAction}from"./stacks-router";export{createTypedRouter}from"./typed-router";export{clearRouteModelBindings,defineRouteModelBinding,resolveRouteModel,routeModelBindings,setRouteModelFallback}from"./route-model-binding";export{isApiRequest,JSON_CONTENT_TYPE}from"./api-shape";export{rateLimit,rateLimitStatus,clearRateLimit,resetRateLimiters}from"./rate-limit";export{cacheRedisConnection,clientAddress,fallbackStorage,rateLimitScale,resetSharedRateLimitStorage,scaledLimit,sharedRateLimitStorage,trustedProxies,useRateLimitStorage}from"./security-settings";export{PathParamError,safePathParam,sanitizePathParam}from"./path-sanitize";export{checkApplicationHealth,runHealthProbes}from"./health";export{stream}from"./stacks-router";export{signedUrl,signUrl,verifySignedUrl,verifySignedUrlMiddleware}from"./signed-url";export{EncryptedSessionStore}from"./encrypted-session-store";export{createSessionStore,createStacksSessionStore,DatabaseSessionStore,FileSessionStore,MemorySessionStore,RedisSessionStore}from"./session-factory";

package/dist/rate-limit.d.ts

@@ -1,3 +1,5 @@
+/** Drop cached limiters and the resolved store (tests, or after a config change). */
+export declare function resetRateLimiters(): void;
 /**
  * Check + consume a rate-limit slot for the current scope.
  *

package/dist/rate-limit.js

@@ -1 +1 @@
-import{clientAddress}from"@stacksjs/bun-router";import{getCurrentRequest}from"./request-context";let limiterCache,limiterModule,httpErrorModule,limiterModulePromise;function loadLimiterModule(){return limiterModulePromise??=import("ts-rate-limiter").then((module)=>limiterModule=module)}function getLimiter(max,windowMs){const cacheKey=`${windowMs}:${max}`;let limiter=limiterCache?.get(cacheKey);if(!limiter){if(!limiterModule)return loadLimiterModule().then(()=>getLimiter(max,windowMs));const{RateLimiter}=limiterModule;limiter=new RateLimiter({windowMs,maxRequests:max,algorithm:"fixed-window",standardHeaders:!1,legacyHeaders:!1});(limiterCache??=new Map).set(cacheKey,limiter)}return limiter}function resolveIdentity(explicit){if(explicit!==void 0)return explicit;const req=getCurrentRequest();if(!req)return"anon";const id=req._authenticatedUser?.id;if(typeof id==="number"&&Number.isFinite(id)||typeof id==="string"&&id!=="")return`user:${id}`;return`ip:${clientAddress(req)??"unknown"}`}export function rateLimit(key,max,options={}){const run=async(windowMs)=>{const id=resolveIdentity(options.identity),pendingLimiter=getLimiter(max,windowMs),limiter=pendingLimiter instanceof Promise?await pendingLimiter:pendingLimiter,bucketKey=`${key}:${id}`;try{await limiter.enforce(bucketKey)}catch(err){const{RateLimitError}=await loadLimiterModule();if(err instanceof RateLimitError){const{HttpError}=httpErrorModule??=await import("@stacksjs/error-handling/http-error");throw Object.assign(new HttpError(429,"Too many requests",{key,max,retryAfter:err.retryAfter}),{headers:err.toHeaders()})}throw err}};return{async per(period){const seconds=period==="second"?1:period==="minute"?60:period==="hour"?3600:period==="day"?86400:void 0;if(!seconds)throw Error(`rateLimit().per: unknown period '${period}'`);await run(seconds*1000)},async over(ttlSeconds){if(!Number.isFinite(ttlSeconds)||ttlSeconds<=0)throw Error(`rateLimit().over: ttl must be a positive number, got ${ttlSeconds}`);await run(ttlSeconds*1000)}}}export async function rateLimitStatus(key,max,windowSeconds,options={}){const identity=resolveIdentity(options.identity),pendingLimiter=getLimiter(max,windowSeconds*1000),[id,limiter]=typeof identity==="string"&&!(pendingLimiter instanceof Promise)?[identity,pendingLimiter]:await Promise.all([identity,pendingLimiter]),bucketKey=`${key}:${id}`,result=await limiter.peek(bucketKey);if(!result)return null;return{count:result.current,limit:result.limit,remaining:Math.max(0,result.limit-result.current)}}export async function clearRateLimit(key,max,windowSeconds,options={}){const identity=resolveIdentity(options.identity),pendingLimiter=getLimiter(max,windowSeconds*1000),[id,limiter]=typeof identity==="string"&&!(pendingLimiter instanceof Promise)?[identity,pendingLimiter]:await Promise.all([identity,pendingLimiter]),bucketKey=`${key}:${id}`;await limiter.reset(bucketKey)}
+import{getCurrentRequest}from"./request-context";import{clientAddress,scaledLimit,sharedRateLimitStorage}from"./security-settings";let limiterCache,limiterModule,httpErrorModule,limiterModulePromise,limiterStorage,limiterStoragePromise;function loadLimiterModule(){return limiterModulePromise??=import("ts-rate-limiter").then((module)=>limiterModule=module)}function loadLimiterStorage(){return limiterStoragePromise??=sharedRateLimitStorage().then((storage)=>limiterStorage=storage)}export function resetRateLimiters(){for(const limiter of limiterCache?.values()??[])limiter.dispose?.();limiterCache=void 0;limiterStorage=void 0;limiterStoragePromise=void 0}function getLimiter(requestedMax,windowMs){const max=scaledLimit(requestedMax),cacheKey=`${windowMs}:${max}`;let limiter=limiterCache?.get(cacheKey);if(!limiter){if(!limiterModule||limiterStorage===void 0)return Promise.all([loadLimiterModule(),loadLimiterStorage()]).then(()=>getLimiter(requestedMax,windowMs));const{RateLimiter}=limiterModule;limiter=new RateLimiter({windowMs,maxRequests:max,algorithm:"fixed-window",...limiterStorage&&{storage:limiterStorage},standardHeaders:!1,legacyHeaders:!1});(limiterCache??=new Map).set(cacheKey,limiter)}return limiter}function resolveIdentity(explicit){if(explicit!==void 0)return explicit;const req=getCurrentRequest();if(!req)return"anon";const id=req._authenticatedUser?.id;if(typeof id==="number"&&Number.isFinite(id)||typeof id==="string"&&id!=="")return`user:${id}`;return`ip:${clientAddress(req)??"unknown"}`}export function rateLimit(key,max,options={}){const run=async(windowMs)=>{const id=resolveIdentity(options.identity),pendingLimiter=getLimiter(max,windowMs),limiter=pendingLimiter instanceof Promise?await pendingLimiter:pendingLimiter,bucketKey=`${key}:${id}`;try{await limiter.enforce(bucketKey)}catch(err){const{RateLimitError}=await loadLimiterModule();if(err instanceof RateLimitError){const{HttpError}=httpErrorModule??=await import("@stacksjs/error-handling/http-error");throw Object.assign(new HttpError(429,"Too many requests",{key,max,retryAfter:err.retryAfter}),{headers:err.toHeaders()})}throw err}};return{async per(period){const seconds=period==="second"?1:period==="minute"?60:period==="hour"?3600:period==="day"?86400:void 0;if(!seconds)throw Error(`rateLimit().per: unknown period '${period}'`);await run(seconds*1000)},async over(ttlSeconds){if(!Number.isFinite(ttlSeconds)||ttlSeconds<=0)throw Error(`rateLimit().over: ttl must be a positive number, got ${ttlSeconds}`);await run(ttlSeconds*1000)}}}export async function rateLimitStatus(key,max,windowSeconds,options={}){const identity=resolveIdentity(options.identity),pendingLimiter=getLimiter(max,windowSeconds*1000),[id,limiter]=typeof identity==="string"&&!(pendingLimiter instanceof Promise)?[identity,pendingLimiter]:await Promise.all([identity,pendingLimiter]),bucketKey=`${key}:${id}`,result=await limiter.peek(bucketKey);if(!result)return null;return{count:result.current,limit:result.limit,remaining:Math.max(0,result.limit-result.current)}}export async function clearRateLimit(key,max,windowSeconds,options={}){const identity=resolveIdentity(options.identity),pendingLimiter=getLimiter(max,windowSeconds*1000),[id,limiter]=typeof identity==="string"&&!(pendingLimiter instanceof Promise)?[identity,pendingLimiter]:await Promise.all([identity,pendingLimiter]),bucketKey=`${key}:${id}`;await limiter.reset(bucketKey)}

package/dist/security-settings.d.ts

@@ -0,0 +1,60 @@
+import type { ClientAddressOptions } from '@stacksjs/bun-router';
+import type { StorageProvider } from 'ts-rate-limiter';
+/**
+ * The `config/security.ts` settings the request layer reads on every request:
+ * the rate-limit scale, the trusted proxies behind `clientAddress()`, and the
+ * shared store rate limits count in.
+ */
+/**
+ * The multiplier applied to every application rate limit and the login
+ * lockout. `STACKS_RATE_LIMIT_SCALE` wins over `config.security.rateLimit.scale`;
+ * anything that is not a positive finite number reads as 1.
+ */
+export declare function rateLimitScale(): number;
+/** `max` under the configured scale, never below 1. */
+export declare function scaledLimit(max: number): number;
+/**
+ * `config.security.trustedProxies`, or undefined for bun-router's default
+ * (loopback, private and link-local networks). A non-array is ignored with
+ * the default kept, rather than trusting everything or nothing by accident.
+ */
+export declare function trustedProxies(): readonly string[] | undefined;
+/**
+ * The client's address, believing forwarding headers only from the proxies
+ * `config.security.trustedProxies` names (default: loopback and private
+ * networks). Explicit `options` win. This is what `@stacksjs/router` exports
+ * as `clientAddress`, shadowing bun-router's config-unaware export.
+ */
+export declare function clientAddress(req: Request, options?: ClientAddressOptions): string | null;
+/**
+ * The Redis URL and key prefix of the configured cache, or null when the
+ * cache is not Redis. Shared by every limiter that must count across
+ * processes (this package's and `@stacksjs/auth`'s lockout).
+ */
+export declare function cacheRedisConnection(cache?: CacheSettings | undefined): { url: string, prefix: string } | null;
+/**
+ * A ts-rate-limiter storage that counts in the shared store and falls back
+ * to process memory when the shared store errors, so a Redis outage weakens
+ * limits to per-process instead of failing every rate-limited request.
+ */
+export declare function fallbackStorage(shared: StorageProvider, local: StorageProvider): StorageProvider;
+/**
+ * The storage route and action rate limits count in: the configured Redis
+ * cache when there is one (so a limit holds across every process and
+ * instance), otherwise null for ts-rate-limiter's in-memory default.
+ */
+export declare function sharedRateLimitStorage(): Promise<StorageProvider | null>;
+/**
+ * Count route and action rate limits in `storage` (any ts-rate-limiter
+ * `StorageProvider`: a database-backed one, a test double), or `null` for
+ * process memory. Call `resetRateLimiters()` afterwards so limiters already
+ * built pick it up.
+ */
+export declare function useRateLimitStorage(storage: StorageProvider | null): void;
+/** Forget the resolved store (tests, or after changing the cache config). */
+export declare function resetSharedRateLimitStorage(): void;
+declare interface CacheSettings {
+  driver?: string
+  prefix?: string
+  drivers?: { redis?: { url?: string, host?: string, port?: number, username?: string, password?: string, database?: number, tls?: boolean } }
+}

package/dist/security-settings.js

@@ -0,0 +1 @@
+import process from"node:process";import{clientAddress as resolveClientAddress}from"@stacksjs/bun-router";import{config}from"@stacksjs/config";export function rateLimitScale(){const fromEnv=process.env.STACKS_RATE_LIMIT_SCALE,raw=fromEnv!==void 0&&fromEnv!==""?Number(fromEnv):config.security?.rateLimit?.scale,scale=typeof raw==="number"?raw:Number(raw);return Number.isFinite(scale)&&scale>0?scale:1}export function scaledLimit(max){return Math.max(1,Math.floor(max*rateLimitScale()))}export function trustedProxies(){const configured=config.security?.trustedProxies;if(!Array.isArray(configured))return;return configured.filter((entry)=>typeof entry==="string"&&entry.length>0)}export function clientAddress(req,options){if(options)return resolveClientAddress(req,options);const proxies=trustedProxies();return resolveClientAddress(req,proxies?{trustedProxies:proxies}:void 0)}export function cacheRedisConnection(cache=config.cache){const redis=cache?.drivers?.redis;if(cache?.driver!=="redis"||!redis)return null;const prefix=cache.prefix??"stacks";if(redis.url)return{url:redis.url,prefix};const protocol=redis.tls?"rediss":"redis",credentials=redis.username?`${encodeURIComponent(redis.username)}:${encodeURIComponent(redis.password??"")}@`:redis.password?`:${encodeURIComponent(redis.password)}@`:"",database=redis.database==null?"":`/${redis.database}`;return{url:`${protocol}://${credentials}${redis.host??"127.0.0.1"}:${redis.port??6379}${database}`,prefix}}let warnedSharedStore=!1;function warnSharedStoreOnce(error){if(warnedSharedStore)return;warnedSharedStore=!0;console.warn(`[router] rate limits fell back to this process's memory: the configured Redis cache is unreachable (${error instanceof Error?error.message:String(error)}). Limits are per process until it recovers.`)}export function fallbackStorage(shared,local){async function attempt(primary,secondary){try{return await primary()}catch(error){warnSharedStoreOnce(error);return secondary()}}return{increment:(key,windowMs)=>attempt(()=>shared.increment(key,windowMs),()=>local.increment(key,windowMs)),reset:(key)=>attempt(()=>shared.reset(key),()=>local.reset(key)),getCount:(key)=>attempt(()=>shared.getCount?.(key)??Promise.resolve(0),()=>local.getCount?.(key)??Promise.resolve(0)),dispose:()=>{shared.dispose?.();local.dispose?.()}}}let sharedStorage;export function sharedRateLimitStorage(){return sharedStorage??=(async()=>{const connection=cacheRedisConnection();if(!connection)return null;const[{RedisClient},{MemoryStorage,RedisStorage}]=await Promise.all([import("bun"),import("ts-rate-limiter")]),client=new RedisClient(connection.url),shared=new RedisStorage({client,keyPrefix:`${connection.prefix}:ratelimit:`});return fallbackStorage(shared,new MemoryStorage)})()}export function useRateLimitStorage(storage){sharedStorage=Promise.resolve(storage)}export function resetSharedRateLimitStorage(){sharedStorage=void 0;warnedSharedStore=!1}

package/package.json

@@ -2,7 +2,7 @@
   "name": "@stacksjs/router",
   "type": "module",
   "sideEffects": false,
-  "version": "0.75.225",
+  "version": "0.75.230",
   "description": "The Stacks framework router.",
   "author": "Chris Breuer",
   "contributors": [
@@ -67,27 +67,27 @@
   },
   "dependencies": {
     "@stacksjs/bun-router": "^0.1.24",
-    "@stacksjs/cache": "0.75.225",
-    "@stacksjs/collections": "0.75.225",
-    "@stacksjs/config": "0.75.225",
-    "@stacksjs/error-handling": "0.75.225",
-    "@stacksjs/logging": "0.75.225",
-    "@stacksjs/pagination": "0.75.225",
-    "@stacksjs/path": "0.75.225",
-    "@stacksjs/security": "0.75.225",
-    "@stacksjs/storage": "0.75.225",
+    "@stacksjs/cache": "0.75.230",
+    "@stacksjs/collections": "0.75.230",
+    "@stacksjs/config": "0.75.230",
+    "@stacksjs/error-handling": "0.75.230",
+    "@stacksjs/logging": "0.75.230",
+    "@stacksjs/pagination": "0.75.230",
+    "@stacksjs/path": "0.75.230",
+    "@stacksjs/security": "0.75.230",
+    "@stacksjs/storage": "0.75.230",
     "ts-rate-limiter": "^0.4.10"
   },
   "devDependencies": {
-    "@stacksjs/actions": "0.75.225",
-    "@stacksjs/types": "0.75.225",
+    "@stacksjs/actions": "0.75.230",
+    "@stacksjs/types": "0.75.230",
     "better-dx": "^0.2.24"
   },
   "peerDependencies": {
-    "@stacksjs/api": "0.75.225",
-    "@stacksjs/auth": "0.75.225",
-    "@stacksjs/database": "0.75.225",
-    "@stacksjs/validation": "0.75.225"
+    "@stacksjs/api": "0.75.230",
+    "@stacksjs/auth": "0.75.230",
+    "@stacksjs/database": "0.75.230",
+    "@stacksjs/validation": "0.75.230"
   },
   "peerDependenciesMeta": {
     "@stacksjs/api": {