@spfn/core 0.2.0-beta.57 → 0.2.0-beta.59

package/dist/middleware/index.d.ts

@@ -1,5 +1,5 @@
 import { Context, Next, MiddlewareHandler } from 'hono';
-import { b as NamedMiddlewareFactory } from '../define-middleware-DuXD8Hvu.js';
+import { b as NamedMiddlewareFactory, N as NamedMiddleware } from '../define-middleware-DuXD8Hvu.js';
 
 /**
  * Error Handler Middleware
@@ -285,8 +285,17 @@ declare function createCacheNonceStore(cache: CacheClient, prefix?: string): Non
  */
 declare function createInMemoryNonceStore(): NonceStore;
 
+/**
+ * One identity dimension to limit on. A bare string uses the top-level `limit`;
+ * an object can carry its own `limit` so dimensions can differ (e.g. a loose
+ * per-IP cap alongside a tight per-account cap).
+ */
+type RateLimitDimension = string | {
+    key: string;
+    limit?: number;
+};
 interface RateLimitOptions {
-    /** Max requests allowed per window, applied to each identity dimension. */
+    /** Max requests allowed per window, applied to each dimension without its own `limit`. */
     limit: number;
     /** Window length in milliseconds. */
     windowMs: number;
@@ -297,10 +306,11 @@ interface RateLimitOptions {
     scope?: string;
     /**
      * Identity dimensions to limit on. Each non-empty value is counted
-     * separately and the strictest wins (e.g. by IP and by account). Defaults
-     * to the client IP only.
+     * separately and the strictest wins (e.g. by IP and by account). A dimension
+     * may override the top-level `limit` via `{ key, limit }`. Defaults to the
+     * client IP only.
      */
-    by?: (c: Context) => (string | null | undefined)[] | Promise<(string | null | undefined)[]>;
+    by?: (c: Context) => (RateLimitDimension | null | undefined)[] | Promise<(RateLimitDimension | null | undefined)[]>;
     /** Reject with 429 instead of allowing through when the cache is unavailable. */
     failClosed?: boolean;
     /** Message for the 429 response. */
@@ -316,6 +326,10 @@ interface RateLimitOptions {
  * the forwarded header is attacker-settable, so fall back to the raw chain — whose
  * leftmost hop is itself spoofable, so still pair with an account/target dimension
  * for anything security-sensitive.
+ *
+ * Last resort before giving up is the TCP peer address from the Node adapter
+ * socket. Without it, a deployment that sets no forwarding header would collapse
+ * every client onto a single `'unknown'` bucket.
  */
 declare function getClientIp(c: Context): string;
 /**
@@ -329,5 +343,41 @@ declare function getClientIp(c: Context): string;
  * ```
  */
 declare const rateLimit: NamedMiddlewareFactory<"rateLimit", [options: RateLimitOptions]>;
+/** Set the fail-closed default for named policies. Called by the server at boot. */
+declare function setRateLimitFailClosedDefault(failClosed: boolean): void;
+/**
+ * Replace the named-policy registry. Called by the server at boot; passing
+ * undefined clears it (so a restart without policies doesn't keep stale ones).
+ */
+declare function setRateLimitPolicies(policies?: Record<string, RateLimitOptions>): void;
+/** Look up a configured policy by name — undefined when the app didn't set it. */
+declare function getRateLimitPolicy(name: string): RateLimitOptions | undefined;
+/**
+ * Rate-limit a route under a named policy.
+ *
+ * A package author tags a sensitive route with a policy name plus a safe
+ * fallback; the consuming app tunes the numbers centrally via
+ * `defineServerConfig().rateLimit({ policies: { [name]: {...} } })`. When the
+ * app configures the policy, its fields override the fallback (shallow merge);
+ * otherwise the fallback applies, so the route is protected out of the box.
+ *
+ * LAYERS on top of the global default limiter rather than replacing it: the tag
+ * has a distinct name (`rateLimit:<name>`) and does not skip the global, so a
+ * route gets both the global per-IP floor (when enabled) and this policy's own
+ * bucket — whichever is stricter trips first. Opt out of the global floor on a
+ * route with `.skip(['rateLimit'])`.
+ *
+ * The counter scope defaults to the policy name, so (a) every route sharing a
+ * policy shares one bucket, and (b) the key never collides with the global
+ * default's per-route `${method} ${path}` scope.
+ *
+ * @example
+ * ```typescript
+ * route.post('/_auth/login')
+ *     .use([rateLimitPolicy('auth-login', { limit: 5, windowMs: 60_000 })])
+ *     .handler(...);
+ * ```
+ */
+declare function rateLimitPolicy(name: string, fallback: RateLimitOptions): NamedMiddleware<string>;
 
-export { type ClientType, ErrorHandler, type ErrorHandlerOptions, type NonceStore, type OnErrorContext, type ProxyGuardConfig, type ProxyGuardMode, type RateLimitOptions, RequestLogger, type RequestLoggerConfig, type RequestLoggerOptions, createCacheNonceStore, createInMemoryNonceStore, createProxyGuard, getClientIp, maskSensitiveData, rateLimit };
+export { type ClientType, ErrorHandler, type ErrorHandlerOptions, type NonceStore, type OnErrorContext, type ProxyGuardConfig, type ProxyGuardMode, type RateLimitDimension, type RateLimitOptions, RequestLogger, type RequestLoggerConfig, type RequestLoggerOptions, createCacheNonceStore, createInMemoryNonceStore, createProxyGuard, getClientIp, getRateLimitPolicy, maskSensitiveData, rateLimit, rateLimitPolicy, setRateLimitFailClosedDefault, setRateLimitPolicies };

package/dist/middleware/index.js

@@ -237,6 +237,42 @@ function verifyProxyRequest(input) {
 }
 
 // src/route/define-middleware.ts
+function defineMiddleware(name, handlerOrFactory, options) {
+  const skips = options?.skips;
+  if (typeof handlerOrFactory === "function") {
+    const paramCount = handlerOrFactory.length;
+    if (paramCount === 2) {
+      return {
+        name,
+        handler: handlerOrFactory,
+        _name: name,
+        ...skips
+      };
+    } else {
+      const factory = handlerOrFactory;
+      const wrapper = (...args) => factory(...args);
+      Object.defineProperty(wrapper, "name", {
+        value: name,
+        writable: false,
+        enumerable: false,
+        configurable: true
+      });
+      Object.defineProperty(wrapper, "_name", {
+        value: name,
+        writable: false,
+        enumerable: false,
+        configurable: true
+      });
+      return wrapper;
+    }
+  }
+  return {
+    name,
+    handler: handlerOrFactory,
+    _name: name,
+    ...skips
+  };
+}
 function defineMiddlewareFactory(name, factory) {
   const wrapper = (...args) => factory(...args);
   Object.defineProperty(wrapper, "name", {
@@ -1066,7 +1102,12 @@ function getClientIp(c) {
     }
   }
   const forwardedFor = c.req.header("x-forwarded-for");
-  return forwardedFor?.split(",")[0]?.trim() || c.req.header("x-real-ip") || "unknown";
+  return forwardedFor?.split(",")[0]?.trim() || c.req.header("x-real-ip") || socketRemoteAddress(c) || "unknown";
+}
+function socketRemoteAddress(c) {
+  const env4 = c.env;
+  const bindings = env4?.server ?? env4;
+  return bindings?.incoming?.socket?.remoteAddress;
 }
 var rateLimit = defineMiddlewareFactory(
   "rateLimit",
@@ -1086,13 +1127,18 @@ var rateLimit = defineMiddlewareFactory(
       const dimensions = (by ? await by(c) : [getClientIp(c)]).filter((d) => Boolean(d));
       const ns = scope || `${c.req.method} ${c.req.routePath || c.req.path}`;
       for (const dimension of dimensions) {
+        const key = typeof dimension === "string" ? dimension : dimension.key;
+        if (!key) {
+          continue;
+        }
+        const dimLimit = typeof dimension === "string" ? limit : dimension.limit ?? limit;
         const [count, pttl] = await cache.eval(
           FIXED_WINDOW_LUA,
           1,
-          `ratelimit:${ns}:${dimension}`,
+          `ratelimit:${ns}:${key}`,
           String(windowMs)
         );
-        if (count > limit) {
+        if (count > dimLimit) {
           const retryAfter = Math.max(1, Math.ceil((pttl > 0 ? pttl : windowMs) / 1e3));
           c.header("Retry-After", String(retryAfter));
           throw new TooManyRequestsError({
@@ -1105,6 +1151,41 @@ var rateLimit = defineMiddlewareFactory(
     };
   }
 );
+var policyRegistry = /* @__PURE__ */ new Map();
+var policyFailClosedDefault = false;
+function setRateLimitFailClosedDefault(failClosed) {
+  policyFailClosedDefault = failClosed;
+}
+function setRateLimitPolicies(policies) {
+  policyRegistry.clear();
+  if (!policies) {
+    return;
+  }
+  for (const [name, options] of Object.entries(policies)) {
+    policyRegistry.set(name, options);
+  }
+}
+function getRateLimitPolicy(name) {
+  return policyRegistry.get(name);
+}
+function rateLimitPolicy(name, fallback) {
+  let resolved;
+  const handler = (c, next) => {
+    if (!resolved) {
+      const configured = getRateLimitPolicy(name);
+      const merged = configured ? { ...fallback, ...configured } : { ...fallback };
+      if (merged.scope === void 0) {
+        merged.scope = name;
+      }
+      if (merged.failClosed === void 0) {
+        merged.failClosed = policyFailClosedDefault;
+      }
+      resolved = rateLimit(merged);
+    }
+    return resolved(c, next);
+  };
+  return defineMiddleware(`rateLimit:${name}`, handler);
+}
 
 // src/middleware/request-logger.ts
 var DEFAULT_CONFIG = {
@@ -1383,6 +1464,6 @@ function reject(c, mode, next, reason) {
   return next();
 }
 
-export { ErrorHandler, RequestLogger, createCacheNonceStore, createInMemoryNonceStore, createProxyGuard, getClientIp, maskSensitiveData2 as maskSensitiveData, rateLimit };
+export { ErrorHandler, RequestLogger, createCacheNonceStore, createInMemoryNonceStore, createProxyGuard, getClientIp, getRateLimitPolicy, maskSensitiveData2 as maskSensitiveData, rateLimit, rateLimitPolicy, setRateLimitFailClosedDefault, setRateLimitPolicies };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map