hono-cloudflare-rate-limit 0.0.0-stage → 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 binochoi
+
+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/README.md

@@ -1,3 +1,110 @@
-# Temporary Holding Version
+# hono-cloudflare-rate-limit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm](https://img.shields.io/npm/v/hono-cloudflare-rate-limit)](https://www.npmjs.com/package/hono-cloudflare-rate-limit)
+[![license](https://img.shields.io/npm/l/hono-cloudflare-rate-limit)](./LICENSE)
+
+A tiny, env-agnostic **[Hono](https://hono.dev) rate limit middleware for Cloudflare Workers**, built on the native [Workers Rate Limiting binding](https://developers.cloudflare.com/workers/runtime-apis/bindings/rate-limit/) (`ratelimits` in `wrangler.jsonc` / `wrangler.toml`). Throttle API requests per IP, per user, or per API key and return `429 Too Many Requests` when the limit is exceeded — useful for protecting login, signup, password reset, and OTP endpoints from brute-force attacks and abuse at the edge.
+
+The middleware only calls the binding, throws on overflow, and exposes an on/off hook. **You decide which binding to use, how to build the counter key, and when to skip limiting** — it never reads a fixed `env` shape, so it works in any Hono app on Cloudflare Workers.
+
+## Install
+
+```bash
+npm install hono-cloudflare-rate-limit
+# pnpm add hono-cloudflare-rate-limit
+```
+
+`hono` and `@cloudflare/workers-types` are peer dependencies.
+
+## Runtime requirement
+
+The `limit()` binding is a **Cloudflare Workers (workerd) only API**. It does not exist on Node.js, Bun, Deno, or other regular servers, so this middleware won't work there.
+
+To rate limit an origin server through Cloudflare instead:
+
+- Use **WAF Rate Limiting Rules** at the edge, or put a **thin Worker** in front of the origin.
+- Lock the origin down to **Cloudflare IP ranges + Authenticated Origin Pulls (mTLS)**. Only then can you trust `CF-Connecting-IP` — requests that bypass the edge can omit or spoof that header.
+
+## Usage
+
+Declare a rate limit binding in `wrangler.jsonc`:
+
+```jsonc
+{
+  "ratelimits": [
+    {
+      "name": "RL",
+      "namespace_id": "1001",
+      "simple": { "limit": 100, "period": 60 }
+    }
+  ]
+}
+```
+
+Then apply the middleware:
+
+```ts
+import { Hono } from "hono";
+import type { RateLimit } from "@cloudflare/workers-types";
+import { rateLimit, cfConnectingIp } from "hono-cloudflare-rate-limit";
+
+type AppEnv = {
+  Bindings: { RL: RateLimit; APP_URL: string };
+  Variables: {};
+};
+
+const app = new Hono<AppEnv>();
+
+const guard = rateLimit<AppEnv>({
+  // Return false to skip limiting, e.g. in local development.
+  enabled: (c) => !c.env.APP_URL.startsWith("http://localhost"),
+  limiter: (c) => c.env.RL,
+  key: (c) => {
+    const ip = cfConnectingIp(c);
+    if (!ip) throw new Error("unknown client");
+    return `api:${ip}`;
+  },
+});
+
+app.use("/api/*", guard);
+```
+
+By default an exceeded limit throws `HTTPException(429, "too many requests")`. Pass `onExceeded` to return a custom response.
+
+## Use cases
+
+- **Per-IP API limit** — key by `api:${ip}` on `/api/*`.
+- **Stricter limits on sensitive routes** — bind a separate, tighter limiter to login, signup, password reset, or OTP endpoints to slow down brute-force and spam.
+- **Per-user or per-API-key quotas** — key by `user:${userId}` or `key:${apiKey}` for plan-based limits.
+- **Disable in development** — return `false` from `enabled` for localhost.
+- **Custom 429 response** — use `onExceeded` to send a JSON error body or a `Retry-After` header:
+
+```ts
+rateLimit<AppEnv>({
+  limiter: (c) => c.env.RL,
+  key: (c) => `login:${cfConnectingIp(c) ?? "unknown"}`,
+  onExceeded: (c) => {
+    c.header("Retry-After", "60");
+    return c.json({ error: "rate_limited" }, 429);
+  },
+});
+```
+
+## API
+
+### `rateLimit(options): MiddlewareHandler`
+
+| Option       | Type                                          | Description                                                                                              |
+| ------------ | --------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| `limiter`    | `(c) => RateLimit`                            | Picks the rate limit binding from `env`.                                                                 |
+| `key`        | `(c) => string`                               | Builds the counter key. If it throws (e.g. client can't be identified), the error propagates as-is.     |
+| `enabled?`   | `(c) => boolean`                              | Return `false` to skip limiting for this request. Defaults to always on.                                 |
+| `onExceeded?` | `(c) => Response \| Promise<Response>`       | Response to send when the limit is exceeded. Defaults to throwing `HTTPException(429)`.                  |
+
+### `cfConnectingIp(c): string | null`
+
+Returns the `CF-Connecting-IP` header set by the Cloudflare edge. It is `null` for requests that didn't pass through the edge (local dev, service bindings, etc.).
+
+## License
+
+[MIT](./LICENSE)

package/dist/index.d.mts

@@ -0,0 +1,27 @@
+import { Context, MiddlewareHandler } from "hono";
+import { RateLimit } from "@cloudflare/workers-types";
+export type RateLimitOptions<E extends {
+  Bindings: object;
+  Variables: object;
+} = {
+  Bindings: object;
+  Variables: object;
+}> = {
+  /** env 에서 쓸 RateLimit 바인딩을 고른다. */
+  limiter: (c: Context<E>) => RateLimit;
+  /** 카운터 키를 파생한다. 키를 만들 수 없는 상황(예: 클라이언트 식별 불가)의
+   *  처리는 소비자 책임 — 여기서 throw 하면 미들웨어가 그대로 전파한다. */
+  key: (c: Context<E>) => string;
+  /** false 를 반환하면 이 요청은 리밋을 건너뛴다(예: 개발환경). 생략하면 항상 적용. */
+  enabled?: (c: Context<E>) => boolean;
+  /** 초과 시 동작. 생략하면 HTTPException(429, "too many requests") 를 던진다. */
+  onExceeded?: (c: Context<E>) => Response | Promise<Response>;
+};
+/** RateLimit 바인딩으로 요청을 제한하는 Hono 미들웨어를 만든다. */
+export declare const rateLimit: <E extends {
+  Bindings: object;
+  Variables: object;
+}>(opts: RateLimitOptions<E>) => MiddlewareHandler<E>;
+/** Cloudflare 엣지가 찍는 표준 클라이언트 IP 헤더. 엣지를 거치지 않은 요청
+ *  (로컬 dev, service binding 등)에는 없으므로 null 이 반환될 수 있다. */
+export declare const cfConnectingIp: (c: Context) => string | null;

package/dist/index.mjs

@@ -0,0 +1,14 @@
+import { HTTPException } from "hono/http-exception";
+const rateLimit = (opts) => {
+	return async (c, next) => {
+		if (opts.enabled && !opts.enabled(c)) return next();
+		const { success } = await opts.limiter(c).limit({ key: opts.key(c) });
+		if (!success) {
+			if (opts.onExceeded) return opts.onExceeded(c);
+			throw new HTTPException(429, { message: "too many requests" });
+		}
+		return next();
+	};
+};
+const cfConnectingIp = (c) => c.req.header("CF-Connecting-IP") ?? null;
+export { cfConnectingIp, rateLimit };

package/package.json

@@ -1,6 +1,70 @@
 {
   "name": "hono-cloudflare-rate-limit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.0.1",
+  "description": "Hono rate limit middleware for Cloudflare Workers using the native Rate Limiting binding. Throttle requests per IP, user, or API key and return 429 Too Many Requests.",
+  "type": "module",
+  "license": "MIT",
+  "author": "binochoi",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/binochoi/hono-cloudflare-rate-limit.git"
+  },
+  "homepage": "https://github.com/binochoi/hono-cloudflare-rate-limit#readme",
+  "bugs": {
+    "url": "https://github.com/binochoi/hono-cloudflare-rate-limit/issues"
+  },
+  "keywords": [
+    "hono",
+    "hono-middleware",
+    "middleware",
+    "rate-limit",
+    "rate-limiter",
+    "ratelimit",
+    "rate-limiting",
+    "throttle",
+    "throttling",
+    "cloudflare",
+    "cloudflare-workers",
+    "workers",
+    "workerd",
+    "wrangler",
+    "ratelimits",
+    "cloudflare-rate-limiting",
+    "429",
+    "too-many-requests",
+    "brute-force",
+    "abuse-protection",
+    "api-security",
+    "edge",
+    "serverless",
+    "typescript"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "hono": "^4.9.0",
+    "@cloudflare/workers-types": "^4.20250101.0"
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "^4.20250101.0",
+    "@types/node": "^22.10.0",
+    "hono": "^4.9.0",
+    "obuild": "^0.4.38",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.10"
+  },
+  "scripts": {
+    "build:dist": "obuild",
+    "release": "pnpm build:dist && pnpm publish --ignore-scripts",
+    "clean": "rm -rf dist node_modules .turbo",
+    "lint": "oxlint ./src && tsc --noEmit",
+    "test": "vitest run"
+  }
 }